otto-execute 0.1.0

package/dist/vendor/otto-intel-mcp/execution-types.d.ts

@@ -0,0 +1,274 @@
+import { type Address, type Hex } from 'viem';
+import { type HyperliquidOrderAction, type HyperliquidSigningDeclaration, type PolymarketOrderArgs, type PolymarketOrderTypedData } from './execution-tool-definitions.js';
+export { MAX_ARTIFACT_TTL_MS, artifactIdTimestampMs, createArtifactId } from './artifact-id.js';
+export type AccountKind = 'eoa' | 'safe';
+export type SigningCapability = 'send_evm_transaction' | 'submit_evm_batch' | 'sign_eip712' | 'sign_hyperliquid_l1';
+export interface AccountProfile {
+    readonly kind: AccountKind;
+    readonly address: Address;
+    readonly chainId: number;
+}
+export interface AccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly lifi: {
+            readonly sender: Address;
+            readonly receiver: Address;
+        };
+    };
+}
+export interface EvmExecutionStep {
+    readonly to: Address;
+    readonly value: string;
+    readonly data: Hex;
+    readonly kind: 'approve_reset' | 'approve' | 'call';
+}
+export interface EvmExecutionPlan {
+    readonly kind: 'evm_execution_plan';
+    readonly chain_id: number;
+    readonly steps: readonly EvmExecutionStep[];
+}
+/** The EVM-plan payload variant, shared by the swap and bridge rails. */
+export type ExecutionPayload = EvmExecutionPlan;
+/**
+ * The Polymarket payload variant: order args pre-signing plus the exact EIP-712 payload and digest
+ * the caller's own signer will sign. No signature, no CLOB credential, no collateral movement.
+ */
+export interface PolymarketOrderPayload {
+    readonly kind: 'polymarket_order_v2';
+    readonly chain_id: number;
+    readonly exchange: Address;
+    readonly neg_risk: boolean;
+    readonly tick_size: string;
+    readonly order_type: 'GTC';
+    readonly order: PolymarketOrderArgs;
+    readonly eip712: PolymarketOrderTypedData;
+    readonly order_hash: Hex;
+}
+export interface ExecutionAssertion {
+    readonly id: string;
+    readonly result: 'passed';
+}
+export interface ExecutionSubmission {
+    readonly method: SigningCapability;
+    readonly chain_id: number;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    /** Commitment over every envelope field except itself, including valid_until. */
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['nonce', 'gas', 'serialization'];
+    readonly client_ref?: string;
+}
+export interface ExecutionEnvelope {
+    readonly schema_version: '1';
+    readonly artifact_id: string;
+    readonly rail: 'lifi';
+    readonly operation: 'swap';
+    readonly intent_digest: Hex;
+    readonly account_binding: AccountBinding;
+    readonly required_capabilities: readonly SigningCapability[];
+    readonly payload: ExecutionPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'lifi_integrator_fee';
+        readonly config_version: string;
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        readonly onchain_replay_boundary: 'signer_account_nonce';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly assertions: readonly ExecutionAssertion[];
+    readonly valid_until: string;
+    readonly submission: ExecutionSubmission;
+}
+export interface BridgeAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly lifi: {
+            readonly sender: Address;
+            /** Where the destination chain mints. For a Safe this is caller-declared, never derived. */
+            readonly receiver: Address;
+            readonly source_chain_id: number;
+            readonly destination_chain_id: number;
+            readonly sending_asset: Address;
+            readonly receiving_asset: Address;
+        };
+    };
+}
+export interface BridgeExecutionEnvelope extends Omit<ExecutionEnvelope, 'operation' | 'account_binding'> {
+    readonly operation: 'bridge';
+    readonly account_binding: BridgeAccountBinding;
+}
+export interface PolymarketAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly polymarket: {
+            /** Source of funds for the order; inside the signed struct (spec §4). */
+            readonly maker: Address;
+            /** Who signs the EIP-712 order; inside the signed struct. */
+            readonly signer: Address;
+            /** Who holds the collateral. For the v1 EOA profile all three are the same account. */
+            readonly funder: Address;
+            readonly exchange: Address;
+            readonly token_id: string;
+            readonly signature_type: 0;
+        };
+    };
+}
+export interface PolymarketExecutionSubmission {
+    readonly method: 'sign_eip712';
+    readonly chain_id: number;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['signature', 'clob_post'];
+    readonly client_ref?: string;
+}
+export interface PolymarketExecutionEnvelope extends Omit<ExecutionEnvelope, 'rail' | 'operation' | 'account_binding' | 'payload' | 'fee_attribution' | 'replay_disclosure' | 'required_capabilities' | 'submission'> {
+    readonly rail: 'polymarket';
+    readonly operation: 'pm_order';
+    readonly account_binding: PolymarketAccountBinding;
+    readonly required_capabilities: readonly ['sign_eip712'];
+    readonly payload: PolymarketOrderPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'polymarket_builder_code';
+        readonly config_version: string;
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        /** An order struct carries its own salt, so the exchange's order hash is the replay boundary. */
+        readonly onchain_replay_boundary: 'exchange_order_hash';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly submission: PolymarketExecutionSubmission;
+}
+/**
+ * The Hyperliquid payload variant: the canonical L1 order action plus the declared EIP-712 signing
+ * fields the caller's own signer needs. No nonce, no signature, no derived agent wallet.
+ */
+export interface HyperliquidL1ActionPayload {
+    readonly kind: 'hyperliquid_l1_action';
+    readonly chain_id: 1337;
+    readonly action: HyperliquidOrderAction;
+    readonly signing: HyperliquidSigningDeclaration;
+    readonly vault_address: Address | null;
+    /** Constructor-owned expiry in unix ms, equal to `valid_until` and inside the signed digest. */
+    readonly expires_after: number;
+}
+export interface HyperliquidAccountBinding extends AccountProfile {
+    readonly protocol_roles: {
+        readonly hyperliquid: {
+            readonly master: Address;
+            readonly trading_signer: Address;
+            readonly vault_address: Address | null;
+            readonly asset: string;
+            readonly asset_id: number;
+            readonly sz_decimals: number;
+        };
+    };
+}
+export interface HyperliquidExecutionSubmission {
+    readonly method: 'sign_hyperliquid_l1';
+    readonly chain_id: 1337;
+    readonly artifact_id: string;
+    readonly payload_digest: Hex;
+    readonly artifact_digest: Hex;
+    readonly adapter_owned_fields: readonly ['nonce', 'signature', 'exchange_post'];
+    readonly client_ref?: string;
+}
+export interface HyperliquidExecutionEnvelope extends Omit<ExecutionEnvelope, 'rail' | 'operation' | 'account_binding' | 'payload' | 'fee_attribution' | 'replay_disclosure' | 'required_capabilities' | 'submission'> {
+    readonly rail: 'hyperliquid';
+    readonly operation: 'perp_order';
+    readonly account_binding: HyperliquidAccountBinding;
+    readonly required_capabilities: readonly ['sign_hyperliquid_l1'];
+    readonly payload: HyperliquidL1ActionPayload;
+    readonly fee_attribution: {
+        readonly mechanism: 'hyperliquid_builder_fee';
+        readonly config_version: string;
+        /** Ruled pending state; the `{b, f}` assert lands with the Step-0 reversal (spec §7.2). */
+        readonly status: 'pending_step0_builder_fee_approval';
+    };
+    readonly replay_disclosure: {
+        readonly artifact_role: 'construction_aid';
+        readonly freshness_boundary: 'valid_until';
+        /** HL's signed digest covers an adapter-chosen nonce AND the constructor's expiresAfter. */
+        readonly onchain_replay_boundary: 'signer_nonce_and_expires_after';
+        readonly tool_guarantees_single_execution: false;
+    };
+    readonly submission: HyperliquidExecutionSubmission;
+}
+/** Any artifact this MCP produces. Discriminated by `operation`. */
+export type ExecutionArtifact = ExecutionEnvelope | BridgeExecutionEnvelope | PolymarketExecutionEnvelope | HyperliquidExecutionEnvelope;
+/** Envelope shape before the self-referential artifact digest is stamped into submission. */
+export type UncommittedExecutionEnvelope = Omit<ExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<ExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Bridge envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedBridgeExecutionEnvelope = Omit<BridgeExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<ExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Polymarket envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedPolymarketExecutionEnvelope = Omit<PolymarketExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<PolymarketExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Hyperliquid envelope before the self-referential artifact digest is stamped into submission. */
+export type UncommittedHyperliquidExecutionEnvelope = Omit<HyperliquidExecutionEnvelope, 'submission'> & {
+    readonly submission: Omit<HyperliquidExecutionSubmission, 'artifact_digest'> & {
+        readonly artifact_digest?: Hex;
+    };
+};
+/** Any envelope shape awaiting its whole-envelope commitment. */
+export type UncommittedExecutionArtifact = UncommittedExecutionEnvelope | UncommittedBridgeExecutionEnvelope | UncommittedPolymarketExecutionEnvelope | UncommittedHyperliquidExecutionEnvelope;
+export declare function canonicalJson(value: unknown): string;
+export declare function executionDigest(value: unknown): Hex;
+export declare function accountBinding(profile: AccountProfile): AccountBinding;
+export declare function bridgeAccountBinding(profile: AccountProfile, route: {
+    readonly destinationRecipient: Address;
+    readonly destinationChainId: number;
+    readonly sendingAsset: Address;
+    readonly receivingAsset: Address;
+}): BridgeAccountBinding;
+/**
+ * The v1 Polymarket profile is a single EOA in all three roles: it signs the order, it is the maker
+ * of record inside the signed struct, and it funds the collateral. A Safe profile would need a
+ * signature type (POLY_GNOSIS_SAFE vs POLY_1271) that spec §13 leaves open, so it is refused rather
+ * than guessed — which is why this factory takes no separate signer or funder.
+ */
+export declare function polymarketAccountBinding(profile: AccountProfile, order: {
+    readonly exchange: Address;
+    readonly tokenId: string;
+}): PolymarketAccountBinding;
+/**
+ * The v1 Hyperliquid profile binds the master account to the signing EOA. `tradingSigner` may be a
+ * DIFFERENT address — the user's own approved API wallet — and is taken as a declared fact: Otto never
+ * derives an agent key, which is the custody line spec §11 draws around
+ * `trade-execution-agent/src/lib/hyperliquid-client.ts:558`. The vault address is likewise declared,
+ * never inferred from the account.
+ */
+export declare function hyperliquidAccountBinding(profile: AccountProfile, market: {
+    readonly tradingSigner?: Address;
+    readonly vaultAddress?: Address;
+    readonly asset: string;
+    readonly assetId: number;
+    readonly szDecimals: number;
+}): HyperliquidAccountBinding;
+export declare function assertArtifactAccountBinding(artifact: ExecutionArtifact, expected: AccountProfile): void;
+export declare function assertArtifactPayloadDigest(artifact: ExecutionArtifact): void;
+/**
+ * Commitment over the whole envelope except the commitment field itself. `valid_until` sits
+ * inside it, so freshness is bound to the artifact rather than being an editable side field.
+ */
+export declare function artifactCommitmentDigest(artifact: UncommittedExecutionArtifact): Hex;
+/**
+ * Fail-closed commitment check: payload digest, whole-envelope commitment, and the
+ * constructor-owned freshness bound derived from the artifact id.
+ */
+export declare function assertArtifactCommitment(artifact: ExecutionArtifact): void;
+/** Strict adapter-side validation, including every envelope cross-field relationship. */
+export declare function assertArtifactEnvelope(artifact: unknown): ExecutionArtifact;
+export declare function assertArtifactFresh(artifact: ExecutionArtifact, nowMs?: number): void;

package/dist/vendor/otto-intel-mcp/execution-types.js

@@ -0,0 +1,157 @@
+import { getAddress, keccak256, stringToHex } from 'viem';
+import { isArtifactFreshnessWellFormed } from './artifact-id.js';
+import { refuse } from './execution-errors.js';
+import { EXECUTION_ARTIFACT_SCHEMA, } from './execution-tool-definitions.js';
+export { MAX_ARTIFACT_TTL_MS, artifactIdTimestampMs, createArtifactId } from './artifact-id.js';
+function canonicalize(value) {
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value))
+        return value.map((item) => canonicalize(item));
+    const source = value;
+    const sorted = {};
+    for (const key of Object.keys(source).sort()) {
+        if (source[key] !== undefined)
+            sorted[key] = canonicalize(source[key]);
+    }
+    return sorted;
+}
+export function canonicalJson(value) {
+    return JSON.stringify(canonicalize(value));
+}
+export function executionDigest(value) {
+    return keccak256(stringToHex(canonicalJson(value)));
+}
+export function accountBinding(profile) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            lifi: Object.freeze({ sender: address, receiver: address }),
+        }),
+    });
+}
+export function bridgeAccountBinding(profile, route) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            lifi: Object.freeze({
+                sender: address,
+                receiver: getAddress(route.destinationRecipient),
+                source_chain_id: profile.chainId,
+                destination_chain_id: route.destinationChainId,
+                sending_asset: getAddress(route.sendingAsset),
+                receiving_asset: getAddress(route.receivingAsset),
+            }),
+        }),
+    });
+}
+/**
+ * The v1 Polymarket profile is a single EOA in all three roles: it signs the order, it is the maker
+ * of record inside the signed struct, and it funds the collateral. A Safe profile would need a
+ * signature type (POLY_GNOSIS_SAFE vs POLY_1271) that spec §13 leaves open, so it is refused rather
+ * than guessed — which is why this factory takes no separate signer or funder.
+ */
+export function polymarketAccountBinding(profile, order) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            polymarket: Object.freeze({
+                maker: address,
+                signer: address,
+                funder: address,
+                exchange: getAddress(order.exchange),
+                token_id: order.tokenId,
+                signature_type: 0,
+            }),
+        }),
+    });
+}
+/**
+ * The v1 Hyperliquid profile binds the master account to the signing EOA. `tradingSigner` may be a
+ * DIFFERENT address — the user's own approved API wallet — and is taken as a declared fact: Otto never
+ * derives an agent key, which is the custody line spec §11 draws around
+ * `trade-execution-agent/src/lib/hyperliquid-client.ts:558`. The vault address is likewise declared,
+ * never inferred from the account.
+ */
+export function hyperliquidAccountBinding(profile, market) {
+    const address = getAddress(profile.address);
+    return Object.freeze({
+        kind: profile.kind,
+        address,
+        chainId: profile.chainId,
+        protocol_roles: Object.freeze({
+            hyperliquid: Object.freeze({
+                master: address,
+                trading_signer: market.tradingSigner ? getAddress(market.tradingSigner) : address,
+                vault_address: market.vaultAddress ? getAddress(market.vaultAddress) : null,
+                asset: market.asset,
+                asset_id: market.assetId,
+                sz_decimals: market.szDecimals,
+            }),
+        }),
+    });
+}
+export function assertArtifactAccountBinding(artifact, expected) {
+    const actual = artifact.account_binding;
+    if (actual.kind !== expected.kind ||
+        actual.chainId !== expected.chainId ||
+        getAddress(actual.address) !== getAddress(expected.address)) {
+        refuse('ACCOUNT_BINDING_MISMATCH', 'execution artifact is bound to a different account');
+    }
+}
+export function assertArtifactPayloadDigest(artifact) {
+    if (artifact.submission.artifact_id !== artifact.artifact_id ||
+        executionDigest(artifact.payload) !== artifact.submission.payload_digest) {
+        refuse('DIGEST_MISMATCH', 'execution artifact payload digest does not match its payload');
+    }
+}
+/**
+ * Commitment over the whole envelope except the commitment field itself. `valid_until` sits
+ * inside it, so freshness is bound to the artifact rather than being an editable side field.
+ */
+export function artifactCommitmentDigest(artifact) {
+    const { submission, ...envelope } = artifact;
+    const { artifact_digest: _committed, ...committedSubmission } = submission;
+    return executionDigest({ ...envelope, submission: committedSubmission });
+}
+/**
+ * Fail-closed commitment check: payload digest, whole-envelope commitment, and the
+ * constructor-owned freshness bound derived from the artifact id.
+ */
+export function assertArtifactCommitment(artifact) {
+    assertArtifactPayloadDigest(artifact);
+    if (artifactCommitmentDigest(artifact) !== artifact.submission.artifact_digest) {
+        refuse('DIGEST_MISMATCH', 'execution artifact digest does not commit to this envelope');
+    }
+    if (!isArtifactFreshnessWellFormed(artifact.artifact_id, artifact.valid_until)) {
+        refuse('ARTIFACT_INVALID', 'execution artifact expiry is outside the constructor bound');
+    }
+}
+/** Strict adapter-side validation, including every envelope cross-field relationship. */
+export function assertArtifactEnvelope(artifact) {
+    const parsed = EXECUTION_ARTIFACT_SCHEMA.safeParse(artifact);
+    if (!parsed.success) {
+        return refuse('ARTIFACT_INVALID', 'execution artifact failed strict envelope validation');
+    }
+    const envelope = parsed.data;
+    assertArtifactCommitment(envelope);
+    return envelope;
+}
+export function assertArtifactFresh(artifact, nowMs = Date.now()) {
+    // Fail-closed first: the commitment check binds valid_until to the artifact and rejects any
+    // expiry outside the construction-anchored ceiling, so the deadline below is constructor-owned.
+    assertArtifactCommitment(artifact);
+    if (Date.parse(artifact.valid_until) <= nowMs) {
+        refuse('STALE_ARTIFACT', 'execution artifact has expired');
+    }
+}
+//# sourceMappingURL=execution-types.js.map

package/dist/verify.d.ts

@@ -0,0 +1,2 @@
+/** verify.ts — re-exported from `./vendor/otto-intel-mcp/adapter-index.js` (moved 2026-08-29; see that entry's header). */
+export { VERIFY_CHECK_IDS, assertPlanSignableBy, assertVerifiedPlanIntact, defaultAdapterPolicy, isDeepFrozen, isVerifierOutput, verifiedPlanIdentity, verifySwapEnvelope, type AdapterPolicy, type AttributionPolicy, type PlanIdentity, type SignerIdentity, type SigningCapability, type SwapIntent, type VerifiedCheck, type VerifiedStep, type VerifiedSwap, type VerifyExpectations, } from './vendor/otto-intel-mcp/adapter-index.js';

package/dist/verify.js

@@ -0,0 +1,3 @@
+/** verify.ts — re-exported from `./vendor/otto-intel-mcp/adapter-index.js` (moved 2026-08-29; see that entry's header). */
+export { VERIFY_CHECK_IDS, assertPlanSignableBy, assertVerifiedPlanIntact, defaultAdapterPolicy, isDeepFrozen, isVerifierOutput, verifiedPlanIdentity, verifySwapEnvelope, } from './vendor/otto-intel-mcp/adapter-index.js';
+//# sourceMappingURL=verify.js.map

package/dist/x402-table.d.ts

@@ -0,0 +1,99 @@
+/**
+ * x402-table.ts — the expected-requirements table for x402 challenges (docs/0817_x402_leg_expected_requirements_table.md).
+ *
+ * In Model B the user's own adapter signs x402 payments. Before a challenge reaches that signer, every
+ * field the user is about to authorize payment against is checked against THIS static table — never
+ * derived from the incoming challenge. The failure this prevents: an altered or substituted 402 redirecting
+ * the payment to a substituted recipient, an inflated amount, or a long-lived authorization.
+ *
+ * Rules (0817 §2):
+ *   - exact match, one canonical URL normalization (scheme+host lowercase, no trailing slash);
+ *     addresses compared checksummed; amounts as BigInt atomic units, never floats.
+ *   - unknown resource ⇒ refuse. The table is an allowlist.
+ *   - the table is data, the check is code: adding a row never touches validation.
+ *   - P3: rows are exact values — the type admits no pattern, prefix or regex field.
+ *   - P4: fail-closed — a validation failure throws; nothing reaches the signer.
+ *   - the validated requirement is returned as an IMMUTABLE snapshot, and the signer revalidates the
+ *     document against the table again immediately before it signs (see eoa-signer.ts): validation
+ *     and hand-off are two moments, and nothing that happens in between is trusted.
+ */
+import { type Address } from 'viem';
+export declare const X402_TABLE_VERSION = "x402-req-2026-08-28-v4";
+export interface X402ExpectedRow {
+    /** Exact resource URL after canonical normalization. No patterns. */
+    readonly resource: string;
+    readonly scheme: 'exact';
+    readonly network: 'eip155:8453';
+    /** Exact token contract (USDC on Base), never a symbol. */
+    readonly asset: Address;
+    /** Exact recipient, checksummed. */
+    readonly pay_to: Address;
+    /** The listed price in atomic units; the challenge amount must EQUAL it (fixed-price rows). */
+    readonly amount_atomic: string;
+    /** The EXACT authorization window the challenge must ask for (EIP-3009 validBefore − now). Exact, like every other field. */
+    readonly max_timeout_seconds: number;
+    /** The EIP-712 domain the signer will sign under; pinned so a challenge cannot move the domain. */
+    readonly extra: {
+        readonly name: string;
+        readonly version: string;
+    };
+}
+export interface X402Table {
+    readonly table_version: string;
+    readonly rows: readonly X402ExpectedRow[];
+}
+/** Otto's published x402 revenue recipient of record (captured live 2026-08-25/26 from all four challenges). */
+export declare const OTTO_X402_PAY_TO: `0x${string}`;
+export declare const BASE_USDC: `0x${string}`;
+/**
+ * Rows whose SERVED price is changing on the storefront (catalog.ts already carries the new price)
+ * but whose live capture in test/fixtures has not been re-captured yet. This table is an EXACT
+ * match against a signed live 402, so it can only move AFTER the backend deploys the new price and
+ * the fixture is re-captured — between those two moments the adapter REFUSES the row (fail-closed,
+ * never an overpay). `scripts/audit/client-price-caps.mjs` downgrades these rows to a warning until
+ * the re-capture PR clears them; it hard-fails any other table/catalog mismatch, and it fails a
+ * declaration that lingers after the table already matches (so this list cannot go stale).
+ * EMPTY = every row's table amount equals its live capture and the catalog price.
+ */
+export declare const PENDING_RECAPTURE: readonly string[];
+/** The no-argument intelligence resources the proof may pay for ($0.001 reads; /base-season $0.002). Every row has a live capture in test/fixtures. */
+export declare const X402_TABLE: X402Table;
+export declare const X402_REFUSAL_CODES: readonly ["X402_MALFORMED", "X402_UNKNOWN_RESOURCE", "X402_SCHEME_MISMATCH", "X402_NETWORK_MISMATCH", "X402_ASSET_MISMATCH", "X402_PAYTO_MISMATCH", "X402_AMOUNT_EXCEEDED", "X402_TIMEOUT_EXCEEDED", "X402_DOMAIN_MISMATCH", "X402_SPEND_LIMIT_EXCEEDED"];
+export type X402RefusalCode = (typeof X402_REFUSAL_CODES)[number];
+export declare class X402Refusal extends Error {
+    readonly code: X402RefusalCode;
+    readonly field: string;
+    readonly expected: string;
+    readonly actual: string;
+    readonly tableVersion: string;
+    readonly errorType: X402RefusalCode;
+    constructor(code: X402RefusalCode, field: string, expected: string, actual: string, tableVersion: string);
+}
+export declare function canonicalResourceUrl(raw: string): string;
+export interface PaymentRequirementLike {
+    readonly scheme: string;
+    readonly network: string;
+    readonly amount: string;
+    readonly asset: string;
+    readonly payTo: string;
+    readonly maxTimeoutSeconds: number;
+    readonly extra: {
+        readonly name: string;
+        readonly version: string;
+    };
+}
+export interface ValidatedX402Challenge {
+    readonly row: X402ExpectedRow;
+    /** An IMMUTABLE canonical snapshot of the accepted requirement's bound fields, taken at validation time. */
+    readonly requirement: PaymentRequirementLike;
+    readonly requirementIndex: number;
+    readonly amount: bigint;
+}
+/** True iff `requirement` carries exactly the row's bound fields (checksummed addresses, exact amount, window ≤ ceiling, pinned domain). */
+export declare function requirementMatchesRow(requirement: unknown, row: X402ExpectedRow): boolean;
+/**
+ * Validate an x402 v2 PaymentRequired document against the table. Returns the single accepted
+ * requirement that matches its row exactly (as an immutable snapshot), or throws the refusal naming
+ * the first mismatched field.
+ */
+export declare function validateX402Challenge(paymentRequired: unknown, table?: X402Table): ValidatedX402Challenge;