@tetsuo-ai/marketplace-react 0.3.2 → 0.4.1

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 (42) hide show
  1. package/CHANGELOG.md +44 -0
  2. package/dist/{chunk-ZAMIL27X.js → chunk-JVXGNW3Q.js} +35 -4
  3. package/dist/chunk-JVXGNW3Q.js.map +1 -0
  4. package/dist/chunk-XLA7DARS.js +255 -0
  5. package/dist/chunk-XLA7DARS.js.map +1 -0
  6. package/dist/components/index.cjs +179 -43
  7. package/dist/components/index.cjs.map +1 -1
  8. package/dist/components/index.d.cts +2 -2
  9. package/dist/components/index.d.ts +2 -2
  10. package/dist/components/index.js +2 -2
  11. package/dist/hooks/index.cjs +206 -40
  12. package/dist/hooks/index.cjs.map +1 -1
  13. package/dist/hooks/index.d.cts +64 -4
  14. package/dist/hooks/index.d.ts +64 -4
  15. package/dist/hooks/index.js +98 -46
  16. package/dist/hooks/index.js.map +1 -1
  17. package/dist/{index-DQ3Xovkq.d.ts → index-CmVz0OOm.d.ts} +50 -5
  18. package/dist/{index-UxuvIlmD.d.cts → index-DAZzhuO4.d.cts} +50 -5
  19. package/dist/index.cjs +168 -33
  20. package/dist/index.cjs.map +1 -1
  21. package/dist/index.d.cts +3 -3
  22. package/dist/index.d.ts +3 -3
  23. package/dist/index.js +3 -3
  24. package/dist/{useAgentTrackRecord-BCvRHYM2.d.cts → useAgentTrackRecord-DPt3SfYz.d.cts} +39 -2
  25. package/dist/{useAgentTrackRecord-BCvRHYM2.d.ts → useAgentTrackRecord-DPt3SfYz.d.ts} +39 -2
  26. package/package.json +2 -2
  27. package/src/components/GuaranteedBadge.tsx +73 -0
  28. package/src/components/index.ts +4 -0
  29. package/src/components/strings.ts +8 -0
  30. package/src/hooks/index.ts +13 -0
  31. package/src/hooks/internal.ts +3 -0
  32. package/src/hooks/moderation-attestor.ts +176 -57
  33. package/src/hooks/useCompletionBond.ts +156 -0
  34. package/src/hooks/useHire.ts +27 -0
  35. package/src/hooks/useHumanlessHireFlow.ts +74 -17
  36. package/src/hooks/useTaskActivation.ts +19 -13
  37. package/src/hooks/useTaskGuarantee.ts +120 -0
  38. package/src/index.ts +2 -0
  39. package/src/types.ts +5 -2
  40. package/dist/chunk-2Y6JN2VZ.js +0 -143
  41. package/dist/chunk-2Y6JN2VZ.js.map +0 -1
  42. package/dist/chunk-ZAMIL27X.js.map +0 -1
@@ -0,0 +1,156 @@
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 } from "react";
26
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
27
+ import { useAgencContext } from "../provider/context.js";
28
+ import {
29
+ mutationStatusOf,
30
+ pdaKey,
31
+ queryKeys,
32
+ requireClient,
33
+ type MutationStatus,
34
+ } from "./internal.js";
35
+
36
+ /**
37
+ * Per-call input for `post` (task auto-bound; the bonding `authority` signer
38
+ * defaults to the client's signer). `role` stays explicit: 1 = worker (the
39
+ * guarantee), 0 = creator.
40
+ */
41
+ export type PostCompletionBondInput = Omit<
42
+ Parameters<typeof facadeNs.postCompletionBond>[0],
43
+ "task" | "authority"
44
+ > & {
45
+ /** Override the bonding authority signer (defaults to the client signer). */
46
+ authority?: Parameters<typeof facadeNs.postCompletionBond>[0]["authority"];
47
+ };
48
+
49
+ /**
50
+ * Per-call input for `reclaim` (task auto-bound; `party` — the posting wallet
51
+ * the refund returns to — defaults to the client signer's address). The
52
+ * instruction is a permissionless crank, so any fee payer may run it.
53
+ */
54
+ export type ReclaimCompletionBondInput = Omit<
55
+ Parameters<typeof facadeNs.reclaimCompletionBond>[0],
56
+ "task" | "party"
57
+ > & {
58
+ /** Override the bond's posting wallet (defaults to the client signer). */
59
+ party?: Parameters<typeof facadeNs.reclaimCompletionBond>[0]["party"];
60
+ };
61
+
62
+ /** Lifecycle status of a bond verb. */
63
+ export type CompletionBondStatus = MutationStatus;
64
+
65
+ /** Return value of {@link useCompletionBond}. */
66
+ export interface UseCompletionBondResult {
67
+ /** Post a bond. Resolves to the tx signature; rejects with `AgencError`. */
68
+ post: (input: PostCompletionBondInput) => Promise<string>;
69
+ /** Reclaim a settled-but-live bond. Resolves to the tx signature. */
70
+ reclaim: (input: ReclaimCompletionBondInput) => Promise<string>;
71
+ /** Aggregate status: `pending` if either verb is in flight, else last settled. */
72
+ status: CompletionBondStatus;
73
+ /** The most recent error across the two verbs, or null. */
74
+ error: Error | null;
75
+ /** Signature of the last successful action, or null. */
76
+ signature: string | null;
77
+ /** True while either verb is in flight. */
78
+ isPending: boolean;
79
+ /** Reset both mutations to idle. */
80
+ reset: () => void;
81
+ }
82
+
83
+ /**
84
+ * Completion-bond actions for one task.
85
+ *
86
+ * @param taskPda - The Task PDA (bound to both verbs).
87
+ * @returns {@link UseCompletionBondResult}.
88
+ */
89
+ export function useCompletionBond(
90
+ taskPda: Parameters<typeof facadeNs.postCompletionBond>[0]["task"],
91
+ ): UseCompletionBondResult {
92
+ const ctx = useAgencContext();
93
+ const queryClient = useQueryClient();
94
+
95
+ const invalidateGuarantee = useCallback(() => {
96
+ void queryClient.invalidateQueries({
97
+ queryKey: queryKeys.taskGuarantee(pdaKey(taskPda)),
98
+ });
99
+ }, [queryClient, taskPda]);
100
+
101
+ const postMut = useMutation<string, Error, PostCompletionBondInput>({
102
+ mutationFn: async (input) => {
103
+ const client = requireClient(ctx.client);
104
+ const { signature } = await client.postCompletionBond({
105
+ ...input,
106
+ task: taskPda,
107
+ authority: input.authority ?? client.signer,
108
+ } as Parameters<typeof facadeNs.postCompletionBond>[0]);
109
+ invalidateGuarantee();
110
+ return signature;
111
+ },
112
+ });
113
+
114
+ const reclaimMut = useMutation<string, Error, ReclaimCompletionBondInput>({
115
+ mutationFn: async (input) => {
116
+ const client = requireClient(ctx.client);
117
+ const { signature } = await client.reclaimCompletionBond({
118
+ ...input,
119
+ task: taskPda,
120
+ party: input.party ?? client.signer.address,
121
+ } as Parameters<typeof facadeNs.reclaimCompletionBond>[0]);
122
+ invalidateGuarantee();
123
+ return signature;
124
+ },
125
+ });
126
+
127
+ const post = useCallback(
128
+ (input: PostCompletionBondInput) => postMut.mutateAsync(input),
129
+ [postMut],
130
+ );
131
+ const reclaim = useCallback(
132
+ (input: ReclaimCompletionBondInput) => reclaimMut.mutateAsync(input),
133
+ [reclaimMut],
134
+ );
135
+
136
+ const isPending = postMut.isPending || reclaimMut.isPending;
137
+ const status: CompletionBondStatus = isPending
138
+ ? "pending"
139
+ : mutationStatusOf(
140
+ // Surface the most recently-touched verb's terminal state.
141
+ [postMut, reclaimMut].find((m) => m.isError || m.isSuccess) ?? postMut,
142
+ );
143
+
144
+ return {
145
+ post,
146
+ reclaim,
147
+ status,
148
+ error: postMut.error ?? reclaimMut.error ?? null,
149
+ signature: postMut.data ?? reclaimMut.data ?? null,
150
+ isPending,
151
+ reset: () => {
152
+ postMut.reset();
153
+ reclaimMut.reset();
154
+ },
155
+ };
156
+ }
@@ -28,6 +28,10 @@ import {
28
28
  signerAddress,
29
29
  withoutReferrerArgs,
30
30
  } from "./internal.js";
31
+ import {
32
+ resolveHireListingModerationAccounts,
33
+ type HireListingModerationAccounts,
34
+ } from "./moderation-attestor.js";
31
35
 
32
36
  /**
33
37
  * Input to a standard `hire(...)` — a buyer that has a registered marketplace
@@ -132,6 +136,27 @@ export function useHire(): UseHireResult {
132
136
  const { referrerArgs, referrerInjected } = resolveReferrerArgs(ctx);
133
137
  const hireInput = withoutReferrerArgs(input);
134
138
 
139
+ // P1.2: the hire gate names an explicit `moderator` (the caller's trust
140
+ // decision) and needs the roster-entry PDA when that moderator is a
141
+ // registered attestor, plus a record override when the listing
142
+ // attestation predates the upgrade (legacy grace window). Resolve the
143
+ // mechanics automatically unless the caller supplied any of them.
144
+ const listingSpecHash = input.listingSpecHash;
145
+ let moderationArgs: HireListingModerationAccounts = {};
146
+ if (
147
+ input.moderationAttestor === undefined &&
148
+ input.moderatorIsAttestor === undefined &&
149
+ input.listingModeration === undefined &&
150
+ listingSpecHash !== undefined
151
+ ) {
152
+ moderationArgs = await resolveHireListingModerationAccounts({
153
+ rpcUrl: ctx.rpcUrl,
154
+ listing: input.listing,
155
+ listingSpecHash,
156
+ moderator: input.moderator,
157
+ });
158
+ }
159
+
135
160
  const creator = input.creator ?? client.signer;
136
161
  let signature: string;
137
162
 
@@ -140,6 +165,7 @@ export function useHire(): UseHireResult {
140
165
  // it settles via the buyer review path (useSubmissionReview).
141
166
  const result = await client.hireFromListingHumanless({
142
167
  ...hireInput,
168
+ ...moderationArgs,
143
169
  creator,
144
170
  ...referrerArgs,
145
171
  } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
@@ -149,6 +175,7 @@ export function useHire(): UseHireResult {
149
175
  const authority = input.authority ?? client.signer;
150
176
  const result = await client.hireFromListing({
151
177
  ...hireInput,
178
+ ...moderationArgs,
152
179
  authority,
153
180
  creator,
154
181
  ...referrerArgs,
@@ -12,7 +12,11 @@ import {
12
12
  withoutReferrerArgs,
13
13
  type MutationStatus,
14
14
  } from "./internal.js";
15
- import { resolveActivationModerationAttestor } from "./moderation-attestor.js";
15
+ import {
16
+ resolveActivationModerationAccounts,
17
+ resolveHireListingModerationAccounts,
18
+ type HireListingModerationAccounts,
19
+ } from "./moderation-attestor.js";
16
20
  import type { HumanlessHireInput } from "./useHire.js";
17
21
  import type { TaskActivationInput } from "./useTaskActivation.js";
18
22
 
@@ -33,8 +37,15 @@ export type HumanlessHireFlowHireInput = Omit<
33
37
 
34
38
  export type HumanlessHireFlowActivationInput = Omit<
35
39
  TaskActivationInput,
36
- "creator" | "jobSpecHash" | "jobSpecUri"
37
- >;
40
+ "creator" | "jobSpecHash" | "jobSpecUri" | "moderator"
41
+ > & {
42
+ /**
43
+ * Override the activation `moderator` (P1.2). Defaults to the `moderator`
44
+ * returned by `hostAndModerateJobSpec` — the attestation service that
45
+ * signed the task moderation is whose record the publish gate consumes.
46
+ */
47
+ moderator?: TaskActivationInput["moderator"];
48
+ };
38
49
 
39
50
  export type HumanlessHireFlowCreator = HumanlessHireInput["creator"];
40
51
 
@@ -45,6 +56,12 @@ export interface HumanlessHireFlowModerationResult {
45
56
  jobSpecHash: HumanlessHireFlowJobSpecHash;
46
57
  jobSpecUri: string;
47
58
  moderationAttested: boolean;
59
+ /**
60
+ * The pubkey that signed/recorded the task attestation (P1.2) — the
61
+ * attestation service's signer (e.g. attest.agenc.ag `GET /v1/info` →
62
+ * `moderator`). Names whose record the publish gate consumes.
63
+ */
64
+ moderator: Address;
48
65
  moderation?: unknown;
49
66
  }
50
67
 
@@ -114,7 +131,11 @@ function emptyProgress(): HumanlessHireFlowProgress {
114
131
 
115
132
  function validateModerationResult(
116
133
  result: HumanlessHireFlowModerationResult,
117
- ): { jobSpecHash: HumanlessHireFlowJobSpecHash; jobSpecUri: string } {
134
+ ): {
135
+ jobSpecHash: HumanlessHireFlowJobSpecHash;
136
+ jobSpecUri: string;
137
+ moderator: Address;
138
+ } {
118
139
  if (result.moderationAttested !== true) {
119
140
  throw new Error(
120
141
  "Task moderation was not attested; activation was not signed.",
@@ -134,7 +155,16 @@ function validateModerationResult(
134
155
  "Task moderation returned an empty jobSpecUri; activation was not signed.",
135
156
  );
136
157
  }
137
- return { jobSpecHash: result.jobSpecHash, jobSpecUri };
158
+ if (typeof result.moderator !== "string" || !result.moderator.trim()) {
159
+ throw new Error(
160
+ "Task moderation returned no moderator pubkey; activation was not signed.",
161
+ );
162
+ }
163
+ return {
164
+ jobSpecHash: result.jobSpecHash,
165
+ jobSpecUri,
166
+ moderator: result.moderator,
167
+ };
138
168
  }
139
169
 
140
170
  export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlowResult<TJobSpec> {
@@ -159,8 +189,26 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
159
189
  setProgress(emptyProgress());
160
190
 
161
191
  try {
192
+ // P1.2: resolve the hire gate's moderation mechanics (roster PDA /
193
+ // legacy record override) unless the caller supplied any of them.
194
+ const hireListingSpecHash = input.hire.listingSpecHash;
195
+ let hireModerationArgs: HireListingModerationAccounts = {};
196
+ if (
197
+ input.hire.moderationAttestor === undefined &&
198
+ input.hire.moderatorIsAttestor === undefined &&
199
+ input.hire.listingModeration === undefined &&
200
+ hireListingSpecHash !== undefined
201
+ ) {
202
+ hireModerationArgs = await resolveHireListingModerationAccounts({
203
+ rpcUrl: ctx.rpcUrl,
204
+ listing: input.hire.listing,
205
+ listingSpecHash: hireListingSpecHash,
206
+ moderator: input.hire.moderator,
207
+ });
208
+ }
162
209
  const hireResult = await client.hireFromListingHumanless({
163
210
  ...hireInput,
211
+ ...hireModerationArgs,
164
212
  creator,
165
213
  ...referrerArgs,
166
214
  } as Parameters<typeof facadeNs.hireFromListingHumanless>[0]);
@@ -186,7 +234,8 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
186
234
  hireSignature: hireResult.signature,
187
235
  referrerInjected,
188
236
  });
189
- const { jobSpecHash, jobSpecUri } = validateModerationResult(moderation);
237
+ const { jobSpecHash, jobSpecUri, moderator } =
238
+ validateModerationResult(moderation);
190
239
 
191
240
  setProgress((current) => ({
192
241
  ...current,
@@ -195,23 +244,31 @@ export function useHumanlessHireFlow<TJobSpec = unknown>(): UseHumanlessHireFlow
195
244
  }));
196
245
 
197
246
  setPhase("activating");
198
- // WP-A1: attach the roster-attestor account when the moderation was
199
- // authored by a roster attestor (e.g. the public attestation
200
- // service) — without it the publish gate rejects the activation.
201
- const moderationAttestor =
202
- input.activation?.moderationAttestor ??
203
- (await resolveActivationModerationAttestor({
204
- rpcUrl: ctx.rpcUrl,
205
- task: taskPda,
206
- jobSpecHash,
207
- }));
247
+ // P1.2: the publish gate consumes the record of the moderator that
248
+ // signed the attestation (the host callback's service by default).
249
+ // Resolve the gate mechanics (roster PDA / legacy record override)
250
+ // unless the caller supplied any of them.
251
+ const activationModerator = input.activation?.moderator ?? moderator;
252
+ const activationCallerResolved =
253
+ input.activation?.moderationAttestor !== undefined ||
254
+ input.activation?.moderatorIsAttestor !== undefined ||
255
+ input.activation?.taskModeration !== undefined;
256
+ const activationModerationArgs = activationCallerResolved
257
+ ? {}
258
+ : await resolveActivationModerationAccounts({
259
+ rpcUrl: ctx.rpcUrl,
260
+ task: taskPda,
261
+ jobSpecHash,
262
+ moderator: activationModerator,
263
+ });
208
264
  const activationResult = await client.setTaskJobSpec({
209
265
  ...(input.activation ?? {}),
210
- ...(moderationAttestor !== undefined ? { moderationAttestor } : {}),
266
+ ...activationModerationArgs,
211
267
  task: taskPda,
212
268
  creator,
213
269
  jobSpecHash,
214
270
  jobSpecUri,
271
+ moderator: activationModerator,
215
272
  } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
216
273
 
217
274
  const result: HumanlessHireFlowResult = {
@@ -7,7 +7,7 @@ import {
7
7
  requireClient,
8
8
  type MutationStatus,
9
9
  } from "./internal.js";
10
- import { resolveActivationModerationAttestor } from "./moderation-attestor.js";
10
+ import { resolveActivationModerationAccounts } from "./moderation-attestor.js";
11
11
 
12
12
  export type TaskActivationInput = Omit<
13
13
  Parameters<typeof facadeNs.setTaskJobSpec>[0],
@@ -34,20 +34,26 @@ export function useTaskActivation(
34
34
  const mutation = useMutation<string, Error, TaskActivationInput>({
35
35
  mutationFn: async (input) => {
36
36
  const client = requireClient(ctx.client);
37
- // WP-A1: when the task moderation was authored by a roster attestor
38
- // (not the global authority), the publish gate only unlocks if the
39
- // attestor's roster-entry PDA is attached. Resolve it automatically
40
- // unless the caller supplied one.
41
- const moderationAttestor =
42
- input.moderationAttestor ??
43
- (await resolveActivationModerationAttestor({
44
- rpcUrl: ctx.rpcUrl,
45
- task: taskPda,
46
- jobSpecHash: input.jobSpecHash,
47
- }));
37
+ // P1.2: the publish gate names an explicit `moderator` (supplied by the
38
+ // caller — the trust decision) and needs the roster-entry PDA when that
39
+ // moderator is a registered attestor, plus a record override when the
40
+ // attestation predates the upgrade (legacy grace window). Resolve the
41
+ // mechanics automatically unless the caller supplied any of them.
42
+ const callerResolved =
43
+ input.moderationAttestor !== undefined ||
44
+ input.moderatorIsAttestor !== undefined ||
45
+ input.taskModeration !== undefined;
46
+ const resolved = callerResolved
47
+ ? {}
48
+ : await resolveActivationModerationAccounts({
49
+ rpcUrl: ctx.rpcUrl,
50
+ task: taskPda,
51
+ jobSpecHash: input.jobSpecHash,
52
+ moderator: input.moderator,
53
+ });
48
54
  const { signature } = await client.setTaskJobSpec({
49
55
  ...input,
50
- ...(moderationAttestor !== undefined ? { moderationAttestor } : {}),
56
+ ...resolved,
51
57
  task: taskPda,
52
58
  creator: input.creator ?? client.signer,
53
59
  } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
@@ -0,0 +1,120 @@
1
+ /**
2
+ * `useTaskGuarantee(taskPda)` — a task's completion-bond ("Guaranteed Hire")
3
+ * state, read-only.
4
+ *
5
+ * Guaranteed Hire is the productized read of the LIVE completion-bond
6
+ * machinery: a worker who posts a completion bond stakes 25% of the reward on
7
+ * passing review, and forfeits it if the result is rejected or they lose a
8
+ * dispute. `guaranteed` is `true` iff the worker bond is posted and unresolved
9
+ * (bond PDAs are closed by every settlement exit, so live == unresolved).
10
+ *
11
+ * HONEST BOUNDARY (phase 1 — do not overclaim in UI copy): a FORFEITED bond
12
+ * pays the protocol **treasury**, not the harmed party. The buyer's protection
13
+ * today is the escrow refund on a failed review PLUS the worker's 25% skin in
14
+ * the game — the buyer does not receive the bond itself. Phase 2 (batch-2
15
+ * program work) redirects forfeiture to the harmed party.
16
+ *
17
+ * ## How it reads
18
+ *
19
+ * The bond accounts are keyed by (task, posting wallet) and the worker's
20
+ * wallet is not derivable from the Task account alone, so this is a
21
+ * `getProgramAccounts` read (`CompletionBond.task` memcmp) — the SDK's
22
+ * `fetchTaskGuarantee`. Resolution order:
23
+ * 1. `options.guaranteeReader` — an injected reader seam (tests, litesvm,
24
+ * custom transports; same pattern as `useTaskStatus`/`useDispute`);
25
+ * 2. the provider's resolved `rpcUrl` — a kit RPC is built for the read. NOTE:
26
+ * the RPC must allow `getProgramAccounts` (many public providers restrict
27
+ * it); a rejection surfaces in `error`, never a crash.
28
+ * Without either, the hook stays idle.
29
+ *
30
+ * @module hooks/useTaskGuarantee
31
+ */
32
+ import { useQuery } from "@tanstack/react-query";
33
+ import { useMemo } from "react";
34
+ import { createSolanaRpc } from "@solana/kit";
35
+ import {
36
+ fetchTaskGuarantee,
37
+ type ProgramAccountsSource,
38
+ type TaskGuarantee,
39
+ } from "@tetsuo-ai/marketplace-sdk";
40
+ import { useAgencContext } from "../provider/context.js";
41
+ import type { Address } from "../types.js";
42
+ import { pdaKey, queryKeys } from "./internal.js";
43
+
44
+ /** Reads a task's {@link TaskGuarantee} (the SDK `fetchTaskGuarantee` shape). */
45
+ export type TaskGuaranteeReader = (
46
+ taskPda: Address | string,
47
+ ) => Promise<TaskGuarantee>;
48
+
49
+ /** Options for {@link useTaskGuarantee}. */
50
+ export interface UseTaskGuaranteeOptions {
51
+ /**
52
+ * Injected reader seam (wins over the provider `rpcUrl` default). Wire it
53
+ * from litesvm/gpa-sim in tests or from your own transport.
54
+ */
55
+ guaranteeReader?: TaskGuaranteeReader;
56
+ /** Disable the read. Default `true` when `taskPda` + a read source exist. */
57
+ enabled?: boolean;
58
+ }
59
+
60
+ /** Return value of {@link useTaskGuarantee}. */
61
+ export interface UseTaskGuaranteeResult {
62
+ /** The full bond state (worker/creator bonds + flag), or null until read. */
63
+ guarantee: TaskGuarantee | null;
64
+ /**
65
+ * Convenience: `guarantee?.guaranteed ?? false` — `true` iff the worker
66
+ * bond is live (posted and unresolved).
67
+ */
68
+ guaranteed: boolean;
69
+ /** True while the first read is in flight. */
70
+ isLoading: boolean;
71
+ /** The read error, or null. */
72
+ error: Error | null;
73
+ /** Force a refetch (e.g. after posting/reclaiming a bond). */
74
+ refetch: () => void;
75
+ }
76
+
77
+ /**
78
+ * Read a task's Guaranteed Hire state.
79
+ *
80
+ * @param taskPda - The Task PDA (falsy disables the read).
81
+ * @param options - Reader seam + enabled.
82
+ * @returns {@link UseTaskGuaranteeResult}.
83
+ */
84
+ export function useTaskGuarantee(
85
+ taskPda: Address | string | undefined | null,
86
+ options?: UseTaskGuaranteeOptions,
87
+ ): UseTaskGuaranteeResult {
88
+ const ctx = useAgencContext();
89
+ const injected = options?.guaranteeReader;
90
+ const rpcUrl = ctx.rpcUrl;
91
+
92
+ // Injected seam wins; else build a gPA read over the provider's rpcUrl.
93
+ const reader = useMemo<TaskGuaranteeReader | null>(() => {
94
+ if (injected) return injected;
95
+ if (!rpcUrl) return null;
96
+ return (pda) =>
97
+ fetchTaskGuarantee(
98
+ createSolanaRpc(rpcUrl) as unknown as ProgramAccountsSource,
99
+ pda as Address,
100
+ );
101
+ }, [injected, rpcUrl]);
102
+
103
+ const enabled =
104
+ (options?.enabled ?? true) && Boolean(taskPda) && reader !== null;
105
+
106
+ const query = useQuery<TaskGuarantee, Error>({
107
+ queryKey: queryKeys.taskGuarantee(taskPda ? pdaKey(taskPda) : ""),
108
+ enabled,
109
+ queryFn: () => reader!(taskPda as Address | string),
110
+ });
111
+
112
+ const guarantee = query.data ?? null;
113
+ return {
114
+ guarantee,
115
+ guaranteed: guarantee?.guaranteed ?? false,
116
+ isLoading: query.isLoading,
117
+ error: query.error ?? null,
118
+ refetch: () => void query.refetch(),
119
+ };
120
+ }
package/src/index.ts CHANGED
@@ -88,6 +88,7 @@ export {
88
88
  Button,
89
89
  DEFAULT_TRUST_HREF,
90
90
  DisputeBanner,
91
+ GuaranteedBadge,
91
92
  HireButton,
92
93
  HireCheckoutModal,
93
94
  ListingCard,
@@ -132,6 +133,7 @@ export {
132
133
  type ButtonVariant,
133
134
  type ComponentStringId,
134
135
  type DisputeBannerProps,
136
+ type GuaranteedBadgeProps,
135
137
  type HireButtonProps,
136
138
  type HireCheckoutListing,
137
139
  type HireCheckoutModalProps,
package/src/types.ts CHANGED
@@ -200,9 +200,12 @@ export interface AgencContextValue {
200
200
  client: MarketplaceClient | null;
201
201
  /**
202
202
  * The resolved HTTP RPC endpoint (config override or the network default),
203
- * or `null` when none resolves. Hooks use it for single-account reads —
203
+ * or `null` when none resolves. Hooks use it for targeted per-task reads —
204
204
  * e.g. resolving the WP-A1 `moderation_attestor` roster account during
205
- * activation. NOT a gPA/list-query source; the read transport owns those.
205
+ * activation, and the `useTaskGuarantee` completion-bond read (a
206
+ * task-scoped `getProgramAccounts` with no single-account equivalent; the
207
+ * RPC must allow gPA, and an injected reader seam bypasses it). LIST
208
+ * queries stay with the read transport.
206
209
  */
207
210
  rpcUrl: string | null;
208
211
  /**