@bankofai/x402 0.5.9 → 0.6.0-beta.0

package/dist/server/x402Server.js

@@ -0,0 +1,318 @@
+/**
+ * X402Server — TypeScript port of `bankofai.x402.server.X402Server`.
+ *
+ * High-level server orchestration:
+ * - Registry of {@link ServerMechanism}s keyed by `(network, scheme)`
+ * - Build {@link PaymentRequirements} from {@link ResourceConfig} via `parsePrice`
+ *   + optional facilitator `feeQuote` enrichment for permit-style schemes
+ * - Anti-tamper validation of incoming `PaymentPayload` against server's
+ *   original requirements
+ * - Delegates `/verify` and `/settle` to a {@link FacilitatorClient}
+ *
+ * This sits **above** the framework-agnostic {@link processX402Request} core
+ * (see `src/middleware/core.ts`). Framework middleware (Hono / Express)
+ * can be wired against either:
+ * - Raw `accepts[]` + `FacilitatorClient` (lower-level, `processX402Request`)
+ * - `X402Server` + `ResourceConfig[]` (higher-level, this file)
+ */
+import { getAddress, isAddress } from 'viem';
+import { parsePrice } from '../tokens.js';
+import { generatePaymentId } from '../utils/index.js';
+import { PAYMENT_ONLY } from './types.js';
+/**
+ * Default {@link ServerMechanism} that delegates `parsePrice` to the token
+ * registry and applies a no-op `enhancePaymentRequirements`. Useful when a
+ * chain/scheme needs no scheme-specific enrichment.
+ */
+export class DefaultServerMechanism {
+    schemeName;
+    constructor(schemeName) {
+        this.schemeName = schemeName;
+    }
+    scheme() {
+        return this.schemeName;
+    }
+    async parsePrice(price, network) {
+        return parsePrice(price, network);
+    }
+    async enhancePaymentRequirements(requirements, _deliveryMode) {
+        return requirements;
+    }
+    validatePaymentRequirements(_requirements) {
+        return true;
+    }
+}
+/**
+ * Core server orchestration. One instance per resource server.
+ *
+ * @example
+ * ```ts
+ * const facilitator = new FacilitatorClient({ baseUrl: 'https://fac.example' });
+ * const server = new X402Server()
+ *   .register('tron:nile', new DefaultServerMechanism('exact_permit'))
+ *   .setFacilitator(facilitator);
+ *
+ * const accepts = await server.buildPaymentRequirements([
+ *   { scheme: 'exact_permit', network: 'tron:nile', price: '1 USDT', payTo: 'T...' },
+ * ]);
+ * const challenge = server.createPaymentRequiredResponse(accepts);
+ * ```
+ */
+export class X402Server {
+    /** network → scheme → mechanism */
+    mechanisms = new Map();
+    facilitator = null;
+    /** Register a {@link ServerMechanism} for one network. Chainable. */
+    register(network, mechanism) {
+        const scheme = mechanism.scheme();
+        let byScheme = this.mechanisms.get(network);
+        if (!byScheme) {
+            byScheme = new Map();
+            this.mechanisms.set(network, byScheme);
+        }
+        byScheme.set(scheme, mechanism);
+        return this;
+    }
+    /** Set the facilitator client. Required before {@link verifyPayment} / {@link settlePayment}. */
+    setFacilitator(client) {
+        this.facilitator = client;
+        return this;
+    }
+    /**
+     * Turn a list of {@link ResourceConfig} into ready-to-serve {@link PaymentRequirements}.
+     *
+     * Pipeline per config:
+     * 1. Find mechanism by `(network, scheme)`; throw if not registered.
+     * 2. Parse `price` → asset + amount via mechanism.
+     * 3. Build initial `PaymentRequirements`.
+     * 4. Let mechanism `enhancePaymentRequirements` attach extras (token name/version, etc.).
+     * 5. Normalize EVM addresses via checksum.
+     *
+     * If a facilitator is configured, permit-style requirements (`scheme !== 'exact'`)
+     * get enriched with `extra.fee` from `/fee/quote`. Unsupported (network, scheme, asset)
+     * tuples returned by the facilitator are silently dropped from the result.
+     *
+     * Mirrors Python `X402Server.build_payment_requirements`.
+     */
+    async buildPaymentRequirements(configs) {
+        const built = [];
+        for (const config of configs) {
+            const mechanism = this.findMechanism(config.network, config.scheme);
+            if (!mechanism) {
+                throw new Error(`No ServerMechanism registered for network=${config.network}, scheme=${config.scheme}`);
+            }
+            const assetInfo = await mechanism.parsePrice(config.price, config.network);
+            let requirements = {
+                scheme: config.scheme,
+                network: config.network,
+                amount: assetInfo.amount,
+                asset: assetInfo.asset,
+                payTo: config.payTo,
+                maxTimeoutSeconds: config.validFor ?? 3600,
+            };
+            requirements = await mechanism.enhancePaymentRequirements(requirements, config.deliveryMode ?? PAYMENT_ONLY);
+            requirements = this.normalizeEvmRequirements(requirements);
+            built.push(requirements);
+        }
+        if (!this.facilitator) {
+            throw new Error('Facilitator is not set (call setFacilitator first)');
+        }
+        // Split: exact doesn't need fee quote; everything else (permit-style) does.
+        const exactReqs = built.filter((r) => r.scheme === 'exact');
+        const permitReqs = built.filter((r) => r.scheme !== 'exact');
+        const supported = [...exactReqs];
+        if (permitReqs.length > 0) {
+            const quotes = await this.facilitator.feeQuote(permitReqs);
+            const quoteMap = new Map();
+            for (const q of quotes) {
+                quoteMap.set(`${q.scheme}|${q.network}|${q.asset}`, q);
+            }
+            for (const req of permitReqs) {
+                const quote = quoteMap.get(`${req.scheme}|${req.network}|${req.asset}`);
+                if (!quote) {
+                    // Facilitator can't quote this (unsupported token / scheme). Silently skip.
+                    continue;
+                }
+                const enriched = {
+                    ...req,
+                    extra: {
+                        ...(req.extra ?? {}),
+                        fee: {
+                            ...quote.fee,
+                            facilitatorId: this.facilitator.facilitatorId,
+                        },
+                    },
+                };
+                supported.push(this.normalizeEvmRequirements(enriched));
+            }
+        }
+        return supported;
+    }
+    /**
+     * Build the 402 PaymentRequired challenge body. The facilitator is not
+     * consulted here — the caller has already obtained `requirements` via
+     * {@link buildPaymentRequirements} or constructed them by hand.
+     */
+    createPaymentRequiredResponse(requirements, options = {}) {
+        const now = Math.floor(Date.now() / 1000);
+        const validBefore = options.validBefore ?? now + 3600;
+        const validAfter = options.validAfter ?? now;
+        return {
+            x402Version: 2,
+            error: 'Payment required',
+            ...(options.resource ? { resource: options.resource } : {}),
+            accepts: requirements,
+            extensions: {
+                paymentPermitContext: {
+                    meta: {
+                        kind: PAYMENT_ONLY,
+                        paymentId: options.paymentId ?? generatePaymentId(),
+                        nonce: options.nonce ?? generateNonce(),
+                        validAfter,
+                        validBefore,
+                    },
+                },
+            },
+        };
+    }
+    /**
+     * Anti-tamper validation + optional server-side signature check, then
+     * delegate to the facilitator. Mirrors Python `verify_payment`.
+     */
+    async verifyPayment(payload, requirements) {
+        if (!this.validatePayloadMatchesRequirements(payload, requirements)) {
+            return { isValid: false, invalidReason: 'payload_mismatch' };
+        }
+        const mechanism = this.findMechanism(requirements.network, requirements.scheme);
+        if (mechanism?.verifySignature) {
+            const permit = payload.payload.paymentPermit ?? null;
+            const signature = payload.payload.signature;
+            const ok = await mechanism.verifySignature(permit, signature, requirements.network);
+            if (!ok) {
+                return { isValid: false, invalidReason: 'invalid_signature_server' };
+            }
+        }
+        if (!this.facilitator) {
+            return { isValid: false, invalidReason: 'no_facilitator' };
+        }
+        return this.facilitator.verify(payload, requirements);
+    }
+    /** Delegate settlement to the facilitator. Mirrors Python `settle_payment`. */
+    async settlePayment(payload, requirements) {
+        if (!this.facilitator) {
+            return {
+                success: false,
+                network: requirements.network,
+                errorReason: 'no_facilitator',
+            };
+        }
+        return this.facilitator.settle(payload, requirements);
+    }
+    /**
+     * Anti-tampering: the client's `payload.accepted` must match server's
+     * canonical `requirements`, and the embedded authorization / permit must
+     * point at the right asset / payTo / amount.
+     *
+     * Two flavors:
+     * - `exact` (ERC-3009): inspects `payload.payload.authorization`
+     * - other (permit-style): inspects `payload.payload.paymentPermit`
+     */
+    validatePayloadMatchesRequirements(payload, requirements) {
+        if (requirements.scheme === 'exact') {
+            const auth = payload.payload.authorization ??
+                (payload.extensions ?? {})['transferAuthorization'];
+            if (!auth)
+                return false;
+            if (payload.accepted) {
+                if (payload.accepted.asset !== requirements.asset)
+                    return false;
+                if (payload.accepted.network !== requirements.network)
+                    return false;
+            }
+            try {
+                if (BigInt(String(auth.value)) < BigInt(requirements.amount))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            if (String(auth.to).toLowerCase() !== String(requirements.payTo).toLowerCase()) {
+                return false;
+            }
+            const now = Math.floor(Date.now() / 1000);
+            try {
+                const validBefore = BigInt(String(auth.validBefore ?? '0'));
+                const validAfter = BigInt(String(auth.validAfter ?? now));
+                if (validBefore < BigInt(now))
+                    return false;
+                if (validAfter > BigInt(now))
+                    return false;
+            }
+            catch {
+                return false;
+            }
+            return true;
+        }
+        const permit = payload.payload.paymentPermit;
+        if (!permit)
+            return false;
+        if (permit.payment.payToken !== requirements.asset)
+            return false;
+        if (permit.payment.payTo !== requirements.payTo)
+            return false;
+        try {
+            if (BigInt(permit.payment.payAmount) < BigInt(requirements.amount))
+                return false;
+        }
+        catch {
+            return false;
+        }
+        return true;
+    }
+    findMechanism(network, scheme) {
+        return this.mechanisms.get(network)?.get(scheme) ?? null;
+    }
+    normalizeEvmRequirements(reqs) {
+        if (!reqs.network.startsWith('eip155:')) {
+            return reqs;
+        }
+        return {
+            ...reqs,
+            asset: checksumOrThrow(reqs.asset, 'asset'),
+            payTo: checksumOrThrow(reqs.payTo, 'payTo'),
+            extra: reqs.extra
+                ? {
+                    ...reqs.extra,
+                    ...(reqs.extra.fee
+                        ? {
+                            fee: {
+                                ...reqs.extra.fee,
+                                feeTo: checksumOrThrow(reqs.extra.fee.feeTo, 'extra.fee.feeTo'),
+                                ...(reqs.extra.fee.caller
+                                    ? { caller: checksumOrThrow(reqs.extra.fee.caller, 'extra.fee.caller') }
+                                    : {}),
+                            },
+                        }
+                        : {}),
+                }
+                : reqs.extra,
+        };
+    }
+}
+function checksumOrThrow(address, field) {
+    if (!isAddress(address, { strict: false })) {
+        throw new Error(`Invalid EVM address for ${field}: ${address}`);
+    }
+    return getAddress(address);
+}
+function generateNonce() {
+    // 16 random bytes, decimal-encoded — matches Python's str(uuid.uuid4().int) shape.
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let nonce = 0n;
+    for (const byte of bytes) {
+        nonce = (nonce << 8n) | BigInt(byte);
+    }
+    return nonce.toString();
+}
+//# sourceMappingURL=x402Server.js.map

package/dist/server/x402Server.js.map

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

package/dist/tokens.d.ts

@@ -16,4 +16,33 @@ export declare function findByAddress(network: string, address: string): TokenIn
 export declare function getNetworkTokens(network: string): Record<string, TokenInfo>;
 /** Register a custom token */
 export declare function registerToken(network: string, token: TokenInfo): void;
+/** Parsed asset amount returned by {@link parsePrice}. */
+export interface AssetAmount {
+    /** Amount in smallest unit (e.g. "1000000" for 1 USDT with 6 decimals). */
+    amount: string;
+    /** Token contract address on the network. */
+    asset: string;
+    /** Token decimals. */
+    decimals: number;
+    /** Token symbol (e.g. "USDT"). */
+    symbol: string;
+    /** Token display name. */
+    name: string;
+    /** EIP-712 / TIP-712 contract version (for permit) when applicable. */
+    version?: string;
+}
+/**
+ * Parse a human-readable price string into a typed asset amount.
+ *
+ * @param price - `"<decimal-amount> <symbol>"` (e.g. `"1.25 USDT"` or `"100 USDC"`).
+ *                Whitespace-tolerant. `<symbol>` lookup is case-insensitive.
+ * @param network - CAIP-2 network identifier (e.g. `"tron:nile"`, `"eip155:97"`).
+ *
+ * @throws if the price format is invalid, the amount cannot be parsed,
+ *         the token is not registered on `network`, or the amount has more
+ *         decimal places than the token supports.
+ *
+ * Mirrors `bankofai.x402.tokens.TokenRegistry.parse_price`.
+ */
+export declare function parsePrice(price: string, network: string): AssetAmount;
 //# sourceMappingURL=tokens.d.ts.map

package/dist/tokens.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkFD,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE/E;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAKrF;AAED,mCAAmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAE3E;AAED,8BAA8B;AAC9B,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAKrE"}
+{"version":3,"file":"tokens.d.ts","sourceRoot":"","sources":["../src/tokens.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,MAAM,WAAW,SAAS;IACxB,OAAO,EAAE,MAAM,CAAC;IAChB,QAAQ,EAAE,MAAM,CAAC;IACjB,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAkFD,2CAA2C;AAC3C,wBAAgB,QAAQ,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAE/E;AAED,sDAAsD;AACtD,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,SAAS,GAAG,SAAS,CAKrF;AAED,mCAAmC;AACnC,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,SAAS,CAAC,CAE3E;AAED,8BAA8B;AAC9B,wBAAgB,aAAa,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,SAAS,GAAG,IAAI,CAKrE;AAED,0DAA0D;AAC1D,MAAM,WAAW,WAAW;IAC1B,2EAA2E;IAC3E,MAAM,EAAE,MAAM,CAAC;IACf,6CAA6C;IAC7C,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,kCAAkC;IAClC,MAAM,EAAE,MAAM,CAAC;IACf,0BAA0B;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,uEAAuE;IACvE,OAAO,CAAC,EAAE,MAAM,CAAC;CAClB;AAED;;;;;;;;;;;;GAYG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,MAAM,EAAE,OAAO,EAAE,MAAM,GAAG,WAAW,CAsCtE"}

package/dist/tokens.js

@@ -103,4 +103,48 @@ export function registerToken(network, token) {
     }
     TOKENS[network][token.symbol.toUpperCase()] = token;
 }
+/**
+ * Parse a human-readable price string into a typed asset amount.
+ *
+ * @param price - `"<decimal-amount> <symbol>"` (e.g. `"1.25 USDT"` or `"100 USDC"`).
+ *                Whitespace-tolerant. `<symbol>` lookup is case-insensitive.
+ * @param network - CAIP-2 network identifier (e.g. `"tron:nile"`, `"eip155:97"`).
+ *
+ * @throws if the price format is invalid, the amount cannot be parsed,
+ *         the token is not registered on `network`, or the amount has more
+ *         decimal places than the token supports.
+ *
+ * Mirrors `bankofai.x402.tokens.TokenRegistry.parse_price`.
+ */
+export function parsePrice(price, network) {
+    const parts = price.trim().split(/\s+/);
+    if (parts.length !== 2) {
+        throw new Error(`Invalid price format: "${price}". Expected "<amount> <symbol>" (e.g. "1.25 USDT").`);
+    }
+    const [amountStr, symbol] = parts;
+    if (!/^\d+(\.\d+)?$/.test(amountStr)) {
+        throw new Error(`Invalid amount in price "${price}": "${amountStr}" is not a non-negative decimal.`);
+    }
+    const token = getToken(network, symbol);
+    if (!token) {
+        throw new Error(`Unknown token "${symbol}" on network "${network}".`);
+    }
+    // BigInt-safe smallest-unit conversion. Reject precision overflow.
+    const [intPart, fracPart = ''] = amountStr.split('.');
+    if (fracPart.length > token.decimals) {
+        throw new Error(`Amount "${amountStr}" has more decimal places (${fracPart.length}) than ${symbol} supports (${token.decimals}).`);
+    }
+    const paddedFrac = fracPart.padEnd(token.decimals, '0');
+    // strip leading zeros to keep canonical numeric string
+    const combined = `${intPart}${paddedFrac}`.replace(/^0+(?=\d)/, '');
+    const amount = combined === '' ? '0' : combined;
+    return {
+        amount,
+        asset: token.address,
+        decimals: token.decimals,
+        symbol: token.symbol,
+        name: token.name,
+        ...(token.version !== undefined ? { version: token.version } : {}),
+    };
+}
 //# sourceMappingURL=tokens.js.map

package/dist/tokens.js.map

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

package/dist/utils/encoding.d.ts

@@ -29,6 +29,13 @@ export declare function encodePaymentPayload(payload: unknown): string;
  * Decode payment payload from base64 HTTP header
  */
 export declare function decodePaymentPayload<T>(encoded: string): T;
+/**
+ * Generate a random 16-byte payment ID, formatted as `0x` + 32 hex chars.
+ *
+ * Used by `X402Server.createPaymentRequiredResponse` when the caller doesn't
+ * supply an explicit `paymentId`. Mirrors Python `generate_payment_id`.
+ */
+export declare function generatePaymentId(): string;
 /**
  * Convert hex string to Uint8Array
  */

package/dist/utils/encoding.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAW9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAU5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAEnD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAG7D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAG1D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOlD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,UAAO,GAAG,MAAM,CAKnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAW9D"}
+{"version":3,"file":"encoding.d.ts","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,GAAG,MAAM,CAW9D;AAED;;GAEG;AACH,wBAAgB,YAAY,CAAC,IAAI,EAAE,MAAM,GAAG,MAAM,CAKjD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,MAAM,GAAG,UAAU,CAU5D;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,CAEhD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,CAAC,GAAG,GAAG,EAAE,IAAI,EAAE,MAAM,GAAG,CAAC,CAEnD;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,OAAO,EAAE,OAAO,GAAG,MAAM,CAG7D;AAED;;GAEG;AACH,wBAAgB,oBAAoB,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,GAAG,CAAC,CAG1D;AAED;;;;;GAKG;AACH,wBAAgB,iBAAiB,IAAI,MAAM,CAQ1C;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,GAAG,EAAE,MAAM,GAAG,UAAU,CAOlD;AAED;;GAEG;AACH,wBAAgB,UAAU,CAAC,KAAK,EAAE,UAAU,EAAE,MAAM,UAAO,GAAG,MAAM,CAKnE;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAAC,SAAS,EAAE,MAAM,GAAG,UAAU,CAW9D"}

package/dist/utils/encoding.js

@@ -65,6 +65,21 @@ export function decodePaymentPayload(encoded) {
     const json = decodeBase64(encoded);
     return JSON.parse(json);
 }
+/**
+ * Generate a random 16-byte payment ID, formatted as `0x` + 32 hex chars.
+ *
+ * Used by `X402Server.createPaymentRequiredResponse` when the caller doesn't
+ * supply an explicit `paymentId`. Mirrors Python `generate_payment_id`.
+ */
+export function generatePaymentId() {
+    const bytes = new Uint8Array(16);
+    crypto.getRandomValues(bytes);
+    let hex = '';
+    for (const byte of bytes) {
+        hex += byte.toString(16).padStart(2, '0');
+    }
+    return `0x${hex}`;
+}
 /**
  * Convert hex string to Uint8Array
  */

package/dist/utils/encoding.js.map

@@ -1 +1 @@
-{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"encoding.js","sourceRoot":"","sources":["../../src/utils/encoding.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAyB;IACpD,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;YAC7B,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,OAAO,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;QACvD,CAAC;QACD,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAAC;IAC9C,CAAC;IACD,IAAI,OAAO,IAAI,KAAK,QAAQ,EAAE,CAAC;QAC7B,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IAC/B,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,MAAM,CAAC,YAAY,CAAC,GAAG,IAAI,CAAC,CAAC,CAAC;AACvD,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,YAAY,CAAC,IAAY;IACvC,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,QAAQ,CAAC,OAAO,CAAC,CAAC;IACvD,CAAC;IACD,OAAO,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,mBAAmB,CAAC,IAAY;IAC9C,IAAI,OAAO,MAAM,KAAK,WAAW,EAAE,CAAC;QAClC,OAAO,IAAI,UAAU,CAAC,MAAM,CAAC,IAAI,CAAC,IAAI,EAAE,QAAQ,CAAC,CAAC,CAAC;IACrD,CAAC;IACD,MAAM,MAAM,GAAG,UAAU,CAAC,IAAI,CAAC,IAAI,CAAC,CAAC;IACrC,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;IAC5C,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,MAAM,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACvC,KAAK,CAAC,CAAC,CAAC,GAAG,MAAM,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC;IAClC,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,IAAa;IACtC,OAAO,IAAI,CAAC,SAAS,CAAC,IAAI,CAAC,CAAC;AAC9B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAU,IAAY;IAC9C,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAC,OAAgB;IACnD,MAAM,IAAI,GAAG,IAAI,CAAC,SAAS,CAAC,OAAO,CAAC,CAAC;IACrC,OAAO,YAAY,CAAC,IAAI,CAAC,CAAC;AAC5B,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,oBAAoB,CAAI,OAAe;IACrD,MAAM,IAAI,GAAG,YAAY,CAAC,OAAO,CAAC,CAAC;IACnC,OAAO,IAAI,CAAC,KAAK,CAAC,IAAI,CAAM,CAAC;AAC/B,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB;IAC/B,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,EAAE,CAAC,CAAC;IACjC,MAAM,CAAC,eAAe,CAAC,KAAK,CAAC,CAAC;IAC9B,IAAI,GAAG,GAAG,EAAE,CAAC;IACb,KAAK,MAAM,IAAI,IAAI,KAAK,EAAE,CAAC;QACzB,GAAG,IAAI,IAAI,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;IAC5C,CAAC;IACD,OAAO,KAAK,GAAG,EAAE,CAAC;AACpB,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,GAAW;IACpC,MAAM,QAAQ,GAAG,GAAG,CAAC,UAAU,CAAC,IAAI,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC,CAAC,CAAC,GAAG,CAAC;IAC3D,MAAM,KAAK,GAAG,IAAI,UAAU,CAAC,QAAQ,CAAC,MAAM,GAAG,CAAC,CAAC,CAAC;IAClD,KAAK,IAAI,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,KAAK,CAAC,MAAM,EAAE,CAAC,EAAE,EAAE,CAAC;QACtC,KAAK,CAAC,CAAC,CAAC,GAAG,QAAQ,CAAC,QAAQ,CAAC,KAAK,CAAC,CAAC,GAAG,CAAC,EAAE,CAAC,GAAG,CAAC,GAAG,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC;IAC5D,CAAC;IACD,OAAO,KAAK,CAAC;AACf,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,UAAU,CAAC,KAAiB,EAAE,MAAM,GAAG,IAAI;IACzD,MAAM,GAAG,GAAG,KAAK,CAAC,IAAI,CAAC,KAAK,CAAC;SAC1B,GAAG,CAAC,CAAC,CAAC,EAAE,CAAC,CAAC,CAAC,QAAQ,CAAC,EAAE,CAAC,CAAC,QAAQ,CAAC,CAAC,EAAE,GAAG,CAAC,CAAC;SACzC,IAAI,CAAC,EAAE,CAAC,CAAC;IACZ,OAAO,MAAM,CAAC,CAAC,CAAC,KAAK,GAAG,EAAE,CAAC,CAAC,CAAC,GAAG,CAAC;AACnC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,gBAAgB,CAAC,SAAiB;IAChD,IAAI,CAAC,SAAS,CAAC,UAAU,CAAC,IAAI,CAAC,EAAE,CAAC;QAChC,MAAM,IAAI,KAAK,CAAC,8BAA8B,SAAS,sCAAsC,CAAC,CAAC;IACjG,CAAC;IAED,MAAM,YAAY,GAAG,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC,CAAC;IACxC,IAAI,YAAY,CAAC,MAAM,KAAK,EAAE,EAAE,CAAC;QAC/B,MAAM,IAAI,KAAK,CAAC,8BAA8B,YAAY,CAAC,MAAM,yCAAyC,CAAC,CAAC;IAC9G,CAAC;IAED,OAAO,UAAU,CAAC,SAAS,CAAC,CAAC;AAC/B,CAAC"}

package/dist/utils/index.d.ts

@@ -2,6 +2,6 @@
  * Utility exports
  */
 export * from './encoding.js';
-export { encodeBase64, decodeBase64, decodeBase64ToBytes, hexToBytes, bytesToHex, paymentIdToBytes } from './encoding.js';
+export { encodeBase64, decodeBase64, decodeBase64ToBytes, generatePaymentId, hexToBytes, bytesToHex, paymentIdToBytes, } from './encoding.js';
 export * from './gasfree.js';
 //# sourceMappingURL=index.d.ts.map

package/dist/utils/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1H,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,cAAc,cAAc,CAAC"}

package/dist/utils/index.js

@@ -2,6 +2,6 @@
  * Utility exports
  */
 export * from './encoding.js';
-export { encodeBase64, decodeBase64, decodeBase64ToBytes, hexToBytes, bytesToHex, paymentIdToBytes } from './encoding.js';
+export { encodeBase64, decodeBase64, decodeBase64ToBytes, generatePaymentId, hexToBytes, bytesToHex, paymentIdToBytes, } from './encoding.js';
 export * from './gasfree.js';
 //# sourceMappingURL=index.js.map

package/dist/utils/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EAAE,YAAY,EAAE,YAAY,EAAE,mBAAmB,EAAE,UAAU,EAAE,UAAU,EAAE,gBAAgB,EAAE,MAAM,eAAe,CAAC;AAC1H,cAAc,cAAc,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../../src/utils/index.ts"],"names":[],"mappings":"AAAA;;GAEG;AAEH,cAAc,eAAe,CAAC;AAC9B,OAAO,EACL,YAAY,EACZ,YAAY,EACZ,mBAAmB,EACnB,iBAAiB,EACjB,UAAU,EACV,UAAU,EACV,gBAAgB,GACjB,MAAM,eAAe,CAAC;AACvB,cAAc,cAAc,CAAC"}

package/dist/utils/tx_verification.d.ts

@@ -0,0 +1,113 @@
+/**
+ * Transaction Verification Utilities
+ *
+ * Generic functionality to verify blockchain transaction results after the
+ * facilitator reports settlement, ensuring on-chain transfers match expected
+ * parameters. Mirrors `bankofai.x402.utils.tx_verification`.
+ *
+ * This module provides the **base contracts**. Chain-specific implementations
+ * (TRON via tronweb, EVM via viem) subclass {@link BaseTransactionVerifier}
+ * and plug in via {@link getVerifierForNetwork}.
+ */
+import type { PaymentPayload, PaymentRequirements } from '../types/index.js';
+/** A single token transfer event extracted from a transaction. */
+export interface TransferEvent {
+    /** Token contract address. */
+    token: string;
+    /** Sender address. */
+    fromAddr: string;
+    /** Recipient address. */
+    toAddr: string;
+    /** Transfer amount in smallest unit (as a BigInt-safe string). */
+    amount: string;
+}
+/** Outcome of {@link TransactionVerifier.verifyTransaction}. */
+export interface TransactionVerificationResult {
+    success: boolean;
+    txHash: string;
+    blockNumber?: string;
+    errorReason?: string;
+    transfers?: TransferEvent[];
+    /** Whether the on-chain transaction status was "success". */
+    statusVerified: boolean;
+    /** Whether the payment transfer (amount + recipient) was verified. */
+    paymentVerified: boolean;
+    /** Whether the facilitator fee transfer was verified (when applicable). */
+    feeVerified: boolean;
+}
+/**
+ * Interface for transaction verification implementations. One per chain family.
+ *
+ * Wraps the chain's transaction-info / transfer-events RPC and applies the
+ * canonical "did the right transfer happen" check.
+ */
+export interface TransactionVerifier {
+    verifyTransaction(txHash: string, payload: PaymentPayload, requirements: PaymentRequirements): Promise<TransactionVerificationResult>;
+    getTransactionTransfers(txHash: string, tokenAddress: string): Promise<TransferEvent[]>;
+}
+/** Generic transaction-info shape returned by chain-specific RPC adapters. */
+export interface TransactionInfo {
+    status?: string | number;
+    blockNumber?: string;
+}
+/**
+ * Abstract base class for transaction verifiers. Subclasses implement the
+ * chain-specific RPC calls; the canonical verification flow lives here.
+ *
+ * Mirrors Python `BaseTransactionVerifier`. Like the Python base, the default
+ * {@link verifyTransaction} only checks that the on-chain transaction
+ * succeeded — chain-specific subclasses MAY override for richer transfer +
+ * fee verification.
+ */
+export declare abstract class BaseTransactionVerifier implements TransactionVerifier {
+    /** Chain-specific: pull transaction info (status, blockNumber) from RPC. */
+    abstract getTransactionInfo(txHash: string): Promise<TransactionInfo>;
+    /** Chain-specific: pull token transfer events from the transaction. */
+    abstract getTransactionTransfers(txHash: string, tokenAddress: string): Promise<TransferEvent[]>;
+    /** Chain-specific: normalize an address for equality comparison. */
+    abstract normalizeAddress(address: string): string;
+    /**
+     * Canonical verification flow: pull transaction info, check status.
+     *
+     * Subclasses can override to additionally verify transfer amounts /
+     * fee transfers — set `paymentVerified` / `feeVerified` accordingly.
+     */
+    verifyTransaction(txHash: string, _payload: PaymentPayload, _requirements: PaymentRequirements): Promise<TransactionVerificationResult>;
+}
+/**
+ * Registry of (network-prefix → verifier factory) entries.
+ *
+ * Chain-specific verifiers register themselves at module load (e.g. a TRON
+ * verifier package would call `registerVerifierFactory('tron:', ...)`); the
+ * core `@bankofai/x402` package ships no concrete verifiers itself.
+ */
+type VerifierFactory = (network: string, opts?: {
+    rpcUrl?: string;
+}) => TransactionVerifier;
+/**
+ * Register a verifier factory for a network prefix (e.g. `"tron:"`, `"eip155:"`).
+ * Calls override any prior registration for the same prefix.
+ */
+export declare function registerVerifierFactory(prefix: string, factory: VerifierFactory): void;
+/**
+ * Resolve a {@link TransactionVerifier} for a given network.
+ *
+ * Throws if no factory has been registered for the network's prefix. Callers
+ * that want optional verification (e.g. server middleware) should catch this
+ * and skip verification gracefully.
+ *
+ * @example
+ * ```ts
+ * try {
+ *   const verifier = getVerifierForNetwork('tron:nile');
+ *   const result = await verifier.verifyTransaction(txHash, payload, requirements);
+ * } catch {
+ *   // No verifier registered → skip on-chain re-check (facilitator is trusted).
+ * }
+ * ```
+ */
+export declare function getVerifierForNetwork(network: string, opts?: {
+    rpcUrl?: string;
+}): TransactionVerifier;
+export {};
+//# sourceMappingURL=tx_verification.d.ts.map

package/dist/utils/tx_verification.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"tx_verification.d.ts","sourceRoot":"","sources":["../../src/utils/tx_verification.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;GAUG;AAEH,OAAO,KAAK,EAAE,cAAc,EAAE,mBAAmB,EAAE,MAAM,mBAAmB,CAAC;AAE7E,kEAAkE;AAClE,MAAM,WAAW,aAAa;IAC5B,8BAA8B;IAC9B,KAAK,EAAE,MAAM,CAAC;IACd,sBAAsB;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,yBAAyB;IACzB,MAAM,EAAE,MAAM,CAAC;IACf,kEAAkE;IAClE,MAAM,EAAE,MAAM,CAAC;CAChB;AAED,gEAAgE;AAChE,MAAM,WAAW,6BAA6B;IAC5C,OAAO,EAAE,OAAO,CAAC;IACjB,MAAM,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,SAAS,CAAC,EAAE,aAAa,EAAE,CAAC;IAC5B,6DAA6D;IAC7D,cAAc,EAAE,OAAO,CAAC;IACxB,sEAAsE;IACtE,eAAe,EAAE,OAAO,CAAC;IACzB,2EAA2E;IAC3E,WAAW,EAAE,OAAO,CAAC;CACtB;AAED;;;;;GAKG;AACH,MAAM,WAAW,mBAAmB;IAClC,iBAAiB,CACf,MAAM,EAAE,MAAM,EACd,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,6BAA6B,CAAC,CAAC;IAC1C,uBAAuB,CACrB,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC,CAAC;CAC7B;AAED,8EAA8E;AAC9E,MAAM,WAAW,eAAe;IAC9B,MAAM,CAAC,EAAE,MAAM,GAAG,MAAM,CAAC;IACzB,WAAW,CAAC,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,8BAAsB,uBAAwB,YAAW,mBAAmB;IAC1E,4EAA4E;IAC5E,QAAQ,CAAC,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG,OAAO,CAAC,eAAe,CAAC;IAErE,uEAAuE;IACvE,QAAQ,CAAC,uBAAuB,CAC9B,MAAM,EAAE,MAAM,EACd,YAAY,EAAE,MAAM,GACnB,OAAO,CAAC,aAAa,EAAE,CAAC;IAE3B,oEAAoE;IACpE,QAAQ,CAAC,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM;IAElD;;;;;OAKG;IACG,iBAAiB,CACrB,MAAM,EAAE,MAAM,EACd,QAAQ,EAAE,cAAc,EACxB,aAAa,EAAE,mBAAmB,GACjC,OAAO,CAAC,6BAA6B,CAAC;CAmC1C;AAED;;;;;;GAMG;AACH,KAAK,eAAe,GAAG,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,KAAK,mBAAmB,CAAC;AAG5F;;;GAGG;AACH,wBAAgB,uBAAuB,CAAC,MAAM,EAAE,MAAM,EAAE,OAAO,EAAE,eAAe,GAAG,IAAI,CAEtF;AAED;;;;;;;;;;;;;;;;GAgBG;AACH,wBAAgB,qBAAqB,CACnC,OAAO,EAAE,MAAM,EACf,IAAI,CAAC,EAAE;IAAE,MAAM,CAAC,EAAE,MAAM,CAAA;CAAE,GACzB,mBAAmB,CAOrB"}