@t2000/sui-x402 10.20.1

package/dist/index.d.cts

@@ -0,0 +1,234 @@
+import { ClientWithCoreApi } from '@mysten/sui/client';
+import { Signer } from '@mysten/sui/cryptography';
+
+interface Currency {
+    type: string;
+    decimals: number;
+}
+declare const SUI_USDC_TYPE = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC";
+declare const SUI_USDC_TESTNET_TYPE = "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
+declare const USDC: {
+    readonly type: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC";
+    readonly decimals: 6;
+};
+declare const USDC_TESTNET: {
+    readonly type: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
+    readonly decimals: 6;
+};
+
+interface DigestStore {
+    has(digest: string): Promise<boolean>;
+    set(digest: string): Promise<void>;
+}
+/** What a successful settlement reports to the host (ops / activity hooks). */
+interface PaymentReport {
+    digest: string;
+    sender?: string;
+    recipient: string;
+    amount: string;
+    currency: string;
+    network: string;
+}
+/** Dev/test store — per-process, TTL-evicted. Production sellers supply a
+ *  durable DigestStore (Redis, Postgres); replay windows must survive
+ *  restarts. */
+declare class InMemoryDigestStore implements DigestStore {
+    private store;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    has(digest: string): Promise<boolean>;
+    set(digest: string): Promise<void>;
+    private evict;
+}
+
+/**
+ * Parse a string amount to raw bigint units without floating-point math.
+ * "0.01" with 6 decimals → 10000n
+ */
+declare function parseAmountToRaw(amount: string, decimals: number): bigint;
+/**
+ * Retry an async function with linear backoff.
+ * Throws the last error if all attempts fail.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, { attempts, baseDelayMs, }?: {
+    attempts?: number;
+    baseDelayMs?: number;
+}): Promise<T>;
+
+declare const X402_SCHEME: "exact";
+declare const X402_VERSION: 1;
+/** Request header carrying the signed payment (x402 standard). */
+declare const X402_PAYMENT_HEADER = "X-PAYMENT";
+/** Response header carrying the settlement result (x402 standard). */
+declare const X402_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+type X402Network = `sui:${'mainnet' | 'testnet' | 'devnet' | 'localnet'}`;
+interface X402Requirements {
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    /** Full Sui coin type of the payment asset. */
+    asset: string;
+    /** Atomic units (e.g. USDC 6dp) as a decimal string. */
+    maxAmountRequired: string;
+    payTo: string;
+    resource: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        suimpp: {
+            /** The mppx challenge id this payment must bind to (single-use). */
+            challengeId: string;
+            /** u32 derived from challengeId — goes into ValidDuring.nonce. */
+            nonce: number;
+            /** Chain identifier string for ValidDuring (genesis digest). */
+            chain: string;
+            minEpoch: string;
+            maxEpoch: string;
+        };
+    };
+}
+interface X402EscrowTerms {
+    /** Time the seller commits to deliver within, in ms from job creation. */
+    deliverWithinMs: number;
+    /** Buyer's accept/reject window after delivery, in ms. Lapse = release. */
+    reviewWindowMs: number;
+    /** Buyer's share in basis points if they reject (0–10000). Fixed at job
+     *  creation — neither side can move the goalposts later. */
+    rejectSplitBps: number;
+    /** The escrow Move package the seller verifies jobs against
+     *  (`a2a_escrow::escrow` on the advertised network). */
+    packageId?: string;
+    /** Optional pointer (URL or short note) describing the expected job-spec
+     *  format the buyer should hash into the job's `spec_hash`. */
+    specSchema?: string;
+}
+/** A job-class `accepts[]` entry. Same base fields as the instant entry
+ *  (`maxAmountRequired` = the job price) but NO settlement challenge —
+ *  `extra.escrow` replaces `extra.suimpp`. */
+interface X402EscrowRequirements {
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    asset: string;
+    /** The job price in atomic units (decimal string). */
+    maxAmountRequired: string;
+    /** The seller wallet the Job must pay (and the claimed Agent ID wallet). */
+    payTo: string;
+    resource: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        escrow: X402EscrowTerms;
+    };
+}
+/** Discriminate a job-class entry inside a mixed accepts[] array. */
+declare function isX402EscrowRequirements(entry: unknown): entry is X402EscrowRequirements;
+/** Discriminate escrow vs instant X-PAYMENT credentials without throwing —
+ *  sellers serving both classes route on this before parsing. */
+declare function isX402EscrowHeader(headerValue: string): boolean;
+interface X402PaymentPayload {
+    x402Version: typeof X402_VERSION;
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    payload: {
+        senderAddress: string;
+        /** base64 BCS TransactionData — fully signed-ready bytes. */
+        txBytes: string;
+        /** Sender signature over txBytes (Ed25519 / secp / zkLogin). */
+        senderSignature: string;
+        challengeId: string;
+    };
+}
+interface X402SettleResponse {
+    success: boolean;
+    network: X402Network;
+    /** Settled transaction digest. */
+    transaction: string;
+    payer: string;
+}
+/**
+ * Derive the ValidDuring nonce (u32) from a challenge id. FNV-1a 32-bit —
+ * dependency-free and browser-safe. The nonce provides per-challenge
+ * UNIQUENESS (distinct digests for otherwise-identical payments); it is not
+ * a secret and carries no security on its own.
+ */
+declare function challengeNonce(challengeId: string): number;
+declare function x402Network(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'): X402Network;
+interface CreateRequirementsOptions {
+    challengeId: string;
+    /** Human-units amount string from the challenge (e.g. "0.02"). */
+    amount: string;
+    currency: Currency;
+    recipient: string;
+    resource: string;
+    network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+    /** Chain identifier string (genesis digest) for ValidDuring. */
+    chain: string;
+    /** Current epoch — requirements are valid for [epoch, epoch + 1]. */
+    currentEpoch: bigint | number | string;
+    maxTimeoutSeconds?: number;
+}
+declare function createX402Requirements(options: CreateRequirementsOptions): X402Requirements;
+interface BuildSignedPaymentOptions {
+    requirements: X402Requirements;
+    signer: Signer;
+    /**
+     * Optional client for build-time resolution. The canonical stateless
+     * shape (address-balance withdrawal → redeem_funds → send_funds) has no
+     * object inputs, so the build is offline when omitted.
+     */
+    client?: ClientWithCoreApi;
+}
+/**
+ * Build the canonical stateless payment transaction, sign it, and return the
+ * `X-PAYMENT` header value + parsed payload. Never submits — settlement is
+ * the server's job (`settleX402Payment`).
+ */
+declare function buildX402SignedPayment(options: BuildSignedPaymentOptions): Promise<{
+    header: string;
+    payment: X402PaymentPayload;
+}>;
+declare function encodeX402Header(payment: X402PaymentPayload): string;
+declare function parseX402Header(headerValue: string): X402PaymentPayload;
+interface VerifyX402Options {
+    payment: X402PaymentPayload;
+    /** The terms this payment must match (from the original challenge). */
+    expected: {
+        challengeId: string;
+        amount: string;
+        currency: Currency;
+        recipient: string;
+        network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+    };
+}
+/**
+ * Structural pre-settle verification: the signed bytes must be the canonical
+ * gasless payment for OUR terms before we relay them. Catches wrong-terms /
+ * relay-abuse payloads without an RPC call.
+ *
+ * SCOPE (Phase 1): this is a STRUCTURAL check — it does NOT verify
+ * `senderSignature`. Signature authority is the chain at `settleX402Payment`
+ * (a bad signature fails `executeTransaction`, and under settle-then-serve
+ * the upstream is never called), plus the post-settle balance-change check.
+ * A standalone Phase-3 public `/verify` endpoint adds an explicit async
+ * signature check (needs a client for zkLogin) on top of this.
+ */
+declare function verifyX402Payment(options: VerifyX402Options): {
+    txBytes: Uint8Array;
+    nonce: number;
+};
+interface SettleX402Options {
+    payment: X402PaymentPayload;
+    client: ClientWithCoreApi;
+    /** Digest replay store — shared with the legacy dialect. */
+    store: DigestStore;
+    expected: VerifyX402Options['expected'];
+    onPayment?: (report: PaymentReport) => void;
+}
+/**
+ * Settle-then-serve: verify structurally, submit the client-signed bytes,
+ * confirm the on-chain balance change, record the digest. Throws (and the
+ * host returns 402) without serving if anything fails — and because the
+ * host only calls the upstream AFTER this resolves, a failed upstream can
+ * void/refund before any service value is lost.
+ */
+declare function settleX402Payment(options: SettleX402Options): Promise<X402SettleResponse>;
+declare function encodeX402Response(response: X402SettleResponse): string;
+
+export { type BuildSignedPaymentOptions, type CreateRequirementsOptions, type Currency, type DigestStore, InMemoryDigestStore, type PaymentReport, SUI_USDC_TESTNET_TYPE, SUI_USDC_TYPE, type SettleX402Options, USDC, USDC_TESTNET, type VerifyX402Options, type X402EscrowRequirements, type X402EscrowTerms, type X402Network, type X402PaymentPayload, type X402Requirements, type X402SettleResponse, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, X402_SCHEME, X402_VERSION, buildX402SignedPayment, challengeNonce, createX402Requirements, encodeX402Header, encodeX402Response, isX402EscrowHeader, isX402EscrowRequirements, parseAmountToRaw, parseX402Header, settleX402Payment, verifyX402Payment, withRetry, x402Network };

package/dist/index.d.ts

@@ -0,0 +1,234 @@
+import { ClientWithCoreApi } from '@mysten/sui/client';
+import { Signer } from '@mysten/sui/cryptography';
+
+interface Currency {
+    type: string;
+    decimals: number;
+}
+declare const SUI_USDC_TYPE = "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC";
+declare const SUI_USDC_TESTNET_TYPE = "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
+declare const USDC: {
+    readonly type: "0xdba34672e30cb065b1f93e3ab55318768fd6fef66c15942c9f7cb846e2f900e7::usdc::USDC";
+    readonly decimals: 6;
+};
+declare const USDC_TESTNET: {
+    readonly type: "0xa1ec7fc00a6f40db9693ad1415d0c193ad3906494428cf252621037bd7117e29::usdc::USDC";
+    readonly decimals: 6;
+};
+
+interface DigestStore {
+    has(digest: string): Promise<boolean>;
+    set(digest: string): Promise<void>;
+}
+/** What a successful settlement reports to the host (ops / activity hooks). */
+interface PaymentReport {
+    digest: string;
+    sender?: string;
+    recipient: string;
+    amount: string;
+    currency: string;
+    network: string;
+}
+/** Dev/test store — per-process, TTL-evicted. Production sellers supply a
+ *  durable DigestStore (Redis, Postgres); replay windows must survive
+ *  restarts. */
+declare class InMemoryDigestStore implements DigestStore {
+    private store;
+    private readonly ttlMs;
+    constructor(ttlMs?: number);
+    has(digest: string): Promise<boolean>;
+    set(digest: string): Promise<void>;
+    private evict;
+}
+
+/**
+ * Parse a string amount to raw bigint units without floating-point math.
+ * "0.01" with 6 decimals → 10000n
+ */
+declare function parseAmountToRaw(amount: string, decimals: number): bigint;
+/**
+ * Retry an async function with linear backoff.
+ * Throws the last error if all attempts fail.
+ */
+declare function withRetry<T>(fn: () => Promise<T>, { attempts, baseDelayMs, }?: {
+    attempts?: number;
+    baseDelayMs?: number;
+}): Promise<T>;
+
+declare const X402_SCHEME: "exact";
+declare const X402_VERSION: 1;
+/** Request header carrying the signed payment (x402 standard). */
+declare const X402_PAYMENT_HEADER = "X-PAYMENT";
+/** Response header carrying the settlement result (x402 standard). */
+declare const X402_PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+type X402Network = `sui:${'mainnet' | 'testnet' | 'devnet' | 'localnet'}`;
+interface X402Requirements {
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    /** Full Sui coin type of the payment asset. */
+    asset: string;
+    /** Atomic units (e.g. USDC 6dp) as a decimal string. */
+    maxAmountRequired: string;
+    payTo: string;
+    resource: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        suimpp: {
+            /** The mppx challenge id this payment must bind to (single-use). */
+            challengeId: string;
+            /** u32 derived from challengeId — goes into ValidDuring.nonce. */
+            nonce: number;
+            /** Chain identifier string for ValidDuring (genesis digest). */
+            chain: string;
+            minEpoch: string;
+            maxEpoch: string;
+        };
+    };
+}
+interface X402EscrowTerms {
+    /** Time the seller commits to deliver within, in ms from job creation. */
+    deliverWithinMs: number;
+    /** Buyer's accept/reject window after delivery, in ms. Lapse = release. */
+    reviewWindowMs: number;
+    /** Buyer's share in basis points if they reject (0–10000). Fixed at job
+     *  creation — neither side can move the goalposts later. */
+    rejectSplitBps: number;
+    /** The escrow Move package the seller verifies jobs against
+     *  (`a2a_escrow::escrow` on the advertised network). */
+    packageId?: string;
+    /** Optional pointer (URL or short note) describing the expected job-spec
+     *  format the buyer should hash into the job's `spec_hash`. */
+    specSchema?: string;
+}
+/** A job-class `accepts[]` entry. Same base fields as the instant entry
+ *  (`maxAmountRequired` = the job price) but NO settlement challenge —
+ *  `extra.escrow` replaces `extra.suimpp`. */
+interface X402EscrowRequirements {
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    asset: string;
+    /** The job price in atomic units (decimal string). */
+    maxAmountRequired: string;
+    /** The seller wallet the Job must pay (and the claimed Agent ID wallet). */
+    payTo: string;
+    resource: string;
+    maxTimeoutSeconds: number;
+    extra: {
+        escrow: X402EscrowTerms;
+    };
+}
+/** Discriminate a job-class entry inside a mixed accepts[] array. */
+declare function isX402EscrowRequirements(entry: unknown): entry is X402EscrowRequirements;
+/** Discriminate escrow vs instant X-PAYMENT credentials without throwing —
+ *  sellers serving both classes route on this before parsing. */
+declare function isX402EscrowHeader(headerValue: string): boolean;
+interface X402PaymentPayload {
+    x402Version: typeof X402_VERSION;
+    scheme: typeof X402_SCHEME;
+    network: X402Network;
+    payload: {
+        senderAddress: string;
+        /** base64 BCS TransactionData — fully signed-ready bytes. */
+        txBytes: string;
+        /** Sender signature over txBytes (Ed25519 / secp / zkLogin). */
+        senderSignature: string;
+        challengeId: string;
+    };
+}
+interface X402SettleResponse {
+    success: boolean;
+    network: X402Network;
+    /** Settled transaction digest. */
+    transaction: string;
+    payer: string;
+}
+/**
+ * Derive the ValidDuring nonce (u32) from a challenge id. FNV-1a 32-bit —
+ * dependency-free and browser-safe. The nonce provides per-challenge
+ * UNIQUENESS (distinct digests for otherwise-identical payments); it is not
+ * a secret and carries no security on its own.
+ */
+declare function challengeNonce(challengeId: string): number;
+declare function x402Network(network: 'mainnet' | 'testnet' | 'devnet' | 'localnet'): X402Network;
+interface CreateRequirementsOptions {
+    challengeId: string;
+    /** Human-units amount string from the challenge (e.g. "0.02"). */
+    amount: string;
+    currency: Currency;
+    recipient: string;
+    resource: string;
+    network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+    /** Chain identifier string (genesis digest) for ValidDuring. */
+    chain: string;
+    /** Current epoch — requirements are valid for [epoch, epoch + 1]. */
+    currentEpoch: bigint | number | string;
+    maxTimeoutSeconds?: number;
+}
+declare function createX402Requirements(options: CreateRequirementsOptions): X402Requirements;
+interface BuildSignedPaymentOptions {
+    requirements: X402Requirements;
+    signer: Signer;
+    /**
+     * Optional client for build-time resolution. The canonical stateless
+     * shape (address-balance withdrawal → redeem_funds → send_funds) has no
+     * object inputs, so the build is offline when omitted.
+     */
+    client?: ClientWithCoreApi;
+}
+/**
+ * Build the canonical stateless payment transaction, sign it, and return the
+ * `X-PAYMENT` header value + parsed payload. Never submits — settlement is
+ * the server's job (`settleX402Payment`).
+ */
+declare function buildX402SignedPayment(options: BuildSignedPaymentOptions): Promise<{
+    header: string;
+    payment: X402PaymentPayload;
+}>;
+declare function encodeX402Header(payment: X402PaymentPayload): string;
+declare function parseX402Header(headerValue: string): X402PaymentPayload;
+interface VerifyX402Options {
+    payment: X402PaymentPayload;
+    /** The terms this payment must match (from the original challenge). */
+    expected: {
+        challengeId: string;
+        amount: string;
+        currency: Currency;
+        recipient: string;
+        network: 'mainnet' | 'testnet' | 'devnet' | 'localnet';
+    };
+}
+/**
+ * Structural pre-settle verification: the signed bytes must be the canonical
+ * gasless payment for OUR terms before we relay them. Catches wrong-terms /
+ * relay-abuse payloads without an RPC call.
+ *
+ * SCOPE (Phase 1): this is a STRUCTURAL check — it does NOT verify
+ * `senderSignature`. Signature authority is the chain at `settleX402Payment`
+ * (a bad signature fails `executeTransaction`, and under settle-then-serve
+ * the upstream is never called), plus the post-settle balance-change check.
+ * A standalone Phase-3 public `/verify` endpoint adds an explicit async
+ * signature check (needs a client for zkLogin) on top of this.
+ */
+declare function verifyX402Payment(options: VerifyX402Options): {
+    txBytes: Uint8Array;
+    nonce: number;
+};
+interface SettleX402Options {
+    payment: X402PaymentPayload;
+    client: ClientWithCoreApi;
+    /** Digest replay store — shared with the legacy dialect. */
+    store: DigestStore;
+    expected: VerifyX402Options['expected'];
+    onPayment?: (report: PaymentReport) => void;
+}
+/**
+ * Settle-then-serve: verify structurally, submit the client-signed bytes,
+ * confirm the on-chain balance change, record the digest. Throws (and the
+ * host returns 402) without serving if anything fails — and because the
+ * host only calls the upstream AFTER this resolves, a failed upstream can
+ * void/refund before any service value is lost.
+ */
+declare function settleX402Payment(options: SettleX402Options): Promise<X402SettleResponse>;
+declare function encodeX402Response(response: X402SettleResponse): string;
+
+export { type BuildSignedPaymentOptions, type CreateRequirementsOptions, type Currency, type DigestStore, InMemoryDigestStore, type PaymentReport, SUI_USDC_TESTNET_TYPE, SUI_USDC_TYPE, type SettleX402Options, USDC, USDC_TESTNET, type VerifyX402Options, type X402EscrowRequirements, type X402EscrowTerms, type X402Network, type X402PaymentPayload, type X402Requirements, type X402SettleResponse, X402_PAYMENT_HEADER, X402_PAYMENT_RESPONSE_HEADER, X402_SCHEME, X402_VERSION, buildX402SignedPayment, challengeNonce, createX402Requirements, encodeX402Header, encodeX402Response, isX402EscrowHeader, isX402EscrowRequirements, parseAmountToRaw, parseX402Header, settleX402Payment, verifyX402Payment, withRetry, x402Network };