@tetsuo-ai/marketplace-react 0.4.0 → 0.5.0

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.
Files changed (88) hide show
  1. package/CHANGELOG.md +78 -0
  2. package/README.md +93 -47
  3. package/dist/chunk-7NKRSPPN.js +227 -0
  4. package/dist/chunk-7NKRSPPN.js.map +1 -0
  5. package/dist/{chunk-BNILOX3O.js → chunk-CDDHUFMG.js} +38 -6
  6. package/dist/chunk-CDDHUFMG.js.map +1 -0
  7. package/dist/chunk-FIDFPM5A.cjs +40 -0
  8. package/dist/chunk-FIDFPM5A.cjs.map +1 -0
  9. package/dist/chunk-IJKWKY4H.cjs +1370 -0
  10. package/dist/chunk-IJKWKY4H.cjs.map +1 -0
  11. package/dist/chunk-JTSG5FGC.cjs +397 -0
  12. package/dist/chunk-JTSG5FGC.cjs.map +1 -0
  13. package/dist/chunk-ONC6L3IX.cjs +97 -0
  14. package/dist/chunk-ONC6L3IX.cjs.map +1 -0
  15. package/dist/chunk-R76EUYDI.cjs +233 -0
  16. package/dist/chunk-R76EUYDI.cjs.map +1 -0
  17. package/dist/chunk-RG5JZ6JL.js +378 -0
  18. package/dist/chunk-RG5JZ6JL.js.map +1 -0
  19. package/dist/components/index.cjs +158 -1513
  20. package/dist/components/index.cjs.map +1 -1
  21. package/dist/components/index.d.cts +2 -2
  22. package/dist/components/index.d.ts +2 -2
  23. package/dist/components/index.js +2 -2
  24. package/dist/hooks/index.cjs +693 -457
  25. package/dist/hooks/index.cjs.map +1 -1
  26. package/dist/hooks/index.d.cts +109 -28
  27. package/dist/hooks/index.d.ts +109 -28
  28. package/dist/hooks/index.js +659 -178
  29. package/dist/hooks/index.js.map +1 -1
  30. package/dist/{index-DQ3Xovkq.d.ts → index-BAyr1ODZ.d.ts} +76 -6
  31. package/dist/{index-UxuvIlmD.d.cts → index-C20NVU7_.d.cts} +76 -6
  32. package/dist/index.cjs +284 -1752
  33. package/dist/index.cjs.map +1 -1
  34. package/dist/index.d.cts +7 -8
  35. package/dist/index.d.ts +7 -8
  36. package/dist/index.js +64 -4
  37. package/dist/index.js.map +1 -1
  38. package/dist/signers/index.cjs +22 -161
  39. package/dist/signers/index.cjs.map +1 -1
  40. package/dist/signers/index.d.cts +16 -11
  41. package/dist/signers/index.d.ts +16 -11
  42. package/dist/signers/index.js +1 -1
  43. package/dist/testing/index.d.cts +1 -1
  44. package/dist/testing/index.d.ts +1 -1
  45. package/dist/theme/agenc-tailwind-preset.cjs +134 -108
  46. package/dist/{types-jvISR6bc.d.cts → types-B10rndEI.d.cts} +16 -7
  47. package/dist/{types-jvISR6bc.d.ts → types-B10rndEI.d.ts} +16 -7
  48. package/dist/{useAgentTrackRecord-BCvRHYM2.d.cts → useAgentTrackRecord-Ch7gHTFj.d.cts} +40 -3
  49. package/dist/{useAgentTrackRecord-BCvRHYM2.d.ts → useAgentTrackRecord-Ch7gHTFj.d.ts} +40 -3
  50. package/package.json +6 -3
  51. package/src/components/GuaranteedBadge.tsx +73 -0
  52. package/src/components/HireCheckoutModal.tsx +5 -2
  53. package/src/components/index.ts +4 -0
  54. package/src/components/strings.ts +8 -0
  55. package/src/hooks/index.ts +14 -0
  56. package/src/hooks/internal.ts +179 -22
  57. package/src/hooks/useAgentTrackRecord.ts +5 -2
  58. package/src/hooks/useCompletionBond.ts +191 -0
  59. package/src/hooks/useDispute.ts +46 -9
  60. package/src/hooks/useHire.ts +113 -23
  61. package/src/hooks/useHumanlessHireFlow.ts +335 -115
  62. package/src/hooks/useListing.ts +2 -2
  63. package/src/hooks/useListings.ts +2 -2
  64. package/src/hooks/useRateHire.ts +32 -5
  65. package/src/hooks/useReferrerEarnings.ts +4 -1
  66. package/src/hooks/useSubmissionReview.ts +95 -32
  67. package/src/hooks/useTaskActivation.ts +51 -9
  68. package/src/hooks/useTaskGuarantee.ts +123 -0
  69. package/src/hooks/useTaskLifecycle.ts +104 -24
  70. package/src/hooks/useTaskStatus.ts +121 -26
  71. package/src/hooks/useTaskWork.ts +76 -12
  72. package/src/hooks/useWalletSigner.ts +11 -16
  73. package/src/index.ts +5 -0
  74. package/src/provider/AgencProvider.tsx +95 -3
  75. package/src/provider/referrer.ts +1 -1
  76. package/src/signers/README.md +13 -7
  77. package/src/signers/index.ts +6 -1
  78. package/src/signers/strings.ts +13 -1
  79. package/src/signers/types.ts +16 -5
  80. package/src/signers/wallet-account.ts +115 -29
  81. package/src/signers/wallet-adapter.ts +38 -4
  82. package/src/theme/agenc-tailwind-preset.cjs +134 -108
  83. package/src/types.ts +32 -3
  84. package/dist/chunk-BNILOX3O.js.map +0 -1
  85. package/dist/chunk-BTAVED7S.js +0 -226
  86. package/dist/chunk-BTAVED7S.js.map +0 -1
  87. package/dist/chunk-ON6XR4XO.js +0 -128
  88. package/dist/chunk-ON6XR4XO.js.map +0 -1
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@tetsuo-ai/marketplace-react",
3
- "version": "0.4.0",
3
+ "version": "0.5.0",
4
4
  "description": "Headless React hooks + themable components for the AgenC marketplace — provider, indexer-first read transport, and live referrer config",
5
5
  "type": "module",
6
6
  "main": "./dist/index.cjs",
@@ -79,6 +79,7 @@
79
79
  "build": "tsup",
80
80
  "typecheck": "tsc --noEmit",
81
81
  "test": "vitest run",
82
+ "test:localnet": "AGENC_REACT_LOCALNET_E2E=1 vitest run test/playwright/checkout.e2e.test.tsx",
82
83
  "test:watch": "vitest",
83
84
  "prepack": "npm run build",
84
85
  "ladle": "ladle serve",
@@ -87,7 +88,7 @@
87
88
  "peerDependencies": {
88
89
  "@solana/kit": "^6.9.0",
89
90
  "@solana/program-client-core": "^6.4.0",
90
- "@tetsuo-ai/marketplace-sdk": "^0.8.0",
91
+ "@tetsuo-ai/marketplace-sdk": "^0.12.0",
91
92
  "react": ">=18"
92
93
  },
93
94
  "dependencies": {
@@ -104,8 +105,10 @@
104
105
  "@types/react-dom": "^18.3.1",
105
106
  "axe-core": "^4.12.0",
106
107
  "jsdom": "^25.0.1",
108
+ "postcss": "8.5.20",
107
109
  "react": "^18.3.1",
108
110
  "react-dom": "^18.3.1",
111
+ "tailwindcss": "3.4.19",
109
112
  "tsup": "8.5.1",
110
113
  "typescript": "5.9.3",
111
114
  "vitest": "4.1.8",
@@ -135,6 +138,6 @@
135
138
  ],
136
139
  "author": "Tetsuo AI",
137
140
  "engines": {
138
- "node": ">=20.18.0"
141
+ "node": ">=22.23.1"
139
142
  }
140
143
  }
@@ -0,0 +1,73 @@
1
+ /**
2
+ * `<GuaranteedBadge task={...} />` — the Guaranteed Hire badge (WP-H3).
3
+ *
4
+ * Renders NOTHING unless the task is guaranteed (a live worker completion
5
+ * bond: the worker staked 25% of the reward on passing review). When it is,
6
+ * shows a small success-tone badge with plain-English copy; the full detail
7
+ * sentence rides on `title`/`aria-label`.
8
+ *
9
+ * Connected by default: given `task`, it reads through {@link useTaskGuarantee}
10
+ * (provider `rpcUrl` gPA read, or the `guaranteeReader` seam). Pass a
11
+ * pre-resolved `guarantee` to use it presentationally (no read at all) — an
12
+ * explicit `guarantee` (including `null`) wins over the `task` read.
13
+ *
14
+ * HONEST BOUNDARY (phase 1): the copy says the buyer is refunded and the
15
+ * worker FORFEITS the bond — it deliberately does NOT promise the buyer the
16
+ * bond itself, because a forfeited bond pays the protocol treasury until
17
+ * phase 2 redirects it to the harmed party. Keep host copy within that line.
18
+ *
19
+ * @module components/GuaranteedBadge
20
+ */
21
+ import type { ReactNode } from "react";
22
+ import type { TaskGuarantee } from "@tetsuo-ai/marketplace-sdk";
23
+ import {
24
+ useTaskGuarantee,
25
+ type TaskGuaranteeReader,
26
+ } from "../hooks/useTaskGuarantee.js";
27
+ import type { Address } from "../types.js";
28
+ import { tc } from "./format.js";
29
+ import { Badge, type ThemableProps } from "./primitives.js";
30
+
31
+ /** Props for {@link GuaranteedBadge}. */
32
+ export interface GuaranteedBadgeProps extends ThemableProps {
33
+ /** The Task PDA to read the guarantee for (connected mode). */
34
+ task?: Address | string | null;
35
+ /**
36
+ * Pre-resolved guarantee state (presentational mode — overrides the `task`
37
+ * read entirely; pass `null` for a known-unguaranteed task).
38
+ */
39
+ guarantee?: TaskGuarantee | null;
40
+ /** Injected reader seam forwarded to {@link useTaskGuarantee} (tests/litesvm). */
41
+ guaranteeReader?: TaskGuaranteeReader;
42
+ }
43
+
44
+ /**
45
+ * Show that a task's result is backed by the worker's 25% completion bond.
46
+ * Renders nothing while loading, on read errors, and for unguaranteed tasks —
47
+ * the badge only ever ASSERTS a live guarantee, never its absence.
48
+ */
49
+ export function GuaranteedBadge({
50
+ task,
51
+ guarantee,
52
+ guaranteeReader,
53
+ unstyled,
54
+ className,
55
+ }: GuaranteedBadgeProps): ReactNode {
56
+ const overridden = guarantee !== undefined;
57
+ const read = useTaskGuarantee(overridden ? null : task, {
58
+ guaranteeReader,
59
+ enabled: !overridden,
60
+ });
61
+ const resolved = overridden ? guarantee : read.guarantee;
62
+ if (!resolved?.guaranteed) return null;
63
+ return (
64
+ <Badge
65
+ tone="success"
66
+ unstyled={unstyled}
67
+ className={className}
68
+ label={tc("components.guarantee.detail")}
69
+ >
70
+ {tc("components.guarantee.badge")}
71
+ </Badge>
72
+ );
73
+ }
@@ -152,10 +152,13 @@ export function HireCheckoutModal({
152
152
  return;
153
153
  }
154
154
  if (result && typeof (result as Promise<void>).then === "function") {
155
- void (result as Promise<void>).finally(() => {
155
+ const releaseLatch = () => {
156
156
  submittingRef.current = false;
157
157
  setSubmitting(false);
158
- });
158
+ };
159
+ // `finally()` creates a second rejected promise when onConfirm rejects.
160
+ // Both handlers below return void, so this discarded chain fulfills.
161
+ void Promise.resolve(result).then(releaseLatch, releaseLatch);
159
162
  }
160
163
  // For a synchronous (void) onConfirm the parent drives `status`; the effect
161
164
  // above clears the latch when it reaches a terminal/closed state.
@@ -45,6 +45,10 @@ export {
45
45
  type ModerationState,
46
46
  type VerifiedBadgeProps,
47
47
  } from "./badges.js";
48
+ export {
49
+ GuaranteedBadge,
50
+ type GuaranteedBadgeProps,
51
+ } from "./GuaranteedBadge.js";
48
52
 
49
53
  // Presentational formatting helpers + the component string resolver.
50
54
  export {
@@ -120,6 +120,14 @@ export const EN_COMPONENT_STRINGS = {
120
120
  "components.provider.claimedDomainLabel":
121
121
  "Claimed domain {domain} (not verified on-chain)",
122
122
 
123
+ // GuaranteedBadge (WP-H3 Guaranteed Hire). The detail copy is deliberately
124
+ // phase-1-honest: the buyer is refunded (escrow) and the worker FORFEITS the
125
+ // bond — it does NOT say the buyer receives the bond, because a forfeited
126
+ // bond pays the protocol treasury until phase 2 redirects it.
127
+ "components.guarantee.badge": "Guaranteed — worker has 25% at stake",
128
+ "components.guarantee.detail":
129
+ "Worker has 25% at stake — if the result fails review you're refunded and the worker forfeits the bond.",
130
+
123
131
  // PoweredByAgenC.
124
132
  "components.poweredBy.label": "Powered by AgenC",
125
133
  "components.poweredBy.trustLink": "Learn how this works",
@@ -38,10 +38,17 @@ export {
38
38
  useTaskStatus,
39
39
  type ObservedEvent,
40
40
  type TaskEventsSource,
41
+ type TaskEventsSourceFactory,
41
42
  type TaskReader,
42
43
  type UseTaskStatusOptions,
43
44
  type UseTaskStatusResult,
44
45
  } from "./useTaskStatus.js";
46
+ export {
47
+ useTaskGuarantee,
48
+ type TaskGuaranteeReader,
49
+ type UseTaskGuaranteeOptions,
50
+ type UseTaskGuaranteeResult,
51
+ } from "./useTaskGuarantee.js";
45
52
 
46
53
  // Writes
47
54
  export {
@@ -113,6 +120,13 @@ export {
113
120
  type UseDisputeOptions,
114
121
  type UseDisputeResult,
115
122
  } from "./useDispute.js";
123
+ export {
124
+ useCompletionBond,
125
+ type CompletionBondStatus,
126
+ type PostCompletionBondInput,
127
+ type ReclaimCompletionBondInput,
128
+ type UseCompletionBondResult,
129
+ } from "./useCompletionBond.js";
116
130
 
117
131
  // Wallet bridge
118
132
  export {
@@ -11,6 +11,7 @@
11
11
  *
12
12
  * @module hooks/internal
13
13
  */
14
+ import { stabilizeTransactionSigner } from "@tetsuo-ai/marketplace-sdk";
14
15
  import { t } from "../strings/index.js";
15
16
  import type {
16
17
  Address,
@@ -22,10 +23,18 @@ import type {
22
23
  /** Root namespace for every cache key this package writes. */
23
24
  export const QUERY_KEY_ROOT = "agenc" as const;
24
25
 
26
+ /** Namespace used only by direct callers that omit deployment identity. */
27
+ export const DEFAULT_QUERY_CACHE_NAMESPACE = "default" as const;
28
+
29
+ function queryRoot(cacheNamespace: string) {
30
+ return [QUERY_KEY_ROOT, cacheNamespace] as const;
31
+ }
32
+
25
33
  /**
26
34
  * Stable, hierarchical TanStack Query keys. Hooks build their keys ONLY through
27
- * this factory so a consumer (or a hook) can invalidate a whole sub-tree
28
- * (`["agenc", "listings"]`) or one entity (`["agenc", "listing", pda]`).
35
+ * this factory so a consumer (or a hook) can invalidate a deployment sub-tree
36
+ * (`["agenc", namespace, "listings"]`) or one entity
37
+ * (`["agenc", namespace, "listing", pda]`).
29
38
  *
30
39
  * `JSON.stringify` is intentionally NOT used — TanStack compares keys
31
40
  * structurally, so passing the raw filter object keeps equality correct for
@@ -33,21 +42,40 @@ export const QUERY_KEY_ROOT = "agenc" as const;
33
42
  */
34
43
  export const queryKeys = {
35
44
  /** All listings list queries (with their filter object as the leaf). */
36
- listings: (filter?: unknown) =>
37
- [QUERY_KEY_ROOT, "listings", filter ?? null] as const,
45
+ listings: (
46
+ filter?: unknown,
47
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
48
+ ) => [...queryRoot(cacheNamespace), "listings", filter ?? null] as const,
38
49
  /** One listing + its joined provider/track-record/moderation. */
39
- listing: (pda: string) => [QUERY_KEY_ROOT, "listing", pda] as const,
50
+ listing: (
51
+ pda: string,
52
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
53
+ ) => [...queryRoot(cacheNamespace), "listing", pda] as const,
40
54
  /** One agent's indexer track record. */
41
- agentTrackRecord: (agentPda: string) =>
42
- [QUERY_KEY_ROOT, "agentTrackRecord", agentPda] as const,
55
+ agentTrackRecord: (
56
+ agentPda: string,
57
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
58
+ ) => [...queryRoot(cacheNamespace), "agentTrackRecord", agentPda] as const,
43
59
  /** One task's status (read via transport / svm decode). */
44
- taskStatus: (taskPda: string) =>
45
- [QUERY_KEY_ROOT, "taskStatus", taskPda] as const,
60
+ taskStatus: (
61
+ taskPda: string,
62
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
63
+ ) => [...queryRoot(cacheNamespace), "taskStatus", taskPda] as const,
46
64
  /** One task's dispute record. */
47
- dispute: (taskPda: string) => [QUERY_KEY_ROOT, "dispute", taskPda] as const,
65
+ dispute: (
66
+ taskPda: string,
67
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
68
+ ) => [...queryRoot(cacheNamespace), "dispute", taskPda] as const,
69
+ /** One task's completion-bond ("Guaranteed Hire") state. */
70
+ taskGuarantee: (
71
+ taskPda: string,
72
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
73
+ ) => [...queryRoot(cacheNamespace), "taskGuarantee", taskPda] as const,
48
74
  /** One referrer wallet's earnings (indexer-gated; see useReferrerEarnings). */
49
- referrerEarnings: (wallet: string) =>
50
- [QUERY_KEY_ROOT, "referrerEarnings", wallet] as const,
75
+ referrerEarnings: (
76
+ wallet: string,
77
+ cacheNamespace: string = DEFAULT_QUERY_CACHE_NAMESPACE,
78
+ ) => [...queryRoot(cacheNamespace), "referrerEarnings", wallet] as const,
51
79
  } as const;
52
80
 
53
81
  /**
@@ -113,21 +141,150 @@ export function resolveReferrerArgs(
113
141
  };
114
142
  }
115
143
 
116
- export type SignerOrAddress = TransactionSigner | Address;
144
+ /**
145
+ * Detach one on-chain fixed-byte value from caller-owned mutable storage.
146
+ * Validation happens synchronously at the hook's public enqueue boundary so a
147
+ * later TanStack/SDK await can never observe a different byte sequence.
148
+ */
149
+ export function snapshotFixedBytes32(
150
+ value: unknown,
151
+ label: string,
152
+ ): Uint8Array {
153
+ return snapshotFixedBytes(value, 32, label);
154
+ }
155
+
156
+ function snapshotFixedBytes(
157
+ value: unknown,
158
+ byteLength: number,
159
+ label: string,
160
+ ): Uint8Array {
161
+ if (
162
+ !isExactUint8Array(value) ||
163
+ typedArrayByteLengthGetter?.call(value) !== byteLength ||
164
+ !hasOrdinaryArrayBuffer(value)
165
+ ) {
166
+ throw new TypeError(`${label} must be exactly ${byteLength} bytes`);
167
+ }
168
+ return new Uint8Array(value);
169
+ }
170
+
171
+ const typedArrayPrototype = Object.getPrototypeOf(Uint8Array.prototype);
172
+ const typedArrayTagGetter = Object.getOwnPropertyDescriptor(
173
+ typedArrayPrototype,
174
+ Symbol.toStringTag,
175
+ )?.get;
176
+ const typedArrayByteLengthGetter = Object.getOwnPropertyDescriptor(
177
+ typedArrayPrototype,
178
+ "byteLength",
179
+ )?.get;
180
+ const typedArrayBufferGetter = Object.getOwnPropertyDescriptor(
181
+ typedArrayPrototype,
182
+ "buffer",
183
+ )?.get;
184
+ const arrayBufferByteLengthGetter = Object.getOwnPropertyDescriptor(
185
+ ArrayBuffer.prototype,
186
+ "byteLength",
187
+ )?.get;
188
+
189
+ /**
190
+ * Recognize the SDK's exact byte-view contract across browser/worker realms.
191
+ * `instanceof` is realm-local and `Object#toString` honors a spoofable own
192
+ * `Symbol.toStringTag`. Calling the shared `%TypedArray%` intrinsic getter
193
+ * directly performs the unforgeable typed-array-kind check across realms.
194
+ */
195
+ function isExactUint8Array(value: unknown): value is Uint8Array {
196
+ return (
197
+ ArrayBuffer.isView(value) &&
198
+ typedArrayTagGetter?.call(value) === "Uint8Array"
199
+ );
200
+ }
201
+
202
+ /** Shared backing can change concurrently and cannot yield one coherent hash. */
203
+ function hasOrdinaryArrayBuffer(value: Uint8Array): boolean {
204
+ try {
205
+ const buffer = typedArrayBufferGetter?.call(value);
206
+ return (
207
+ buffer !== undefined &&
208
+ typeof arrayBufferByteLengthGetter?.call(buffer) === "number"
209
+ );
210
+ } catch {
211
+ // `%ArrayBuffer%.byteLength` rejects SharedArrayBuffer and foreign brands.
212
+ return false;
213
+ }
214
+ }
215
+
216
+ /**
217
+ * Detach a nullable Solana `OptionOrNullable<ReadonlyUint8Array>` while
218
+ * preserving its public representation. Both the convenient nullable form and
219
+ * Kit's explicit `Some`/`None` objects are accepted by generated encoders.
220
+ */
221
+ export function snapshotOptionalFixedBytes<T>(
222
+ value: T,
223
+ byteLength: number,
224
+ label: string,
225
+ ): T {
226
+ if (value === undefined || value === null) return value;
227
+ if (isExactUint8Array(value)) {
228
+ return snapshotFixedBytes(value, byteLength, label) as T;
229
+ }
230
+ if (typeof value !== "object") {
231
+ throw new TypeError(`${label} must be exactly ${byteLength} bytes or None`);
232
+ }
117
233
 
118
- export function signerAddress(signerOrAddress: SignerOrAddress): Address {
119
- if (typeof signerOrAddress === "string") {
120
- return signerOrAddress;
234
+ const option = value as {
235
+ readonly __option?: unknown;
236
+ readonly value?: unknown;
237
+ };
238
+ const tag = option.__option;
239
+ if (tag === "None") {
240
+ return Object.freeze({ __option: "None" }) as T;
121
241
  }
242
+ if (tag === "Some") {
243
+ const bytes = snapshotFixedBytes(option.value, byteLength, label);
244
+ return Object.freeze({ __option: "Some", value: bytes }) as T;
245
+ }
246
+ throw new TypeError(`${label} must be exactly ${byteLength} bytes or None`);
247
+ }
248
+
249
+ /**
250
+ * Copy and freeze one caller-owned record. Callers with nested mutable values
251
+ * must replace those values with their own snapshots before enqueueing.
252
+ */
253
+ export function snapshotRecord<T extends object>(value: T): T {
254
+ return Object.freeze({ ...value }) as T;
255
+ }
256
+
257
+ /** Copy a caller-owned account collection and every known-flat entry. */
258
+ export function snapshotRecordArray<T extends object>(
259
+ value: readonly T[],
260
+ ): readonly T[] {
261
+ return Object.freeze(value.map((entry) => snapshotRecord(entry)));
262
+ }
263
+
264
+ /**
265
+ * Stabilize the fee-payer signer and the exact optional instruction override at
266
+ * the synchronous hook boundary. An override for the fee-payer's canonical
267
+ * address resolves to the fee-payer object because Solana Kit rejects distinct
268
+ * signer implementations for one address. A different-address override keeps
269
+ * its own identity after the SDK guard permanently locks its address. Other
270
+ * stateful wallet/session fields remain usable.
271
+ */
272
+ export function stabilizeSelectedTransactionSigner(
273
+ clientSigner: TransactionSigner,
274
+ override?: TransactionSigner,
275
+ ): TransactionSigner {
276
+ const stableClientSigner = stabilizeTransactionSigner(clientSigner);
122
277
  if (
123
- typeof signerOrAddress === "object" &&
124
- signerOrAddress !== null &&
125
- "address" in signerOrAddress &&
126
- typeof signerOrAddress.address === "string"
278
+ override === undefined ||
279
+ override === stableClientSigner ||
280
+ override.address === stableClientSigner.address
127
281
  ) {
128
- return signerOrAddress.address;
282
+ return stableClientSigner;
129
283
  }
130
- throw new Error("Expected a TransactionSigner or Address with an address field.");
284
+ const stableOverride = stabilizeTransactionSigner(override);
285
+ return stableOverride.address === stableClientSigner.address
286
+ ? stableClientSigner
287
+ : stableOverride;
131
288
  }
132
289
 
133
290
  export function withoutReferrerArgs<T extends object>(
@@ -140,11 +140,14 @@ export function useAgentTrackRecord(
140
140
  agentPda: Address | string | undefined | null,
141
141
  options?: UseAgentTrackRecordOptions,
142
142
  ): UseAgentTrackRecordResult {
143
- const { read } = useAgencContext();
143
+ const { read, cacheNamespace } = useAgencContext();
144
144
  const enabled = (options?.enabled ?? true) && Boolean(agentPda);
145
145
 
146
146
  const query = useQuery<AgentTrackRecord, Error>({
147
- queryKey: queryKeys.agentTrackRecord(agentPda ? pdaKey(agentPda) : ""),
147
+ queryKey: queryKeys.agentTrackRecord(
148
+ agentPda ? pdaKey(agentPda) : "",
149
+ cacheNamespace,
150
+ ),
148
151
  enabled,
149
152
  queryFn: async () => {
150
153
  const raw = await read.agentTrackRecord(agentPda as Address | string);
@@ -0,0 +1,191 @@
1
+ /**
2
+ * `useCompletionBond(taskPda)` — the completion-bond ("Guaranteed Hire")
3
+ * mutations for one task.
4
+ *
5
+ * Two verbs over the write client, each its own mutation (independent
6
+ * pending/error per button, like `useSubmissionReview`):
7
+ * - `post(...)` — post a completion bond (`client.postCompletionBond`). The
8
+ * bond PDA is auto-derived from (task, signing wallet); size is fixed
9
+ * on-chain at 25% of the reward (`BOND_BPS`), SOL-only in v1. A worker
10
+ * posting the role-1 bond is what makes the task read as GUARANTEED.
11
+ * - `reclaim(...)` — the recovery crank (`client.reclaimCompletionBond`) for a
12
+ * bond a settlement left live; refunds to the recorded posting wallet.
13
+ *
14
+ * A successful verb invalidates the task's `useTaskGuarantee` cache entry so
15
+ * badges refresh without manual wiring. Typed `AgencError`s surface UNTOUCHED.
16
+ *
17
+ * HONEST BOUNDARY (phase 1 — do not overclaim in UI copy): a FORFEITED bond
18
+ * pays the protocol **treasury**, not the harmed party; the buyer's protection
19
+ * is the escrow refund plus the worker's skin in the game. Phase 2 (batch-2
20
+ * program work) redirects forfeiture to the harmed party.
21
+ *
22
+ * @module hooks/useCompletionBond
23
+ */
24
+ import { useMutation, useQueryClient } from "@tanstack/react-query";
25
+ import { useCallback, useRef } from "react";
26
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
27
+ import { useAgencContext } from "../provider/context.js";
28
+ import type { MarketplaceClient } from "../types.js";
29
+ import {
30
+ mutationStatusOf,
31
+ pdaKey,
32
+ queryKeys,
33
+ requireClient,
34
+ snapshotRecord,
35
+ stabilizeSelectedTransactionSigner,
36
+ type MutationStatus,
37
+ } from "./internal.js";
38
+
39
+ /**
40
+ * Per-call input for `post` (task auto-bound; the bonding `authority` signer
41
+ * defaults to the client's signer). `role` stays explicit: 1 = worker (the
42
+ * guarantee), 0 = creator.
43
+ */
44
+ export type PostCompletionBondInput = Omit<
45
+ Parameters<typeof facadeNs.postCompletionBond>[0],
46
+ "task" | "authority"
47
+ > & {
48
+ /** Override the bonding authority signer (defaults to the client signer). */
49
+ authority?: Parameters<typeof facadeNs.postCompletionBond>[0]["authority"];
50
+ };
51
+
52
+ /**
53
+ * Per-call input for `reclaim` (task auto-bound; `party` — the posting wallet
54
+ * the refund returns to — defaults to the client signer's address). The
55
+ * instruction is a permissionless crank, so any fee payer may run it.
56
+ */
57
+ export type ReclaimCompletionBondInput = Omit<
58
+ Parameters<typeof facadeNs.reclaimCompletionBond>[0],
59
+ "task" | "party"
60
+ > & {
61
+ /** Override the bond's posting wallet (defaults to the client signer). */
62
+ party?: Parameters<typeof facadeNs.reclaimCompletionBond>[0]["party"];
63
+ };
64
+
65
+ /** Lifecycle status of a bond verb. */
66
+ export type CompletionBondStatus = MutationStatus;
67
+
68
+ interface QueuedCompletionBondInput<TInput> {
69
+ readonly client: MarketplaceClient;
70
+ readonly input: TInput;
71
+ }
72
+
73
+ /** Return value of {@link useCompletionBond}. */
74
+ export interface UseCompletionBondResult {
75
+ /** Post a bond. Resolves to the tx signature; rejects with `AgencError`. */
76
+ post: (input: PostCompletionBondInput) => Promise<string>;
77
+ /** Reclaim a settled-but-live bond. Resolves to the tx signature. */
78
+ reclaim: (input: ReclaimCompletionBondInput) => Promise<string>;
79
+ /** Aggregate status: `pending` if either verb is in flight, else last settled. */
80
+ status: CompletionBondStatus;
81
+ /** The most recent error across the two verbs, or null. */
82
+ error: Error | null;
83
+ /** Signature of the last successful action, or null. */
84
+ signature: string | null;
85
+ /** True while either verb is in flight. */
86
+ isPending: boolean;
87
+ /** Reset both mutations to idle. */
88
+ reset: () => void;
89
+ }
90
+
91
+ /**
92
+ * Completion-bond actions for one task.
93
+ *
94
+ * @param taskPda - The Task PDA (bound to both verbs).
95
+ * @returns {@link UseCompletionBondResult}.
96
+ */
97
+ export function useCompletionBond(
98
+ taskPda: Parameters<typeof facadeNs.postCompletionBond>[0]["task"],
99
+ ): UseCompletionBondResult {
100
+ const ctx = useAgencContext();
101
+ const queryClient = useQueryClient();
102
+ const lastAction = useRef<"post" | "reclaim" | null>(null);
103
+
104
+ const invalidateGuarantee = useCallback(() => {
105
+ void queryClient.invalidateQueries({
106
+ queryKey: queryKeys.taskGuarantee(pdaKey(taskPda), ctx.cacheNamespace),
107
+ });
108
+ }, [ctx.cacheNamespace, queryClient, taskPda]);
109
+
110
+ const postMut = useMutation<
111
+ string,
112
+ Error,
113
+ QueuedCompletionBondInput<PostCompletionBondInput>
114
+ >({
115
+ mutationFn: async ({ client, input }) => {
116
+ const { signature } = await client.postCompletionBond({
117
+ ...input,
118
+ task: taskPda,
119
+ } as Parameters<typeof facadeNs.postCompletionBond>[0]);
120
+ invalidateGuarantee();
121
+ return signature;
122
+ },
123
+ });
124
+
125
+ const reclaimMut = useMutation<
126
+ string,
127
+ Error,
128
+ QueuedCompletionBondInput<ReclaimCompletionBondInput>
129
+ >({
130
+ mutationFn: async ({ client, input }) => {
131
+ const { signature } = await client.reclaimCompletionBond({
132
+ ...input,
133
+ task: taskPda,
134
+ } as Parameters<typeof facadeNs.reclaimCompletionBond>[0]);
135
+ invalidateGuarantee();
136
+ return signature;
137
+ },
138
+ });
139
+
140
+ const post = useCallback(
141
+ async (input: PostCompletionBondInput) => {
142
+ const client = requireClient(ctx.client);
143
+ const detachedInput = snapshotRecord(input);
144
+ const authority = stabilizeSelectedTransactionSigner(
145
+ client.signer,
146
+ detachedInput.authority,
147
+ );
148
+ const snapshottedInput = snapshotRecord({
149
+ ...detachedInput,
150
+ authority,
151
+ }) as PostCompletionBondInput;
152
+ lastAction.current = "post";
153
+ return postMut.mutateAsync({ client, input: snapshottedInput });
154
+ },
155
+ [ctx.client, postMut],
156
+ );
157
+ const reclaim = useCallback(
158
+ async (input: ReclaimCompletionBondInput) => {
159
+ const client = requireClient(ctx.client);
160
+ const detachedInput = snapshotRecord(input);
161
+ const feePayer = stabilizeSelectedTransactionSigner(client.signer);
162
+ const snapshottedInput = snapshotRecord({
163
+ ...detachedInput,
164
+ party: detachedInput.party ?? feePayer.address,
165
+ }) as ReclaimCompletionBondInput;
166
+ lastAction.current = "reclaim";
167
+ return reclaimMut.mutateAsync({ client, input: snapshottedInput });
168
+ },
169
+ [ctx.client, reclaimMut],
170
+ );
171
+
172
+ const isPending = postMut.isPending || reclaimMut.isPending;
173
+ const latest = lastAction.current === "reclaim" ? reclaimMut : postMut;
174
+ const status: CompletionBondStatus = isPending
175
+ ? "pending"
176
+ : mutationStatusOf(latest);
177
+
178
+ return {
179
+ post,
180
+ reclaim,
181
+ status,
182
+ error: latest.error ?? null,
183
+ signature: latest.data ?? null,
184
+ isPending,
185
+ reset: () => {
186
+ lastAction.current = null;
187
+ postMut.reset();
188
+ reclaimMut.reset();
189
+ },
190
+ };
191
+ }