@redditech/x402-solana 0.0.0-stage → 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.
Files changed (46) hide show
  1. package/CHANGELOG.md +84 -0
  2. package/LICENSE +21 -0
  3. package/README.md +301 -2
  4. package/dist/budget-policy.d.ts +68 -0
  5. package/dist/budget-policy.js +234 -0
  6. package/dist/buyer.d.ts +54 -0
  7. package/dist/buyer.js +147 -0
  8. package/dist/client.d.ts +80 -0
  9. package/dist/client.js +225 -0
  10. package/dist/direct-auth.d.ts +94 -0
  11. package/dist/direct-auth.js +120 -0
  12. package/dist/direct-payment.d.ts +33 -0
  13. package/dist/direct-payment.js +65 -0
  14. package/dist/ed25519.d.ts +6 -0
  15. package/dist/ed25519.js +42 -0
  16. package/dist/escrow-http.d.ts +125 -0
  17. package/dist/escrow-http.js +192 -0
  18. package/dist/escrow-readiness.d.ts +132 -0
  19. package/dist/escrow-readiness.js +171 -0
  20. package/dist/index.d.ts +26 -0
  21. package/dist/index.js +42 -0
  22. package/dist/jupiter.d.ts +36 -0
  23. package/dist/jupiter.js +120 -0
  24. package/dist/metered.d.ts +58 -0
  25. package/dist/metered.js +82 -0
  26. package/dist/middleware.d.ts +9 -0
  27. package/dist/middleware.js +71 -0
  28. package/dist/nonce.d.ts +57 -0
  29. package/dist/nonce.js +123 -0
  30. package/dist/payment.d.ts +202 -0
  31. package/dist/payment.js +967 -0
  32. package/dist/provider.d.ts +371 -0
  33. package/dist/provider.js +492 -0
  34. package/dist/rating.d.ts +552 -0
  35. package/dist/rating.js +829 -0
  36. package/dist/session-auth.d.ts +168 -0
  37. package/dist/session-auth.js +341 -0
  38. package/dist/session.d.ts +220 -0
  39. package/dist/session.js +297 -0
  40. package/dist/spl-token-observer.d.ts +70 -0
  41. package/dist/spl-token-observer.js +319 -0
  42. package/dist/token-escrow.d.ts +125 -0
  43. package/dist/token-escrow.js +163 -0
  44. package/dist/types.d.ts +148 -0
  45. package/dist/types.js +2 -0
  46. package/package.json +109 -4
@@ -0,0 +1,202 @@
1
+ import { SwapClient } from './jupiter';
2
+ import { X402Request, PaymentReceipt } from './types';
3
+ import type { NonceReplayStore, PayerProofCheck, ProtocolFeeConfig, ReceiptVerificationResult, ReceiptVerifier, SolanaPaymentNetwork, X402Challenge, X402ChallengeInput, X402FeeTerms } from './types';
4
+ /**
5
+ * Strictly validate canonical Solana public-key text.
6
+ * Requires base58 decode to exactly 32 bytes and round-trips to the same string.
7
+ */
8
+ export declare function isValidSolanaPublicKey(address: string): boolean;
9
+ /** Backwards-compatible alias for older callers. */
10
+ export declare const isValidPaymentAddress: typeof isValidSolanaPublicKey;
11
+ /** Standard protocol fee rate: 500 basis points, which is 5% of the price paid. */
12
+ export declare const PROTOCOL_FEE_BPS = 500;
13
+ /** Launch rate: 250 basis points (2.5%) for payments made before LAUNCH_RATE_ENDS_AT_MS. */
14
+ export declare const LAUNCH_PROTOCOL_FEE_BPS = 250;
15
+ /**
16
+ * 2027-04-01T00:00:00Z in milliseconds. The escrow program holds the same
17
+ * instant (LAUNCH_RATE_ENDS_UNIX, in seconds) and reads it at payout.
18
+ */
19
+ export declare const LAUNCH_RATE_ENDS_AT_MS = 1806537600000;
20
+ /** Either side of the switch, how long a payment may still be checked at the other rate (block times and clocks drift). */
21
+ export declare const FEE_RATE_SWITCH_GRACE_MS: number;
22
+ /** The protocol fee rate in force at `atMs` (milliseconds since the epoch). */
23
+ export declare function protocolFeeBpsAt(atMs?: number): number;
24
+ /**
25
+ * The rates a payment made around `atMs` may carry: the rate then, plus the
26
+ * other rate within FEE_RATE_SWITCH_GRACE_MS of the switch. With no time
27
+ * known, both.
28
+ */
29
+ export declare function protocolFeeBpsNear(atMs?: number | null): number[];
30
+ /** Ceiling on the protocol fee for a SOL payment: 0.1 SOL. Token payments have no ceiling. */
31
+ export declare const SOL_PROTOCOL_FEE_CAP_LAMPORTS: bigint;
32
+ /** A currency a direct per-call payment can be made in. `tokenProgram` is absent for native SOL. */
33
+ export interface DirectPaymentCurrency {
34
+ decimals: number;
35
+ tokenProgram?: string;
36
+ }
37
+ /**
38
+ * Currencies accepted for direct per-call payments. The token program is fixed
39
+ * per currency: USDC and AUDD are classic SPL Token mints, PYUSD and USDG are
40
+ * Token-2022 mints. The mint address itself always comes from configuration.
41
+ */
42
+ export declare const DIRECT_PAYMENT_CURRENCIES: Readonly<Record<string, DirectPaymentCurrency>>;
43
+ /** Looks up a direct payment currency without reading inherited object keys. */
44
+ export declare function directPaymentCurrency(currency: string): DirectPaymentCurrency | undefined;
45
+ /**
46
+ * Mainnet mint addresses, read on-chain on 20 November 2026. Reference values
47
+ * for operator configuration; nothing in this package uses them by default.
48
+ */
49
+ export declare const MAINNET_STABLECOIN_MINTS: Readonly<{
50
+ USDC: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
51
+ AUDD: "AUDDttiEpCydTm7joUMbYddm72jAWXZnCpPZtDoxqBSw";
52
+ PYUSD: "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo";
53
+ USDG: "2u1tszSeqZ3qBWF3uNGPFc8TzMk2tdiwknnRMWGWjGWH";
54
+ }>;
55
+ /**
56
+ * Converts a decimal amount to whole base units without floating point
57
+ * multiplication. Returns undefined for anything that is not a positive amount
58
+ * with at most `decimals` decimal places.
59
+ */
60
+ export declare function decimalToBaseUnits(amount: string | number, decimals: number): bigint | undefined;
61
+ /** Renders whole base units as a decimal string with no trailing zeros. */
62
+ export declare function baseUnitsToDecimal(units: bigint, decimals: number): string;
63
+ /**
64
+ * Fee in base units: the price times the rate, rounded down, never above
65
+ * `capBaseUnits` when one is given. There is no minimum fee.
66
+ */
67
+ export declare function protocolFeeBaseUnits(priceBaseUnits: bigint, bps?: number, capBaseUnits?: bigint): bigint;
68
+ /** Fee ceiling for a currency in its base units: 0.1 SOL for SOL, none for tokens. */
69
+ export declare function protocolFeeCapBaseUnits(currency: string): bigint | undefined;
70
+ /** Fee terms for a listed price, as a challenge states them. Throws on an unusable amount, currency or configuration. */
71
+ export declare function protocolFeeTerms(amount: string | number, currency: string, payTo: string, config: ProtocolFeeConfig): X402FeeTerms;
72
+ export interface BuildX402ChallengeOptions {
73
+ /** When set, the challenge states the fee split. Comes from operator configuration only. */
74
+ protocolFee?: ProtocolFeeConfig;
75
+ }
76
+ export declare function buildX402Challenge(input: X402ChallengeInput, options?: BuildX402ChallengeOptions): X402Challenge;
77
+ /**
78
+ * Parse x402-request header into structured request.
79
+ * Expected format: JSON string with amount, currency, paymentAddress, nonce.
80
+ * @throws Error if header is invalid.
81
+ */
82
+ export declare function parseX402Header(header: string): X402Request;
83
+ export declare function parseX402PaymentHeader(header: string): unknown;
84
+ export declare function verifyDemoPaymentReceipt(input: {
85
+ receipt: unknown;
86
+ challenge: X402Challenge;
87
+ allowDemoPayment: boolean;
88
+ replayStore?: NonceReplayStore;
89
+ }): Promise<ReceiptVerificationResult>;
90
+ export declare class DemoPaymentVerifier implements ReceiptVerifier {
91
+ private readonly allowDemoPayment;
92
+ constructor(allowDemoPayment: boolean);
93
+ verifyReceipt(receipt: unknown, challenge: X402Challenge, replayStore?: NonceReplayStore): Promise<ReceiptVerificationResult>;
94
+ }
95
+ export interface ParsedTransactionConnection {
96
+ getParsedTransaction(signature: string, options?: unknown): Promise<unknown>;
97
+ /** Used to confirm the RPC endpoint serves the network the challenge names. */
98
+ getGenesisHash?(): Promise<string>;
99
+ }
100
+ /** Genesis hashes of the public Solana clusters. */
101
+ export declare const SOLANA_GENESIS_HASHES: Record<SolanaPaymentNetwork, string>;
102
+ /** Default limit on how old a payment transaction may be when it is presented. */
103
+ export declare const DEFAULT_MAX_TRANSACTION_AGE_SECONDS = 900;
104
+ export interface SolanaReceiptVerifierOptions {
105
+ allowRealPayment: boolean;
106
+ connection: ParsedTransactionConnection;
107
+ /** Required when verifying USDC/SPL-token receipts. Same as `mints.USDC`. */
108
+ usdcMint?: string;
109
+ /**
110
+ * Accepted mint per token currency (USDC, AUDD, PYUSD, USDG), from operator
111
+ * configuration only. A currency with no entry here is refused, apart from
112
+ * the legacy `usdcMint` and `auddMint` options. Amounts in a challenge for a
113
+ * currency configured here are decimal amounts, as for USDC.
114
+ */
115
+ mints?: Readonly<Record<string, string | undefined>>;
116
+ /** Required when verifying AUDD x402 v2 SVM exact receipts. */
117
+ auddMint?: string;
118
+ /** Defaults to the legacy SPL Token program for AUDD exact receipts. */
119
+ auddTokenProgram?: string;
120
+ /**
121
+ * Oldest block time accepted, in seconds before now. On solana-mainnet-beta it
122
+ * defaults to DEFAULT_MAX_TRANSACTION_AGE_SECONDS and cannot be switched off.
123
+ * On other networks the check runs only when this is set.
124
+ */
125
+ maxTransactionAgeSeconds?: number;
126
+ /** Clock used for the age check, in milliseconds. Defaults to Date.now. */
127
+ now?: () => number;
128
+ /**
129
+ * Genesis hash the RPC endpoint must report. On solana-mainnet-beta the public
130
+ * mainnet hash is always enforced and this cannot replace it. On other networks
131
+ * the check runs only when this is set (see SOLANA_GENESIS_HASHES).
132
+ */
133
+ expectedGenesisHash?: string;
134
+ /**
135
+ * Protocol fee the payment must include, or 'disabled' for an operator that
136
+ * takes none. On solana-mainnet-beta one of the two must be set: a mainnet
137
+ * verifier with no fee decision refuses every receipt. The treasury is taken
138
+ * from here only, never from the challenge or the receipt.
139
+ */
140
+ protocolFee?: ProtocolFeeConfig | 'disabled';
141
+ /**
142
+ * Whether the request presenting a receipt must prove it comes from the
143
+ * wallet that paid. Defaults to `'required'`: a confirmed transfer is public,
144
+ * so anyone who sees it could otherwise present it first and be served,
145
+ * leaving the buyer refused as a duplicate. A provider passes a check built by
146
+ * `directPaymentProofCheck` to `verifyReceipt`. `'not-required'` is only for a
147
+ * verifier that serves nothing, such as a job ledger checking a receipt after
148
+ * the call.
149
+ */
150
+ payerProof?: 'required' | 'not-required';
151
+ }
152
+ export declare class SolanaReceiptVerifier implements ReceiptVerifier {
153
+ private readonly options;
154
+ private verifiedGenesisHash?;
155
+ constructor(options: SolanaReceiptVerifierOptions);
156
+ /**
157
+ * Confirms the RPC endpoint serves the challenged network, so a transaction from
158
+ * a cheaper cluster cannot settle a challenge for another. Always enforced on
159
+ * solana-mainnet-beta against the public genesis hash. On other networks it runs
160
+ * only when expectedGenesisHash is set, so local validators keep working.
161
+ * A successful answer is remembered; a failure is asked again.
162
+ */
163
+ private clusterFailure;
164
+ /** Refuses a transaction older than the configured limit, or one with no usable block time when a limit applies. */
165
+ private ageFailure;
166
+ verifyReceipt(receiptInput: unknown, challenge: X402Challenge, replayStore?: NonceReplayStore, payerProof?: PayerProofCheck): Promise<ReceiptVerificationResult>;
167
+ /**
168
+ * Works out the fee split this verifier requires for a challenge, from its own
169
+ * configuration. Fee terms printed in the challenge are only compared against
170
+ * that, so a challenge cannot lower the fee or redirect it.
171
+ */
172
+ private feeSplitFor;
173
+ /** Returns a failure result when the parsed transaction does not settle the challenge, otherwise undefined. */
174
+ private challengePaymentFailure;
175
+ }
176
+ /** Replay key for a settled transaction; namespaced so it cannot collide with a caller-chosen nonce. */
177
+ export declare function transactionReplayKey(network: string, signature: string): string;
178
+ /** Longest receipt nonce accepted, so every namespaced key fits the replay ledger's 300-character limit. */
179
+ export declare const MAX_RECEIPT_NONCE_LENGTH = 128;
180
+ /** True for a nonce of 1 to 128 characters from letters, digits and `. _ : ~ -`. */
181
+ export declare function isValidReceiptNonce(nonce: unknown): nonce is string;
182
+ /** Replay key for a real payment's challenge nonce, scoped to the network and payee. */
183
+ export declare function nonceReplayKey(network: string, payTo: string, nonce: string): string;
184
+ /** Replay key for a demo receipt's nonce; demo keys never share a namespace with real payments. */
185
+ export declare function demoNonceReplayKey(nonce: string): string;
186
+ /**
187
+ * Converts a SOL amount to lamports without floating point multiplication, which
188
+ * can land one lamport above the exact value (0.00051 SOL becomes 510000.00000000006,
189
+ * which rounds up to 510001 and rejects an exact payment).
190
+ * Returns undefined for anything that is not a positive amount with at most nine
191
+ * decimal places.
192
+ */
193
+ export declare function solAmountToLamports(amount: string | number): bigint | undefined;
194
+ export interface SendPaymentOptions {
195
+ swapClient?: SwapClient;
196
+ slippageBps?: number;
197
+ }
198
+ /**
199
+ * Send a payment via Solana SystemProgram.transfer.
200
+ * In this package version, this remains a test stub; no funding transactions are submitted.
201
+ */
202
+ export declare function sendPayment(request: X402Request, options?: SendPaymentOptions): Promise<PaymentReceipt>;