@tetsuo-ai/marketplace-react 0.1.1 → 0.2.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 (58) hide show
  1. package/CHANGELOG.md +21 -3
  2. package/README.md +50 -20
  3. package/dist/{chunk-ABS77JB2.js → chunk-D2TDU3TJ.js} +3 -3
  4. package/dist/{chunk-ABS77JB2.js.map → chunk-D2TDU3TJ.js.map} +1 -1
  5. package/dist/{chunk-GN5DYVN5.js → chunk-ECU7HGO3.js} +6 -5
  6. package/dist/chunk-ECU7HGO3.js.map +1 -0
  7. package/dist/{chunk-YORZNYZZ.js → chunk-FAIRTAIB.js} +53 -17
  8. package/dist/chunk-FAIRTAIB.js.map +1 -0
  9. package/dist/{chunk-5OTKSRHM.js → chunk-MNJ2EQDJ.js} +3 -3
  10. package/dist/{chunk-5OTKSRHM.js.map → chunk-MNJ2EQDJ.js.map} +1 -1
  11. package/dist/{chunk-A7ETZFNH.js → chunk-WJUVTFJ7.js} +6 -6
  12. package/dist/chunk-WJUVTFJ7.js.map +1 -0
  13. package/dist/components/index.cjs +47 -16
  14. package/dist/components/index.cjs.map +1 -1
  15. package/dist/components/index.d.cts +2 -2
  16. package/dist/components/index.d.ts +2 -2
  17. package/dist/components/index.js +3 -3
  18. package/dist/hooks/index.cjs +350 -28
  19. package/dist/hooks/index.cjs.map +1 -1
  20. package/dist/hooks/index.d.cts +160 -36
  21. package/dist/hooks/index.d.ts +160 -36
  22. package/dist/hooks/index.js +299 -19
  23. package/dist/hooks/index.js.map +1 -1
  24. package/dist/{index-zLJX8XdK.d.ts → index-C9R3B80j.d.ts} +29 -37
  25. package/dist/{index-DUsGVhDz.d.cts → index-CTTh1ZPg.d.cts} +29 -37
  26. package/dist/index.cjs +68 -32
  27. package/dist/index.cjs.map +1 -1
  28. package/dist/index.d.cts +10 -19
  29. package/dist/index.d.ts +10 -19
  30. package/dist/index.js +17 -12
  31. package/dist/index.js.map +1 -1
  32. package/dist/signers/index.cjs +4 -3
  33. package/dist/signers/index.cjs.map +1 -1
  34. package/dist/signers/index.js +2 -2
  35. package/dist/{useAgentTrackRecord-BLf1nrbu.d.cts → useAgentTrackRecord-BCvRHYM2.d.cts} +7 -7
  36. package/dist/{useAgentTrackRecord-BLf1nrbu.d.ts → useAgentTrackRecord-BCvRHYM2.d.ts} +7 -7
  37. package/package.json +3 -2
  38. package/src/components/HireButton.tsx +1 -2
  39. package/src/components/HireCheckoutModal.tsx +8 -9
  40. package/src/components/ReferrerDisclosure.tsx +8 -12
  41. package/src/components/strings.ts +2 -2
  42. package/src/hooks/index.ts +47 -4
  43. package/src/hooks/internal.ts +74 -2
  44. package/src/hooks/useHire.ts +30 -38
  45. package/src/hooks/useHumanlessHireFlow.ts +259 -0
  46. package/src/hooks/useRateHire.ts +52 -0
  47. package/src/hooks/useReferrerEarnings.ts +32 -33
  48. package/src/hooks/useTaskActivation.ts +58 -0
  49. package/src/hooks/useTaskLifecycle.ts +110 -0
  50. package/src/hooks/useTaskWork.ts +76 -0
  51. package/src/index.ts +2 -2
  52. package/src/provider/AgencProvider.tsx +3 -3
  53. package/src/provider/referrer.ts +24 -32
  54. package/src/strings/index.ts +5 -3
  55. package/src/types.ts +7 -10
  56. package/dist/chunk-A7ETZFNH.js.map +0 -1
  57. package/dist/chunk-GN5DYVN5.js.map +0 -1
  58. package/dist/chunk-YORZNYZZ.js.map +0 -1
@@ -1,23 +1,20 @@
1
1
  /**
2
- * `useReferrerEarnings(wallet)` — referrer earnings (STRICTLY P6.2-GATED).
2
+ * `useReferrerEarnings(wallet)` — referrer earnings (indexer-gated).
3
3
  *
4
- * ## THE P6.2 GATE (PLAN_2 §0, MANDATORY — this hook is the canonical example)
4
+ * ## EARNINGS INDEXER GATE
5
5
  *
6
- * Referrer earnings depend on TWO unbuilt things:
7
- * 1. the on-chain P6.2 referrer fields snapshotted on `HireRecord` (the 4th
8
- * settlement leg), and
9
- * 2. the off-chain `GET /api/explorer/referrers/:wallet/hires` indexer endpoint
10
- * that aggregates them.
6
+ * Referrer settlement is live in the protocol. Aggregated referrer earnings still
7
+ * depend on the off-chain `GET /api/explorer/referrers/:wallet/hires` indexer
8
+ * endpoint that sums paid referral events.
11
9
  *
12
- * NEITHER exists today. So this hook:
10
+ * That endpoint is not published yet. So this hook:
13
11
  * - resolves `resolveReferrerCapability()` from context;
14
- * - when `live === false` (ALWAYS, today): returns the documented not-live
12
+ * - when the earnings indexer is not live: returns the documented not-live
15
13
  * state `{ live: false, totalLamports: 0n, hires: [] }` and makes NO network
16
14
  * request. It NEVER fabricates earnings and NEVER infers a non-zero total
17
15
  * from anything.
18
- * - the real fetch path is written but DEAD-CODE-GATED behind `capability.live`
19
- * with a clear TODO, so when P6.2 + the endpoint land, only the gate flips —
20
- * the surface does not change.
16
+ * - the real fetch path is written but gated behind `EARNINGS_INDEXER_LIVE`, so
17
+ * when the endpoint lands, only the gate flips — the surface does not change.
21
18
  *
22
19
  * @module hooks/useReferrerEarnings
23
20
  */
@@ -27,7 +24,9 @@ import { t } from "../strings/index.js";
27
24
  import type { Address } from "../types.js";
28
25
  import { pdaKey, queryKeys } from "./internal.js";
29
26
 
30
- /** A single referral-earning hire (shape defined now; populated post-P6.2). */
27
+ const EARNINGS_INDEXER_LIVE = false;
28
+
29
+ /** A single referral-earning hire (shape defined now; populated once the earnings indexer ships). */
31
30
  export interface ReferrerHire {
32
31
  /** The minted Task PDA of the referred hire. */
33
32
  taskPda: string;
@@ -42,16 +41,16 @@ export interface ReferrerHire {
42
41
  /** Return value of {@link useReferrerEarnings}. */
43
42
  export interface UseReferrerEarningsResult {
44
43
  /**
45
- * Whether referral settlement is live on this cluster. ALWAYS `false` today
46
- * (the P6.2 gate). When false, the numbers below are the documented not-live
47
- * zero state, not real data.
44
+ * Whether aggregated referral earnings are live. Settlement may be live even
45
+ * when this is false; false means the numbers below are the documented
46
+ * not-live zero state, not real data.
48
47
  */
49
48
  live: boolean;
50
49
  /** Total lamports earned. `0n` while not live (never fabricated). */
51
50
  totalLamports: bigint;
52
51
  /** Per-hire earnings. `[]` while not live. */
53
52
  hires: ReferrerHire[];
54
- /** True while a (post-P6.2) fetch is in flight. Always false today. */
53
+ /** True while a fetch is in flight. Always false until the earnings indexer ships. */
55
54
  isLoading: boolean;
56
55
  /** The fetch error, or null. */
57
56
  error: Error | null;
@@ -69,12 +68,13 @@ export interface UseReferrerEarningsResult {
69
68
  *
70
69
  * @param wallet - The referrer wallet (base58 / Address). Falsy disables the
71
70
  * (future) fetch; the not-live state is still returned.
72
- * @returns {@link UseReferrerEarningsResult} — the not-live zero state today.
71
+ * @returns {@link UseReferrerEarningsResult} — the not-live zero state until
72
+ * the earnings indexer ships.
73
73
  *
74
74
  * @example
75
75
  * ```tsx
76
76
  * const { live, totalLamports, hires, reason } = useReferrerEarnings(myWallet);
77
- * // today: live === false, totalLamports === 0n, hires === []
77
+ * // until the earnings indexer ships: live === false, totalLamports === 0n, hires === []
78
78
  * ```
79
79
  */
80
80
  export function useReferrerEarnings(
@@ -83,30 +83,27 @@ export function useReferrerEarnings(
83
83
  const ctx = useAgencContext();
84
84
  const capability = ctx.resolveReferrerCapability();
85
85
 
86
- // THE GATE: the query is enabled ONLY when referral settlement is live. Today
87
- // `capability.live` is hardcoded false, so this query never runs and we
88
- // return the not-live zero state below. NEVER remove this gate.
89
- const enabled = capability.live && Boolean(wallet);
86
+ // THE GATE: settlement can be live while the aggregate earnings indexer is not.
87
+ // Keep this false until the endpoint is published.
88
+ const enabled = capability.live && EARNINGS_INDEXER_LIVE && Boolean(wallet);
90
89
 
91
90
  const query = useQuery<{ totalLamports: bigint; hires: ReferrerHire[] }, Error>(
92
91
  {
93
92
  queryKey: queryKeys.referrerEarnings(wallet ? pdaKey(wallet) : ""),
94
93
  enabled,
95
94
  queryFn: async () => {
96
- // TODO(P6.2 / indexer): once the referrer fields exist on HireRecord
97
- // AND the indexer exposes `GET /api/explorer/referrers/:wallet/hires`,
98
- // fetch + sum here. Unreachable today because `enabled` is gated on
99
- // `capability.live` (hardcoded false). Returning fabricated numbers
100
- // here would violate PLAN_2 §0 — do not.
95
+ // TODO(indexer): once `GET /api/explorer/referrers/:wallet/hires` is
96
+ // published, fetch + sum here. Returning fabricated numbers here would
97
+ // violate the money-surface contract.
101
98
  throw new Error(
102
- "useReferrerEarnings: the P6.2 referrer earnings path is not " +
103
- "deployed; this query must never run while capability.live is false.",
99
+ "useReferrerEarnings: the referrer earnings indexer is not deployed; " +
100
+ "this query must never run while EARNINGS_INDEXER_LIVE is false.",
104
101
  );
105
102
  },
106
103
  },
107
104
  );
108
105
 
109
- if (!capability.live) {
106
+ if (!capability.live || !EARNINGS_INDEXER_LIVE) {
110
107
  // The documented not-live state. Zeroes are HONEST (no data exists), not
111
108
  // fabricated, and no request was made.
112
109
  return {
@@ -115,14 +112,16 @@ export function useReferrerEarnings(
115
112
  hires: [],
116
113
  isLoading: false,
117
114
  error: null,
118
- reason: capability.reason ?? t("referrer.notLiveReason"),
115
+ reason: capability.live
116
+ ? t("referrer.earningsNotLiveReason")
117
+ : (capability.reason ?? t("referrer.notLiveReason")),
119
118
  refetch: () => {
120
119
  /* no-op while not live */
121
120
  },
122
121
  };
123
122
  }
124
123
 
125
- // --- Post-P6.2 path (currently unreachable; kept wired for the flip) ---
124
+ // --- Post-indexer path (currently unreachable; kept wired for the flip) ---
126
125
  return {
127
126
  live: true,
128
127
  totalLamports: query.data?.totalLamports ?? 0n,
@@ -0,0 +1,58 @@
1
+ import { useMutation } from "@tanstack/react-query";
2
+ import { useCallback } from "react";
3
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
4
+ import { useAgencContext } from "../provider/context.js";
5
+ import {
6
+ mutationStatusOf,
7
+ requireClient,
8
+ type MutationStatus,
9
+ } from "./internal.js";
10
+
11
+ export type TaskActivationInput = Omit<
12
+ Parameters<typeof facadeNs.setTaskJobSpec>[0],
13
+ "task" | "creator"
14
+ > & {
15
+ creator?: Parameters<typeof facadeNs.setTaskJobSpec>[0]["creator"];
16
+ };
17
+
18
+ export type TaskActivationStatus = MutationStatus;
19
+
20
+ export interface UseTaskActivationResult {
21
+ activate: (input: TaskActivationInput) => Promise<string>;
22
+ status: TaskActivationStatus;
23
+ signature: string | null;
24
+ error: Error | null;
25
+ isPending: boolean;
26
+ reset: () => void;
27
+ }
28
+
29
+ export function useTaskActivation(
30
+ taskPda: Parameters<typeof facadeNs.setTaskJobSpec>[0]["task"],
31
+ ): UseTaskActivationResult {
32
+ const ctx = useAgencContext();
33
+ const mutation = useMutation<string, Error, TaskActivationInput>({
34
+ mutationFn: async (input) => {
35
+ const client = requireClient(ctx.client);
36
+ const { signature } = await client.setTaskJobSpec({
37
+ ...input,
38
+ task: taskPda,
39
+ creator: input.creator ?? client.signer,
40
+ } as Parameters<typeof facadeNs.setTaskJobSpec>[0]);
41
+ return signature;
42
+ },
43
+ });
44
+
45
+ const activate = useCallback(
46
+ (input: TaskActivationInput) => mutation.mutateAsync(input),
47
+ [mutation],
48
+ );
49
+
50
+ return {
51
+ activate,
52
+ status: mutationStatusOf(mutation),
53
+ signature: mutation.data ?? null,
54
+ error: mutation.error ?? null,
55
+ isPending: mutation.isPending,
56
+ reset: mutation.reset,
57
+ };
58
+ }
@@ -0,0 +1,110 @@
1
+ import { useMutation } from "@tanstack/react-query";
2
+ import { useCallback } from "react";
3
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
4
+ import { useAgencContext } from "../provider/context.js";
5
+ import {
6
+ mutationStatusOf,
7
+ requireClient,
8
+ type MutationStatus,
9
+ } from "./internal.js";
10
+
11
+ export type CancelTaskInput = Omit<
12
+ Parameters<typeof facadeNs.cancelTask>[0],
13
+ "task" | "authority"
14
+ > & {
15
+ authority?: Parameters<typeof facadeNs.cancelTask>[0]["authority"];
16
+ };
17
+ export type CloseTaskInput = Omit<
18
+ Parameters<typeof facadeNs.closeTask>[0],
19
+ "task" | "authority"
20
+ > & {
21
+ authority?: Parameters<typeof facadeNs.closeTask>[0]["authority"];
22
+ };
23
+ export type AutoAcceptTaskResultInput = Omit<
24
+ Parameters<typeof facadeNs.autoAcceptTaskResult>[0],
25
+ "task" | "authority"
26
+ > & {
27
+ authority?: Parameters<typeof facadeNs.autoAcceptTaskResult>[0]["authority"];
28
+ };
29
+ export type TaskLifecycleStatus = MutationStatus;
30
+
31
+ export interface UseTaskLifecycleResult {
32
+ cancel: (input?: CancelTaskInput) => Promise<string>;
33
+ close: (input?: CloseTaskInput) => Promise<string>;
34
+ autoAccept: (input: AutoAcceptTaskResultInput) => Promise<string>;
35
+ status: TaskLifecycleStatus;
36
+ signature: string | null;
37
+ error: Error | null;
38
+ isPending: boolean;
39
+ reset: () => void;
40
+ }
41
+
42
+ export function useTaskLifecycle(
43
+ taskPda: Parameters<typeof facadeNs.cancelTask>[0]["task"],
44
+ ): UseTaskLifecycleResult {
45
+ const ctx = useAgencContext();
46
+ const cancelMut = useMutation<string, Error, CancelTaskInput | undefined>({
47
+ mutationFn: async (input) => {
48
+ const client = requireClient(ctx.client);
49
+ const { signature } = await client.cancelTask({
50
+ ...(input ?? {}),
51
+ task: taskPda,
52
+ authority: input?.authority ?? client.signer,
53
+ } as Parameters<typeof facadeNs.cancelTask>[0]);
54
+ return signature;
55
+ },
56
+ });
57
+ const closeMut = useMutation<string, Error, CloseTaskInput | undefined>({
58
+ mutationFn: async (input) => {
59
+ const client = requireClient(ctx.client);
60
+ const { signature } = await client.closeTask({
61
+ ...(input ?? {}),
62
+ task: taskPda,
63
+ authority: input?.authority ?? client.signer,
64
+ } as Parameters<typeof facadeNs.closeTask>[0]);
65
+ return signature;
66
+ },
67
+ });
68
+ const autoAcceptMut = useMutation<string, Error, AutoAcceptTaskResultInput>({
69
+ mutationFn: async (input) => {
70
+ const client = requireClient(ctx.client);
71
+ const { signature } = await client.autoAcceptTaskResult({
72
+ ...input,
73
+ task: taskPda,
74
+ authority: input.authority ?? client.signer,
75
+ } as Parameters<typeof facadeNs.autoAcceptTaskResult>[0]);
76
+ return signature;
77
+ },
78
+ });
79
+
80
+ const cancel = useCallback(
81
+ (input?: CancelTaskInput) => cancelMut.mutateAsync(input),
82
+ [cancelMut],
83
+ );
84
+ const close = useCallback(
85
+ (input?: CloseTaskInput) => closeMut.mutateAsync(input),
86
+ [closeMut],
87
+ );
88
+ const autoAccept = useCallback(
89
+ (input: AutoAcceptTaskResultInput) => autoAcceptMut.mutateAsync(input),
90
+ [autoAcceptMut],
91
+ );
92
+ const active = cancelMut.isPending || closeMut.isPending || autoAcceptMut.isPending;
93
+ const latest =
94
+ [cancelMut, closeMut, autoAcceptMut].find((m) => m.isError || m.isSuccess) ?? cancelMut;
95
+
96
+ return {
97
+ cancel,
98
+ close,
99
+ autoAccept,
100
+ status: active ? "pending" : mutationStatusOf(latest),
101
+ signature: latest.data ?? null,
102
+ error: cancelMut.error ?? closeMut.error ?? autoAcceptMut.error ?? null,
103
+ isPending: active,
104
+ reset: () => {
105
+ cancelMut.reset();
106
+ closeMut.reset();
107
+ autoAcceptMut.reset();
108
+ },
109
+ };
110
+ }
@@ -0,0 +1,76 @@
1
+ import { useMutation } from "@tanstack/react-query";
2
+ import { useCallback } from "react";
3
+ import type { facade as facadeNs } from "@tetsuo-ai/marketplace-sdk";
4
+ import { useAgencContext } from "../provider/context.js";
5
+ import {
6
+ mutationStatusOf,
7
+ requireClient,
8
+ type MutationStatus,
9
+ } from "./internal.js";
10
+
11
+ export type ClaimTaskInput = Omit<
12
+ Parameters<typeof facadeNs.claimTaskWithJobSpec>[0],
13
+ "task"
14
+ >;
15
+ export type SubmitTaskResultInput = Omit<
16
+ Parameters<typeof facadeNs.submitTaskResult>[0],
17
+ "task"
18
+ >;
19
+ export type TaskWorkStatus = MutationStatus;
20
+
21
+ export interface UseTaskWorkResult {
22
+ claim: (input: ClaimTaskInput) => Promise<string>;
23
+ submit: (input: SubmitTaskResultInput) => Promise<string>;
24
+ status: TaskWorkStatus;
25
+ signature: string | null;
26
+ error: Error | null;
27
+ isPending: boolean;
28
+ reset: () => void;
29
+ }
30
+
31
+ export function useTaskWork(
32
+ taskPda: Parameters<typeof facadeNs.claimTaskWithJobSpec>[0]["task"],
33
+ ): UseTaskWorkResult {
34
+ const ctx = useAgencContext();
35
+ const claimMut = useMutation<string, Error, ClaimTaskInput>({
36
+ mutationFn: async (input) => {
37
+ const client = requireClient(ctx.client);
38
+ const { signature } = await client.claimTaskWithJobSpec({
39
+ ...input,
40
+ task: taskPda,
41
+ } as Parameters<typeof facadeNs.claimTaskWithJobSpec>[0]);
42
+ return signature;
43
+ },
44
+ });
45
+ const submitMut = useMutation<string, Error, SubmitTaskResultInput>({
46
+ mutationFn: async (input) => {
47
+ const client = requireClient(ctx.client);
48
+ const { signature } = await client.submitTaskResult({
49
+ ...input,
50
+ task: taskPda,
51
+ } as Parameters<typeof facadeNs.submitTaskResult>[0]);
52
+ return signature;
53
+ },
54
+ });
55
+
56
+ const claim = useCallback((input: ClaimTaskInput) => claimMut.mutateAsync(input), [claimMut]);
57
+ const submit = useCallback(
58
+ (input: SubmitTaskResultInput) => submitMut.mutateAsync(input),
59
+ [submitMut],
60
+ );
61
+ const active = claimMut.isPending || submitMut.isPending;
62
+ const latest = [claimMut, submitMut].find((m) => m.isError || m.isSuccess) ?? claimMut;
63
+
64
+ return {
65
+ claim,
66
+ submit,
67
+ status: active ? "pending" : mutationStatusOf(latest),
68
+ signature: latest.data ?? null,
69
+ error: claimMut.error ?? submitMut.error ?? null,
70
+ isPending: active,
71
+ reset: () => {
72
+ claimMut.reset();
73
+ submitMut.reset();
74
+ },
75
+ };
76
+ }
package/src/index.ts CHANGED
@@ -4,9 +4,9 @@
4
4
  *
5
5
  * This barrel exposes the FOUNDATION layer (PLAN.md P4.2 / PLAN_2 Part A):
6
6
  * - `<AgencProvider>` + `useAgencContext()` — the one context wiring reads,
7
- * writes, and the (P6.2-gated) referrer config;
7
+ * writes, and the live referrer config;
8
8
  * - `createReadTransport()` — indexer-first read transport with gPA fallback;
9
- * - the referrer validation + capability gate (`resolveReferrerCapability()`,
9
+ * - the referrer validation + capability resolver (`resolveReferrerCapability()`,
10
10
  * not-live today per PLAN_2 §0);
11
11
  * - the `--agenc-*` theme contract helpers + the English string catalog.
12
12
  *
@@ -1,6 +1,6 @@
1
1
  /**
2
2
  * `<AgencProvider>` — the one context that wires reads, writes, and the
3
- * (P6.2-gated) referrer config for every AgenC hook/component beneath it.
3
+ * live referrer config for every AgenC hook/component beneath it.
4
4
  *
5
5
  * Wraps a bundled TanStack {@link QueryClientProvider} so hooks get
6
6
  * caching/refetch/optimistic states with no consumer config. The
@@ -140,8 +140,8 @@ export function AgencProvider(props: AgencProviderProps): ReactNode {
140
140
  const value = useMemo<AgencContextValue>(() => {
141
141
  const network: AgencNetwork = config.network ?? "mainnet";
142
142
 
143
- // Validate + normalize referrer ALWAYS (the P6.2 gate decides injection,
144
- // not validation). A bad config throws here, at provider construction.
143
+ // Validate + normalize referrer at provider construction. A bad config
144
+ // throws here, before any hire transaction can be built.
145
145
  const referrer: ValidatedReferrerConfig | null = config.referrer
146
146
  ? validateReferrerConfig(config.referrer)
147
147
  : null;
@@ -1,21 +1,19 @@
1
1
  /**
2
- * Referrer config validation + the P6.2 capability gate.
2
+ * Referrer config validation + the live referral-settlement capability.
3
3
  *
4
- * ## THE P6.2 GATE (PLAN_2 §0, MANDATORY)
4
+ * ## REFERRER SETTLEMENT
5
5
  *
6
- * Referrer args + the 4th settlement leg are an UNBUILT Phase-6 on-chain change
7
- * (PLAN.md P6.2). The SDK `facade.hireFromListing` has NO referrer params yet.
8
- * So this module:
6
+ * Referrer args + the 4th settlement leg are part of the full 84-instruction
7
+ * surface. The SDK `facade.hireFromListing` and
8
+ * `facade.hireFromListingHumanless` both accept referrer fields. This module:
9
9
  * - ACCEPTS + VALIDATES `referrer: { wallet, feeBps }` and stores the normalized
10
10
  * form (validation is real: bad base58 throws, out-of-range bps rejected);
11
- * - exposes {@link resolveReferrerCapability}, which currently returns
12
- * `{ live: false, reason: "P6.2 not deployed" }` — HARDCODED false today, with
13
- * a clear TODO citing P6.2 / P6.5 `getDeployedSurface` as the future signal.
11
+ * - exposes {@link resolveReferrerCapability}, which reports live when a valid
12
+ * referrer config is present.
14
13
  *
15
- * When NOT live (today, always): referrer is NEVER injected into a hire, the
16
- * earnings hook returns a documented not-live state, and disclosure UI may still
17
- * SHOW "this site earns a referral fee (pending protocol support)". We NEVER
18
- * fake earnings or silently inject.
14
+ * Aggregated earnings are separate from settlement. `useReferrerEarnings` still
15
+ * remains indexer-gated and must not fabricate totals before that endpoint is
16
+ * published.
19
17
  *
20
18
  * @module provider/referrer
21
19
  */
@@ -31,12 +29,11 @@ import type {
31
29
  /** Minimum referral fee, in basis points. */
32
30
  export const REFERRER_FEE_BPS_MIN = 0;
33
31
  /**
34
- * Maximum referral fee, in basis points. 10000 bps = 100%. The on-chain P6.2
35
- * leg will enforce its own cap; this client-side bound is a sane outer guard so
36
- * an obviously-wrong config (e.g. a typo'd 99999) is rejected at provider
37
- * construction rather than silently stored.
32
+ * Maximum referral fee, in basis points. Mirrors the on-chain per-leg cap
33
+ * (`MAX_REFERRER_FEE_BPS = 2000`) so invalid provider config fails before the
34
+ * user signs a transaction.
38
35
  */
39
- export const REFERRER_FEE_BPS_MAX = 10_000;
36
+ export const REFERRER_FEE_BPS_MAX = 2_000;
40
37
 
41
38
  /**
42
39
  * Validate + normalize a raw {@link ReferrerConfig} into a
@@ -71,27 +68,22 @@ export function validateReferrerConfig(
71
68
  }
72
69
 
73
70
  /**
74
- * Resolve whether a referral fee can actually be charged on the target cluster.
75
- *
76
- * THE P6.2 GATE — returns `live: false` UNCONDITIONALLY today.
77
- *
78
- * TODO(P6.2 / P6.5): once the on-chain referrer args + 4th settlement leg
79
- * (PLAN.md P6.2) are deployed, replace the hardcoded `false` with a real check
80
- * against P6.5 `getDeployedSurface` for the target cluster. Until then, returning
81
- * a truthy `live` here would cause silent fee injection against a program that
82
- * cannot honor it — strictly forbidden by PLAN_2 §0.
71
+ * Resolve whether a referral fee can actually be charged by this provider.
83
72
  *
84
73
  * @param referrer - The validated referrer config under the provider, or null.
85
- * @returns A {@link ReferrerCapability} (always `{ live: false, ... }` today).
74
+ * @returns A {@link ReferrerCapability}; live only when a referrer is configured.
86
75
  */
87
76
  export function resolveReferrerCapability(
88
77
  referrer: ValidatedReferrerConfig | null,
89
78
  ): ReferrerCapability {
90
- // P6.2 GATE: hardcoded not-live. Do NOT make this conditionally true until
91
- // P6.2 is deployed AND P6.5 getDeployedSurface confirms it on the cluster.
79
+ if (!referrer) {
80
+ return {
81
+ live: false,
82
+ reason: t("referrer.notLiveReason"),
83
+ };
84
+ }
92
85
  return {
93
- live: false,
94
- reason: t("referrer.notLiveReason"),
95
- ...(referrer ? { referrer } : {}),
86
+ live: true,
87
+ referrer,
96
88
  };
97
89
  }
@@ -41,15 +41,17 @@ export const EN_STRINGS = {
41
41
  "provider.missingSigner":
42
42
  "No signer is configured on <AgencProvider>. Connect a wallet or pass config.signer.",
43
43
 
44
- // Referrer config validation (the P6.2 gate surface).
44
+ // Referrer config validation / capability surface.
45
45
  "referrer.invalidWallet":
46
46
  "Referrer wallet is not a valid base58 Solana address: {wallet}.",
47
47
  "referrer.invalidFeeBps":
48
48
  "Referrer feeBps must be an integer between {min} and {max} (basis points); got {feeBps}.",
49
49
  "referrer.notLive":
50
- "This site earns a referral fee (pending protocol support).",
50
+ "Referral fee is not active for this hire.",
51
51
  "referrer.notLiveReason":
52
- "Referral settlement is not yet deployed on this cluster (PLAN.md P6.2). Referrer config is accepted and validated but not injected into hires.",
52
+ "No referrer is configured for this provider.",
53
+ "referrer.earningsNotLiveReason":
54
+ "Referral settlement is live, but aggregated referrer earnings are not yet exposed by the indexer.",
53
55
 
54
56
  // Read transport.
55
57
  "transport.noReadSource":
package/src/types.ts CHANGED
@@ -110,8 +110,8 @@ export type AgencNetwork = "localnet" | "devnet" | "mainnet";
110
110
 
111
111
  /**
112
112
  * Referrer configuration. Accepted + validated + stored ALWAYS; injected into
113
- * hires only when {@link ReferrerCapability.live} is true (the P6.2 gate — not
114
- * today). See {@link resolveReferrerCapability}.
113
+ * hires only when {@link ReferrerCapability.live} is true. See
114
+ * {@link resolveReferrerCapability}.
115
115
  */
116
116
  export interface ReferrerConfig {
117
117
  /** Referrer wallet that earns the fee. Must be a valid base58 address. */
@@ -138,11 +138,9 @@ export interface ValidatedReferrerConfig {
138
138
  * The runtime answer to "can a referral fee actually be charged on this
139
139
  * cluster?". Returned by `resolveReferrerCapability()`.
140
140
  *
141
- * THE P6.2 GATE: `live` is hardcoded `false` today because the on-chain
142
- * referrer args + 4th settlement leg (PLAN.md P6.2) are unbuilt. When it ships,
143
- * this resolver will consult P6.5 `getDeployedSurface` instead. Until then:
144
- * referrer is never injected, earnings hooks return a documented not-live
145
- * state, and disclosure UI may still show the pending-support copy.
141
+ * Referrer settlement is live on the full 84-instruction surface. `live` is true
142
+ * when a validated provider referrer is configured. Aggregated earnings remain a
143
+ * separate indexer-gated read surface.
146
144
  */
147
145
  export interface ReferrerCapability {
148
146
  /** Whether referral settlement is live on the target cluster. */
@@ -169,7 +167,7 @@ export interface AgencProviderConfig {
169
167
  rpcSubscriptionsUrl?: string;
170
168
  /** Indexer connection — presence of `indexer.baseUrl` selects indexer-first. */
171
169
  indexer?: IndexerConfig;
172
- /** Referrer config (accepted + validated; injected only when P6.2 is live). */
170
+ /** Referrer config (accepted + validated; injected into hire transactions). */
173
171
  referrer?: ReferrerConfig;
174
172
  /** Signer for write operations (the kit `TransactionSigner`). */
175
173
  signer?: TransactionSigner;
@@ -205,8 +203,7 @@ export interface AgencContextValue {
205
203
  /** Validated referrer config, or `null` when none was supplied. */
206
204
  referrer: ValidatedReferrerConfig | null;
207
205
  /**
208
- * Resolve whether referral settlement is live on this cluster (the P6.2
209
- * gate). Today always `{ live: false, ... }`.
206
+ * Resolve whether this provider has a live referral-settlement config.
210
207
  */
211
208
  resolveReferrerCapability(): ReferrerCapability;
212
209
  }