@tetsuo-ai/marketplace-react 0.1.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.
- package/CHANGELOG.md +28 -0
- package/LICENSE +21 -0
- package/README.md +172 -0
- package/dist/chunk-5OTKSRHM.js +128 -0
- package/dist/chunk-5OTKSRHM.js.map +1 -0
- package/dist/chunk-ABS77JB2.js +94 -0
- package/dist/chunk-ABS77JB2.js.map +1 -0
- package/dist/chunk-GN5DYVN5.js +35 -0
- package/dist/chunk-GN5DYVN5.js.map +1 -0
- package/dist/chunk-KJMR6OGC.js +1198 -0
- package/dist/chunk-KJMR6OGC.js.map +1 -0
- package/dist/chunk-YORZNYZZ.js +107 -0
- package/dist/chunk-YORZNYZZ.js.map +1 -0
- package/dist/components/agenc-components.css +570 -0
- package/dist/components/index.cjs +1335 -0
- package/dist/components/index.cjs.map +1 -0
- package/dist/components/index.d.cts +5 -0
- package/dist/components/index.d.ts +5 -0
- package/dist/components/index.js +5 -0
- package/dist/components/index.js.map +1 -0
- package/dist/hooks/index.cjs +493 -0
- package/dist/hooks/index.cjs.map +1 -0
- package/dist/hooks/index.d.cts +294 -0
- package/dist/hooks/index.d.ts +294 -0
- package/dist/hooks/index.js +339 -0
- package/dist/hooks/index.js.map +1 -0
- package/dist/index-BLrlBVj-.d.cts +1129 -0
- package/dist/index-CKTYsNPH.d.ts +1129 -0
- package/dist/index.cjs +1690 -0
- package/dist/index.cjs.map +1 -0
- package/dist/index.d.cts +235 -0
- package/dist/index.d.ts +235 -0
- package/dist/index.js +127 -0
- package/dist/index.js.map +1 -0
- package/dist/signers/index.cjs +166 -0
- package/dist/signers/index.cjs.map +1 -0
- package/dist/signers/index.d.cts +136 -0
- package/dist/signers/index.d.ts +136 -0
- package/dist/signers/index.js +4 -0
- package/dist/signers/index.js.map +1 -0
- package/dist/testing/index.cjs +62 -0
- package/dist/testing/index.cjs.map +1 -0
- package/dist/testing/index.d.cts +71 -0
- package/dist/testing/index.d.ts +71 -0
- package/dist/testing/index.js +60 -0
- package/dist/testing/index.js.map +1 -0
- package/dist/theme/agenc-tailwind-preset.cjs +184 -0
- package/dist/theme/agenc-tokens.css +132 -0
- package/dist/types-jvISR6bc.d.cts +135 -0
- package/dist/types-jvISR6bc.d.ts +135 -0
- package/dist/useAgentTrackRecord-BLf1nrbu.d.cts +249 -0
- package/dist/useAgentTrackRecord-BLf1nrbu.d.ts +249 -0
- package/package.json +139 -0
- package/src/components/DisputeBanner.stories.tsx +39 -0
- package/src/components/DisputeBanner.tsx +110 -0
- package/src/components/HireButton.stories.tsx +72 -0
- package/src/components/HireButton.tsx +151 -0
- package/src/components/HireCheckoutModal.stories.tsx +107 -0
- package/src/components/HireCheckoutModal.tsx +284 -0
- package/src/components/ListingCard.stories.tsx +55 -0
- package/src/components/ListingCard.tsx +148 -0
- package/src/components/ListingGrid.stories.tsx +44 -0
- package/src/components/ListingGrid.tsx +137 -0
- package/src/components/Modal.tsx +121 -0
- package/src/components/PoweredByAgenC.tsx +85 -0
- package/src/components/ProviderCard.stories.tsx +61 -0
- package/src/components/ProviderCard.tsx +154 -0
- package/src/components/ReferrerDisclosure.tsx +67 -0
- package/src/components/ReviewPanel.stories.tsx +65 -0
- package/src/components/ReviewPanel.tsx +141 -0
- package/src/components/TaskTimeline.stories.tsx +43 -0
- package/src/components/TaskTimeline.tsx +156 -0
- package/src/components/__fixtures__/index.tsx +173 -0
- package/src/components/agenc-components.css +570 -0
- package/src/components/badges.tsx +115 -0
- package/src/components/format.ts +150 -0
- package/src/components/index.ts +102 -0
- package/src/components/primitives.tsx +236 -0
- package/src/components/strings.ts +131 -0
- package/src/components/useFocusTrap.ts +122 -0
- package/src/hooks/index.ts +90 -0
- package/src/hooks/internal.ts +70 -0
- package/src/hooks/useAgentTrackRecord.ts +166 -0
- package/src/hooks/useDispute.ts +130 -0
- package/src/hooks/useHire.ts +198 -0
- package/src/hooks/useListing.ts +138 -0
- package/src/hooks/useListings.ts +133 -0
- package/src/hooks/useReferrerEarnings.ts +134 -0
- package/src/hooks/useSubmissionReview.ts +179 -0
- package/src/hooks/useTaskStatus.ts +192 -0
- package/src/hooks/useWalletSigner.ts +99 -0
- package/src/index.ts +170 -0
- package/src/provider/AgencProvider.tsx +169 -0
- package/src/provider/context.ts +35 -0
- package/src/provider/index.ts +17 -0
- package/src/provider/network.ts +68 -0
- package/src/provider/referrer.ts +97 -0
- package/src/signers/README.md +130 -0
- package/src/signers/embedded-wallet-mock.ts +158 -0
- package/src/signers/embedded-wallet.ts +64 -0
- package/src/signers/index.ts +48 -0
- package/src/signers/strings.ts +39 -0
- package/src/signers/types.ts +158 -0
- package/src/signers/wallet-account.ts +128 -0
- package/src/signers/wallet-adapter.ts +149 -0
- package/src/strings/index.ts +119 -0
- package/src/testing/index.ts +24 -0
- package/src/theme/agenc-tailwind-preset.cjs +184 -0
- package/src/theme/agenc-tokens.css +132 -0
- package/src/theme/index.ts +94 -0
- package/src/transport/index.ts +164 -0
- package/src/types.ts +224 -0
|
@@ -0,0 +1,169 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* `<AgencProvider>` — the one context that wires reads, writes, and the
|
|
3
|
+
* (P6.2-gated) referrer config for every AgenC hook/component beneath it.
|
|
4
|
+
*
|
|
5
|
+
* Wraps a bundled TanStack {@link QueryClientProvider} so hooks get
|
|
6
|
+
* caching/refetch/optimistic states with no consumer config. The
|
|
7
|
+
* {@link AgencProviderConfig.client} and {@link AgencProviderConfig.queryTransport}
|
|
8
|
+
* slots are PUBLIC test seams: `startLocalMarketplace().client` plugs straight
|
|
9
|
+
* into `client` for hook e2e, and a mock {@link ReadTransport} plugs into
|
|
10
|
+
* `queryTransport`.
|
|
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.
|
|
15
|
+
*
|
|
16
|
+
* @module provider/AgencProvider
|
|
17
|
+
*/
|
|
18
|
+
import {
|
|
19
|
+
QueryClient,
|
|
20
|
+
QueryClientProvider,
|
|
21
|
+
type QueryClientConfig,
|
|
22
|
+
} from "@tanstack/react-query";
|
|
23
|
+
import { createMarketplaceClient } from "@tetsuo-ai/marketplace-sdk";
|
|
24
|
+
import { useMemo, useState, type ReactNode } from "react";
|
|
25
|
+
import { createReadTransport } from "../transport/index.js";
|
|
26
|
+
import type {
|
|
27
|
+
AgencContextValue,
|
|
28
|
+
AgencNetwork,
|
|
29
|
+
AgencProviderConfig,
|
|
30
|
+
MarketplaceClient,
|
|
31
|
+
ReadTransport,
|
|
32
|
+
ValidatedReferrerConfig,
|
|
33
|
+
} from "../types.js";
|
|
34
|
+
import { AgencContext } from "./context.js";
|
|
35
|
+
import { resolveEndpoints } from "./network.js";
|
|
36
|
+
import {
|
|
37
|
+
resolveReferrerCapability as resolveReferrerCapabilityImpl,
|
|
38
|
+
validateReferrerConfig,
|
|
39
|
+
} from "./referrer.js";
|
|
40
|
+
|
|
41
|
+
/** Props for {@link AgencProvider}. */
|
|
42
|
+
export interface AgencProviderProps {
|
|
43
|
+
/** Provider configuration. See {@link AgencProviderConfig}. */
|
|
44
|
+
config: AgencProviderConfig;
|
|
45
|
+
/**
|
|
46
|
+
* Optional pre-built TanStack QueryClient. When omitted, the provider creates
|
|
47
|
+
* one lazily (stable across renders). Pass your own to share a cache with the
|
|
48
|
+
* rest of your app.
|
|
49
|
+
*/
|
|
50
|
+
queryClient?: QueryClient;
|
|
51
|
+
/** Override config for the lazily-created QueryClient (ignored if you pass one). */
|
|
52
|
+
queryClientConfig?: QueryClientConfig;
|
|
53
|
+
children: ReactNode;
|
|
54
|
+
}
|
|
55
|
+
|
|
56
|
+
/** Default QueryClient tuning for marketplace reads (sane, overridable). */
|
|
57
|
+
const DEFAULT_QUERY_CLIENT_CONFIG: QueryClientConfig = {
|
|
58
|
+
defaultOptions: {
|
|
59
|
+
queries: {
|
|
60
|
+
// Marketplace listings change on-chain slowly relative to a UI session;
|
|
61
|
+
// a short stale window avoids refetch storms while staying fresh.
|
|
62
|
+
staleTime: 15_000,
|
|
63
|
+
retry: 1,
|
|
64
|
+
refetchOnWindowFocus: false,
|
|
65
|
+
},
|
|
66
|
+
},
|
|
67
|
+
};
|
|
68
|
+
|
|
69
|
+
/**
|
|
70
|
+
* Build the read transport from config. The `queryTransport` override wins;
|
|
71
|
+
* otherwise indexer-first (when `indexer.baseUrl` is set) with a gPA fallback
|
|
72
|
+
* over the resolved RPC URL.
|
|
73
|
+
*
|
|
74
|
+
* NOTE: the gPA fallback needs a kit `Rpc<GetProgramAccountsApi>`, which we do
|
|
75
|
+
* NOT build here from a bare URL — the SDK write client owns RPC construction.
|
|
76
|
+
* When only a URL (no indexer, no queryTransport) is available, reads require
|
|
77
|
+
* an indexer; the transport factory throws a descriptive error on first use.
|
|
78
|
+
*/
|
|
79
|
+
function buildReadTransport(
|
|
80
|
+
config: AgencProviderConfig,
|
|
81
|
+
): ReadTransport {
|
|
82
|
+
return createReadTransport({
|
|
83
|
+
indexer: config.indexer,
|
|
84
|
+
queryTransport: config.queryTransport,
|
|
85
|
+
// The gPA read source is provided only via queryTransport in v1 (a kit RPC
|
|
86
|
+
// or ProgramAccountsTransport). A future revision can derive a kit RPC from
|
|
87
|
+
// the resolved rpcUrl; for now indexer-first is the supported read path and
|
|
88
|
+
// queryTransport is the test/mocks seam.
|
|
89
|
+
});
|
|
90
|
+
}
|
|
91
|
+
|
|
92
|
+
/**
|
|
93
|
+
* Build the write client from config. The `client` override wins. Otherwise a
|
|
94
|
+
* client is built only when BOTH a resolvable `rpcUrl` and a `signer` exist;
|
|
95
|
+
* absent either, the provider exposes `client: null` and mutating hooks surface
|
|
96
|
+
* a clear error (read-only / indexer-only setups are valid).
|
|
97
|
+
*/
|
|
98
|
+
function buildWriteClient(
|
|
99
|
+
config: AgencProviderConfig,
|
|
100
|
+
network: AgencNetwork,
|
|
101
|
+
): MarketplaceClient | null {
|
|
102
|
+
if (config.client) return config.client;
|
|
103
|
+
if (!config.signer) return null;
|
|
104
|
+
const { rpcUrl, rpcSubscriptionsUrl } = resolveEndpoints(
|
|
105
|
+
network,
|
|
106
|
+
config.rpcUrl,
|
|
107
|
+
config.rpcSubscriptionsUrl,
|
|
108
|
+
);
|
|
109
|
+
if (rpcUrl === null) return null;
|
|
110
|
+
return createMarketplaceClient({
|
|
111
|
+
rpcUrl,
|
|
112
|
+
...(rpcSubscriptionsUrl ? { rpcSubscriptionsUrl } : {}),
|
|
113
|
+
signer: config.signer,
|
|
114
|
+
});
|
|
115
|
+
}
|
|
116
|
+
|
|
117
|
+
/**
|
|
118
|
+
* The AgenC provider. Place at the root of any tree that uses AgenC hooks or
|
|
119
|
+
* components.
|
|
120
|
+
*
|
|
121
|
+
* @example
|
|
122
|
+
* ```tsx
|
|
123
|
+
* <AgencProvider config={{ network: "devnet", indexer: { baseUrl } }}>
|
|
124
|
+
* <App />
|
|
125
|
+
* </AgencProvider>
|
|
126
|
+
* ```
|
|
127
|
+
*/
|
|
128
|
+
export function AgencProvider(props: AgencProviderProps): ReactNode {
|
|
129
|
+
const { config, children } = props;
|
|
130
|
+
|
|
131
|
+
// Lazily create (and keep stable) the QueryClient. useState initializer runs
|
|
132
|
+
// once; passing your own `queryClient` overrides it.
|
|
133
|
+
const [internalQueryClient] = useState<QueryClient>(
|
|
134
|
+
() =>
|
|
135
|
+
props.queryClient ??
|
|
136
|
+
new QueryClient(props.queryClientConfig ?? DEFAULT_QUERY_CLIENT_CONFIG),
|
|
137
|
+
);
|
|
138
|
+
const queryClient = props.queryClient ?? internalQueryClient;
|
|
139
|
+
|
|
140
|
+
const value = useMemo<AgencContextValue>(() => {
|
|
141
|
+
const network: AgencNetwork = config.network ?? "mainnet";
|
|
142
|
+
|
|
143
|
+
// Validate + normalize referrer ALWAYS (the P6.2 gate decides injection,
|
|
144
|
+
// not validation). A bad config throws here, at provider construction.
|
|
145
|
+
const referrer: ValidatedReferrerConfig | null = config.referrer
|
|
146
|
+
? validateReferrerConfig(config.referrer)
|
|
147
|
+
: null;
|
|
148
|
+
|
|
149
|
+
const read = buildReadTransport(config);
|
|
150
|
+
const client = buildWriteClient(config, network);
|
|
151
|
+
|
|
152
|
+
return {
|
|
153
|
+
network,
|
|
154
|
+
read,
|
|
155
|
+
client,
|
|
156
|
+
signer: config.signer ?? null,
|
|
157
|
+
referrer,
|
|
158
|
+
resolveReferrerCapability: () => resolveReferrerCapabilityImpl(referrer),
|
|
159
|
+
};
|
|
160
|
+
// Re-resolve when any wiring input changes. Referrer object identity is
|
|
161
|
+
// intentionally part of the deps (a new referrer config must re-validate).
|
|
162
|
+
}, [config]);
|
|
163
|
+
|
|
164
|
+
return (
|
|
165
|
+
<QueryClientProvider client={queryClient}>
|
|
166
|
+
<AgencContext.Provider value={value}>{children}</AgencContext.Provider>
|
|
167
|
+
</QueryClientProvider>
|
|
168
|
+
);
|
|
169
|
+
}
|
|
@@ -0,0 +1,35 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* The React context object + the internal `useAgencContext()` hook.
|
|
3
|
+
*
|
|
4
|
+
* Split from the component file so the context identity is stable and so hooks
|
|
5
|
+
* can import the context without pulling the JSX provider into their module
|
|
6
|
+
* graph. SSR-safe: this module only calls `createContext` at import time, never
|
|
7
|
+
* touches `window`.
|
|
8
|
+
*
|
|
9
|
+
* @module provider/context
|
|
10
|
+
*/
|
|
11
|
+
import { createContext, useContext } from "react";
|
|
12
|
+
import { t } from "../strings/index.js";
|
|
13
|
+
import type { AgencContextValue } from "../types.js";
|
|
14
|
+
|
|
15
|
+
/**
|
|
16
|
+
* The AgenC context. `null` until a `<AgencProvider>` mounts above the consumer
|
|
17
|
+
* — {@link useAgencContext} turns that into a clear developer error.
|
|
18
|
+
*/
|
|
19
|
+
export const AgencContext = createContext<AgencContextValue | null>(null);
|
|
20
|
+
AgencContext.displayName = "AgencContext";
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* Read the AgenC context. INTERNAL hook the package's own hooks build on; also
|
|
24
|
+
* exported from the package root so downstream hooks (components agent) can
|
|
25
|
+
* reach the resolved transport/client/referrer.
|
|
26
|
+
*
|
|
27
|
+
* @throws Error when called outside a `<AgencProvider>`.
|
|
28
|
+
*/
|
|
29
|
+
export function useAgencContext(): AgencContextValue {
|
|
30
|
+
const ctx = useContext(AgencContext);
|
|
31
|
+
if (ctx === null) {
|
|
32
|
+
throw new Error(t("provider.missingContext"));
|
|
33
|
+
}
|
|
34
|
+
return ctx;
|
|
35
|
+
}
|
|
@@ -0,0 +1,17 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Provider surface barrel.
|
|
3
|
+
* @module provider
|
|
4
|
+
*/
|
|
5
|
+
export { AgencProvider, type AgencProviderProps } from "./AgencProvider.js";
|
|
6
|
+
export { AgencContext, useAgencContext } from "./context.js";
|
|
7
|
+
export {
|
|
8
|
+
REFERRER_FEE_BPS_MAX,
|
|
9
|
+
REFERRER_FEE_BPS_MIN,
|
|
10
|
+
resolveReferrerCapability,
|
|
11
|
+
validateReferrerConfig,
|
|
12
|
+
} from "./referrer.js";
|
|
13
|
+
export {
|
|
14
|
+
deriveSubscriptionsUrl,
|
|
15
|
+
resolveEndpoints,
|
|
16
|
+
type ResolvedEndpoints,
|
|
17
|
+
} from "./network.js";
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Network → endpoint defaults.
|
|
3
|
+
*
|
|
4
|
+
* Reuses the resolution philosophy of the SDK sandbox env seam
|
|
5
|
+
* (`resolveSandboxEnvironment`): explicit config beats a per-network default,
|
|
6
|
+
* and the WebSocket endpoint is derived from the HTTP one when not given. This
|
|
7
|
+
* is intentionally a SMALL, synchronous, SSR-safe mirror — the provider needs
|
|
8
|
+
* no `process`/`fs` access and the sandbox seam's async file-reading path.
|
|
9
|
+
*
|
|
10
|
+
* @module provider/network
|
|
11
|
+
*/
|
|
12
|
+
import type { AgencNetwork } from "../types.js";
|
|
13
|
+
|
|
14
|
+
/** Per-network default HTTP RPC endpoints. `mainnet` has no public default. */
|
|
15
|
+
const NETWORK_HTTP_DEFAULTS: Record<AgencNetwork, string | null> = {
|
|
16
|
+
localnet: "http://127.0.0.1:8899",
|
|
17
|
+
devnet: "https://api.devnet.solana.com",
|
|
18
|
+
// No public default: mainnet RPC is operator-supplied (rate/cost sensitive).
|
|
19
|
+
mainnet: null,
|
|
20
|
+
};
|
|
21
|
+
|
|
22
|
+
/**
|
|
23
|
+
* `solana-test-validator` serves PubSub on RPC port + 1 (8900), so localnet's
|
|
24
|
+
* WS endpoint is NOT derivable from the HTTP URL by scheme swap alone.
|
|
25
|
+
*/
|
|
26
|
+
const NETWORK_WS_DEFAULTS: Record<AgencNetwork, string | null> = {
|
|
27
|
+
localnet: "ws://127.0.0.1:8900",
|
|
28
|
+
devnet: "wss://api.devnet.solana.com",
|
|
29
|
+
mainnet: null,
|
|
30
|
+
};
|
|
31
|
+
|
|
32
|
+
/** Derive a ws(s) endpoint from an http(s) one (same host/port/path). */
|
|
33
|
+
export function deriveSubscriptionsUrl(rpcUrl: string): string {
|
|
34
|
+
if (/^https:\/\//i.test(rpcUrl)) {
|
|
35
|
+
return `wss://${rpcUrl.slice("https://".length)}`;
|
|
36
|
+
}
|
|
37
|
+
if (/^http:\/\//i.test(rpcUrl)) {
|
|
38
|
+
return `ws://${rpcUrl.slice("http://".length)}`;
|
|
39
|
+
}
|
|
40
|
+
return rpcUrl;
|
|
41
|
+
}
|
|
42
|
+
|
|
43
|
+
/** A resolved pair of RPC endpoints (either may be `null` when unresolvable). */
|
|
44
|
+
export interface ResolvedEndpoints {
|
|
45
|
+
rpcUrl: string | null;
|
|
46
|
+
rpcSubscriptionsUrl: string | null;
|
|
47
|
+
}
|
|
48
|
+
|
|
49
|
+
/**
|
|
50
|
+
* Resolve the HTTP + WS RPC endpoints for a network, honoring explicit
|
|
51
|
+
* overrides. Returns `{ rpcUrl: null }` when neither an override nor a default
|
|
52
|
+
* exists (mainnet with no `rpcUrl`) — the provider treats that as "no write
|
|
53
|
+
* client buildable from URLs", not a throw, so a read-only/indexer-only or
|
|
54
|
+
* `client`-override setup still works.
|
|
55
|
+
*/
|
|
56
|
+
export function resolveEndpoints(
|
|
57
|
+
network: AgencNetwork,
|
|
58
|
+
rpcUrl?: string,
|
|
59
|
+
rpcSubscriptionsUrl?: string,
|
|
60
|
+
): ResolvedEndpoints {
|
|
61
|
+
const resolvedRpc = rpcUrl ?? NETWORK_HTTP_DEFAULTS[network];
|
|
62
|
+
const resolvedWs =
|
|
63
|
+
rpcSubscriptionsUrl ??
|
|
64
|
+
(rpcUrl !== undefined
|
|
65
|
+
? deriveSubscriptionsUrl(rpcUrl)
|
|
66
|
+
: NETWORK_WS_DEFAULTS[network]);
|
|
67
|
+
return { rpcUrl: resolvedRpc, rpcSubscriptionsUrl: resolvedWs };
|
|
68
|
+
}
|
|
@@ -0,0 +1,97 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Referrer config validation + the P6.2 capability gate.
|
|
3
|
+
*
|
|
4
|
+
* ## THE P6.2 GATE (PLAN_2 §0, MANDATORY)
|
|
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:
|
|
9
|
+
* - ACCEPTS + VALIDATES `referrer: { wallet, feeBps }` and stores the normalized
|
|
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.
|
|
14
|
+
*
|
|
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.
|
|
19
|
+
*
|
|
20
|
+
* @module provider/referrer
|
|
21
|
+
*/
|
|
22
|
+
import { isAddress } from "@solana/kit";
|
|
23
|
+
import { t } from "../strings/index.js";
|
|
24
|
+
import type {
|
|
25
|
+
Address,
|
|
26
|
+
ReferrerCapability,
|
|
27
|
+
ReferrerConfig,
|
|
28
|
+
ValidatedReferrerConfig,
|
|
29
|
+
} from "../types.js";
|
|
30
|
+
|
|
31
|
+
/** Minimum referral fee, in basis points. */
|
|
32
|
+
export const REFERRER_FEE_BPS_MIN = 0;
|
|
33
|
+
/**
|
|
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.
|
|
38
|
+
*/
|
|
39
|
+
export const REFERRER_FEE_BPS_MAX = 10_000;
|
|
40
|
+
|
|
41
|
+
/**
|
|
42
|
+
* Validate + normalize a raw {@link ReferrerConfig} into a
|
|
43
|
+
* {@link ValidatedReferrerConfig}.
|
|
44
|
+
*
|
|
45
|
+
* @throws TypeError when `wallet` is not a valid base58 Solana address.
|
|
46
|
+
* @throws RangeError when `feeBps` is not an integer in
|
|
47
|
+
* `[REFERRER_FEE_BPS_MIN, REFERRER_FEE_BPS_MAX]`.
|
|
48
|
+
*/
|
|
49
|
+
export function validateReferrerConfig(
|
|
50
|
+
config: ReferrerConfig,
|
|
51
|
+
): ValidatedReferrerConfig {
|
|
52
|
+
const { wallet, feeBps } = config;
|
|
53
|
+
if (typeof wallet !== "string" || !isAddress(wallet)) {
|
|
54
|
+
throw new TypeError(t("referrer.invalidWallet", { wallet: String(wallet) }));
|
|
55
|
+
}
|
|
56
|
+
if (
|
|
57
|
+
typeof feeBps !== "number" ||
|
|
58
|
+
!Number.isInteger(feeBps) ||
|
|
59
|
+
feeBps < REFERRER_FEE_BPS_MIN ||
|
|
60
|
+
feeBps > REFERRER_FEE_BPS_MAX
|
|
61
|
+
) {
|
|
62
|
+
throw new RangeError(
|
|
63
|
+
t("referrer.invalidFeeBps", {
|
|
64
|
+
min: REFERRER_FEE_BPS_MIN,
|
|
65
|
+
max: REFERRER_FEE_BPS_MAX,
|
|
66
|
+
feeBps: String(feeBps),
|
|
67
|
+
}),
|
|
68
|
+
);
|
|
69
|
+
}
|
|
70
|
+
return { wallet: wallet as Address, feeBps };
|
|
71
|
+
}
|
|
72
|
+
|
|
73
|
+
/**
|
|
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.
|
|
83
|
+
*
|
|
84
|
+
* @param referrer - The validated referrer config under the provider, or null.
|
|
85
|
+
* @returns A {@link ReferrerCapability} (always `{ live: false, ... }` today).
|
|
86
|
+
*/
|
|
87
|
+
export function resolveReferrerCapability(
|
|
88
|
+
referrer: ValidatedReferrerConfig | null,
|
|
89
|
+
): 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.
|
|
92
|
+
return {
|
|
93
|
+
live: false,
|
|
94
|
+
reason: t("referrer.notLiveReason"),
|
|
95
|
+
...(referrer ? { referrer } : {}),
|
|
96
|
+
};
|
|
97
|
+
}
|
|
@@ -0,0 +1,130 @@
|
|
|
1
|
+
# Signer adapters — browser wallet → kit `TransactionSigner`
|
|
2
|
+
|
|
3
|
+
`@tetsuo-ai/marketplace-react/signers` (also re-exported from the package root)
|
|
4
|
+
turns a browser wallet into the kit `TransactionSigner` the SDK's
|
|
5
|
+
`createMarketplaceClient` consumes. Pass the result as `<AgencProvider config={{
|
|
6
|
+
signer }}>`.
|
|
7
|
+
|
|
8
|
+
> **Why a PARTIAL signer, not a sending signer.** The SDK client signs with
|
|
9
|
+
> `signTransactionMessageWithSigners(...)` and submits through its **own**
|
|
10
|
+
> transport. `signTransactionMessageWithSigners` deliberately **ignores**
|
|
11
|
+
> `TransactionSendingSigner`s. So every adapter here produces a
|
|
12
|
+
> `TransactionPartialSigner` — it returns signatures; the SDK client broadcasts.
|
|
13
|
+
> If you instead let the wallet send (the
|
|
14
|
+
> `useWalletAccountTransactionSendingSigner` "modern path"), you bypass the SDK
|
|
15
|
+
> client's retry/confirm/AgencError pipeline — not what the provider wires.
|
|
16
|
+
|
|
17
|
+
## 1. Wallet Standard (recommended) — `signerFromWalletAccount`
|
|
18
|
+
|
|
19
|
+
Every modern Solana wallet registers as a Wallet Standard wallet. With
|
|
20
|
+
`@solana/react` you hold a `UiWalletAccount`; bridge it directly:
|
|
21
|
+
|
|
22
|
+
```tsx
|
|
23
|
+
import { useWalletAccountTransactionSigner } from "@solana/react";
|
|
24
|
+
import { signerFromWalletAccount } from "@tetsuo-ai/marketplace-react/signers";
|
|
25
|
+
|
|
26
|
+
// Option A — you have the UiWalletAccount and want the package to resolve the
|
|
27
|
+
// wallet's solana:signTransaction feature:
|
|
28
|
+
const signer = signerFromWalletAccount(account, { chain: "solana:devnet" });
|
|
29
|
+
|
|
30
|
+
// Option B — you already resolved the feature (e.g. from a hook) and want to
|
|
31
|
+
// inject it explicitly:
|
|
32
|
+
const signer = signerFromWalletAccount(account, {
|
|
33
|
+
chain: "solana:devnet",
|
|
34
|
+
signTransaction: account.features["solana:signTransaction"].signTransaction,
|
|
35
|
+
});
|
|
36
|
+
|
|
37
|
+
// -> <AgencProvider config={{ signer, rpcUrl }}>
|
|
38
|
+
```
|
|
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.
|
|
47
|
+
|
|
48
|
+
## 2. Legacy `@solana/wallet-adapter` — `signerFromWalletAdapter`
|
|
49
|
+
|
|
50
|
+
For apps still holding a raw wallet-adapter `WalletContextState`. **No hard
|
|
51
|
+
dependency** on `@solana/wallet-adapter-*` or `@solana/web3.js`: inject the
|
|
52
|
+
web3.js `VersionedTransaction` class (the one piece the shim can't reconstruct).
|
|
53
|
+
A kit transaction and a web3.js `VersionedTransaction` share the same wire
|
|
54
|
+
format, so the bridge is a serialize → adapter-sign → deserialize round-trip.
|
|
55
|
+
|
|
56
|
+
```tsx
|
|
57
|
+
import { VersionedTransaction } from "@solana/web3.js";
|
|
58
|
+
import { useWallet } from "@solana/wallet-adapter-react";
|
|
59
|
+
import { signerFromWalletAdapter } from "@tetsuo-ai/marketplace-react/signers";
|
|
60
|
+
|
|
61
|
+
const wallet = useWallet();
|
|
62
|
+
const signer = signerFromWalletAdapter(wallet, { VersionedTransaction });
|
|
63
|
+
```
|
|
64
|
+
|
|
65
|
+
**Prefer migrating to §1**: a wallet-adapter wallet is also a Wallet Standard
|
|
66
|
+
wallet, so reading the selected account through `@solana/react` and using
|
|
67
|
+
`signerFromWalletAccount` is the more robust long-term path. This shim is a
|
|
68
|
+
bridge, not the destination.
|
|
69
|
+
|
|
70
|
+
## 3. Walletless / embedded wallets — `signerFromEmbeddedWallet`
|
|
71
|
+
|
|
72
|
+
The "no wallet, no SOL" buyer path (Privy / Dynamic / Web3Auth email/social
|
|
73
|
+
login + custodial keys). The marketplace layer only ever sees the vendor-neutral
|
|
74
|
+
`EmbeddedWalletProvider` interface, so templates/widget toggle the vendor by
|
|
75
|
+
config without an API break:
|
|
76
|
+
|
|
77
|
+
```ts
|
|
78
|
+
interface EmbeddedWalletProvider {
|
|
79
|
+
connect(): Promise<EmbeddedWalletConnection>; // vendor login (browser gesture)
|
|
80
|
+
isConnected(): boolean;
|
|
81
|
+
getConnection(): EmbeddedWalletConnection | null;
|
|
82
|
+
disconnect?(): Promise<void>;
|
|
83
|
+
}
|
|
84
|
+
interface EmbeddedWalletConnection {
|
|
85
|
+
readonly address: string;
|
|
86
|
+
signTransactions(txs: readonly Transaction[]): Promise<readonly SignatureBytes[]>;
|
|
87
|
+
}
|
|
88
|
+
```
|
|
89
|
+
|
|
90
|
+
```ts
|
|
91
|
+
import {
|
|
92
|
+
signerFromEmbeddedWallet,
|
|
93
|
+
} from "@tetsuo-ai/marketplace-react/signers";
|
|
94
|
+
|
|
95
|
+
const connection = await provider.connect(); // email login provisions the wallet
|
|
96
|
+
const signer = signerFromEmbeddedWallet(connection);
|
|
97
|
+
// -> <AgencProvider config={{ signer, rpcUrl }}>
|
|
98
|
+
```
|
|
99
|
+
|
|
100
|
+
### The MOCK vendor (testing) — `createMockEmbeddedWallet`
|
|
101
|
+
|
|
102
|
+
> **The real vendor adapter is `[HUMAN]`-gated** (Solana tx-signing support,
|
|
103
|
+
> email/social login, custody model, pricing, SDK weight — PLAN_2 D-1). It must
|
|
104
|
+
> NOT live in this package. Only the interface above is depended on.
|
|
105
|
+
|
|
106
|
+
A working local-keypair `EmbeddedWalletProvider` so the walletless Done-when
|
|
107
|
+
runs against localnet **without** committing to a vendor. It holds a private key
|
|
108
|
+
in-process, so it is published ONLY behind the dedicated `./testing` subpath
|
|
109
|
+
(never the package root or `./signers`) and warns once if invoked under
|
|
110
|
+
`NODE_ENV=production`:
|
|
111
|
+
|
|
112
|
+
```ts
|
|
113
|
+
import { signerFromEmbeddedWallet } from "@tetsuo-ai/marketplace-react/signers";
|
|
114
|
+
// The MOCK is TEST-ONLY — import it from the ./testing subpath.
|
|
115
|
+
import { createMockEmbeddedWallet } from "@tetsuo-ai/marketplace-react/testing";
|
|
116
|
+
|
|
117
|
+
const provider = createMockEmbeddedWallet();
|
|
118
|
+
const conn = await provider.connect(); // "email login"
|
|
119
|
+
svm.airdrop(address(conn.address), lamports(1_000_000_000n)); // fund it
|
|
120
|
+
const signer = signerFromEmbeddedWallet(conn); // drive a real hire
|
|
121
|
+
```
|
|
122
|
+
|
|
123
|
+
See `test/signers/embedded-wallet.e2e.test.ts` for the full
|
|
124
|
+
provision → airdrop → hire → settle proof through `startLocalMarketplace()`.
|
|
125
|
+
|
|
126
|
+
## SSR-safety
|
|
127
|
+
|
|
128
|
+
Nothing here touches `window`/`document` at module scope. The only browser-bound
|
|
129
|
+
step is `provider.connect()` (a user gesture), which is the vendor's concern.
|
|
130
|
+
All factory functions are import-safe under Next.js App Router.
|
|
@@ -0,0 +1,158 @@
|
|
|
1
|
+
/**
|
|
2
|
+
* Local-keypair MOCK embedded-wallet adapter (PLAN_2 D-1 test seam).
|
|
3
|
+
*
|
|
4
|
+
* A WORKING {@link EmbeddedWalletProvider} backed by a freshly generated kit
|
|
5
|
+
* keypair — it stands in for a real vendor (Privy / Dynamic / Web3Auth) so the
|
|
6
|
+
* "no wallet, no SOL" Done-when runs against localnet WITHOUT committing to a
|
|
7
|
+
* vendor. `connect()` mimics "email login provisions a wallet": first call
|
|
8
|
+
* generates (or adopts a supplied) keypair; the address is then fundable by a
|
|
9
|
+
* localnet/devnet airdrop exactly like a real freshly created embedded wallet.
|
|
10
|
+
*
|
|
11
|
+
* NOT for production: it holds the private key in-process. The REAL vendor
|
|
12
|
+
* adapter is `[HUMAN]`-gated (it must NOT live here). The interface it
|
|
13
|
+
* implements is the only contract templates/widget depend on.
|
|
14
|
+
*
|
|
15
|
+
* Published ONLY behind the `@tetsuo-ai/marketplace-react/testing` subpath — it
|
|
16
|
+
* is deliberately NOT in the package root barrel or the `./signers` export, so
|
|
17
|
+
* it cannot reach a production bundle by accident. It also warns once if it is
|
|
18
|
+
* ever invoked under `NODE_ENV === "production"`.
|
|
19
|
+
*
|
|
20
|
+
* SSR-safe: generation is lazy (inside `connect()`); nothing touches `window`.
|
|
21
|
+
*
|
|
22
|
+
* @module signers/embedded-wallet-mock
|
|
23
|
+
*/
|
|
24
|
+
import {
|
|
25
|
+
createKeyPairSignerFromBytes,
|
|
26
|
+
generateKeyPairSigner,
|
|
27
|
+
type KeyPairSigner,
|
|
28
|
+
type SignatureBytes,
|
|
29
|
+
type Transaction,
|
|
30
|
+
} from "@solana/kit";
|
|
31
|
+
import type {
|
|
32
|
+
EmbeddedWalletConnection,
|
|
33
|
+
EmbeddedWalletProvider,
|
|
34
|
+
} from "./types.js";
|
|
35
|
+
|
|
36
|
+
/**
|
|
37
|
+
* One-time production guard. The mock holds a private key IN-PROCESS and must
|
|
38
|
+
* never ship to production; it lives behind the `./testing` subpath (not the
|
|
39
|
+
* root barrel) so it can't be imported by accident. As a second layer, warn
|
|
40
|
+
* loudly (once) if it is ever invoked under `NODE_ENV === "production"`.
|
|
41
|
+
*/
|
|
42
|
+
let warnedInProduction = false;
|
|
43
|
+
function warnIfProduction(): void {
|
|
44
|
+
if (warnedInProduction) return;
|
|
45
|
+
warnedInProduction = true;
|
|
46
|
+
const nodeEnv =
|
|
47
|
+
typeof process !== "undefined" ? process.env?.NODE_ENV : undefined;
|
|
48
|
+
if (nodeEnv === "production") {
|
|
49
|
+
// eslint-disable-next-line no-console
|
|
50
|
+
console.warn(
|
|
51
|
+
"[@tetsuo-ai/marketplace-react] createMockEmbeddedWallet() was called " +
|
|
52
|
+
"with NODE_ENV=production. This mock holds a private key in-process " +
|
|
53
|
+
"and is for tests ONLY — never ship it. Use a real embedded-wallet " +
|
|
54
|
+
"vendor adapter via signerFromEmbeddedWallet().",
|
|
55
|
+
);
|
|
56
|
+
}
|
|
57
|
+
}
|
|
58
|
+
|
|
59
|
+
/** Options for {@link createMockEmbeddedWallet}. */
|
|
60
|
+
export interface MockEmbeddedWalletOptions {
|
|
61
|
+
/**
|
|
62
|
+
* Adopt an existing 64-byte secret key instead of generating one (e.g. to
|
|
63
|
+
* reuse a wallet across a test or pre-seed a known address). When omitted,
|
|
64
|
+
* `connect()` generates a fresh keypair on first call — the realistic
|
|
65
|
+
* "new email user" flow.
|
|
66
|
+
*/
|
|
67
|
+
secretKeyBytes?: Uint8Array;
|
|
68
|
+
}
|
|
69
|
+
|
|
70
|
+
/**
|
|
71
|
+
* A mock embedded-wallet provider whose connection exposes the backing
|
|
72
|
+
* {@link KeyPairSigner} (test escape hatch — real vendors never leak the key).
|
|
73
|
+
*/
|
|
74
|
+
export interface MockEmbeddedWalletProvider extends EmbeddedWalletProvider {
|
|
75
|
+
connect(): Promise<MockEmbeddedWalletConnection>;
|
|
76
|
+
getConnection(): MockEmbeddedWalletConnection | null;
|
|
77
|
+
}
|
|
78
|
+
|
|
79
|
+
/** A mock connection that also surfaces the underlying keypair signer. */
|
|
80
|
+
export interface MockEmbeddedWalletConnection extends EmbeddedWalletConnection {
|
|
81
|
+
/** The local keypair signer backing this connection (test-only). */
|
|
82
|
+
readonly keyPairSigner: KeyPairSigner;
|
|
83
|
+
}
|
|
84
|
+
|
|
85
|
+
/** Lift a kit {@link KeyPairSigner} into the embedded-wallet connection shape. */
|
|
86
|
+
function connectionFromKeyPair(
|
|
87
|
+
keyPairSigner: KeyPairSigner,
|
|
88
|
+
): MockEmbeddedWalletConnection {
|
|
89
|
+
const signerAddress = keyPairSigner.address;
|
|
90
|
+
return {
|
|
91
|
+
address: signerAddress,
|
|
92
|
+
keyPairSigner,
|
|
93
|
+
async signTransactions(
|
|
94
|
+
transactions: readonly Transaction[],
|
|
95
|
+
): Promise<readonly SignatureBytes[]> {
|
|
96
|
+
// KeyPairSigner.signTransactions returns one SignatureDictionary per tx;
|
|
97
|
+
// pull THIS address's signature out of each to match the embedded
|
|
98
|
+
// connection's flat SignatureBytes[] contract.
|
|
99
|
+
const dictionaries = await keyPairSigner.signTransactions(
|
|
100
|
+
transactions as Parameters<KeyPairSigner["signTransactions"]>[0],
|
|
101
|
+
);
|
|
102
|
+
return dictionaries.map((dict, i) => {
|
|
103
|
+
const signature = dict[signerAddress];
|
|
104
|
+
if (!signature) {
|
|
105
|
+
throw new Error(
|
|
106
|
+
`mock embedded wallet: keypair produced no signature for transaction ${i}`,
|
|
107
|
+
);
|
|
108
|
+
}
|
|
109
|
+
return signature;
|
|
110
|
+
});
|
|
111
|
+
},
|
|
112
|
+
};
|
|
113
|
+
}
|
|
114
|
+
|
|
115
|
+
/**
|
|
116
|
+
* Create a local-keypair-backed mock {@link EmbeddedWalletProvider}.
|
|
117
|
+
*
|
|
118
|
+
* Use it to exercise the walletless path end-to-end: `connect()` to provision
|
|
119
|
+
* the wallet, airdrop/fund its `address`, then `signerFromEmbeddedWallet(conn)`
|
|
120
|
+
* to drive a real hire through the SDK client.
|
|
121
|
+
*
|
|
122
|
+
* @param options - Optionally adopt a known secret key.
|
|
123
|
+
* @returns A mock provider (its connection leaks the keypair, for tests only).
|
|
124
|
+
*
|
|
125
|
+
* @example
|
|
126
|
+
* ```ts
|
|
127
|
+
* const provider = createMockEmbeddedWallet();
|
|
128
|
+
* const conn = await provider.connect(); // "email login"
|
|
129
|
+
* svm.airdrop(address(conn.address), lamports(1_000_000_000n)); // fund it
|
|
130
|
+
* const signer = signerFromEmbeddedWallet(conn);
|
|
131
|
+
* ```
|
|
132
|
+
*/
|
|
133
|
+
export function createMockEmbeddedWallet(
|
|
134
|
+
options: MockEmbeddedWalletOptions = {},
|
|
135
|
+
): MockEmbeddedWalletProvider {
|
|
136
|
+
warnIfProduction();
|
|
137
|
+
let connection: MockEmbeddedWalletConnection | null = null;
|
|
138
|
+
|
|
139
|
+
return {
|
|
140
|
+
async connect(): Promise<MockEmbeddedWalletConnection> {
|
|
141
|
+
if (connection) return connection;
|
|
142
|
+
const keyPairSigner = options.secretKeyBytes
|
|
143
|
+
? await createKeyPairSignerFromBytes(options.secretKeyBytes)
|
|
144
|
+
: await generateKeyPairSigner();
|
|
145
|
+
connection = connectionFromKeyPair(keyPairSigner);
|
|
146
|
+
return connection;
|
|
147
|
+
},
|
|
148
|
+
isConnected(): boolean {
|
|
149
|
+
return connection !== null;
|
|
150
|
+
},
|
|
151
|
+
getConnection(): MockEmbeddedWalletConnection | null {
|
|
152
|
+
return connection;
|
|
153
|
+
},
|
|
154
|
+
async disconnect(): Promise<void> {
|
|
155
|
+
connection = null;
|
|
156
|
+
},
|
|
157
|
+
};
|
|
158
|
+
}
|