@tetsuo-ai/marketplace-react 0.4.1 → 0.6.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 (84) hide show
  1. package/CHANGELOG.md +65 -0
  2. package/README.md +97 -51
  3. package/dist/chunk-7NKRSPPN.js +227 -0
  4. package/dist/chunk-7NKRSPPN.js.map +1 -0
  5. package/dist/{chunk-JVXGNW3Q.js → chunk-CDDHUFMG.js} +6 -5
  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-XLA7DARS.js → chunk-RG5JZ6JL.js} +159 -36
  18. package/dist/chunk-RG5JZ6JL.js.map +1 -0
  19. package/dist/components/index.cjs +158 -1594
  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 +656 -509
  25. package/dist/hooks/index.cjs.map +1 -1
  26. package/dist/hooks/index.d.cts +63 -29
  27. package/dist/hooks/index.d.ts +63 -29
  28. package/dist/hooks/index.js +619 -196
  29. package/dist/hooks/index.js.map +1 -1
  30. package/dist/{index-CmVz0OOm.d.ts → index-BAyr1ODZ.d.ts} +28 -3
  31. package/dist/{index-DAZzhuO4.d.cts → index-C20NVU7_.d.cts} +28 -3
  32. package/dist/index.cjs +284 -1833
  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-DPt3SfYz.d.cts → useAgentTrackRecord-Ch7gHTFj.d.cts} +1 -1
  49. package/dist/{useAgentTrackRecord-DPt3SfYz.d.ts → useAgentTrackRecord-Ch7gHTFj.d.ts} +1 -1
  50. package/package.json +7 -4
  51. package/src/components/HireCheckoutModal.tsx +5 -2
  52. package/src/hooks/index.ts +1 -0
  53. package/src/hooks/internal.ts +178 -24
  54. package/src/hooks/useAgentTrackRecord.ts +5 -2
  55. package/src/hooks/useCompletionBond.ts +56 -21
  56. package/src/hooks/useDispute.ts +46 -9
  57. package/src/hooks/useHire.ts +113 -23
  58. package/src/hooks/useHumanlessHireFlow.ts +335 -115
  59. package/src/hooks/useListing.ts +2 -2
  60. package/src/hooks/useListings.ts +2 -2
  61. package/src/hooks/useRateHire.ts +32 -5
  62. package/src/hooks/useReferrerEarnings.ts +4 -1
  63. package/src/hooks/useSubmissionReview.ts +95 -32
  64. package/src/hooks/useTaskActivation.ts +51 -9
  65. package/src/hooks/useTaskGuarantee.ts +4 -1
  66. package/src/hooks/useTaskLifecycle.ts +104 -24
  67. package/src/hooks/useTaskStatus.ts +121 -26
  68. package/src/hooks/useTaskWork.ts +76 -12
  69. package/src/hooks/useWalletSigner.ts +11 -16
  70. package/src/index.ts +3 -0
  71. package/src/provider/AgencProvider.tsx +95 -3
  72. package/src/provider/referrer.ts +1 -1
  73. package/src/signers/README.md +13 -7
  74. package/src/signers/index.ts +6 -1
  75. package/src/signers/strings.ts +13 -1
  76. package/src/signers/types.ts +16 -5
  77. package/src/signers/wallet-account.ts +115 -29
  78. package/src/signers/wallet-adapter.ts +38 -4
  79. package/src/theme/agenc-tailwind-preset.cjs +134 -108
  80. package/src/types.ts +27 -1
  81. package/dist/chunk-JVXGNW3Q.js.map +0 -1
  82. package/dist/chunk-ON6XR4XO.js +0 -128
  83. package/dist/chunk-ON6XR4XO.js.map +0 -1
  84. package/dist/chunk-XLA7DARS.js.map +0 -1
@@ -23,11 +23,12 @@
23
23
  * - Polling: TanStack Query `refetchInterval` re-runs `taskReader` until the
24
24
  * task reaches a terminal status (`Completed`/`Cancelled`/`RejectFrozen`) or
25
25
  * the optional `targetStatus` — then stops.
26
- * - Subscription: when an `events` async-iterable is supplied (e.g. from the
27
- * SDK's `subscribeMarketplaceEvents`), a `useEffect` (browser-only; never runs
28
- * during SSR) drains it, appends each event to `events`, and triggers a
29
- * refetch so status stays fresh without tight polling. The effect aborts the
30
- * iterable and clears state on unmount.
26
+ * - Subscription: `events` prefers an abort-aware source factory, while still
27
+ * accepting the original `AsyncIterable` API for compatibility. A browser-
28
+ * only effect owns its `AbortController`, drains the iterable, retains a
29
+ * bounded tail, and triggers a refetch. Cleanup races blocked legacy
30
+ * `next()` calls against abort and requests iterator return; factories can
31
+ * additionally release their transport cooperatively through the signal.
31
32
  *
32
33
  * @module hooks/useTaskStatus
33
34
  */
@@ -48,12 +49,26 @@ export type TaskReader = (pda: Address | string) => Promise<Task | null>;
48
49
  export type ObservedEvent = unknown;
49
50
 
50
51
  /**
51
- * An async source of coordination events for the watched task. Pass the result
52
- * of the SDK's `subscribeMarketplaceEvents(...)` (already address-filtered) or
53
- * any async iterable. Optional.
52
+ * Original coordination-event stream API.
53
+ *
54
+ * @deprecated Prefer {@link TaskEventsSourceFactory}. A pre-created iterable
55
+ * cannot pass this hook's abort signal into its subscription transport. Legacy
56
+ * streams remain cancellation-safe at the iterator boundary through an abort
57
+ * race and best-effort `iterator.return()` cleanup.
54
58
  */
55
59
  export type TaskEventsSource = AsyncIterable<ObservedEvent>;
56
60
 
61
+ /**
62
+ * Abort-aware coordination-event factory. Implementations should pass the
63
+ * signal to their subscription transport. The task identity lets a factory
64
+ * construct an address-filtered stream. This form is preferred over the
65
+ * deprecated pre-created {@link TaskEventsSource}.
66
+ */
67
+ export type TaskEventsSourceFactory = (options: {
68
+ signal: AbortSignal;
69
+ taskPda: Address | string;
70
+ }) => AsyncIterable<ObservedEvent>;
71
+
57
72
  /** Options for {@link useTaskStatus}. */
58
73
  export interface UseTaskStatusOptions {
59
74
  /**
@@ -62,17 +77,24 @@ export interface UseTaskStatusOptions {
62
77
  */
63
78
  taskReader?: TaskReader;
64
79
  /**
65
- * Optional event source. When given, observed events are appended to
66
- * `events` and each triggers a refetch. Drained in a browser-only effect and
67
- * aborted on unmount.
80
+ * Optional event stream. Prefer an abort-aware factory; the deprecated
81
+ * pre-created AsyncIterable form remains supported for compatibility. Each
82
+ * event triggers a refetch.
68
83
  */
69
- events?: TaskEventsSource;
84
+ events?: TaskEventsSourceFactory | TaskEventsSource;
85
+ /** Maximum recent events retained in memory (default `256`). */
86
+ maxEvents?: number;
70
87
  /**
71
88
  * Stop polling once the task reaches this status (in addition to terminal
72
89
  * statuses). Useful to await a specific transition (e.g. `Completed`).
73
90
  */
74
91
  targetStatus?: TaskStatus;
75
- /** Poll interval in ms while non-terminal. Default `2000`. */
92
+ /**
93
+ * Poll interval in ms while non-terminal. Default `2000`.
94
+ *
95
+ * Must be a non-negative integer no greater than `2_147_483_647`, the
96
+ * maximum portable JavaScript timer delay; invalid values throw RangeError.
97
+ */
76
98
  pollIntervalMs?: number;
77
99
  /** Disable the hook entirely. Default `true` when `taskPda` + reader exist. */
78
100
  enabled?: boolean;
@@ -106,10 +128,14 @@ const TERMINAL_STATUSES: ReadonlySet<TaskStatus> = new Set([
106
128
  TaskStatus.Cancelled,
107
129
  TaskStatus.RejectFrozen,
108
130
  ]);
131
+ const DEFAULT_MAX_EVENTS = 256;
132
+ const MAX_POLL_INTERVAL_MS = 2_147_483_647;
109
133
 
110
134
  /** True when the task's `result` bytes are present and non-empty. */
111
135
  function hasResult(task: Task | null): boolean {
112
- return task !== null && task.result.length > 0 && task.result.some((b) => b !== 0);
136
+ return (
137
+ task !== null && task.result.length > 0 && task.result.some((b) => b !== 0)
138
+ );
113
139
  }
114
140
 
115
141
  /**
@@ -123,19 +149,41 @@ export function useTaskStatus(
123
149
  taskPda: Address | string | undefined | null,
124
150
  options?: UseTaskStatusOptions,
125
151
  ): UseTaskStatusResult {
126
- // Touch context so the hook is provider-bound (and throws clearly outside it),
127
- // matching every other hook's contract even though reads come via the reader.
128
- useAgencContext();
152
+ // Bind custom readers to the provider's deployment cache namespace.
153
+ const ctx = useAgencContext();
129
154
 
130
155
  const reader = options?.taskReader;
131
156
  const enabled =
132
157
  (options?.enabled ?? true) && Boolean(taskPda) && Boolean(reader);
133
158
  const pollIntervalMs = options?.pollIntervalMs ?? 2000;
159
+ const maxEvents = options?.maxEvents ?? DEFAULT_MAX_EVENTS;
160
+ if (
161
+ !Number.isSafeInteger(pollIntervalMs) ||
162
+ pollIntervalMs < 0 ||
163
+ pollIntervalMs > MAX_POLL_INTERVAL_MS
164
+ ) {
165
+ throw new RangeError(
166
+ `useTaskStatus: pollIntervalMs must be a non-negative integer no greater than ${MAX_POLL_INTERVAL_MS} (got ${pollIntervalMs})`,
167
+ );
168
+ }
169
+ if (!Number.isSafeInteger(maxEvents) || maxEvents < 0) {
170
+ throw new RangeError(
171
+ `useTaskStatus: maxEvents must be a non-negative safe integer (got ${maxEvents})`,
172
+ );
173
+ }
174
+ const taskIdentity = taskPda ? pdaKey(taskPda) : "";
134
175
 
135
- const [events, setEvents] = useState<ObservedEvent[]>([]);
176
+ const [eventState, setEventState] = useState<{
177
+ taskIdentity: string;
178
+ events: ObservedEvent[];
179
+ }>(() => ({ taskIdentity, events: [] }));
180
+ // Effects run after render, so derive an empty list synchronously when the
181
+ // task changes rather than exposing task A's history for one task-B frame.
182
+ const events =
183
+ eventState.taskIdentity === taskIdentity ? eventState.events : [];
136
184
 
137
185
  const query = useQuery<Task | null, Error>({
138
- queryKey: queryKeys.taskStatus(taskPda ? pdaKey(taskPda) : ""),
186
+ queryKey: queryKeys.taskStatus(taskIdentity, ctx.cacheNamespace),
139
187
  enabled,
140
188
  queryFn: () => reader!(taskPda as Address | string),
141
189
  // Poll until terminal / target reached; then stop (return `false`).
@@ -153,31 +201,78 @@ export function useTaskStatus(
153
201
  },
154
202
  });
155
203
 
156
- // Drain the optional event source in a browser-only effect (never during SSR;
157
- // effects don't run on the server). Abort + reset on unmount / source change.
204
+ // Own the optional event iterator so cleanup can release a subscription that
205
+ // is blocked in next(). Event history is scoped to the current task.
158
206
  const refetchRef = useRef(query.refetch);
159
207
  refetchRef.current = query.refetch;
160
208
  const eventsSource = options?.events;
161
209
  useEffect(() => {
162
- if (!eventsSource) return;
210
+ setEventState({ taskIdentity, events: [] });
211
+ if (!enabled || !eventsSource || !taskPda) return;
212
+
213
+ const controller = new AbortController();
214
+ const aborted = Symbol("aborted");
215
+ const abortPromise = new Promise<typeof aborted>((resolve) => {
216
+ controller.signal.addEventListener("abort", () => resolve(aborted), {
217
+ once: true,
218
+ });
219
+ });
220
+ let iterator: AsyncIterator<ObservedEvent> | null = null;
163
221
  let cancelled = false;
164
- (async () => {
222
+ let finished = false;
223
+ void (async () => {
165
224
  try {
166
- for await (const ev of eventsSource) {
225
+ // A callable value wins even if it also implements AsyncIterable: the
226
+ // factory form is the only one able to propagate cooperative abort
227
+ // into the underlying subscription transport.
228
+ const iterable =
229
+ typeof eventsSource === "function"
230
+ ? eventsSource({ signal: controller.signal, taskPda })
231
+ : eventsSource;
232
+ iterator = iterable[Symbol.asyncIterator]();
233
+ while (!cancelled) {
234
+ const next = await Promise.race([iterator.next(), abortPromise]);
235
+ if (next === aborted) break;
167
236
  if (cancelled) break;
168
- setEvents((prev) => [...prev, ev]);
237
+ if (next.done) {
238
+ finished = true;
239
+ break;
240
+ }
241
+ setEventState((prev) => ({
242
+ taskIdentity,
243
+ events:
244
+ prev.taskIdentity === taskIdentity
245
+ ? maxEvents === 0
246
+ ? []
247
+ : [...prev.events, next.value].slice(-maxEvents)
248
+ : maxEvents === 0
249
+ ? []
250
+ : [next.value],
251
+ }));
169
252
  // A status-changing event landed — pull a fresh read.
170
253
  void refetchRef.current();
171
254
  }
172
255
  } catch {
173
256
  // A torn-down subscription (unmount) surfaces as an iterator throw;
174
257
  // swallow it — the read query owns the surfaced error channel.
258
+ } finally {
259
+ finished = true;
175
260
  }
176
261
  })();
177
262
  return () => {
178
263
  cancelled = true;
264
+ controller.abort();
265
+ if (!finished && iterator?.return) {
266
+ try {
267
+ // React cleanup cannot await. Start closing immediately and consume
268
+ // either a synchronous throw or asynchronous rejection locally.
269
+ void Promise.resolve(iterator.return()).catch(() => undefined);
270
+ } catch {
271
+ // Best-effort teardown; the query owns the visible error channel.
272
+ }
273
+ }
179
274
  };
180
- }, [eventsSource]);
275
+ }, [enabled, eventsSource, maxEvents, taskIdentity, taskPda]);
181
276
 
182
277
  const task = query.data ?? null;
183
278
  return {
@@ -1,10 +1,15 @@
1
1
  import { useMutation } from "@tanstack/react-query";
2
- import { useCallback } from "react";
2
+ import { useCallback, useRef } from "react";
3
3
  import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
4
4
  import { useAgencContext } from "../provider/context.js";
5
+ import type { MarketplaceClient } from "../types.js";
5
6
  import {
6
7
  mutationStatusOf,
7
8
  requireClient,
9
+ snapshotFixedBytes32,
10
+ snapshotOptionalFixedBytes,
11
+ snapshotRecord,
12
+ stabilizeSelectedTransactionSigner,
8
13
  type MutationStatus,
9
14
  } from "./internal.js";
10
15
 
@@ -18,6 +23,11 @@ export type SubmitTaskResultInput = Omit<
18
23
  >;
19
24
  export type TaskWorkStatus = MutationStatus;
20
25
 
26
+ interface QueuedTaskWorkInput<TInput> {
27
+ readonly client: MarketplaceClient;
28
+ readonly input: TInput;
29
+ }
30
+
21
31
  export interface UseTaskWorkResult {
22
32
  claim: (input: ClaimTaskInput) => Promise<string>;
23
33
  submit: (input: SubmitTaskResultInput) => Promise<string>;
@@ -32,9 +42,13 @@ export function useTaskWork(
32
42
  taskPda: Parameters<typeof facadeNs.claimTaskWithJobSpec>[0]["task"],
33
43
  ): UseTaskWorkResult {
34
44
  const ctx = useAgencContext();
35
- const claimMut = useMutation<string, Error, ClaimTaskInput>({
36
- mutationFn: async (input) => {
37
- const client = requireClient(ctx.client);
45
+ const lastAction = useRef<"claim" | "submit" | null>(null);
46
+ const claimMut = useMutation<
47
+ string,
48
+ Error,
49
+ QueuedTaskWorkInput<ClaimTaskInput>
50
+ >({
51
+ mutationFn: async ({ client, input }) => {
38
52
  const { signature } = await client.claimTaskWithJobSpec({
39
53
  ...input,
40
54
  task: taskPda,
@@ -42,9 +56,12 @@ export function useTaskWork(
42
56
  return signature;
43
57
  },
44
58
  });
45
- const submitMut = useMutation<string, Error, SubmitTaskResultInput>({
46
- mutationFn: async (input) => {
47
- const client = requireClient(ctx.client);
59
+ const submitMut = useMutation<
60
+ string,
61
+ Error,
62
+ QueuedTaskWorkInput<SubmitTaskResultInput>
63
+ >({
64
+ mutationFn: async ({ client, input }) => {
48
65
  const { signature } = await client.submitTaskResult({
49
66
  ...input,
50
67
  task: taskPda,
@@ -53,22 +70,69 @@ export function useTaskWork(
53
70
  },
54
71
  });
55
72
 
56
- const claim = useCallback((input: ClaimTaskInput) => claimMut.mutateAsync(input), [claimMut]);
73
+ const claim = useCallback(
74
+ async (input: ClaimTaskInput) => {
75
+ const client = requireClient(ctx.client);
76
+ const detachedInput = snapshotRecord(input);
77
+ const authority = stabilizeSelectedTransactionSigner(
78
+ client.signer,
79
+ detachedInput.authority,
80
+ );
81
+ const snapshottedInput = snapshotRecord({
82
+ ...detachedInput,
83
+ authority,
84
+ ...(detachedInput.jobSpecHash === undefined
85
+ ? {}
86
+ : {
87
+ jobSpecHash: snapshotFixedBytes32(
88
+ detachedInput.jobSpecHash,
89
+ "useTaskWork.claim: jobSpecHash",
90
+ ),
91
+ }),
92
+ }) as ClaimTaskInput;
93
+ lastAction.current = "claim";
94
+ return claimMut.mutateAsync({ client, input: snapshottedInput });
95
+ },
96
+ [claimMut, ctx.client],
97
+ );
57
98
  const submit = useCallback(
58
- (input: SubmitTaskResultInput) => submitMut.mutateAsync(input),
59
- [submitMut],
99
+ async (input: SubmitTaskResultInput) => {
100
+ const client = requireClient(ctx.client);
101
+ const detachedInput = snapshotRecord(input);
102
+ const authority = stabilizeSelectedTransactionSigner(
103
+ client.signer,
104
+ detachedInput.authority,
105
+ );
106
+ const snapshottedInput = snapshotRecord({
107
+ ...detachedInput,
108
+ authority,
109
+ proofHash: snapshotFixedBytes32(
110
+ detachedInput.proofHash,
111
+ "useTaskWork.submit: proofHash",
112
+ ),
113
+ resultData: snapshotOptionalFixedBytes(
114
+ detachedInput.resultData,
115
+ 64,
116
+ "useTaskWork.submit: resultData",
117
+ ),
118
+ }) as SubmitTaskResultInput;
119
+ lastAction.current = "submit";
120
+ return submitMut.mutateAsync({ client, input: snapshottedInput });
121
+ },
122
+ [ctx.client, submitMut],
60
123
  );
61
124
  const active = claimMut.isPending || submitMut.isPending;
62
- const latest = [claimMut, submitMut].find((m) => m.isError || m.isSuccess) ?? claimMut;
125
+ const latest = lastAction.current === "submit" ? submitMut : claimMut;
63
126
 
64
127
  return {
65
128
  claim,
66
129
  submit,
67
130
  status: active ? "pending" : mutationStatusOf(latest),
68
131
  signature: latest.data ?? null,
69
- error: claimMut.error ?? submitMut.error ?? null,
132
+ error: latest.error ?? null,
70
133
  isPending: active,
71
134
  reset: () => {
135
+ lastAction.current = null;
72
136
  claimMut.reset();
73
137
  submitMut.reset();
74
138
  },
@@ -2,16 +2,13 @@
2
2
  * `useWalletSigner()` — bridges a browser wallet into the kit `TransactionSigner`
3
3
  * the SDK write client expects.
4
4
  *
5
- * ## Adapter seam (the signer-adapters package is not built yet)
5
+ * ## Adapter seam
6
6
  *
7
- * The dedicated `@tetsuo-ai/signer-adapters` package (the signers agent, PLAN.md
8
- * P4.1) — which wraps `@solana/react`'s
9
- * `useWalletAccountTransactionSendingSigner` (Wallet Standard) and the legacy
10
- * `@solana/wallet-adapter` shim into a kit `TransactionSigner` — does not exist
11
- * at this hook's build time. So this hook is defined against a **documented
12
- * adapter interface** ({@link WalletSignerAdapter}) rather than importing that
13
- * package. A caller passes an adapter (today: a thin wrapper they write, or the
14
- * signer-adapters hook once it ships) and this hook normalizes it to the
7
+ * The package's Wallet Standard and legacy wallet-adapter bridges produce kit
8
+ * `TransactionSigner`s, while this hook stays defined against a small
9
+ * **documented adapter interface** ({@link WalletSignerAdapter}) so it does not
10
+ * own any wallet library's connection lifecycle. A caller passes its adapter
11
+ * state and this hook normalizes it to the
15
12
  * `{ signer, connected, connect() }` contract every other hook expects.
16
13
  *
17
14
  * With NO adapter passed, the hook falls back to the provider's configured
@@ -29,10 +26,9 @@ import { useAgencContext } from "../provider/context.js";
29
26
  import type { TransactionSigner } from "../types.js";
30
27
 
31
28
  /**
32
- * The minimal adapter shape this hook bridges. The forthcoming
33
- * `@tetsuo-ai/signer-adapters` hook is expected to return exactly this shape
34
- * (its `signerFromWalletAccount(...)` resolves the `signer`); until it ships,
35
- * any object matching this interface works.
29
+ * The minimal adapter shape this hook bridges. Any wallet connection hook can
30
+ * return this shape after resolving its signer with `signerFromWalletAccount`
31
+ * or `signerFromWalletAdapter`.
36
32
  */
37
33
  export interface WalletSignerAdapter {
38
34
  /** The resolved kit signer, or null when no wallet is connected. */
@@ -70,8 +66,7 @@ export interface UseWalletSignerResult {
70
66
  *
71
67
  * @example
72
68
  * ```tsx
73
- * // Once @tetsuo-ai/signer-adapters ships:
74
- * const adapter = useWalletStandardSigner(); // returns WalletSignerAdapter
69
+ * const adapter = useMyWalletConnection(); // returns WalletSignerAdapter
75
70
  * const { signer, connected, connect } = useWalletSigner({ adapter });
76
71
  * ```
77
72
  */
@@ -83,7 +78,7 @@ export function useWalletSigner(
83
78
 
84
79
  // Adapter wins when present; otherwise the provider's configured signer.
85
80
  const signer: TransactionSigner | null =
86
- adapter?.signer ?? ctx.signer ?? null;
81
+ adapter !== undefined ? adapter.signer : (ctx.signer ?? null);
87
82
  const connected =
88
83
  adapter !== undefined
89
84
  ? (adapter.connected ?? adapter.signer !== null)
package/src/index.ts CHANGED
@@ -70,11 +70,14 @@ export {
70
70
  signerFromEmbeddedWallet,
71
71
  signerFromWalletAccount,
72
72
  signerFromWalletAdapter,
73
+ walletStandardChainForNetwork,
74
+ type ChainBoundTransactionSigner,
73
75
  type EmbeddedWalletConnection,
74
76
  type EmbeddedWalletProvider,
75
77
  type SignerFromWalletAccountOptions,
76
78
  type SignerFromWalletAdapterOptions,
77
79
  type SignerStringId,
80
+ type SolanaWalletNetwork,
78
81
  type VersionedTransactionCtor,
79
82
  type VersionedTransactionLike,
80
83
  type WalletAdapterLike,
@@ -9,9 +9,8 @@
9
9
  * into `client` for hook e2e, and a mock {@link ReadTransport} plugs into
10
10
  * `queryTransport`.
11
11
  *
12
- * SSR-safe: no `window`/`document` access at module scope or during render; all
13
- * resolution is pure. The provider memoizes the context value and the
14
- * QueryClient on config identity so SSR + hydration stay stable.
12
+ * SSR-safe: no `window`/`document` access at module scope or during render. The
13
+ * provider memoizes the context value and QueryClient on config identity.
15
14
  *
16
15
  * @module provider/AgencProvider
17
16
  */
@@ -22,6 +21,7 @@ import {
22
21
  } from "@tanstack/react-query";
23
22
  import { createMarketplaceClient } from "@tetsuo-ai/marketplace-sdk";
24
23
  import { useMemo, useState, type ReactNode } from "react";
24
+ import { walletStandardChainForNetwork } from "../signers/wallet-account.js";
25
25
  import { createReadTransport } from "../transport/index.js";
26
26
  import type {
27
27
  AgencContextValue,
@@ -66,6 +66,53 @@ const DEFAULT_QUERY_CLIENT_CONFIG: QueryClientConfig = {
66
66
  },
67
67
  };
68
68
 
69
+ // Opaque override objects do not expose a deployment id. Give each one a
70
+ // process-local identity so switching objects is cache-safe. Persisted/SSR
71
+ // caches should use config.cacheNamespace for a stable cross-runtime id.
72
+ const OPAQUE_DEPLOYMENT_IDS = new WeakMap<object, number>();
73
+ let nextOpaqueDeploymentId = 1;
74
+
75
+ function opaqueDeploymentId(value: object | undefined): number | null {
76
+ if (value === undefined) return null;
77
+ const existing = OPAQUE_DEPLOYMENT_IDS.get(value);
78
+ if (existing !== undefined) return existing;
79
+ const allocated = nextOpaqueDeploymentId++;
80
+ OPAQUE_DEPLOYMENT_IDS.set(value, allocated);
81
+ return allocated;
82
+ }
83
+
84
+ /** Keep credentials/private labels out of query keys (identity use only). */
85
+ function cacheFingerprint(value: string | null | undefined): string | null {
86
+ if (value == null) return null;
87
+ let hash = 0xcbf29ce484222325n;
88
+ for (let index = 0; index < value.length; index += 1) {
89
+ hash ^= BigInt(value.charCodeAt(index));
90
+ hash = BigInt.asUintN(64, hash * 0x100000001b3n);
91
+ }
92
+ return hash.toString(16).padStart(16, "0");
93
+ }
94
+
95
+ function resolveCacheNamespace(
96
+ config: AgencProviderConfig,
97
+ network: AgencNetwork,
98
+ rpcUrl: string | null,
99
+ ): string {
100
+ const explicit = config.cacheNamespace?.trim();
101
+ if (config.cacheNamespace !== undefined && !explicit) {
102
+ throw new TypeError("AgencProvider cacheNamespace must not be empty.");
103
+ }
104
+ return JSON.stringify({
105
+ version: 1,
106
+ network,
107
+ rpc: cacheFingerprint(rpcUrl),
108
+ indexer: cacheFingerprint(config.indexer?.baseUrl),
109
+ custom: cacheFingerprint(explicit),
110
+ queryTransport:
111
+ explicit === undefined ? opaqueDeploymentId(config.queryTransport) : null,
112
+ client: explicit === undefined ? opaqueDeploymentId(config.client) : null,
113
+ });
114
+ }
115
+
69
116
  /**
70
117
  * Build the read transport from config. The `queryTransport` override wins;
71
118
  * otherwise indexer-first (when `indexer.baseUrl` is set) with a gPA fallback
@@ -114,6 +161,25 @@ function buildWriteClient(
114
161
  });
115
162
  }
116
163
 
164
+ /** Validate wallet-bridge signers with chain metadata; generic signers are opaque. */
165
+ function assertSignerMatchesNetwork(
166
+ signer: unknown,
167
+ network: AgencNetwork,
168
+ source: string,
169
+ ): void {
170
+ const chain =
171
+ typeof signer === "object" && signer !== null && "chain" in signer
172
+ ? (signer as { readonly chain?: unknown }).chain
173
+ : undefined;
174
+ if (typeof chain !== "string") return;
175
+ const expected = walletStandardChainForNetwork(network);
176
+ if (chain !== expected) {
177
+ throw new Error(
178
+ `${source} is bound to ${chain}, but AgencProvider network ${network} requires ${expected}.`,
179
+ );
180
+ }
181
+ }
182
+
117
183
  /**
118
184
  * The AgenC provider. Place at the root of any tree that uses AgenC hooks or
119
185
  * components.
@@ -140,6 +206,13 @@ export function AgencProvider(props: AgencProviderProps): ReactNode {
140
206
  const value = useMemo<AgencContextValue>(() => {
141
207
  const network: AgencNetwork = config.network ?? "mainnet";
142
208
 
209
+ assertSignerMatchesNetwork(config.signer, network, "config.signer");
210
+ assertSignerMatchesNetwork(
211
+ config.client?.signer,
212
+ network,
213
+ "config.client.signer",
214
+ );
215
+
143
216
  // Validate + normalize referrer at provider construction. A bad config
144
217
  // throws here, before any hire transaction can be built.
145
218
  const referrer: ValidatedReferrerConfig | null = config.referrer
@@ -158,12 +231,31 @@ export function AgencProvider(props: AgencProviderProps): ReactNode {
158
231
  config.rpcUrl,
159
232
  config.rpcSubscriptionsUrl,
160
233
  );
234
+ // A custom write client is an opaque deployment seam. Never couple it to
235
+ // the selected network's implicit endpoint: reconciliation against the
236
+ // wrong cluster can block a valid local/custom transaction or, worse,
237
+ // produce misleading state evidence. An explicitly supplied URL remains
238
+ // opt-in; an injected RPC wins over either URL path.
239
+ const orchestrationRpcUrl =
240
+ config.orchestrationRpc !== undefined
241
+ ? null
242
+ : config.client !== undefined
243
+ ? (config.rpcUrl ?? null)
244
+ : (rpcUrl ?? null);
245
+ const cacheNamespace = resolveCacheNamespace(
246
+ config,
247
+ network,
248
+ rpcUrl ?? null,
249
+ );
161
250
 
162
251
  return {
163
252
  network,
253
+ cacheNamespace,
164
254
  read,
165
255
  client,
166
256
  rpcUrl: rpcUrl ?? null,
257
+ orchestrationRpc: config.orchestrationRpc ?? null,
258
+ orchestrationRpcUrl,
167
259
  indexerBaseUrl: config.indexer?.baseUrl ?? null,
168
260
  signer: config.signer ?? null,
169
261
  referrer,
@@ -3,7 +3,7 @@
3
3
  *
4
4
  * ## REFERRER SETTLEMENT
5
5
  *
6
- * Referrer args + the 4th settlement leg are part of the full 84-instruction
6
+ * Referrer args + the 4th settlement leg are part of the full
7
7
  * surface. The SDK `facade.hireFromListing` and
8
8
  * `facade.hireFromListingHumanless` both accept referrer fields. This module:
9
9
  * - ACCEPTS + VALIDATES `referrer: { wallet, feeBps }` and stores the normalized
@@ -37,13 +37,19 @@ const signer = signerFromWalletAccount(account, {
37
37
  // -> <AgencProvider config={{ signer, rpcUrl }}>
38
38
  ```
39
39
 
40
- `signerFromWalletAccount` serializes each transaction, hands it to the wallet's
41
- `solana:signTransaction` feature, and decodes the returned (possibly modified)
42
- signed transaction to recover **this** account's signature.
43
-
44
- > The forthcoming `useWalletSigner()` hook (A2) is expected to own the
45
- > connect/selection lifecycle and call `signerFromWalletAccount` internally —
46
- > these functions are its building blocks.
40
+ `signerFromWalletAccount` sends one variadic `solana:signTransaction` request,
41
+ requires one ordered response per input, and recovers **this** account's
42
+ signature only after checking that the returned message is byte-identical and
43
+ the signature verifies over it. A wallet that rewrites a transaction is
44
+ rejected because the SDK submits the original message.
45
+
46
+ Pass `network` or `chain` explicitly when an account supports more than one
47
+ Solana chain. The returned signer carries that chain identity, and
48
+ `AgencProvider` rejects a mismatch with its configured network.
49
+
50
+ `useWalletSigner()` normalizes an application's connection state after it has
51
+ resolved one of these signers; the application still owns wallet selection and
52
+ connect/disconnect lifecycle.
47
53
 
48
54
  ## 2. Legacy `@solana/wallet-adapter` — `signerFromWalletAdapter`
49
55
 
@@ -16,7 +16,10 @@
16
16
  */
17
17
 
18
18
  // Wallet Standard bridge (the supported browser-wallet path).
19
- export { signerFromWalletAccount } from "./wallet-account.js";
19
+ export {
20
+ signerFromWalletAccount,
21
+ walletStandardChainForNetwork,
22
+ } from "./wallet-account.js";
20
23
 
21
24
  // Legacy @solana/wallet-adapter compatibility shim (optional, no hard dep).
22
25
  export {
@@ -36,9 +39,11 @@ export { signerFromEmbeddedWallet } from "./embedded-wallet.js";
36
39
 
37
40
  // The signer-adapter contracts (the seam the hooks/components/templates bind to).
38
41
  export type {
42
+ ChainBoundTransactionSigner,
39
43
  EmbeddedWalletConnection,
40
44
  EmbeddedWalletProvider,
41
45
  SignerFromWalletAccountOptions,
46
+ SolanaWalletNetwork,
42
47
  TransactionSigner,
43
48
  WalletStandardAccountLike,
44
49
  WalletStandardSignTransaction,
@@ -15,7 +15,19 @@ export const EN_SIGNER_STRINGS = {
15
15
  "signer.walletNoSignFeature":
16
16
  "Wallet account {address} does not expose a solana:signTransaction feature. Pass options.signTransaction explicitly, or use a Wallet Standard account that supports transaction signing.",
17
17
  "signer.walletNoSignature":
18
- "The wallet returned no signature for account {address}. The wallet may have rejected or modified the transaction so the fee-payer signature is absent.",
18
+ "The wallet returned no signature for account {address}. The wallet may have rejected the signing request.",
19
+ "signer.walletResponseCount":
20
+ "Wallet returned {got} signed transactions; expected {expected} ordered outputs, one per input.",
21
+ "signer.walletModifiedTransaction":
22
+ "Wallet modified the transaction message for account {address}. AgenC cannot attach a signature over different bytes to the original transaction.",
23
+ "signer.walletInvalidSignature":
24
+ "Wallet returned an invalid signature for account {address} over the requested transaction message.",
25
+ "signer.walletChainRequired":
26
+ "Wallet account {address} exposes {count} Solana chains. Select exactly one with options.chain or options.network.",
27
+ "signer.walletChainUnsupported":
28
+ "Wallet account {address} does not support requested chain {chain}.",
29
+ "signer.walletChainNetworkMismatch":
30
+ "Requested chain {chain} does not match options.network {network} ({expected}).",
19
31
  "signer.embeddedSignatureCount":
20
32
  "Embedded wallet returned {got} signatures for {expected} transactions; expected one per transaction.",
21
33
  "signer.walletAdapterDisconnected":