@ashlar-blue/x402-trust 0.3.0

package/dist/reconcile.js

@@ -0,0 +1,136 @@
+// GENERATED from src/x402/reconcile.ts by scripts/sdk/sync-sdk.ts — do not edit here.
+// The canonical module is the one FlareClaw runs in production; this is a copy so
+// that what we publish and what we run cannot diverge. Edit the canonical file.
+const ADDR_RE = /^0x[0-9a-fA-F]{40}$/;
+const NONCE_RE = /^0x[0-9a-fA-F]{64}$/;
+export async function reconcileAuthorization(q, reader, scope, now) {
+    // `now` is defined by this port to return UNIX SECONDS, matching
+    // validBefore's units — the facilitator passes Math.floor(Date.now()/1000)
+    // and the tests pass a seconds constant. Do not re-scale it here.
+    const clockUnixSeconds = now();
+    // Read the height FIRST, so even a verdict that fails early carries the
+    // state it failed at. A height fetched after the decision would describe a
+    // different chain than the one the decision was made against.
+    let blockHeight = null;
+    if (reader.blockHeight) {
+        try {
+            blockHeight = await reader.blockHeight();
+        }
+        catch {
+            blockHeight = null;
+        }
+    }
+    /** Build the observation, marking whether the clock decided this verdict. */
+    const obs = (clockWasLoadBearing) => ({
+        blockHeight,
+        clockUnixSeconds,
+        clockWasLoadBearing,
+        replayable: blockHeight !== null,
+    });
+    const at = blockHeight === null
+        ? 'at an unknown height (this reader does not report one, so the verdict is not replayable)'
+        : `at block ${blockHeight}`;
+    const rederive = `Read authorizationState(payer, nonce) on the asset contract via any ${scope.network} RPC (${scope.rpc}) ${at}; `
+        + 'if consumed, filter AuthorizationUsed(payer, nonce) logs for the settlement tx and decode its Transfer events.';
+    if (!ADDR_RE.test(q.asset ?? '') || !ADDR_RE.test(q.payer ?? '') || !NONCE_RE.test(q.nonce ?? '')) {
+        return {
+            outcome: 'indeterminate', cause: 'invalid-query',
+            reason: 'asset and payer must be 0x addresses and nonce a 32-byte 0x-hex value',
+            observation: obs(false), rederive,
+        };
+    }
+    const symbol = scope.assets[q.asset.toLowerCase()];
+    if (!symbol) {
+        return {
+            outcome: 'indeterminate', cause: 'out-of-scope-asset',
+            reason: `asset ${q.asset} is not an EIP-3009 asset this rail settles — no verdict, not a refusal`,
+            observation: obs(false), rederive,
+        };
+    }
+    let consumed;
+    try {
+        consumed = await reader.authorizationConsumed(q.asset, q.payer, q.nonce);
+    }
+    catch (e) {
+        return {
+            outcome: 'indeterminate', cause: 'rail-unreachable',
+            reason: `rail unreachable (${e.message}) — unknown is not a verdict; retry`,
+            observation: obs(false), rederive,
+        };
+    }
+    if (consumed) {
+        // CONSUMED IS NOT SETTLED. It is used-or-cancelled, and a cancelled
+        // authorization moved no tokens. Resolve which by event before
+        // returning any verdict — the previous version returned `settled`
+        // here and told the reader to widen their log range, which is the
+        // one case where widening never helps and the advice is reassuring
+        // about a payment that never happened.
+        let record = null;
+        try {
+            record = await reader.findConsumption(q.asset, q.payer, q.nonce);
+        }
+        catch {
+            // Enumeration failed. We know the nonce is spent but not how,
+            // and the two possibilities are OPPOSITE verdicts — so this is
+            // indeterminate, never a coin-flip toward settled.
+            return {
+                outcome: 'indeterminate', cause: 'consumption-kind-unknown',
+                reason: 'nonce is consumed but the event read failed — consumed means used OR cancelled, and those are opposite verdicts; retry',
+                observation: obs(false), rederive,
+            };
+        }
+        if (record === null) {
+            return {
+                outcome: 'indeterminate', cause: 'consumption-kind-unknown',
+                reason: 'nonce is consumed but neither AuthorizationUsed nor AuthorizationCanceled was locatable in this reader\'s log range — re-derive with a wider range',
+                observation: obs(false), rederive,
+            };
+        }
+        if (record.kind === 'cancelled') {
+            return {
+                outcome: 'refused-not-charged', cause: 'authorization-cancelled',
+                reason: `authorization was CANCELLED (tx ${record.tx}, block ${record.blockNumber}) — the nonce is consumed but no tokens moved; the payer was not charged`,
+                consumption: record,
+                observation: obs(false), rederive,
+            };
+        }
+        return {
+            outcome: 'settled', cause: 'nonce-used',
+            reason: `authorization used on-chain; settlement tx ${record.tx} (block ${record.blockNumber}) carried ${record.transfers.length} ${symbol} transfer(s)`,
+            consumption: record,
+            observation: obs(false), rederive,
+        };
+    }
+    if (typeof q.validBefore === 'number') {
+        // THE CLOCK IS LOAD-BEARING HERE AND NOWHERE ELSE. Everything above is
+        // decided by chain state; this one comparison is decided by what time
+        // we think it is. The observation publishes the reading so a party who
+        // disagrees can recompute the comparison instead of disputing a verdict.
+        if (clockUnixSeconds > q.validBefore) {
+            return {
+                outcome: 'refused-not-charged', cause: 'window-closed-unconsumed',
+                // HONEST ABOUT WHAT THIS DOES NOT SAY (Circadian-agent, #3226):
+                // the rail cannot distinguish "a settle was attempted and
+                // failed" from "nobody ever tried". x402#3231 is a live
+                // instance of the first — a valid authorization the reference
+                // facilitator could not settle because of a stale nonce on its
+                // OWN relayer wallet. The OUTCOME is right either way (no
+                // tokens moved, the payer was not charged); the reason must not
+                // imply the payer withdrew.
+                reason: `authorization unconsumed and its window closed at ${q.validBefore} (clock ${clockUnixSeconds}) — it can never settle, so the payer was not charged. This does NOT say whether a settle was attempted and failed or never attempted; the rail cannot distinguish those.`,
+                observation: obs(true), rederive,
+            };
+        }
+        return {
+            outcome: 'indeterminate', cause: 'window-open-unconsumed',
+            reason: `authorization unconsumed but valid until ${q.validBefore} (clock ${clockUnixSeconds}) — it could still settle; re-query after expiry for a determinate verdict`,
+            observation: obs(true), rederive,
+        };
+    }
+    return {
+        outcome: 'indeterminate', cause: 'window-unknown-unconsumed',
+        reason: 'authorization unconsumed and no validBefore supplied — cannot rule out a future settle; supply validBefore for a determinate refused-not-charged',
+        observation: obs(false), rederive,
+    };
+}
+//# sourceMappingURL=reconcile.js.map

package/dist/reconcile.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.js","sourceRoot":"","sources":["../src/reconcile.ts"],"names":[],"mappings":"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"}

package/dist/trust-sdk.d.ts

@@ -0,0 +1,127 @@
+/**
+ * @flareclaw/x402-trust — the trust layer for agents that spend money.
+ *
+ * An agent about to pay another agent has two questions, and an agent that just
+ * did work has one obligation. This module answers all three in a handful of
+ * lines, with zero dependencies and — for the verification half — zero network
+ * and zero trust in us:
+ *
+ *   BEFORE YOU PAY   checkService(domain) — discover a service, verify what can
+ *                    be verified, and get a plain safeToPay decision with the
+ *                    reasons behind it. Composes the hardened resolver
+ *                    (same-origin enforcement, SSRF/DoS guards, HTTPS-only,
+ *                    live cross-check) so a caller need not re-implement the
+ *                    adversarial edge cases.
+ *
+ *   WHAT YOU'RE HANDED   verifyReceipt / verifyDirectoryEntry / verifyReconcileRow
+ *                    — check ONE row of a Merkle-committed receipt, census, or
+ *                    reconciliation against its signed root, holding nothing
+ *                    else. Pure math (RFC 6962). It does not call us, and it
+ *                    does not trust us: if the proof verifies, the claim is
+ *                    true whoever produced it.
+ *
+ *   WHAT YOU PRODUCE   new Transcript() — accumulate {id, input, output} entries
+ *                    and emit a root plus per-entry inclusion proofs, so the
+ *                    work YOUR agent did is provable to a third party without
+ *                    disclosing the rest of the session.
+ *
+ * The verification functions are the point of the whole library: an enterprise
+ * does not have to trust FlareClaw to use FlareClaw's proofs. That is the only
+ * kind of trust layer worth adopting.
+ */
+import { resolveX402, type ResolveResult } from './discovery.js';
+import { type TranscriptEntry } from './merkle-transcript.js';
+import { type DirectoryEntry } from './attested-directory.js';
+import { type ReconcileRow } from './census-reconcile.js';
+export interface ServiceTrust {
+    domain: string;
+    /** A discovery record or manifest resolved at all. */
+    reachable: boolean;
+    /** It resolved to a valid x402 discovery manifest. */
+    discoverable: boolean;
+    /** How the manifest was found. */
+    via?: 'dns-txt' | 'well-known';
+    /** The manifest carries a TEE/attestation claim. */
+    attested: boolean;
+    /**
+     * The attestation claim is INDEPENDENTLY CHECKABLE — a same-origin HTTPS
+     * verifier the caller could dereference. False for an absent, `none`, or
+     * off-origin verifier: a claim, not a verified claim.
+     */
+    attestationCheckable: boolean;
+    /** Live /supported cross-check outcome (ok/skipped/unreachable/malformed/refused). */
+    liveCheck?: ResolveResult['liveCheck'];
+    /** True when the facilitator's live kinds match its manifest kinds. */
+    liveConsistent: boolean | null;
+    /** Manifest entries the resolver DROPPED as off-domain — a spoofing signal, surfaced not hidden. */
+    warnings: string[];
+    /** The composed decision under the chosen policy. */
+    safeToPay: boolean;
+    /** Why, in plain words — safe to log, safe to show a human. */
+    reasons: string[];
+    /** The raw resolver result, for callers that want the detail. */
+    resolution?: ResolveResult;
+}
+export interface CheckServiceOptions {
+    /** Require an independently-checkable attestation for safeToPay (default false). */
+    requireAttestation?: boolean;
+    /** Require the live /supported cross-check to have PASSED (default false — 'skipped' is allowed). */
+    requireLiveConsistent?: boolean;
+    /** Pass-throughs for tests / custom transports. */
+    resolveTxt?: Parameters<typeof resolveX402>[1] extends infer O ? O extends {
+        resolveTxt?: infer T;
+    } ? T : never : never;
+    fetchImpl?: typeof fetch;
+    lookupImpl?: Parameters<typeof resolveX402>[1] extends infer O ? O extends {
+        lookupImpl?: infer L;
+    } ? L : never : never;
+    noCache?: boolean;
+}
+/**
+ * Resolve a domain and decide whether an agent should pay it. The default
+ * policy is deliberately conservative but not paranoid: a service is safe to
+ * pay when it is genuinely discoverable, nothing was dropped as a spoofing
+ * attempt, and the live cross-check did not REFUSE (a dead live signal is a
+ * warning, not a veto, unless you ask for one). Tighten with requireAttestation
+ * / requireLiveConsistent.
+ */
+export declare function checkService(domain: string, opts?: CheckServiceOptions): Promise<ServiceTrust>;
+/** One retail receipt proof: an entry, its position, the tree size, the path, the signed root. */
+export interface ReceiptProof {
+    entry: TranscriptEntry;
+    index: number;
+    size: number;
+    proof: string[];
+    root: string;
+}
+/**
+ * Verify ONE draw/work receipt against its signed root, holding nothing else.
+ * Pure RFC 6962. Returns true iff the entry was genuinely in the committed
+ * transcript at that position — no network, no trust in the producer.
+ */
+export declare function verifyReceipt(p: ReceiptProof): boolean;
+/** Verify one directory-census entry against a census outputRoot. */
+export declare function verifyDirectoryEntry(entry: DirectoryEntry, index: number, size: number, proof: string[], outputRoot: string): boolean;
+/** Verify one reconciliation row against a reconciliation rowsRoot. */
+export declare function verifyReconcileRow(row: ReconcileRow, index: number, size: number, proof: string[], rowsRoot: string): boolean;
+/**
+ * Build a verifiable transcript of the work your agent did. Add {id, input,
+ * output} entries; emit a root you sign/anchor and per-entry inclusion proofs a
+ * counterparty can check with verifyReceipt — WITHOUT seeing the rest.
+ *
+ * `id` is committed (it distinguishes two otherwise-identical entries — the
+ * payment-intent identity), so the transcript cannot be made to undercount two
+ * distinct pieces of work.
+ */
+export declare class Transcript {
+    private entries;
+    /** Append one unit of work: an identifier, its input, and its output. */
+    add(id: string, input: string, output: string): this;
+    /** Number of entries so far. */
+    get size(): number;
+    /** The Merkle root to sign or anchor — the single value that commits to all entries. */
+    root(): string;
+    /** A retail inclusion proof for entry `index`, ready to hand to a verifier. */
+    prove(index: number): ReceiptProof;
+}
+//# sourceMappingURL=trust-sdk.d.ts.map

package/dist/trust-sdk.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-sdk.d.ts","sourceRoot":"","sources":["../src/trust-sdk.ts"],"names":[],"mappings":"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"}

package/dist/trust-sdk.js

@@ -0,0 +1,147 @@
+// GENERATED from src/x402/trust-sdk.ts by scripts/sdk/sync-sdk.ts — do not edit here.
+// The canonical module is the one FlareClaw runs in production; this is a copy so
+// that what we publish and what we run cannot diverge. Edit the canonical file.
+/**
+ * @flareclaw/x402-trust — the trust layer for agents that spend money.
+ *
+ * An agent about to pay another agent has two questions, and an agent that just
+ * did work has one obligation. This module answers all three in a handful of
+ * lines, with zero dependencies and — for the verification half — zero network
+ * and zero trust in us:
+ *
+ *   BEFORE YOU PAY   checkService(domain) — discover a service, verify what can
+ *                    be verified, and get a plain safeToPay decision with the
+ *                    reasons behind it. Composes the hardened resolver
+ *                    (same-origin enforcement, SSRF/DoS guards, HTTPS-only,
+ *                    live cross-check) so a caller need not re-implement the
+ *                    adversarial edge cases.
+ *
+ *   WHAT YOU'RE HANDED   verifyReceipt / verifyDirectoryEntry / verifyReconcileRow
+ *                    — check ONE row of a Merkle-committed receipt, census, or
+ *                    reconciliation against its signed root, holding nothing
+ *                    else. Pure math (RFC 6962). It does not call us, and it
+ *                    does not trust us: if the proof verifies, the claim is
+ *                    true whoever produced it.
+ *
+ *   WHAT YOU PRODUCE   new Transcript() — accumulate {id, input, output} entries
+ *                    and emit a root plus per-entry inclusion proofs, so the
+ *                    work YOUR agent did is provable to a third party without
+ *                    disclosing the rest of the session.
+ *
+ * The verification functions are the point of the whole library: an enterprise
+ * does not have to trust FlareClaw to use FlareClaw's proofs. That is the only
+ * kind of trust layer worth adopting.
+ */
+import { resolveX402, X402NegativeCacheError, } from './discovery.js';
+import { transcriptRoot, inclusionProof, verifyInclusion, } from './merkle-transcript.js';
+import { verifyEntry } from './attested-directory.js';
+import { verifyRow } from './census-reconcile.js';
+/**
+ * Resolve a domain and decide whether an agent should pay it. The default
+ * policy is deliberately conservative but not paranoid: a service is safe to
+ * pay when it is genuinely discoverable, nothing was dropped as a spoofing
+ * attempt, and the live cross-check did not REFUSE (a dead live signal is a
+ * warning, not a veto, unless you ask for one). Tighten with requireAttestation
+ * / requireLiveConsistent.
+ */
+export async function checkService(domain, opts = {}) {
+    const reasons = [];
+    let resolution;
+    try {
+        resolution = await resolveX402(domain, {
+            ...(opts.resolveTxt ? { resolveTxt: opts.resolveTxt } : {}),
+            ...(opts.fetchImpl ? { fetchImpl: opts.fetchImpl } : {}),
+            ...(opts.lookupImpl ? { lookupImpl: opts.lookupImpl } : {}),
+            ...(opts.noCache ? { noCache: true } : {}),
+        });
+    }
+    catch (e) {
+        // A resolver refusal (spoofing/malformed/SSRF/DoS) is a firm NO, and its
+        // reason is worth surfacing rather than collapsing to "unreachable".
+        const cached = e instanceof X402NegativeCacheError;
+        return {
+            domain, reachable: false, discoverable: false, attested: false,
+            attestationCheckable: false, liveConsistent: null, warnings: [],
+            safeToPay: false,
+            reasons: [`resolution ${cached ? 'refused (cached)' : 'failed'}: ${e.message}`],
+        };
+    }
+    const attested = !!resolution.manifest.attestation
+        && resolution.manifest.attestation.type !== 'none';
+    const attestationCheckable = resolution.attestationUsable === true;
+    const liveConsistent = resolution.kindsMatchLive ?? null;
+    const warnings = [
+        ...(resolution.droppedResources ?? []).map((r) => `dropped off-domain resource: ${r}`),
+        ...(resolution.droppedPeers ?? []).map((p) => `dropped peer hint: ${p}`),
+    ];
+    reasons.push(`discoverable via ${resolution.via}`);
+    if (attested)
+        reasons.push(attestationCheckable ? 'attestation claim is same-origin checkable' : 'attestation claim present but NOT independently checkable');
+    if (resolution.liveCheck)
+        reasons.push(`live cross-check: ${resolution.liveCheck}`);
+    if (liveConsistent === false)
+        reasons.push('WARNING: live /supported disagrees with the manifest');
+    for (const w of warnings)
+        reasons.push(`WARNING: ${w}`);
+    let safeToPay = resolution.liveCheck !== 'refused' && warnings.length === 0;
+    if (opts.requireAttestation && !attestationCheckable) {
+        safeToPay = false;
+        reasons.push('policy: attestation required, none checkable');
+    }
+    if (opts.requireLiveConsistent && liveConsistent !== true) {
+        safeToPay = false;
+        reasons.push('policy: live consistency required, not confirmed');
+    }
+    return {
+        domain, reachable: true, discoverable: true, via: resolution.via,
+        attested, attestationCheckable,
+        ...(resolution.liveCheck ? { liveCheck: resolution.liveCheck } : {}),
+        liveConsistent, warnings, safeToPay, reasons, resolution,
+    };
+}
+/**
+ * Verify ONE draw/work receipt against its signed root, holding nothing else.
+ * Pure RFC 6962. Returns true iff the entry was genuinely in the committed
+ * transcript at that position — no network, no trust in the producer.
+ */
+export function verifyReceipt(p) {
+    return verifyInclusion(p.entry, p.index, p.size, p.proof, p.root);
+}
+/** Verify one directory-census entry against a census outputRoot. */
+export function verifyDirectoryEntry(entry, index, size, proof, outputRoot) {
+    return verifyEntry(entry, index, size, proof, outputRoot);
+}
+/** Verify one reconciliation row against a reconciliation rowsRoot. */
+export function verifyReconcileRow(row, index, size, proof, rowsRoot) {
+    return verifyRow(row, index, size, proof, rowsRoot);
+}
+// ──────────────────── WHAT YOU PRODUCE ────────────────────
+/**
+ * Build a verifiable transcript of the work your agent did. Add {id, input,
+ * output} entries; emit a root you sign/anchor and per-entry inclusion proofs a
+ * counterparty can check with verifyReceipt — WITHOUT seeing the rest.
+ *
+ * `id` is committed (it distinguishes two otherwise-identical entries — the
+ * payment-intent identity), so the transcript cannot be made to undercount two
+ * distinct pieces of work.
+ */
+export class Transcript {
+    entries = [];
+    /** Append one unit of work: an identifier, its input, and its output. */
+    add(id, input, output) {
+        this.entries.push({ drawId: id, nonce: input, seed: output });
+        return this;
+    }
+    /** Number of entries so far. */
+    get size() { return this.entries.length; }
+    /** The Merkle root to sign or anchor — the single value that commits to all entries. */
+    root() { return transcriptRoot(this.entries); }
+    /** A retail inclusion proof for entry `index`, ready to hand to a verifier. */
+    prove(index) {
+        const entry = this.entries[index];
+        if (!entry)
+            throw new Error(`index ${index} outside transcript of ${this.entries.length}`);
+        return { entry, index, size: this.entries.length, proof: inclusionProof(this.entries, index), root: this.root() };
+    }
+}
+//# sourceMappingURL=trust-sdk.js.map

package/dist/trust-sdk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"trust-sdk.js","sourceRoot":"","sources":["../src/trust-sdk.ts"],"names":[],"mappings":"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"}

package/dist/types.d.ts

@@ -0,0 +1,213 @@
+/**
+ * x402 protocol wire types — EMITS v1, PARSES v1 and v2.
+ *
+ * Shapes follow the x402 spec (Coinbase/x402 Foundation): a resource
+ * server answers 402 with `PaymentRequiredResponse`; the client retries
+ * with an `X-PAYMENT` header carrying base64(JSON(PaymentPayload)); the
+ * facilitator verifies and settles; the server attaches
+ * `X-PAYMENT-RESPONSE` = base64(JSON(SettleResponse)).
+ *
+ * FlareClaw is the first x402 facilitator on Flare (Coston2 first —
+ * network id "coston2", eip155:114).
+ */
+/**
+ * The version we EMIT in our own 402 challenges.
+ *
+ * We accept v2 payloads too (see `normalizeRequirements` /
+ * `decodePaymentHeader`) — being a co-author of x402 extensions while
+ * silently refusing the ecosystem's current wire format would be an
+ * embarrassing kind of wrong. Emission stays on v1 until every one of
+ * our own clients is v2-ready; acceptance is widened first, because
+ * accepting more than you emit is the only safe direction to move a
+ * protocol version.
+ */
+export declare const X402_VERSION = 1;
+/** Versions this implementation can PARSE. */
+export declare const SUPPORTED_X402_VERSIONS: readonly [1, 2];
+export type X402Version = (typeof SUPPORTED_X402_VERSIONS)[number];
+/**
+ * How the payer authorizes the transfer (x402 v2 `extra.assetTransferMethod`).
+ *
+ * `eip3009` is the default and the only one we can SETTLE today — it is
+ * the reason a third-party ERC-20 cannot currently pay us, since the
+ * token itself must implement `transferWithAuthorization`. `permit2`
+ * is x402's universal fallback for arbitrary ERC-20s; we parse it so a
+ * v2 client's intent is never silently misread as EIP-3009, and refuse
+ * it explicitly rather than mis-settling.
+ */
+export type AssetTransferMethod = 'eip3009' | 'permit2' | 'erc7710';
+export declare const PAYMENT_HEADER = "X-PAYMENT";
+/**
+ * v2 servers may deliver the challenge in a RESPONSE HEADER with a null body
+ * instead of in the body. Measured on a live commercial deployment
+ * (x402.glassnode.com, 2026-08-06): `payment-required:` base64, body `null`.
+ * A client that only reads the body sees nothing and cannot pay them.
+ */
+export declare const PAYMENT_REQUIRED_HEADER = "payment-required";
+export declare const PAYMENT_RESPONSE_HEADER = "X-PAYMENT-RESPONSE";
+/** One acceptable way to pay for a resource. */
+export interface PaymentRequirements {
+    scheme: 'exact';
+    /** Network id, e.g. "coston2" (chainId 114). */
+    network: string;
+    /**
+     * Price in the asset's atomic units, decimal string.
+     *
+     * v1 spells this `maxAmountRequired`; **v2 renamed it `amount`**.
+     * Both are optional at the type level so either wire shape parses;
+     * `requirementAmount()` is the single reader that resolves them, so
+     * no call site has to know which version it is holding.
+     */
+    maxAmountRequired?: string;
+    /** x402 v2 name for `maxAmountRequired`. */
+    amount?: string;
+    /** URL/path of the paid resource. */
+    resource: string;
+    description: string;
+    mimeType: string;
+    /** Receiving address (the platform treasury). */
+    payTo: string;
+    /** Seconds the client has to produce a settleable payment. */
+    maxTimeoutSeconds: number;
+    /** ERC-20 (EIP-3009) token contract address. */
+    asset: string;
+    /** EIP-712 domain of the asset — payers need name+version to sign.
+     *  v2 additionally carries `assetTransferMethod` here. */
+    extra: {
+        name: string;
+        version: string;
+        assetTransferMethod?: AssetTransferMethod;
+    };
+}
+/** Body of every 402 response. */
+export interface PaymentRequiredResponse {
+    x402Version: X402Version;
+    error: string;
+    /** The offered options. v1 AND v2 both spell this `accepts` (array). */
+    accepts?: PaymentRequirements[];
+    /**
+     * NOT a v2 rename of `accepts` — we had that wrong. In v2, `accepted` is a
+     * DIFFERENT field carrying the SINGLE requirement a payer chose, and it
+     * lives in the payment payload and settlement response, not in the 402.
+     * (v2 spec §5.1.2: `PaymentRequired.accepts` is a required array; §5.2
+     * `accepted` is "PaymentRequirements object indicating the payment method
+     * chosen".) Kept here only so a server that misuses it in a 402 still
+     * parses — being liberal in what we accept, not endorsing the shape.
+     */
+    accepted?: PaymentRequirements[] | PaymentRequirements;
+}
+/**
+ * The amount a requirement asks for, whichever version wrote it.
+ * Throws rather than defaulting: a missing price must never quietly
+ * become zero on a payment path.
+ */
+export declare function requirementAmount(r: PaymentRequirements): string;
+/**
+ * The offered requirements of a 402 body.
+ *
+ * `accepts` is the spec field in BOTH versions. The `accepted` fallback exists
+ * only to tolerate servers that put the chosen-requirement field in a 402 by
+ * mistake; it is normalised to an array so no caller has to care.
+ */
+export declare function offeredRequirements(body: PaymentRequiredResponse): PaymentRequirements[];
+/** Declared transfer method, defaulting per spec to `eip3009`. */
+export declare function transferMethod(r: PaymentRequirements): AssetTransferMethod;
+/** EIP-3009 TransferWithAuthorization message (all uints as decimal strings). */
+export interface Eip3009Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    /** 32-byte hex nonce, unique per (from, nonce) — on-chain replay guard. */
+    nonce: string;
+}
+/** Scheme-specific payload for "exact" on EVM. */
+export interface ExactEvmPayload {
+    /** 65-byte EIP-712 signature over the authorization, hex. */
+    signature: string;
+    authorization: Eip3009Authorization;
+}
+/** Decoded content of the X-PAYMENT header. */
+export interface PaymentPayload {
+    x402Version: typeof X402_VERSION;
+    scheme: 'exact';
+    network: string;
+    payload: ExactEvmPayload;
+}
+/**
+ * Machine-readable failure classes for `verify`.
+ *
+ * ── WHY A CODE AND NOT JUST PROSE ──
+ * `invalidReason` is a human string, so a payer can only pattern-match
+ * it — and every implementer words it differently. The distinction that
+ * actually matters to a client is REMEDY: is this rejection permanent
+ * (do not retry — you would be signing a second payment for a claim
+ * that will never succeed), or is it a repairable local condition?
+ *
+ * Clock skew is the case that forced this. A payer whose clock is fast
+ * builds `validAfter` in the future, or one whose clock is slow builds
+ * `validBefore` too close to now; the facilitator rejects, and the
+ * payer reads a generic failure as "this venue refuses me" when the
+ * correct action is *resync your clock and re-sign*. That is a
+ * repairable condition being reported as a rejection — the payer gives
+ * up on a service that would have served them.
+ */
+export type InvalidCode = 
+/** Payer's clock disagrees with the facilitator's. RESYNC AND RETRY. */
+'clock-skew'
+/** Payment terms don't match the requirements (payTo, asset, amount, scheme). */
+ | 'terms-mismatch'
+/** Signature invalid or recovers to the wrong address. */
+ | 'signature'
+/** Nonce already used or canceled — this authorization is spent. */
+ | 'nonce-used'
+/**
+ * A settlement for THIS (payer, nonce) is already broadcasting.
+ * Distinct from `nonce-used`: that one is spent, this one is
+ * in-flight and its outcome is not yet knowable. Retry after the
+ * first attempt resolves — do NOT sign a fresh nonce (the original
+ * may well succeed). Costs the payer nothing and the facilitator
+ * no gas.
+ */
+ | 'nonce-in-flight'
+/** Payer lacks the funds. */
+ | 'insufficient-funds'
+/** Authorization expired; a fresh one is required. */
+ | 'expired'
+/** Malformed request the facilitator could not interpret. */
+ | 'malformed';
+export interface VerifyResponse {
+    isValid: boolean;
+    invalidReason?: string;
+    /**
+     * Machine-readable class of `invalidReason`. Optional for backward
+     * compatibility — a client that ignores it behaves exactly as
+     * before; one that reads it can tell "fix your clock" from "this
+     * will never work".
+     */
+    invalidCode?: InvalidCode;
+    /**
+     * Present when the failure is clock-related: the facilitator's own
+     * unix seconds at verification, so the payer can measure its skew
+     * directly instead of guessing. This is the same courtesy HTTP
+     * `Date` provides — the server already knows the answer, and
+     * withholding it makes the payer's problem unsolvable.
+     */
+    serverTime?: number;
+    /** Recovered payer address (when the signature is valid). */
+    payer?: string;
+}
+export interface SettleResponse {
+    success: boolean;
+    errorReason?: string;
+    /** Same classification as VerifyResponse — settle verifies first. */
+    invalidCode?: InvalidCode;
+    /** Facilitator's unix seconds, present on clock-related failures. */
+    serverTime?: number;
+    /** Settlement transaction hash. */
+    transaction: string;
+    network: string;
+    payer: string;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../src/types.ts"],"names":[],"mappings":"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"}