@trustless-work/escrow

Trustless Work React Library

A powerful React library for integrating Trustless Work's escrow and dispute resolution system into your applications. This library provides a set of React hooks and utilities to interact with the Trustless Work API.

Installation

npm install @trustless-work/escrow
# or
yarn add @trustless-work/escrow

Quick Start

• 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.

"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 (
    <TrustlessWorkConfig baseURL={development} apiKey={apiKey}>
      {children}
    </TrustlessWorkConfig>
  );
}

• Wrap your app in the provider

import { TrustlessWorkProvider} from "@/trustless-work-provider.tsx";
 
export function App() {
  return (
    <TrustlessWorkProvider>
      <YourApp />
    </TrustlessWorkProvider>
  );
}

• Use the hooks in your components:

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.

With TanStack Query (Recommended)

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 (
    <QueryClientProvider client={queryClient}>
      <TrustlessWorkConfig baseURL={development} apiKey={apiKey}>
        <YourApp />
      </TrustlessWorkConfig>
    </QueryClientProvider>
  );
}

// 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,
  });
};

With Zustand

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

Escrow Management

• 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

Dispute Resolution

• useStartDispute: Initiate a dispute
• useResolveDispute: Resolve an existing dispute

Milestone Management

• useChangeMilestoneStatus: Update milestone status
• useApproveMilestone: Approve or reject milestones

Transaction Management

• useSendTransaction: Send a transaction

Data Fetching

• 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:

• Use the correct baseURL for your environment
• Store your API key in environment variables
• Use the appropriate API key for your environment
• 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

• State Management: Choose the state management solution that best fits your project needs
• Error Handling: Implement proper error handling for all API calls
• Loading States: Use loading states to provide better user experience
• Type Safety: Take advantage of TypeScript types for better development experience
• API Key Security: Never expose your API key in client-side code. Use environment variables
• Caching: Implement appropriate caching strategies for better performance

Example Usage

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
    }
  };
}

Contributing

We welcome contributions! Please read our contributing guidelines before submitting pull requests.

License

MIT License - see LICENSE file for details

Maintainers | Telegram

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