@elizaos/plugin-x402 2.0.0-alpha.6 → 2.0.0-beta.1

package/dist/payment-config.d.ts

@@ -0,0 +1,256 @@
+/**
+ * Configuration for x402 micropayment system
+ * Route-specific pricing is now defined locally in each route definition
+ *
+ * Payment Verification Methods:
+ *
+ * 1. Direct Blockchain Proof (X-Payment-Proof header)
+ *    - User sends payment transaction on-chain
+ *    - Transaction signature is verified against blockchain
+ *    - Supports: Solana, Base, Polygon
+ *    - Format: base64-encoded JSON with signature and authorization
+ *
+ * 2. Facilitator Payment ID (X-Payment-Id header)
+ *    - Third-party service handles payment
+ *    - Service returns payment ID after successful payment
+ *    - ID is verified through facilitator API
+ *    - Configured via X402_FACILITATOR_URL environment variable
+ *    - Example: X402_FACILITATOR_URL=https://facilitator.x402.ai
+ *
+ * 3. Standard X-Payment / PAYMENT-SIGNATURE (x402-fetch / CDP-style)
+ *    - Base64(JSON) or raw JSON: `{ x402Version, accepted, payload }`
+ *    - Verified and settled with POST `{ paymentPayload, paymentRequirements }`
+ *      to facilitator `/verify` then `/settle`
+ *    - Override endpoints with `X402_FACILITATOR_VERIFY_URL` and
+ *      `X402_FACILITATOR_SETTLE_URL`; otherwise append `/verify` and `/settle`
+ *      to `X402_FACILITATOR_URL`.
+ *
+ * The facilitator endpoint should implement:
+ *   GET /verify/{paymentId}
+ *     - 200 OK: Payment is valid (with optional { valid: true } JSON body)
+ *     - 404 Not Found: Payment ID doesn't exist
+ *     - 410 Gone: Payment already used (prevents replay attacks)
+ *
+ * Seller-side replay: proof / payment ID keys are atomically reserved in the
+ * SQL-backed runtime cache by default (`X402_REPLAY_DURABLE`, see x402 docs),
+ * then marked consumed after successful verification. Disable with
+ * `X402_REPLAY_DURABLE=0` for in-memory TTL-only behavior (dev / tests).
+ */
+import type { X402ScanNetwork } from "./x402-types.js";
+/** Networks supported by built-in x402 presets and verification */
+export type Network = "BASE" | "SOLANA" | "POLYGON" | "BSC";
+/**
+ * Built-in networks supported by default
+ */
+export declare const BUILT_IN_NETWORKS: readonly ["BASE", "SOLANA", "POLYGON", "BSC"];
+export declare const DEFAULT_NETWORK: Network;
+/**
+ * Convert our Network type to x402scan-compliant network names
+ * @throws {Error} If network is not supported by x402scan
+ */
+export declare function toX402Network(network: Network): X402ScanNetwork;
+/** Shipped fallbacks — not your treasury; startup validation warns / errors in production. */
+export declare const BUNDLED_EXAMPLE_EVM_PAYOUT = "0x066E94e1200aa765d0A6392777D543Aa6Dea606C";
+export declare const BUNDLED_EXAMPLE_SOLANA_PAYOUT = "3nMBmufBUBVnk28sTp3NsrSJsdVGTyLZYmsqpMFaUT9J";
+export declare function paymentAddressIsBundledExample(network: Network, paymentAddress: string): boolean;
+/**
+ * Network-specific wallet addresses
+ * Uses existing environment variables from your project configuration
+ */
+export declare const PAYMENT_ADDRESSES: Partial<Record<Network, string>>;
+/**
+ * Get the base URL for the current server
+ * Used to construct full resource URLs for x402 responses
+ */
+export declare function getBaseUrl(): string;
+/**
+ * Convert a route path to a full resource URL
+ */
+export declare function toResourceUrl(path: string): string;
+/**
+ * Token configuration for Solana
+ */
+export declare const SOLANA_TOKENS: {
+    readonly USDC: {
+        readonly symbol: "USDC";
+        readonly address: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v";
+        readonly decimals: 6;
+    };
+    readonly AI16Z: {
+        readonly symbol: "ai16z";
+        readonly address: "HeLp6NuQkmYB4pYWo2zYs22mESHXPQYzXbB8n4V98jwC";
+        readonly decimals: 6;
+    };
+    readonly DEGENAI: {
+        readonly symbol: "degenai";
+        readonly address: "Gu3LDkn7Vx3bmCzLafYNKcDxv2mH7YN44NJZFXnypump";
+        readonly decimals: 6;
+    };
+    readonly ELIZAOS: {
+        readonly symbol: "elizaOS";
+        readonly address: "DuMbhu7mvQvqQHGcnikDgb4XegXJRyhUBfdU22uELiZA";
+        readonly decimals: 6;
+    };
+};
+/**
+ * Token configuration for Base (EVM)
+ */
+export declare const BASE_TOKENS: {
+    readonly USDC: {
+        readonly symbol: "USDC";
+        readonly address: "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913";
+        readonly decimals: 6;
+    };
+    readonly ELIZAOS: {
+        readonly symbol: "elizaOS";
+        readonly address: "0xea17Df5Cf6D172224892B5477A16ACb111182478";
+        readonly decimals: 18;
+    };
+};
+/**
+ * Token configuration for Polygon (EVM)
+ */
+export declare const POLYGON_TOKENS: {
+    readonly USDC: {
+        readonly symbol: "USDC";
+        readonly address: "0x3c499c542cEF5E3811e1192ce70d8cC03d5c3359";
+        readonly decimals: 6;
+    };
+};
+/**
+ * Token configuration for BNB Smart Chain (EVM)
+ */
+export declare const BSC_TOKENS: {
+    readonly USDC: {
+        readonly symbol: "USDC";
+        readonly address: "0x8AC76a51cc950d9822D68b83fE1Ad97B32Cd580d";
+        readonly decimals: 18;
+    };
+};
+/**
+ * Default asset for each network (used in x402 responses)
+ */
+export declare const NETWORK_ASSETS: Partial<Record<Network, string>>;
+/**
+ * Get all accepted assets for a network
+ * @throws {Error} If network is not supported
+ */
+export declare function getNetworkAssets(network: Network): string[];
+export declare const PAYMENT_RECEIVER_ADDRESS: string;
+/**
+ * Named payment config definition - stores individual fields, CAIP-19 constructed on-demand
+ */
+export interface PaymentConfigDefinition {
+    network: Network;
+    assetNamespace: string;
+    assetReference: string;
+    paymentAddress: string;
+    symbol: string;
+    chainId?: string;
+}
+/**
+ * Payment configuration registry - named configs for easy reference
+ */
+export declare const PAYMENT_CONFIGS: Record<string, PaymentConfigDefinition>;
+/**
+ * Construct CAIP-19 asset ID from payment config fields
+ */
+export declare function getCAIP19FromConfig(config: PaymentConfigDefinition): string;
+/**
+ * Register a custom payment configuration
+ * Plugins call this in their init() function
+ *
+ * A second call with the same `name` (or the same `agentId`+`name` for scoped
+ * keys) throws unless `override: true` is set, so two plugins cannot silently
+ * replace each other in `CUSTOM_PAYMENT_CONFIGS`.
+ *
+ * @example
+ * ```typescript
+ * registerX402Config('base_ai16z', {
+ *   network: 'BASE',
+ *   assetNamespace: 'erc20',
+ *   assetReference: '0x...',
+ *   paymentAddress: process.env.BASE_PUBLIC_KEY,
+ *   symbol: 'AI16Z',
+ *   chainId: '8453'
+ * });
+ *
+ * // Agent-specific override
+ * registerX402Config('base_usdc', {...}, { agentId: runtime.agentId });
+ * ```
+ */
+export declare function registerX402Config(name: string, config: PaymentConfigDefinition, options?: {
+    override?: boolean;
+    agentId?: string;
+}): void;
+/**
+ * Get payment config - checks custom registry then built-in
+ * Supports agent-specific configs via agentId parameter
+ */
+export declare function getPaymentConfig(name: string, agentId?: string): PaymentConfigDefinition;
+/**
+ * List all available payment configs (built-in + custom)
+ * Optionally filter to agent-specific configs
+ */
+export declare function listX402Configs(agentId?: string): string[];
+/**
+ * Validate payment config name
+ */
+export declare function validatePaymentConfigName(name: string): boolean;
+export type { X402Config } from "@elizaos/core";
+/**
+ * Get the payment address for a specific network
+ * @throws {Error} If network is not configured
+ */
+export declare function getPaymentAddress(network: Network): string;
+/**
+ * Get all network addresses with metadata
+ * Only returns networks that have configured addresses
+ */
+export declare function getNetworkAddresses(networks: Network[]): Array<{
+    name: Network;
+    address: string;
+    facilitatorEndpoint?: string;
+}>;
+/**
+ * Approximate USD/token map (float) for dashboards or legacy callers.
+ * **Atomic amounts** use exact rational math from the same env defaults — see
+ * `atomicAmountForPriceInCents` / `getTokenUsdPerTokenRational` in this file.
+ */
+export declare const TOKEN_PRICES_USD: Record<string, number>;
+/**
+ * Smallest-unit token amount for x402 `maxAmountRequired` and verification,
+ * from integer USD cents and a concrete payment config (symbol + network).
+ */
+export declare function atomicAmountForPriceInCents(priceInCents: number, config: PaymentConfigDefinition): string;
+/**
+ * Parse price string (e.g., "$0.10") as a USD **dollar** amount and convert to
+ * the asset’s smallest units (ceil), using the same rational pricing as
+ * `atomicAmountForPriceInCents` / env overrides (`ELIZAOS_PRICE_USD`, etc.).
+ */
+export declare function parsePrice(price: string, asset?: string, network?: Network): string;
+/**
+ * Get token address for any network and asset
+ */
+export declare function getTokenAddress(asset: string, network: Network): string | undefined;
+/**
+ * Get the asset for a specific network
+ * @throws {Error} If network is not configured
+ */
+export declare function getNetworkAsset(network: Network): string;
+/**
+ * Get x402 system health status
+ * Useful for monitoring and debugging
+ */
+export declare function getX402Health(): {
+    networks: Array<{
+        network: Network;
+        configured: boolean;
+        address: string | null;
+    }>;
+    facilitator: {
+        url: string | null;
+        configured: boolean;
+    };
+};
+//# sourceMappingURL=payment-config.d.ts.map

package/dist/payment-config.d.ts.map

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

package/dist/payment-wrapper.d.ts

@@ -0,0 +1,42 @@
+import type { Character, PaymentEnabledRoute, Route } from "@elizaos/core";
+/**
+ * x402 **seller** middleware for plugin HTTP routes.
+ *
+ * **Why one middleware layer:** plugins should not each reimplement 402 bodies,
+ * header encodings, facilitator POSTs, replay semantics, or chain RPC checks.
+ * This module is the single integration point for “paid route” behavior.
+ *
+ * **Why multiple verification strategies coexist:** deployments differ—some
+ * have on-chain receipts only, some use facilitator payment IDs, some use modern
+ * `PAYMENT-SIGNATURE` payloads. Keeping strategies behind one `verifyPayment`
+ * function preserves one gate while letting operators choose what their clients send.
+ *
+ * **Why standard path calls settle:** see `x402-standard-payment.ts`—settlement is
+ * the economically meaningful step after verify for facilitator-backed flows.
+ *
+ * **Why we still emit legacy JSON 402:** backward compatibility for wallets and
+ * tools that parse the body; V2 clients additionally read `PAYMENT-REQUIRED`.
+ */
+/**
+ * Set on routes returned by {@link applyPaymentProtection} so HTTP dispatch
+ * (`tryHandleRuntimePluginRoute`) does not call {@link createPaymentAwareHandler} again.
+ */
+export declare const X402_ROUTE_PAYMENT_WRAPPED: unique symbol;
+export declare function isRoutePaymentWrapped(route: unknown): boolean;
+/**
+ * Create a payment-aware route handler
+ */
+export declare function createPaymentAwareHandler(route: PaymentEnabledRoute): NonNullable<Route["handler"]>;
+export type { X402RequestValidator, X402ValidationResult } from "@elizaos/core";
+/**
+ * Apply payment protection to an array of routes
+ * Runs comprehensive startup validation before applying protection. Pass
+ * `character`/`agentId` so routes that use the `x402: true` shorthand (which
+ * resolves price + paymentConfigs from `character.settings.x402`) can validate
+ * without errors.
+ */
+export declare function applyPaymentProtection(routes: Route[], context?: {
+    character?: Character;
+    agentId?: string;
+}): Route[];
+//# sourceMappingURL=payment-wrapper.d.ts.map

package/dist/payment-wrapper.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"payment-wrapper.d.ts","sourceRoot":"","sources":["../src/payment-wrapper.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,SAAS,EAET,mBAAmB,EACnB,KAAK,EAIN,MAAM,eAAe,CAAC;AAsEvB;;;;;;;;;;;;;;;;;GAiBG;AAEH;;;GAGG;AACH,eAAO,MAAM,0BAA0B,eAEtC,CAAC;AAEF,wBAAgB,qBAAqB,CAAC,KAAK,EAAE,OAAO,GAAG,OAAO,CAM7D;AAquCD;;GAEG;AACH,wBAAgB,yBAAyB,CACvC,KAAK,EAAE,mBAAmB,GACzB,WAAW,CAAC,KAAK,CAAC,SAAS,CAAC,CAAC,CA0Q/B;AAqTD,YAAY,EAAE,oBAAoB,EAAE,oBAAoB,EAAE,MAAM,eAAe,CAAC;AAEhF;;;;;;GAMG;AACH,wBAAgB,sBAAsB,CACpC,MAAM,EAAE,KAAK,EAAE,EACf,OAAO,CAAC,EAAE;IAAE,SAAS,CAAC,EAAE,SAAS,CAAC;IAAC,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GACpD,KAAK,EAAE,CAkCT"}

package/dist/startup-validator.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Startup validation for x402 payment system
+ * Validates payment configs and routes before the server starts
+ */
+import type { Character, Route } from "@elizaos/core";
+/**
+ * Validation result with warnings and errors
+ */
+export interface StartupValidationResult {
+    valid: boolean;
+    errors: string[];
+    warnings: string[];
+}
+/**
+ * Comprehensive startup validation
+ * Call this before starting the server to catch configuration issues early
+ */
+export declare function validateX402Startup(routes: Route[], character?: Character, options?: {
+    agentId?: string;
+}): StartupValidationResult;
+/**
+ * Validate routes and throw if invalid
+ * This is used by applyPaymentProtection to fail fast on startup
+ */
+export declare function validateAndThrowIfInvalid(routes: Route[], character?: Character, options?: {
+    agentId?: string;
+}): void;
+//# sourceMappingURL=startup-validator.d.ts.map

package/dist/startup-validator.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"startup-validator.d.ts","sourceRoot":"","sources":["../src/startup-validator.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAEH,OAAO,KAAK,EACV,SAAS,EAGT,KAAK,EACN,MAAM,eAAe,CAAC;AAUvB;;GAEG;AACH,MAAM,WAAW,uBAAuB;IACtC,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,MAAM,EAAE,CAAC;IACjB,QAAQ,EAAE,MAAM,EAAE,CAAC;CACpB;AAiQD;;;GAGG;AACH,wBAAgB,mBAAmB,CACjC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,uBAAuB,CAoCzB;AAED;;;GAGG;AACH,wBAAgB,yBAAyB,CACvC,MAAM,EAAE,KAAK,EAAE,EACf,SAAS,CAAC,EAAE,SAAS,EACrB,OAAO,CAAC,EAAE;IAAE,OAAO,CAAC,EAAE,MAAM,CAAA;CAAE,GAC7B,IAAI,CAUN"}

package/dist/types.d.ts

@@ -0,0 +1,158 @@
+/**
+ * Strict TypeScript types for x402 payment middleware
+ * Replaces all 'any' types with proper interfaces
+ */
+import type { AgentRuntime, RouteRequest } from "@elizaos/core";
+/**
+ * Request shape for x402 (matches plugin routes + IncomingMessage headers)
+ */
+export type X402Request = RouteRequest & {
+    method: string;
+    path: string;
+    headers: Record<string, string | string[] | undefined>;
+    query: Record<string, string | string[] | undefined>;
+    params: Record<string, string>;
+};
+/**
+ * Express-like response object
+ */
+export interface X402Response {
+    status(code: number): X402ResponseStatus;
+    json(data: unknown): void;
+    setHeader?(name: string, value: string | readonly string[]): void;
+    headersSent?: boolean;
+}
+export interface X402ResponseStatus {
+    json(data: unknown): void;
+}
+/**
+ * EIP-712 Authorization data structure
+ */
+export interface EIP712Authorization {
+    from: string;
+    to: string;
+    value: string;
+    validAfter: string;
+    validBefore: string;
+    nonce: string;
+}
+/**
+ * EIP-712 Domain structure
+ */
+export interface EIP712Domain {
+    name: string;
+    version: string;
+    chainId: number;
+    verifyingContract: string;
+}
+export type { EIP712Authorization as EIP712AuthorizationType, EIP712Domain as EIP712DomainType, };
+/**
+ * Payment proof data (EIP-712 format)
+ */
+export interface EIP712PaymentProof {
+    signature: string;
+    authorization: EIP712Authorization;
+    domain?: EIP712Domain;
+    network?: string;
+    scheme?: string;
+    v?: number;
+    r?: string;
+    s?: string;
+    payload?: {
+        signature: string;
+        authorization: EIP712Authorization;
+    };
+}
+/**
+ * Solana payment proof
+ */
+export interface SolanaPaymentProof {
+    signature: string;
+    network: "SOLANA";
+}
+/**
+ * Legacy payment proof format
+ */
+export interface LegacyPaymentProof {
+    network: string;
+    address: string;
+    signature: string;
+}
+/**
+ * Runtime interface with required methods for x402
+ * Uses IAgentRuntime directly to avoid type conflicts
+ */
+export type X402Runtime = AgentRuntime;
+/**
+ * Payment verification parameters (route price + allowed presets)
+ */
+export interface PaymentVerificationParams {
+    paymentProof?: string;
+    paymentId?: string;
+    route: string;
+    /** Integer USD cents (same as route `x402.priceInCents`) */
+    priceInCents: number;
+    /** Names from `x402.paymentConfigs` (resolved), in declaration order */
+    paymentConfigNames: string[];
+    agentId?: string;
+    runtime: X402Runtime;
+    req?: X402Request;
+}
+/** Successful verification metadata for events / receipts */
+export interface PaymentVerifiedDetails {
+    paymentConfig: string;
+    network: string;
+    /** Smallest units of the paid asset */
+    amountAtomic: string;
+    symbol?: string;
+    payer?: string;
+    proofId?: string;
+    paymentResponse?: string;
+}
+export type VerifyPaymentResult = {
+    ok: false;
+} | {
+    ok: true;
+    details: PaymentVerifiedDetails;
+};
+/**
+ * Payment receipt for tracking
+ */
+export interface PaymentReceipt {
+    paymentId: string;
+    route: string;
+    amount: string;
+    network: string;
+    timestamp: number;
+    signature?: string;
+    verified: boolean;
+}
+/**
+ * Facilitator verification response
+ */
+export interface FacilitatorVerificationResponse {
+    valid?: boolean;
+    verified?: boolean;
+    status?: string;
+    message?: string;
+    /** When present, must equal the route’s `resource` URL we sent on verify */
+    resource?: string;
+    /** When present, must match the plugin route path */
+    routePath?: string;
+    /** Alias some facilitators use for path */
+    route?: string;
+    /** When present, must match the route’s `priceInCents` */
+    priceInCents?: number;
+    /** When present, must be one of the route’s allowed preset names */
+    paymentConfig?: string;
+    /** When present, every entry must be in the route’s allowlist */
+    paymentConfigs?: string[];
+}
+/** Sent to the facilitator so responses can be bound to a specific purchase */
+export interface FacilitatorVerifyContext {
+    resource: string;
+    routePath: string;
+    priceInCents: number;
+    paymentConfigNames: 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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"}

package/dist/x402-facilitator-binding.d.ts

@@ -0,0 +1,9 @@
+import type { FacilitatorVerificationResponse, FacilitatorVerifyContext } from "./types.js";
+/**
+ * When true, facilitator JSON must echo `resource`, route, `priceInCents`, and
+ * `paymentConfig` so a generic 200 cannot unlock unrelated routes.
+ * Set `X402_FACILITATOR_RELAXED_BINDING=1` if your facilitator does not return these fields yet.
+ */
+export declare function isFacilitatorBindingRelaxed(): boolean;
+export declare function facilitatorVerifyResponseMatchesRoute(data: FacilitatorVerificationResponse, ctx: FacilitatorVerifyContext, relaxed: boolean): boolean;
+//# sourceMappingURL=x402-facilitator-binding.d.ts.map

package/dist/x402-facilitator-binding.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-facilitator-binding.d.ts","sourceRoot":"","sources":["../src/x402-facilitator-binding.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,+BAA+B,EAC/B,wBAAwB,EACzB,MAAM,YAAY,CAAC;AAEpB;;;;GAIG;AACH,wBAAgB,2BAA2B,IAAI,OAAO,CAKrD;AAgFD,wBAAgB,qCAAqC,CACnD,IAAI,EAAE,+BAA+B,EACrC,GAAG,EAAE,wBAAwB,EAC7B,OAAO,EAAE,OAAO,GACf,OAAO,CAIT"}

package/dist/x402-replay-durable.d.ts

@@ -0,0 +1,30 @@
+import { type AgentRuntime } from "@elizaos/core";
+/** Stored in the runtime cache while verification owns a durable reservation. */
+export type X402ReplayInflightPayload = {
+    state: "inflight";
+    owner: string;
+    reservedAt: number;
+    expiresAt: number;
+};
+/** Stored in the runtime cache after a successful payment verification. */
+export type X402ReplayConsumedPayload = {
+    state: "consumed";
+    consumedAt: number;
+};
+export type X402ReplayPayload = X402ReplayInflightPayload | X402ReplayConsumedPayload;
+export type DurableReplayReservation = {
+    ok: true;
+    owner: string;
+    atomic: boolean;
+} | {
+    ok: false;
+};
+/**
+ * Stable cache key for a replay credential, scoped by agent so two agents never
+ * share the same cache row.
+ */
+export declare function durableReplayCacheKey(agentId: string | undefined, replayKey: string): string;
+export declare function durableReplayTryReserve(runtime: AgentRuntime, agentId: string | undefined, keys: string[]): Promise<DurableReplayReservation>;
+export declare function durableReplayAbortReservation(runtime: AgentRuntime, agentId: string | undefined, keys: string[], owner?: string): Promise<void>;
+export declare function durableReplayCommitReservation(runtime: AgentRuntime, agentId: string | undefined, keys: string[], owner?: string): Promise<void>;
+//# sourceMappingURL=x402-replay-durable.d.ts.map

package/dist/x402-replay-durable.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-replay-durable.d.ts","sourceRoot":"","sources":["../src/x402-replay-durable.ts"],"names":[],"mappings":"AACA,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,eAAe,CAAC;AAO1D,iFAAiF;AACjF,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,UAAU,CAAC;IAClB,KAAK,EAAE,MAAM,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;IACnB,SAAS,EAAE,MAAM,CAAC;CACnB,CAAC;AAEF,2EAA2E;AAC3E,MAAM,MAAM,yBAAyB,GAAG;IACtC,KAAK,EAAE,UAAU,CAAC;IAClB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,iBAAiB,GACzB,yBAAyB,GACzB,yBAAyB,CAAC;AAE9B,MAAM,MAAM,wBAAwB,GAChC;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,KAAK,EAAE,MAAM,CAAC;IAAC,MAAM,EAAE,OAAO,CAAA;CAAE,GAC5C;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAAC;AAMlB;;;GAGG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,SAAS,EAAE,MAAM,GAChB,MAAM,CAGR;AAmHD,wBAAsB,uBAAuB,CAC3C,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,EAAE,GACb,OAAO,CAAC,wBAAwB,CAAC,CAgFnC;AAED,wBAAsB,6BAA6B,CACjD,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAyBf;AAED,wBAAsB,8BAA8B,CAClD,OAAO,EAAE,YAAY,EACrB,OAAO,EAAE,MAAM,GAAG,SAAS,EAC3B,IAAI,EAAE,MAAM,EAAE,EACd,KAAK,CAAC,EAAE,MAAM,GACb,OAAO,CAAC,IAAI,CAAC,CAqCf"}

package/dist/x402-replay-guard.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Replay + in-flight guard for x402 verification.
+ *
+ * - **In-flight (`inflight`)**: in-memory only; prevents concurrent duplicate
+ *   verification in the same process (TOCTOU between check and verify).
+ * - **Consumed**: when `X402_REPLAY_DURABLE` is not disabled and `runtime` is
+ *   passed, credentials are recorded via `runtime.setCache` / `getCache` so they
+ *   survive restarts and work across multiple server processes sharing the DB.
+ *   Entries do not expire (same tx hash / payment id must not unlock paid routes twice).
+ * - **Fallback**: set `X402_REPLAY_DURABLE=0` (or `false` / `off`) to use only an
+ *   in-memory TTL map (`X402_REPLAY_WINDOW_MS` / `X402_REPLAY_TTL_MS`, default 10m).
+ *   If `runtime` is omitted (e.g. isolated unit tests), that same in-memory path is used.
+ */
+import { type AgentRuntime } from "@elizaos/core";
+/** When true (default), use runtime cache for consumed credentials. */
+export declare function isDurableReplayEnabled(): boolean;
+/**
+ * Reserve canonical replay keys for the duration of verification.
+ * Returns false if any key is already consumed, or already in-flight in this process.
+ */
+export declare function replayGuardTryBegin(keys: string[], runtime?: AgentRuntime, agentId?: string): Promise<boolean>;
+/** Release reservation after a failed or abandoned verification attempt. */
+export declare function replayGuardAbort(keys: string[]): void;
+/** Release a durable reservation after a failed or abandoned verification attempt. */
+export declare function replayGuardAbortAsync(keys: string[], runtime?: AgentRuntime, agentId?: string): Promise<void>;
+/** Mark keys consumed after a successful verification (clears in-flight). */
+export declare function replayGuardCommit(keys: string[], runtime?: AgentRuntime, agentId?: string): Promise<void>;
+//# sourceMappingURL=x402-replay-guard.d.ts.map

package/dist/x402-replay-guard.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-replay-guard.d.ts","sourceRoot":"","sources":["../src/x402-replay-guard.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAEH,OAAO,EAAE,KAAK,YAAY,EAAU,MAAM,eAAe,CAAC;AAyB1D,uEAAuE;AACvE,wBAAgB,sBAAsB,IAAI,OAAO,CAIhD;AAED;;;GAGG;AACH,wBAAsB,mBAAmB,CACvC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,OAAO,CAAC,CAgDlB;AAED,4EAA4E;AAC5E,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,MAAM,EAAE,GAAG,IAAI,CAKrD;AAED,sFAAsF;AACtF,wBAAsB,qBAAqB,CACzC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAQf;AAED,6EAA6E;AAC7E,wBAAsB,iBAAiB,CACrC,IAAI,EAAE,MAAM,EAAE,EACd,OAAO,CAAC,EAAE,YAAY,EACtB,OAAO,CAAC,EAAE,MAAM,GACf,OAAO,CAAC,IAAI,CAAC,CAgCf"}

package/dist/x402-replay-keys.d.ts

@@ -0,0 +1,21 @@
+/**
+ * Replay key for facilitator payment IDs (sanitized id → stable hash).
+ */
+export declare function paymentIdReplayKey(paymentId: string): string | null;
+/**
+ * For route handlers: only treat the proof as base64-wrapped UTF-8 when it passes
+ * the same heuristics as replay-key extraction. Raw `0x…` tx hashes and colon proofs
+ * stay intact (unlike unconditional `Buffer.from(s, "base64")`).
+ */
+export declare function decodePaymentProofForParsing(proof: string): string;
+/**
+ * Canonical replay keys derivable from a payment proof string (raw or base64-wrapped).
+ * Same on-chain tx / Solana signature / EIP-712 intent maps to the same key regardless
+ * of outer encoding (e.g. base64 vs plain).
+ */
+export declare function replayKeysFromProofString(proof: string): string[];
+/**
+ * All replay keys to consult before verification and to mark after a successful one.
+ */
+export declare function collectReplayKeysToCheck(paymentProof?: string, paymentId?: string): string[];
+//# sourceMappingURL=x402-replay-keys.d.ts.map

package/dist/x402-replay-keys.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-replay-keys.d.ts","sourceRoot":"","sources":["../src/x402-replay-keys.ts"],"names":[],"mappings":"AAMA;;GAEG;AACH,wBAAgB,kBAAkB,CAAC,SAAS,EAAE,MAAM,GAAG,MAAM,GAAG,IAAI,CAInE;AAgCD;;;;GAIG;AACH,wBAAgB,4BAA4B,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,CAElE;AAgED;;;;GAIG;AACH,wBAAgB,yBAAyB,CAAC,KAAK,EAAE,MAAM,GAAG,MAAM,EAAE,CAWjE;AAED;;GAEG;AACH,wBAAgB,wBAAwB,CACtC,YAAY,CAAC,EAAE,MAAM,EACrB,SAAS,CAAC,EAAE,MAAM,GACjB,MAAM,EAAE,CAUV"}

package/dist/x402-resolve.d.ts

@@ -0,0 +1,6 @@
+import type { AgentRuntime, PaymentEnabledRoute, X402Config } from "@elizaos/core";
+export declare const X402_EVENT_PAYMENT_VERIFIED = "PAYMENT_VERIFIED";
+export declare const X402_EVENT_PAYMENT_REQUIRED = "PAYMENT_REQUIRED";
+/** Resolves `x402: true` / partial route config using `character.settings.x402`. */
+export declare function resolveEffectiveX402(route: PaymentEnabledRoute, runtime: AgentRuntime): X402Config | null;
+//# sourceMappingURL=x402-resolve.d.ts.map

package/dist/x402-resolve.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"x402-resolve.d.ts","sourceRoot":"","sources":["../src/x402-resolve.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EACV,YAAY,EAGZ,mBAAmB,EACnB,UAAU,EACX,MAAM,eAAe,CAAC;AAEvB,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAC9D,eAAO,MAAM,2BAA2B,qBAAqB,CAAC;AAW9D,oFAAoF;AACpF,wBAAgB,oBAAoB,CAClC,KAAK,EAAE,mBAAmB,EAC1B,OAAO,EAAE,YAAY,GACpB,UAAU,GAAG,IAAI,CAkBnB"}