@bankofai/x402 0.6.0-beta.0 → 0.6.0-beta.2

package/dist/mechanisms/_exact_base/facilitator.js

@@ -3,79 +3,215 @@
  *
  * Mirrors Python `mechanisms._exact_base.base.ExactBaseFacilitatorMechanism`.
  *
- * Per-chain subclasses provide a {@link ChainAdapter} and the chain RPC client
- * (viem PublicClient / tronweb instance). The base handles:
- * - basic structural verification (asset / payTo / value match, time window)
- * - dispatching feeQuote / verify / settle to the chain-specific impl
+ * Per-chain subclasses provide a {@link ChainAdapter}. The base handles:
+ * - structural verification (asset / payTo / value match, time window)
+ * - ERC-3009 EIP-712 signature recovery via the injected FacilitatorSigner
+ * - `transferWithAuthorization` settle + receipt polling
  *
- * Subclasses MUST implement chain interactions: signature recovery, balance
- * check, transaction broadcast. The base provides defaults that return
- * `null` / `false` so non-fully-implemented mechanisms remain visible at
- * the structural level but don't pretend to verify on-chain state.
+ * Subclasses ONLY need to override:
+ * - `settlePaymentOnly()` — chain-specific contract call dispatch (TRON
+ *   triggerSmartContract vs EVM viem writeContract)
  */
-import { SCHEME_EXACT } from './types.js';
+import { findByAddress } from '../../tokens.js';
+import { SCHEME_EXACT, TRANSFER_AUTH_EIP712_TYPES, TRANSFER_AUTH_PRIMARY_TYPE, } from './types.js';
+const FEE_QUOTE_EXPIRY_SECONDS = 300;
+function hexToBytes(hex) {
+    const clean = hex.startsWith('0x') ? hex.slice(2) : hex;
+    const out = new Uint8Array(clean.length / 2);
+    for (let i = 0; i < out.length; i++) {
+        out[i] = parseInt(clean.slice(i * 2, i * 2 + 2), 16);
+    }
+    return out;
+}
 export class ExactBaseFacilitatorMechanism {
+    signer;
     adapter;
-    constructor(adapter) {
+    allowedTokens;
+    constructor(signer, adapter, options = {}) {
+        this.signer = signer;
         this.adapter = adapter;
+        this.allowedTokens = options.allowedTokens
+            ? new Set(options.allowedTokens.map((t) => adapter.normalizeAddress(t)))
+            : null;
     }
     scheme() {
         return SCHEME_EXACT;
     }
     /**
-     * `exact` scheme has no facilitator fee — return `null` to drop from the
-     * supported quote list. Permit-based schemes override this.
+     * `exact` scheme has no facilitator fee (single transfer per authorization).
+     * Returns `feeAmount: "0"` for compatibility with the `/fee/quote` flow.
      */
-    async feeQuote(_accept, _context) {
-        return null;
+    async feeQuote(accept, _context) {
+        return {
+            fee: { feeTo: this.signer.getAddress(), feeAmount: '0' },
+            pricing: 'flat',
+            scheme: accept.scheme,
+            network: accept.network,
+            asset: accept.asset,
+            expiresAt: Math.floor(Date.now() / 1000) + FEE_QUOTE_EXPIRY_SECONDS,
+        };
     }
     /**
-     * Off-chain verification: structural + timing checks. Chain-specific
-     * subclasses extend this to add signature recovery and balance check.
+     * Off-chain verify: structural + timing checks, then EIP-712 signature
+     * recovery against the token's ERC-3009 domain.
      */
     async verify(payload, requirements) {
-        const authorization = this.extractAuthorization(payload);
-        if (!authorization) {
-            return { isValid: false, invalidReason: 'missing_authorization' };
+        const auth = this.extractAuthorization(payload);
+        if (!auth) {
+            return { isValid: false, invalidReason: 'missing_transfer_authorization' };
+        }
+        const validationError = this.validateAuthorization(auth, requirements);
+        if (validationError) {
+            return { isValid: false, invalidReason: validationError };
         }
-        // Validate basic structural correctness
-        if (String(authorization.to).toLowerCase() !== String(requirements.payTo).toLowerCase()) {
-            return { isValid: false, invalidReason: 'payTo_mismatch' };
+        const validSig = await this.verifySignature(auth, payload.payload.signature, requirements);
+        if (!validSig) {
+            return { isValid: false, invalidReason: 'invalid_signature' };
         }
+        return { isValid: true };
+    }
+    /**
+     * Settle: verify, then submit `transferWithAuthorization(v,r,s)` via the
+     * subclass-provided `settlePaymentOnly`, then poll the receipt.
+     */
+    async settle(payload, requirements) {
+        const verifyResult = await this.verify(payload, requirements);
+        if (!verifyResult.isValid) {
+            return {
+                success: false,
+                network: requirements.network,
+                errorReason: verifyResult.invalidReason,
+            };
+        }
+        const auth = this.extractAuthorization(payload);
+        const signature = payload.payload.signature;
+        let txHash;
         try {
-            if (BigInt(authorization.value) < BigInt(requirements.amount)) {
-                return { isValid: false, invalidReason: 'amount_too_low' };
+            txHash = await this.settlePaymentOnly(auth, signature, requirements);
+        }
+        catch (err) {
+            return {
+                success: false,
+                network: requirements.network,
+                errorReason: `settle_error: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        if (!txHash) {
+            return {
+                success: false,
+                network: requirements.network,
+                errorReason: 'transaction_failed',
+            };
+        }
+        try {
+            const receipt = await this.signer.waitForTransactionReceipt(txHash, requirements.network);
+            if (receipt.status !== 'confirmed') {
+                return {
+                    success: false,
+                    network: requirements.network,
+                    transaction: txHash,
+                    errorReason: 'transaction_failed_on_chain',
+                };
+            }
+        }
+        catch (err) {
+            return {
+                success: false,
+                network: requirements.network,
+                transaction: txHash,
+                errorReason: `receipt_timeout: ${err instanceof Error ? err.message : String(err)}`,
+            };
+        }
+        return {
+            success: true,
+            network: requirements.network,
+            transaction: txHash,
+        };
+    }
+    // -------------------------------------------------------------------------
+    // Protected helpers
+    // -------------------------------------------------------------------------
+    validateAuthorization(auth, requirements) {
+        const norm = (s) => this.adapter.normalizeAddress(s);
+        if (this.allowedTokens !== null &&
+            !this.allowedTokens.has(norm(requirements.asset))) {
+            return 'token_not_allowed';
+        }
+        try {
+            if (BigInt(auth.value) < BigInt(requirements.amount)) {
+                return 'amount_mismatch';
             }
         }
         catch {
-            return { isValid: false, invalidReason: 'invalid_value' };
+            return 'invalid_value';
+        }
+        if (norm(auth.to) !== norm(requirements.payTo)) {
+            return 'payto_mismatch';
         }
-        // Validate time window
         const now = Math.floor(Date.now() / 1000);
         try {
-            if (BigInt(String(authorization.validBefore ?? '0')) < BigInt(now)) {
-                return { isValid: false, invalidReason: 'expired' };
-            }
-            if (BigInt(String(authorization.validAfter ?? now)) > BigInt(now)) {
-                return { isValid: false, invalidReason: 'not_yet_valid' };
-            }
+            if (BigInt(auth.validBefore) < BigInt(now))
+                return 'expired';
+            if (BigInt(auth.validAfter) > BigInt(now))
+                return 'not_yet_valid';
         }
         catch {
-            return { isValid: false, invalidReason: 'invalid_time_window' };
+            return 'invalid_time_window';
         }
-        // Chain-specific signature + balance check (overridable)
-        const sigResult = await this.verifySignatureOnChain(payload, requirements);
-        if (!sigResult.isValid)
-            return sigResult;
-        return { isValid: true };
+        return null;
     }
     /**
-     * Chain-specific signature recovery + balance check. Default returns
-     * `isValid: true` (trust upstream); subclasses MUST override for real
-     * signature verification. Marked protected so subclass can call super.
+     * Verify the buyer's ERC-3009 EIP-712 signature against the token's domain.
+     *
+     * Domain shape (ERC-3009): `{ name, version, chainId, verifyingContract: <token> }`.
+     * Token name / version come from the SDK token registry; addresses are
+     * converted to signing format (0x EVM hex) for both EVM and TRON.
      */
-    async verifySignatureOnChain(_payload, _requirements) {
-        return { isValid: true };
+    async verifySignature(auth, signature, requirements) {
+        const adapter = this.adapter;
+        const chainId = adapter.parseChainId(requirements.network);
+        const tokenInfo = findByAddress(requirements.network, requirements.asset);
+        const tokenName = tokenInfo?.name ?? 'Unknown Token';
+        const tokenVersion = tokenInfo?.version ?? '1';
+        const domain = {
+            name: tokenName,
+            version: tokenVersion,
+            chainId,
+            verifyingContract: adapter.toSigningAddress(requirements.asset),
+        };
+        const message = {
+            from: adapter.toSigningAddress(auth.from),
+            to: adapter.toSigningAddress(auth.to),
+            value: BigInt(auth.value),
+            validAfter: BigInt(auth.validAfter),
+            validBefore: BigInt(auth.validBefore),
+            // viem accepts hex string for bytes32 types
+            nonce: auth.nonce.startsWith('0x') ? auth.nonce : `0x${auth.nonce}`,
+        };
+        return this.signer.verifyTypedData(adapter.toSigningAddress(auth.from), domain, TRANSFER_AUTH_EIP712_TYPES, message, signature, TRANSFER_AUTH_PRIMARY_TYPE);
+    }
+    /**
+     * Split a 65-byte signature into v / r / s for the (v, r, s) variant of
+     * `transferWithAuthorization`. v is normalized to 27 or 28 (some signers
+     * return 0 / 1).
+     */
+    splitSignature(signature) {
+        const sigBytes = hexToBytes(signature);
+        if (sigBytes.length !== 65) {
+            throw new Error(`Invalid signature length: ${sigBytes.length}`);
+        }
+        const r = '0x' +
+            Array.from(sigBytes.slice(0, 32))
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+        const s = '0x' +
+            Array.from(sigBytes.slice(32, 64))
+                .map((b) => b.toString(16).padStart(2, '0'))
+                .join('');
+        let v = sigBytes[64];
+        if (v < 27)
+            v += 27;
+        return { v, r: r, s: s };
     }
     extractAuthorization(payload) {
         if (payload.payload.authorization)

package/dist/mechanisms/_exact_base/facilitator.js.map

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

package/dist/mechanisms/_exact_permit_base/facilitator.d.ts

@@ -2,43 +2,115 @@
  * Shared base for `exact_permit` scheme facilitator mechanisms.
  *
  * Mirrors Python `mechanisms._exact_permit_base.facilitator.BaseExactPermitFacilitatorMechanism`.
+ *
+ * Subclasses override:
+ * - {@link getAddressConverter} — chain-specific address normalization
+ * - {@link settlePaymentOnly} — chain-specific contract call (PaymentPermit.permitTransferFrom)
  */
+import { FacilitatorSigner } from '../../signers/facilitator/base.js';
 import type { FacilitatorMechanism } from '../../facilitator/x402Facilitator.js';
-import type { FeeQuoteResponse, PaymentPayload, PaymentRequirements, SettleResponse, VerifyResponse } from '../../types/index.js';
+import type { FeeQuoteResponse, PaymentPayload, PaymentPermit, PaymentRequirements, SettleResponse, VerifyResponse } from '../../types/index.js';
+import type { AddressConverter } from '../../address.js';
 /** Fee policy used by `feeQuote`. */
 export interface BaseExactPermitFee {
-    /** Address that collects the facilitator fee. */
-    feeTo: string;
+    /**
+     * Address that collects the facilitator fee. Defaults to
+     * `signer.getAddress()` when undefined.
+     */
+    feeTo?: string;
     /** Optional caller address that the on-chain contract requires. */
     caller?: string;
     /**
-     * Base fee in smallest unit, keyed by `${network}:${tokenAddress}`. Tokens
-     * not in this map use {@link defaultBaseFee}.
+     * Per-symbol base fee (smallest unit string). Token symbol is uppercased
+     * before lookup. Tokens not in this map are rejected by `fee_quote` and
+     * `_validate_permit`.
+     */
+    baseFee?: Record<string, string>;
+    /**
+     * Optional token allowlist (lowercased addresses). If set, only tokens
+     * in this set are accepted; otherwise all tokens pass the address check.
      */
-    baseFeesByToken?: Record<string, string>;
-    /** Fallback fee when no per-token entry matches. Default `"0"`. */
-    defaultBaseFee?: string;
+    allowedTokens?: ReadonlyArray<string>;
 }
+/**
+ * Tuple shape passed to `triggerSmartContract` (TRON) or `writeContract` (EVM)
+ * for `PaymentPermit.permitTransferFrom`. Matches the on-chain ABI tuple.
+ */
+export type PermitTuple = [
+    [
+        number,
+        `0x${string}`,
+        string,
+        number,
+        number
+    ],
+    string,
+    string,
+    [
+        string,
+        string,
+        string
+    ],
+    [
+        string,
+        string
+    ]
+];
 export declare abstract class BaseExactPermitFacilitatorMechanism implements FacilitatorMechanism {
-    protected readonly fee: BaseExactPermitFee;
-    constructor(fee: BaseExactPermitFee);
+    protected readonly signer: FacilitatorSigner;
+    protected readonly feeTo: string;
+    protected readonly caller: string;
+    protected readonly baseFeeMap: Record<string, bigint>;
+    protected readonly allowedTokens: ReadonlySet<string> | null;
+    protected readonly addressConverter: AddressConverter;
+    constructor(signer: FacilitatorSigner, fee?: BaseExactPermitFee);
     scheme(): string;
+    /** Chain-specific address converter. */
+    protected abstract getAddressConverter(): AddressConverter;
+    /**
+     * Look up base fee for a token by symbol. Returns `null` if the token is
+     * not registered in the SDK token registry or the symbol has no entry
+     * in `baseFeeMap`.
+     */
+    protected getBaseFee(tokenAddress: string, network: string): bigint | null;
     feeQuote(accept: PaymentRequirements, _context?: Record<string, unknown>): Promise<FeeQuoteResponse | null>;
     /**
-     * Off-chain verify path: structural checks live here, signature + balance
-     * + nonce + on-chain state checks go in subclass.
+     * Off-chain verify path: structural + fee + signature checks.
      */
     verify(payload: PaymentPayload, requirements: PaymentRequirements): Promise<VerifyResponse>;
     /**
-     * Chain-specific on-chain verification. Default: trust upstream
-     * (returns `isValid: true`). Subclasses MUST override for real
-     * signature recovery + balance + nonce checks.
+     * Settle the permit on-chain: verify, then submit via subclass
+     * `settlePaymentOnly`, then poll the receipt.
+     */
+    settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    /**
+     * Structural + fee validation. Returns the error reason string, or `null`
+     * if valid.
+     */
+    protected validatePermit(permit: PaymentPermit, requirements: PaymentRequirements): string | null;
+    /**
+     * Verify the buyer's EIP-712 / TIP-712 signature against the permit.
+     *
+     * Build the message in the exact shape the buyer signed:
+     * - `kind` as numeric (0 for PAYMENT_ONLY)
+     * - `paymentId` as hex string (bytes16 — viem accepts hex)
+     * - `nonce` / amounts as BigInt strings
+     * - all addresses converted to 0x EVM hex (required for TRON TIP-712)
+     */
+    protected verifySignature(permit: PaymentPermit, signature: string, network: string): Promise<boolean>;
+    /**
+     * Build the tuple passed to `permitTransferFrom(permit, owner, signature)`.
+     * Addresses are returned in the chain-canonical format (Base58 for TRON,
+     * 0x hex for EVM) since each chain's writer accepts both — let the subclass
+     * normalize further if needed.
      */
-    protected verifyOnChain(_payload: PaymentPayload, _requirements: PaymentRequirements): Promise<VerifyResponse>;
+    protected buildPermitTuple(permit: PaymentPermit): PermitTuple;
     /**
-     * Submit the permit on-chain. Chain-specific — subclasses MUST implement
-     * via viem (EVM) / tronweb (TRON).
+     * Submit the permit on-chain. Chain-specific — subclasses MUST implement.
+     *
+     * Returns the tx hash on broadcast success, or `null` on failure (the base
+     * wraps null into a `SettleResponse{ success: false }`).
      */
-    abstract settle(payload: PaymentPayload, requirements: PaymentRequirements): Promise<SettleResponse>;
+    protected abstract settlePaymentOnly(permit: PaymentPermit, signature: string, requirements: PaymentRequirements): Promise<string | null>;
 }
 //# sourceMappingURL=facilitator.d.ts.map

package/dist/mechanisms/_exact_permit_base/facilitator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/mechanisms/_exact_permit_base/facilitator.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,KAAK,EAAE,oBAAoB,EAAE,MAAM,sCAAsC,CAAC;AACjF,OAAO,KAAK,EACV,gBAAgB,EAChB,cAAc,EACd,mBAAmB,EACnB,cAAc,EACd,cAAc,EACf,MAAM,sBAAsB,CAAC;AAI9B,qCAAqC;AACrC,MAAM,WAAW,kBAAkB;IACjC,iDAAiD;IACjD,KAAK,EAAE,MAAM,CAAC;IACd,mEAAmE;IACnE,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB;;;OAGG;IACH,eAAe,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IACzC,mEAAmE;IACnE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,8BAAsB,mCAAoC,YAAW,oBAAoB;IAC3E,SAAS,CAAC,QAAQ,CAAC,GAAG,EAAE,kBAAkB;gBAAvB,GAAG,EAAE,kBAAkB;IAEtD,MAAM,IAAI,MAAM;IAIV,QAAQ,CACZ,MAAM,EAAE,mBAAmB,EAC3B,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GACjC,OAAO,CAAC,gBAAgB,GAAG,IAAI,CAAC;IAiBnC;;;OAGG;IACG,MAAM,CACV,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;IAuB1B;;;;OAIG;cACa,aAAa,CAC3B,QAAQ,EAAE,cAAc,EACxB,aAAa,EAAE,mBAAmB,GACjC,OAAO,CAAC,cAAc,CAAC;IAI1B;;;OAGG;IACH,QAAQ,CAAC,MAAM,CACb,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,mBAAmB,GAChC,OAAO,CAAC,cAAc,CAAC;CAC3B"}
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/mechanisms/_exact_permit_base/facilitator.ts"],"names":[],"mappings":"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"}