<p align="center"> <img src="https://github.com/user-attachments/assets/5b182044-dceb-41f5-acf0-da22dea7c98a" alt="CLR-S (2)"> </p>
npm install @trustless-work/escrow
bash
npm install @trustless-work/escrow
or
yarn add @trustless-work/escrow
`
Quick Start
1. Trustless Work React provides the TrustlessWorkConfig to provide all the custom hooks and entities to the whole project. To achieve this you'll need to create a Provider.
`tsx
"use client"; // make sure this is a client component
import React from "react";
import {
// development environment = "https://dev.api.trustlesswork.com"
development,
// mainnet environment = "https://api.trustlesswork.com"
mainNet,
TrustlessWorkConfig,
} from "@trustless-work/escrow";
interface TrustlessWorkProviderProps {
children: React.ReactNode;
}
export function TrustlessWorkProvider({
children,
}: TrustlessWorkProviderProps) {
/**
* Get the API key from the environment variables
*/
const apiKey = process.env.NEXT_PUBLIC_API_KEY || "";
return (
{children}
);
}
`
2. Wrap your app in the provider
`tsx
import { TrustlessWorkProvider} from "@/trustless-work-provider.tsx";
export function App() {
return (
);
}
`
3. Use the hooks in your components:
`tsx
import { useInitializeEscrow } from '@trustless-work/escrow/hooks';
function YourComponent() {
const { deployEscrow } = useInitializeEscrow();
// Use the hooks...
}
`
State Management Integration
This library is designed to be flexible and work with any state management solution. The hooks expose functions that you can integrate with your preferred state management library.
$3
`tsx
import { QueryClient, QueryClientProvider } from '@tanstack/react-query';
import { TrustlessWorkConfig } from '@trustless-work/escrow';
const queryClient = new QueryClient({
defaultOptions: {
queries: {
staleTime: 5 60 1000, // 5 minutes
gcTime: 10 60 1000, // 10 minutes
},
},
});
function App() {
return (
);
}
// Usage in components
import { useQuery } from '@tanstack/react-query';
import { useGetEscrowsFromIndexerByRole } from '@trustless-work/escrow/hooks';
export const useEscrowsByRoleQuery = (params) => {
const { getEscrowsByRole } = useGetEscrowsFromIndexerByRole();
return useQuery({
queryKey: ["escrows", params.roleAddress, params.role],
queryFn: () => getEscrowsByRole(params),
enabled: !!params.roleAddress && !!params.role,
staleTime: 5 60 1000,
});
};
`
$3
`tsx
import { create } from 'zustand';
import { useGetEscrowsFromIndexerByRole } from '@trustless-work/escrow/hooks';
const useEscrowStore = create((set, get) => ({
escrows: [],
isLoading: false,
error: null,
fetchEscrows: async (params) => {
const { getEscrowsByRole } = useGetEscrowsFromIndexerByRole();
set({ isLoading: true, error: null });
try {
const escrows = await getEscrowsByRole(params);
set({ escrows, isLoading: false });
} catch (error) {
set({ error, isLoading: false });
}
},
}));
`
Available Hooks
$3
- useInitializeEscrow: Create a new escrow
- useGetEscrow: Fetch escrow details
- useGetMultipleEscrowBalances: Get balances for multiple escrows
- useUpdateEscrow: Update escrow information
- useFundEscrow: Fund an escrow
- useReleaseFunds: Release funds from escrow
$3
- useStartDispute: Initiate a dispute
- useResolveDispute: Resolve an existing dispute
$3
- useChangeMilestoneStatus: Update milestone status
- useApproveMilestone: Approve or reject milestones
$3
- useSendTransaction: Send a transaction
$3
- useGetEscrowsFromIndexerByRole: Get escrows by role
- useGetEscrowsFromIndexerBySigner: Get escrows by signer
Types
The library includes comprehensive TypeScript types for all operations. Key type definitions can be found in:
- types.entity.ts: Core entity definitions
- types.payload.ts: Request payload types
- types.response.ts: API response types
Environment Setup
The library supports two environments:
- Production: https://api.trustlesswork.com
- Development: https://dev.api.trustlesswork.com
Make sure to:
1. Use the correct baseURL for your environment
2. Store your API key in environment variables
3. Use the appropriate API key for your environment
4. You can get the API Key from the Trustless Work dApp. Make sure to use the correct API key for the environment you are using. We recommend saving this apiKey in your .env file.
* - "https://dapp.trustlesswork.com" (production)
* - "https://dapp.dev.trustlesswork.com" (development)
Best Practices
1. State Management: Choose the state management solution that best fits your project needs
2. Error Handling: Implement proper error handling for all API calls
3. Loading States: Use loading states to provide better user experience
4. Type Safety: Take advantage of TypeScript types for better development experience
5. API Key Security: Never expose your API key in client-side code. Use environment variables
6. Caching: Implement appropriate caching strategies for better performance
Example Usage
`tsx
import {
useInitializeEscrow,
useSendTransaction,
} from "@trustless-work/escrow/hooks";
import {
InitializeEscrowPayload
} from "@trustless-work/escrow/types";
export const useInitializeEscrowForm = () => {
/*
* useInitializeEscrow
*/
const { deployEscrow } = useInitializeEscrow();
/*
* useSendTransaction
*/
const { sendTransaction } = useSendTransaction();
/*
* onSubmit function, this could be called by form button
*/
const onSubmit = async (payload: InitializeEscrowPayload) => {
try {
/**
* API call by using the trustless work hooks
* @Note:
* - We need to pass the payload to the deployEscrow function
* - The result will be an unsigned transaction
*/
const { unsignedTransaction } = await deployEscrow(
payload,
"single-release" // or "multi-release"
);
if (!unsignedTransaction) {
throw new Error(
"Unsigned transaction is missing from deployEscrow response."
);
}
/**
* @Note:
* - We need to sign the transaction using your [private key] such as wallet
* - The result will be a signed transaction
*/
const signedXdr = await signTransaction({ / This method should be provided by the wallet /
unsignedTransaction,
address: walletAddress || "",
});
if (!signedXdr) {
throw new Error("Signed transaction is missing.");
}
/**
* @Note:
* - We need to send the signed transaction to the API
* - The data will be an SendTransactionResponse
*/
const data = await sendTransaction(signedXdr);
/**
* @Responses:
* data.status === "SUCCESS"
* - Escrow updated successfully
* - Show a success toast
*
* data.status == "ERROR"
* - Show an error toast
*/
if (data.status === "SUCCESS") {
toast.success("Escrow Created");
}
} catch (error: unknown) {
// catch error logic
}
};
}
``
|
Tech Rebel | Product Manager techrebelgit Telegram |
Joel Vargas | Frontend Developer JoelVR17 Telegram |
Armando Murillo | Full Stack Developer armandocodecr Telegram |
Caleb Loría | Smart Contract Developer zkCaleb-dev Telegram |