@trustless-work/blocks 0.0.2 → 0.0.3
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- package/README.md +220 -9
- package/package.json +1 -1
package/README.md
CHANGED
|
@@ -1,8 +1,12 @@
|
|
|
1
1
|
<p align="center"> <img src="https://github.com/user-attachments/assets/5b182044-dceb-41f5-acf0-da22dea7c98a" alt="CLR-S (2)"> </p>
|
|
2
2
|
|
|
3
|
-
# Trustless Work <a href="https://www.npmjs.com/package/@trustless-work/
|
|
3
|
+
# Trustless Work <a href="https://www.npmjs.com/package/@trustless-work/blocks" target="_blank">React Library</a>
|
|
4
4
|
|
|
5
|
-
A
|
|
5
|
+
A production-ready set of React blocks for integrating Trustless Work's escrow and dispute resolution flows. It ships:
|
|
6
|
+
- UI blocks (cards/tables/dialogs/forms) to list and manage escrows
|
|
7
|
+
- Providers for API config, wallet context, dialogs and amounts
|
|
8
|
+
- TanStack Query hooks for fetching and mutating escrows
|
|
9
|
+
- Wallet-kit helpers and error handling utilities
|
|
6
10
|
|
|
7
11
|
## Installation
|
|
8
12
|
|
|
@@ -10,20 +14,144 @@ A powerful React library for integrating Trustless Work's escrow and dispute res
|
|
|
10
14
|
npm install @trustless-work/blocks
|
|
11
15
|
# or
|
|
12
16
|
yarn add @trustless-work/blocks
|
|
17
|
+
|
|
18
|
+
# Then run the CLI to scaffold UI and providers
|
|
19
|
+
npx trustless-work init
|
|
13
20
|
```
|
|
14
21
|
|
|
22
|
+
What init does:
|
|
23
|
+
- Installs shadcn/ui components (prompted)
|
|
24
|
+
- Installs required deps: @tanstack/react-query, @trustless-work/escrow, axios, zod, react-hook-form, @creit.tech/stellar-wallets-kit, react-day-picker, etc.
|
|
25
|
+
- Creates .twblocks.json with your UI base alias (default: "@/components/ui")
|
|
26
|
+
- Optionally wires providers into Next.js `app/layout.tsx`
|
|
27
|
+
|
|
28
|
+
Environment:
|
|
29
|
+
- Create `NEXT_PUBLIC_API_KEY` in your env. The library uses `TrustlessWorkProvider` with `development` base URL by default.
|
|
30
|
+
|
|
31
|
+
Tutorial at <a href="https://dapp.trustlesswork.com" target="_blank">backoffice's landing</a>
|
|
32
|
+
|
|
15
33
|
## Quick Start
|
|
16
34
|
|
|
17
|
-
1.
|
|
35
|
+
1. Initialize
|
|
36
|
+
```bash
|
|
37
|
+
npx trustless-work init
|
|
38
|
+
```
|
|
39
|
+
|
|
40
|
+
2. Add providers (if you skipped wiring during init)
|
|
41
|
+
```bash
|
|
42
|
+
npx trustless-work add providers
|
|
43
|
+
```
|
|
44
|
+
|
|
45
|
+
3. Wrap your Next.js layout
|
|
46
|
+
```tsx
|
|
47
|
+
// app/layout.tsx
|
|
48
|
+
import { ReactQueryClientProvider } from "@/components/tw-blocks/providers/ReactQueryClientProvider";
|
|
49
|
+
import { TrustlessWorkProvider } from "@/components/tw-blocks/providers/TrustlessWork";
|
|
50
|
+
import { WalletProvider } from "@/components/tw-blocks/wallet-kit/WalletProvider";
|
|
51
|
+
import { EscrowProvider } from "@/components/tw-blocks/escrows/escrow-context/EscrowProvider";
|
|
52
|
+
|
|
53
|
+
export default function RootLayout({ children }: { children: React.ReactNode }) {
|
|
54
|
+
return (
|
|
55
|
+
<html lang="en">
|
|
56
|
+
<body>
|
|
57
|
+
<ReactQueryClientProvider>
|
|
58
|
+
<TrustlessWorkProvider>
|
|
59
|
+
<WalletProvider>
|
|
60
|
+
<EscrowProvider>
|
|
61
|
+
{children}
|
|
62
|
+
</EscrowProvider>
|
|
63
|
+
</WalletProvider>
|
|
64
|
+
</TrustlessWorkProvider>
|
|
65
|
+
</ReactQueryClientProvider>
|
|
66
|
+
</body>
|
|
67
|
+
</html>
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
```
|
|
71
|
+
|
|
72
|
+
4. Add a wallet button to your header
|
|
73
|
+
```bash
|
|
74
|
+
npx trustless-work add wallet-kit
|
|
75
|
+
```
|
|
76
|
+
```tsx
|
|
77
|
+
// Example usage
|
|
78
|
+
import { WalletButton } from "@/components/tw-blocks/wallet-kit/WalletButtons";
|
|
79
|
+
|
|
80
|
+
export function Header() {
|
|
81
|
+
return (
|
|
82
|
+
<div className="flex justify-end p-4">
|
|
83
|
+
<WalletButton />
|
|
84
|
+
</div>
|
|
85
|
+
);
|
|
86
|
+
}
|
|
87
|
+
```
|
|
88
|
+
|
|
89
|
+
5. List escrows quickly
|
|
90
|
+
```bash
|
|
91
|
+
# By role
|
|
92
|
+
npx trustless-work add escrows/escrows-by-role/cards
|
|
93
|
+
# Or table view
|
|
94
|
+
npx trustless-work add escrows/escrows-by-role/table
|
|
95
|
+
```
|
|
96
|
+
```tsx
|
|
97
|
+
// app/escrows/page.tsx
|
|
98
|
+
import { EscrowsByRoleCards } from "@/components/tw-blocks/escrows/escrows-by-role/cards/EscrowsCards";
|
|
99
|
+
import { EscrowDialogsProvider } from "@/components/tw-blocks/escrows/escrow-context/EscrowDialogsProvider";
|
|
100
|
+
|
|
101
|
+
export default function Page() {
|
|
102
|
+
return (
|
|
103
|
+
<EscrowDialogsProvider>
|
|
104
|
+
<EscrowsByRoleCards />
|
|
105
|
+
</EscrowDialogsProvider>
|
|
106
|
+
);
|
|
107
|
+
}
|
|
108
|
+
```
|
|
18
109
|
|
|
19
110
|
## State Management Integration
|
|
20
111
|
|
|
21
|
-
This library
|
|
112
|
+
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.
|
|
22
113
|
|
|
23
114
|
### With TanStack Query (Recommended)
|
|
24
115
|
|
|
25
116
|
```tsx
|
|
117
|
+
// Fetch escrows by role
|
|
118
|
+
import { useEscrowsByRoleQuery } from "@/components/tw-blocks/tanstak/useEscrowsByRoleQuery";
|
|
119
|
+
|
|
120
|
+
export function MyEscrows({ roleAddress }: { roleAddress: string }) {
|
|
121
|
+
const { data, isLoading, isError, refetch } = useEscrowsByRoleQuery({
|
|
122
|
+
role: "approver",
|
|
123
|
+
roleAddress,
|
|
124
|
+
isActive: true,
|
|
125
|
+
validateOnChain: true,
|
|
126
|
+
page: 1,
|
|
127
|
+
orderBy: "createdAt",
|
|
128
|
+
orderDirection: "desc",
|
|
129
|
+
});
|
|
130
|
+
|
|
131
|
+
if (isLoading) return <p>Loading…</p>;
|
|
132
|
+
if (isError) return <button onClick={() => refetch()}>Retry</button>;
|
|
133
|
+
return <pre>{JSON.stringify(data, null, 2)}</pre>;
|
|
134
|
+
}
|
|
135
|
+
|
|
136
|
+
// Mutations (deploy/fund/update/approve/change-status/release/dispute/resolve)
|
|
137
|
+
import { useEscrowsMutations } from "@/components/tw-blocks/tanstak/useEscrowsMutations";
|
|
26
138
|
|
|
139
|
+
export function DeployButton({ address }: { address: string }) {
|
|
140
|
+
const { deployEscrow } = useEscrowsMutations();
|
|
141
|
+
return (
|
|
142
|
+
<button
|
|
143
|
+
onClick={() =>
|
|
144
|
+
deployEscrow.mutate({
|
|
145
|
+
payload: { /* InitializeSingleReleaseEscrowPayload */ },
|
|
146
|
+
type: "single-release",
|
|
147
|
+
address,
|
|
148
|
+
})
|
|
149
|
+
}
|
|
150
|
+
>
|
|
151
|
+
Deploy
|
|
152
|
+
</button>
|
|
153
|
+
);
|
|
154
|
+
}
|
|
27
155
|
```
|
|
28
156
|
|
|
29
157
|
## Available Blocks
|
|
@@ -31,18 +159,101 @@ This library is designed to be flexible and work with any state management solut
|
|
|
31
159
|
In order to see all of them, just run this script:
|
|
32
160
|
|
|
33
161
|
```shell
|
|
34
|
-
|
|
162
|
+
|
|
163
|
+
npx trustless-work list
|
|
164
|
+
|
|
165
|
+
# Scaffold top-level groups
|
|
166
|
+
npx trustless-work add providers
|
|
167
|
+
npx trustless-work add wallet-kit
|
|
168
|
+
npx trustless-work add handle-errors
|
|
169
|
+
npx trustless-work add helpers
|
|
170
|
+
npx trustless-work add tanstak
|
|
171
|
+
npx trustless-work add escrows
|
|
172
|
+
|
|
173
|
+
# Escrow context providers
|
|
174
|
+
npx trustless-work add escrows/escrow-context
|
|
175
|
+
|
|
176
|
+
# Escrows by role
|
|
177
|
+
npx trustless-work add escrows/escrows-by-role
|
|
178
|
+
npx trustless-work add escrows/escrows-by-role/table
|
|
179
|
+
npx trustless-work add escrows/escrows-by-role/cards
|
|
180
|
+
|
|
181
|
+
# Escrows by signer
|
|
182
|
+
npx trustless-work add escrows/escrows-by-signer
|
|
183
|
+
npx trustless-work add escrows/escrows-by-signer/table
|
|
184
|
+
npx trustless-work add escrows/escrows-by-signer/cards
|
|
185
|
+
|
|
186
|
+
# Escrow details (optional standalone)
|
|
187
|
+
npx trustless-work add escrows/details
|
|
188
|
+
|
|
189
|
+
# Single-release flows
|
|
190
|
+
npx trustless-work add escrows/single-release
|
|
191
|
+
npx trustless-work add escrows/single-release/initialize-escrow
|
|
192
|
+
npx trustless-work add escrows/single-release/approve-milestone
|
|
193
|
+
npx trustless-work add escrows/single-release/change-milestone-status
|
|
194
|
+
npx trustless-work add escrows/single-release/fund-escrow
|
|
195
|
+
npx trustless-work add escrows/single-release/release-escrow
|
|
196
|
+
npx trustless-work add escrows/single-release/dispute-escrow
|
|
197
|
+
npx trustless-work add escrows/single-release/resolve-dispute
|
|
198
|
+
npx trustless-work add escrows/single-release/update-escrow
|
|
35
199
|
```
|
|
36
200
|
|
|
37
|
-
###
|
|
38
|
-
-
|
|
201
|
+
### Escrows
|
|
202
|
+
- Cards and tables to browse escrows (by role or by signer) with filters, pagination, and sort
|
|
203
|
+
- Detail dialog with actions gated by roles and escrow flags
|
|
204
|
+
- Dialogs/forms for single-release lifecycle (initialize, fund, approve, change status, release, dispute, resolve, update)
|
|
205
|
+
|
|
206
|
+
Using cards (by role):
|
|
207
|
+
```tsx
|
|
208
|
+
import { EscrowDialogsProvider } from "@/components/tw-blocks/escrows/escrow-context/EscrowDialogsProvider";
|
|
209
|
+
import { EscrowsByRoleCards } from "@/components/tw-blocks/escrows/escrows-by-role/cards/EscrowsCards";
|
|
210
|
+
|
|
211
|
+
export default function Screen() {
|
|
212
|
+
return (
|
|
213
|
+
<EscrowDialogsProvider>
|
|
214
|
+
<EscrowsByRoleCards />
|
|
215
|
+
</EscrowDialogsProvider>
|
|
216
|
+
);
|
|
217
|
+
}
|
|
218
|
+
```
|
|
39
219
|
|
|
40
220
|
Make sure to:
|
|
41
|
-
1.
|
|
221
|
+
1. Set `NEXT_PUBLIC_API_KEY` and run the app against the correct environment (the provider defaults to `development`).
|
|
222
|
+
2. Configure your UI base imports. CLI uses `.twblocks.json` `uiBase` to replace `__UI_BASE__`. If your UI alias differs, pass `--ui-base`:
|
|
223
|
+
```bash
|
|
224
|
+
npx trustless-work add escrows/escrows-by-role/cards --ui-base "@/components/ui"
|
|
225
|
+
```
|
|
226
|
+
3. Wrap your app with all providers in the order: `ReactQueryClientProvider` → `TrustlessWorkProvider` → `WalletProvider` → `EscrowProvider`.
|
|
42
227
|
|
|
43
228
|
## Best Practices
|
|
44
229
|
|
|
45
|
-
1.
|
|
230
|
+
1. Providers
|
|
231
|
+
- `ReactQueryClientProvider`: global query cache and devtools.
|
|
232
|
+
- `TrustlessWorkProvider`: sets API `baseURL` and `apiKey` via `TrustlessWorkConfig` from `@trustless-work/escrow`.
|
|
233
|
+
- `WalletProvider`: minimal wallet state (address/name) persisted in localStorage; used by wallet button and mutations.
|
|
234
|
+
- `EscrowProvider`: holds the currently selected escrow and roles; persisted in localStorage.
|
|
235
|
+
- `EscrowDialogsProvider`: centralizes dialog open/close state for escrow UI.
|
|
236
|
+
- `EscrowAmountProvider`: computes receiver/platform/fee splits for releases.
|
|
237
|
+
|
|
238
|
+
2. Queries and caching
|
|
239
|
+
- Use provided queries: `useEscrowsByRoleQuery`, `useEscrowsBySignerQuery`.
|
|
240
|
+
- All mutations invalidate `['escrows']` automatically.
|
|
241
|
+
|
|
242
|
+
3. Error handling
|
|
243
|
+
- Use `handleError(error)` from `handle-errors/handle.ts` to map Axios and wallet errors to normalized types (`ApiErrorTypes`).
|
|
244
|
+
```ts
|
|
245
|
+
import { handleError } from "@/components/tw-blocks/handle-errors/handle";
|
|
246
|
+
try { /* ... */ } catch (e) { const err = handleError(e as any); /* show toast */ }
|
|
247
|
+
```
|
|
248
|
+
|
|
249
|
+
4. Wallet-kit
|
|
250
|
+
- `WalletButton` opens a modal using `@creit.tech/stellar-wallets-kit` and stores address/name in `WalletProvider`.
|
|
251
|
+
- `signTransaction({ unsignedTransaction, address })` signs and returns XDR used by mutations.
|
|
252
|
+
- `trustlines` and `trustlineOptions` include common assets for testnet/mainnet.
|
|
253
|
+
|
|
254
|
+
5. Env and network
|
|
255
|
+
- Use `development` (default) or `mainNet` from `@trustless-work/escrow` in `TrustlessWorkProvider`.
|
|
256
|
+
- Keep your API key in env and never commit it.
|
|
46
257
|
|
|
47
258
|
## Contributing
|
|
48
259
|
|