Skip to content

Trustless-Work/react-library-trustless-work-blocks

BranchesTags

Folders and files

NameName
Last commit message
Last commit date

Latest commit

 

History

217 Commits
bin
bin
 
 
templates
templates
 
 
README.md
README.md
 
 
package.json
package.json
 
 

Repository files navigation

Trustless Work Blocks

Trustless Work React Blocks

Production‑ready React blocks for integrating Trustless Work's escrow and dispute resolution flows into your dApp.

It includes:

  • UI blocks (cards, tables, dialogs, forms) to list and manage escrows
  • Providers for API config, wallet context, dialogs and amount calculations
  • TanStack Query hooks for fetching and mutating escrows
  • Wallet‑kit helpers and error handling utilities

Requirements

  • Node.js >= 18.17
  • React 18 / Next.js 13+ (App Router recommended)

Installation

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

# Then run the CLI to scaffold UI and providers
npx trustless-work init

What init does:

  • Installs shadcn/ui components (prompted)
  • Installs required deps: @tanstack/react-query, @trustless-work/escrow, axios, zod, react-hook-form, @creit.tech/stellar-wallets-kit, react-day-picker, etc.
  • Creates .twblocks.json with your UI base alias (default: "@/components/ui")
  • Optionally wires providers into your Next.js app/layout.tsx

Environment:

  • Create NEXT_PUBLIC_API_KEY in your env. The library uses TrustlessWorkProvider with the development base URL by default.

For a full walkthrough and screenshots, check the tutorial at the backoffice landing.

Quick Start

  1. Initialize
npx trustless-work init
  1. Add providers (if you skipped wiring during init)
npx trustless-work add providers
  1. Wrap your Next.js layout
// app/layout.tsx
import { ReactQueryClientProvider } from "@/components/tw-blocks/providers/ReactQueryClientProvider";
import { TrustlessWorkProvider } from "@/components/tw-blocks/providers/TrustlessWork";
import { EscrowProvider } from "@/components/tw-blocks/providers/EscrowProvider";
import { WalletProvider } from "@/components/tw-blocks/wallet-kit/WalletProvider";

export default function RootLayout({
  children,
}: {
  children: React.ReactNode;
}) {
  return (
    <html lang="en">
      <body>
        <ReactQueryClientProvider>
          <TrustlessWorkProvider>
            <WalletProvider>
              <EscrowProvider>{children}</EscrowProvider>
            </WalletProvider>
          </TrustlessWorkProvider>
        </ReactQueryClientProvider>
      </body>
    </html>
  );
}
  1. Add a wallet button to your header
npx trustless-work add wallet-kit
// Example usage
import { WalletButton } from "@/components/tw-blocks/wallet-kit/WalletButtons";

export function Header() {
  return (
    <div className="flex justify-end p-4">
      <WalletButton />
    </div>
  );
}
  1. List escrows quickly
# By role
npx trustless-work add escrows/escrows-by-role/cards
# Or table view
npx trustless-work add escrows/escrows-by-role/table
// app/escrows/page.tsx
import { EscrowsByRoleCards } from "@/components/tw-blocks/escrows/escrows-by-role/cards/EscrowsCards";
import { EscrowDialogsProvider } from "@/components/tw-blocks/providers/EscrowDialogsProvider";

export default function Page() {
  return (
    <EscrowDialogsProvider>
      <EscrowsByRoleCards />
    </EscrowDialogsProvider>
  );
}

State Management Integration

This library works with any state solution. It exposes React Context providers and TanStack Query hooks. You can also integrate the hooks into Redux/Zustand if needed.

With TanStack Query (Recommended)

// Fetch escrows by role
import { useEscrowsByRoleQuery } from "@/components/tw-blocks/tanstack/useEscrowsByRoleQuery";

export function MyEscrows({ roleAddress }: { roleAddress: string }) {
  const { data, isLoading, isError, refetch } = useEscrowsByRoleQuery({
    role: "approver",
    roleAddress,
    isActive: true,
    validateOnChain: true,
    page: 1,
    orderBy: "createdAt",
    orderDirection: "desc",
  });

  if (isLoading) return <p>Loading…</p>;
  if (isError) return <button onClick={() => refetch()}>Retry</button>;
  return <pre>{JSON.stringify(data, null, 2)}</pre>;
}

// Mutations (deploy/fund/update/approve/change-status/release/dispute/resolve)
import { useEscrowsMutations } from "@/components/tw-blocks/tanstack/useEscrowsMutations";

export function DeployButton({ address }: { address: string }) {
  const { deployEscrow } = useEscrowsMutations();
  return (
    <button
      onClick={() =>
        deployEscrow.mutate({
          payload: {
            /* InitializeSingleReleaseEscrowPayload */
          },
          type: "single-release",
          address,
        })
      }
    >
      Deploy
    </button>
  );
}

Available Blocks

To discover all available blocks, run:

npx trustless-work list

Scaffold top‑level groups

npx trustless-work add providers
npx trustless-work add wallet-kit
npx trustless-work add handle-errors
npx trustless-work add helpers
npx trustless-work add tanstack
npx trustless-work add escrows

Escrows by role

npx trustless-work add escrows/escrows-by-role
npx trustless-work add escrows/escrows-by-role/table
npx trustless-work add escrows/escrows-by-role/cards

Escrows by signer

npx trustless-work add escrows/escrows-by-signer
npx trustless-work add escrows/escrows-by-signer/table
npx trustless-work add escrows/escrows-by-signer/cards

Escrow details (optional standalone)

npx trustless-work add escrows/details

Single‑release flows

npx trustless-work add escrows/single-release
npx trustless-work add escrows/single-release/initialize-escrow
npx trustless-work add escrows/single-release/approve-milestone
npx trustless-work add escrows/single-release/change-milestone-status
npx trustless-work add escrows/single-release/fund-escrow
npx trustless-work add escrows/single-release/release-escrow
npx trustless-work add escrows/single-release/dispute-escrow
npx trustless-work add escrows/single-release/resolve-dispute
npx trustless-work add escrows/single-release/update-escrow

Escrows UI summary

  • Cards and tables to browse escrows (by role or by signer) with filters, pagination, and sorting
  • Detail dialog with actions gated by roles and escrow flags
  • Dialogs/forms for the single‑release lifecycle (initialize, fund, approve, change status, release, dispute, resolve, update)

Using cards (by role):

import { EscrowDialogsProvider } from "@/components/tw-blocks/providers/EscrowDialogsProvider";
import { EscrowsByRoleCards } from "@/components/tw-blocks/escrows/escrows-by-role/cards/EscrowsCards";

export default function Screen() {
  return (
    <EscrowDialogsProvider>
      <EscrowsByRoleCards />
    </EscrowDialogsProvider>
  );
}

Configuration Checklist

Make sure to:

  1. Set NEXT_PUBLIC_API_KEY and run the app against the correct environment (the provider defaults to development).

  2. Configure your UI base imports. The CLI uses .twblocks.json uiBase to replace __UI_BASE__.
    If your UI alias differs, pass --ui-base:

    npx trustless-work add escrows/escrows-by-role/cards --ui-base "@/components/ui"

  3. Wrap your app with all providers in this order:

    ReactQueryClientProvider → TrustlessWorkProvider → WalletProvider → EscrowProvider

Best Practices

  1. Providers

    • ReactQueryClientProvider: global query cache and devtools.
    • TrustlessWorkProvider: sets API baseURL and apiKey via TrustlessWorkConfig from @trustless-work/escrow.
    • WalletProvider: minimal wallet state (address/name) persisted in localStorage; used by wallet button and mutations.
    • EscrowProvider: holds the currently selected escrow and roles; persisted in localStorage.
    • EscrowDialogsProvider: centralizes dialog open/close state for escrow UI.
    • EscrowAmountProvider: computes receiver/platform/fee splits for releases.

  2. Queries and caching

    • Use provided queries: useEscrowsByRoleQuery, useEscrowsBySignerQuery.
    • All mutations invalidate ['escrows'] automatically.

  3. Error handling

    • Use handleError(error) from handle-errors/handle.ts to map Axios and wallet errors to normalized types (ApiErrorTypes).
    import { handleError } from "@/components/tw-blocks/handle-errors/handle";
try {
  /* ... */
} catch (e) {
  const err = handleError(e as any); /* show toast */
}

  4. Wallet-kit

    • WalletButton opens a modal using @creit.tech/stellar-wallets-kit and stores address/name in WalletProvider.
    • signTransaction({ unsignedTransaction, address }) signs and returns XDR used by mutations.
    • trustlines and trustlineOptions include common assets for testnet/mainnet.

  5. Env and network

    • Use development (default) or mainNet from @trustless-work/escrow in TrustlessWorkProvider.
    • Keep your API key in env and never commit it.

Contributing

We welcome contributions! Please open an issue or pull request in the repository and make sure to follow any existing contributing guidelines.

License

MIT License – see the LICENSE file for details.

Maintainers | Telegram

Owner 1

Tech Rebel | Product Manager

techrebelgit
Telegram 		Owner 2

Joel Vargas | Frontend Developer

JoelVR17
Telegram 		Owner 3

Armando Murillo | Full Stack Developer

armandocodecr
Telegram 		Owner 4

Caleb Loría | Smart Contract Developer

zkCaleb-dev
Telegram

About

An open-source library that makes integrating Trustless Work simple and seamless by using components and blocks.

Resources

Readme
Activity
Custom properties

Stars

1 star

Watchers

0 watching

Forks

0 forks
Report repository

Releases 5

New Wallet Kit Version Latest
Dec 3, 2025
+ 4 releases

Packages

 
 
 

Contributors

Languages