@faremeter/payment-evm 0.16.0 → 0.17.1

package/dist/src/erc20.d.ts

@@ -1,10 +1,25 @@
 import { type PublicClient } from "viem";
 import { type Address } from "@faremeter/types/evm";
+/**
+ * Arguments for retrieving an ERC-20 token balance.
+ */
 export interface GetTokenBalanceArgs {
+    /** The wallet address to check the balance for */
     account: Address;
+    /** The ERC-20 token contract address */
     asset: Address;
+    /** Viem public client for querying the chain */
     client: PublicClient;
 }
+/**
+ * Retrieves the ERC-20 token balance and decimals for an account.
+ *
+ * Uses multicall to fetch both values in a single RPC request.
+ *
+ * @param args - The account, asset, and client configuration
+ * @returns The balance amount and token decimals
+ * @throws Error if the balance query fails
+ */
 export declare function getTokenBalance(args: GetTokenBalanceArgs): Promise<{
     amount: bigint;
     decimals: number;

package/dist/src/erc20.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"erc20.d.ts","sourceRoot":"","sources":["../../src/erc20.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD,MAAM,WAAW,mBAAmB;IAClC,OAAO,EAAE,OAAO,CAAC;IACjB,KAAK,EAAE,OAAO,CAAC;IACf,MAAM,EAAE,YAAY,CAAC;CACtB;AAED,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB;;;GA4C9D"}
+{"version":3,"file":"erc20.d.ts","sourceRoot":"","sources":["../../src/erc20.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,YAAY,EAAE,MAAM,MAAM,CAAC;AACzC,OAAO,EAAE,KAAK,OAAO,EAAE,MAAM,sBAAsB,CAAC;AAEpD;;GAEG;AACH,MAAM,WAAW,mBAAmB;IAClC,kDAAkD;IAClD,OAAO,EAAE,OAAO,CAAC;IACjB,wCAAwC;IACxC,KAAK,EAAE,OAAO,CAAC;IACf,gDAAgD;IAChD,MAAM,EAAE,YAAY,CAAC;CACtB;AAED;;;;;;;;GAQG;AACH,wBAAsB,eAAe,CAAC,IAAI,EAAE,mBAAmB;;;GA4C9D"}

package/dist/src/erc20.js

@@ -1,5 +1,14 @@
 import {} from "viem";
 import {} from "@faremeter/types/evm";
+/**
+ * Retrieves the ERC-20 token balance and decimals for an account.
+ *
+ * Uses multicall to fetch both values in a single RPC request.
+ *
+ * @param args - The account, asset, and client configuration
+ * @returns The balance amount and token decimals
+ * @throws Error if the balance query fails
+ */
 export async function getTokenBalance(args) {
     const { account, asset, client } = args;
     const [balance, decimals] = await client.multicall({

package/dist/src/exact/client.d.ts

@@ -16,9 +16,23 @@ interface WalletForPayment {
         }) => Promise<Hex>;
     };
 }
+/**
+ * Options for creating an EVM exact payment handler.
+ */
 export type CreatePaymentHandlerOpts = {
+    /** The asset to use for payments (defaults to USDC) */
     asset?: AssetNameOrContractInfo;
 };
+/**
+ * Creates a payment handler for the EVM exact payment scheme.
+ *
+ * The handler generates EIP-3009 transferWithAuthorization signatures
+ * that can be executed by the facilitator to complete payments.
+ *
+ * @param wallet - Wallet providing chain context and signing capabilities
+ * @param opts - Optional configuration for the asset
+ * @returns A PaymentHandler function for use with the x402 client
+ */
 export declare function createPaymentHandler(wallet: WalletForPayment, opts?: CreatePaymentHandlerOpts): PaymentHandler;
 export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/src/exact/client.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/exact/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAYhC,UAAU,gBAAgB;IACxB,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE;QACP,aAAa,EAAE,CAAC,MAAM,EAAE;YACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,WAAW,EAAE,MAAM,CAAC;YACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAClC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;KACpB,CAAC;CACH;AAED,MAAM,MAAM,wBAAwB,GAAG;IACrC,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE,wBAA6B,GAClC,cAAc,CAqGhB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/exact/client.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,cAAc,EAGf,MAAM,yBAAyB,CAAC;AACjC,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAE7B,OAAO,KAAK,EAAE,GAAG,EAAE,MAAM,MAAM,CAAC;AAYhC,UAAU,gBAAgB;IACxB,KAAK,EAAE;QACL,EAAE,EAAE,MAAM,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;KACd,CAAC;IACF,OAAO,EAAE,GAAG,CAAC;IACb,OAAO,EAAE;QACP,aAAa,EAAE,CAAC,MAAM,EAAE;YACtB,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAChC,KAAK,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;YAC/B,WAAW,EAAE,MAAM,CAAC;YACpB,OAAO,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;SAClC,KAAK,OAAO,CAAC,GAAG,CAAC,CAAC;KACpB,CAAC;CACH;AAED;;GAEG;AACH,MAAM,MAAM,wBAAwB,GAAG;IACrC,uDAAuD;IACvD,KAAK,CAAC,EAAE,uBAAuB,CAAC;CACjC,CAAC;AAEF;;;;;;;;;GASG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,gBAAgB,EACxB,IAAI,GAAE,wBAA6B,GAClC,cAAc,CAqGhB"}

package/dist/src/exact/client.js

@@ -4,6 +4,16 @@ import { isAddress } from "viem";
 import { type } from "arktype";
 import { EIP712_TYPES, eip712Domain, } from "./constants.js";
 import { generateMatcher } from "./common.js";
+/**
+ * Creates a payment handler for the EVM exact payment scheme.
+ *
+ * The handler generates EIP-3009 transferWithAuthorization signatures
+ * that can be executed by the facilitator to complete payments.
+ *
+ * @param wallet - Wallet providing chain context and signing capabilities
+ * @param opts - Optional configuration for the asset
+ * @returns A PaymentHandler function for use with the x402 client
+ */
 export function createPaymentHandler(wallet, opts = {}) {
     const x402Network = lookupX402Network(wallet.chain.id);
     const assetInfo = findAssetInfo(x402Network, opts.asset ?? "USDC");
@@ -29,7 +39,7 @@ export function createPaymentHandler(wallet, opts = {}) {
                 const authorization = {
                     from: wallet.address,
                     to: payToAddress,
-                    value: requirements.maxAmountRequired, // String value of amount
+                    value: requirements.amount, // String value of amount
                     validAfter: validAfter.toString(),
                     validBefore: validBefore.toString(),
                     nonce: nonce,
@@ -56,7 +66,7 @@ export function createPaymentHandler(wallet, opts = {}) {
                 const message = {
                     from: wallet.address,
                     to: payToAddress,
-                    value: BigInt(requirements.maxAmountRequired),
+                    value: BigInt(requirements.amount),
                     validAfter: BigInt(validAfter),
                     validBefore: BigInt(validBefore),
                     nonce: nonce,

package/dist/src/exact/constants.d.ts

@@ -96,6 +96,10 @@ export declare const EIP712_TYPES: {
         readonly type: "bytes32";
     }];
 };
+/**
+ * Validator for the x402 exact payment payload containing
+ * an EIP-3009 authorization and signature.
+ */
 export declare const x402ExactPayload: import("arktype/internal/methods/object.ts").ObjectType<{
     signature: (In: string) => import("arktype").Out<`0x${string}`>;
     authorization: {
@@ -109,6 +113,9 @@ export declare const x402ExactPayload: import("arktype/internal/methods/object.t
 }, {}>;
 export type x402ExactPayload = typeof x402ExactPayload.infer;
 export type eip3009Authorization = x402ExactPayload["authorization"];
+/**
+ * Validator for EIP-712 domain parameters provided in payment requirements.
+ */
 export declare const eip712Domain: import("arktype/internal/methods/object.ts").ObjectType<{
     name?: string;
     version?: string;

package/dist/src/exact/constants.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/exact/constants.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDlC,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;CASf,CAAC;AAEX,eAAO,MAAM,gBAAgB;;;;;;;;;;MAU3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,KAAK,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;AAErE,eAAO,MAAM,YAAY;;;;;MAKvB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,KAAK,CAAC"}
+{"version":3,"file":"constants.d.ts","sourceRoot":"","sources":["../../../src/exact/constants.ts"],"names":[],"mappings":"AAUA,eAAO,MAAM,iBAAiB,UAAU,CAAC;AAEzC,eAAO,MAAM,+BAA+B;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;EAiDlC,CAAC;AAEX,eAAO,MAAM,YAAY;;;;;;;;;;;;;;;;;;;;CASf,CAAC;AAEX;;;GAGG;AACH,eAAO,MAAM,gBAAgB;;;;;;;;;;MAU3B,CAAC;AAEH,MAAM,MAAM,gBAAgB,GAAG,OAAO,gBAAgB,CAAC,KAAK,CAAC;AAC7D,MAAM,MAAM,oBAAoB,GAAG,gBAAgB,CAAC,eAAe,CAAC,CAAC;AAErE;;GAEG;AACH,eAAO,MAAM,YAAY;;;;;MAKvB,CAAC;AAEH,MAAM,MAAM,YAAY,GAAG,OAAO,YAAY,CAAC,KAAK,CAAC"}

package/dist/src/exact/constants.js

@@ -67,6 +67,10 @@ export const EIP712_TYPES = {
         { name: "nonce", type: "bytes32" },
     ],
 };
+/**
+ * Validator for the x402 exact payment payload containing
+ * an EIP-3009 authorization and signature.
+ */
 export const x402ExactPayload = type({
     signature: prefixedHexString,
     authorization: {
@@ -78,6 +82,9 @@ export const x402ExactPayload = type({
         nonce: prefixedHexString,
     },
 });
+/**
+ * Validator for EIP-712 domain parameters provided in payment requirements.
+ */
 export const eip712Domain = type({
     "name?": "string",
     "version?": "string",

package/dist/src/exact/facilitator.d.ts

@@ -1,11 +1,23 @@
 import { type ChainInfoWithRPC } from "@faremeter/types/evm";
 import { type FacilitatorHandler } from "@faremeter/types/facilitator";
 import type { Transport } from "viem";
-import { type KnownX402Network, type AssetNameOrContractInfo } from "@faremeter/info/evm";
+import { type AssetNameOrContractInfo } from "@faremeter/info/evm";
 type CreateFacilitatorHandlerOpts = {
-    network?: KnownX402Network;
+    network?: string;
     transport?: Transport;
 };
+/**
+ * Creates a facilitator handler for the EVM exact payment scheme.
+ *
+ * The handler verifies EIP-3009 authorization signatures and executes
+ * the transferWithAuthorization call on the token contract.
+ *
+ * @param chain - Chain configuration including RPC URLs
+ * @param privateKey - Private key for signing settlement transactions
+ * @param assetNameOrInfo - Asset name or contract info for the token
+ * @param opts - Optional configuration for network and transport
+ * @returns A FacilitatorHandler for processing EVM exact payments
+ */
 export declare function createFacilitatorHandler(chain: ChainInfoWithRPC, privateKey: string, assetNameOrInfo: AssetNameOrContractInfo, opts?: CreateFacilitatorHandlerOpts): Promise<FacilitatorHandler>;
 export {};
 //# sourceMappingURL=facilitator.d.ts.map

package/dist/src/exact/facilitator.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/exact/facilitator.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,MAAM,CAAC;AAapD,OAAO,EAEL,KAAK,gBAAgB,EAErB,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAuB7B,KAAK,4BAA4B,GAAG;IAClC,OAAO,CAAC,EAAE,gBAAgB,CAAC;IAC3B,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AACF,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,uBAAuB,EACxC,IAAI,GAAE,4BAAiC,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAqV7B"}
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/exact/facilitator.ts"],"names":[],"mappings":"AAQA,OAAO,EAAgB,KAAK,gBAAgB,EAAE,MAAM,sBAAsB,CAAC;AAC3E,OAAO,EAAE,KAAK,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,KAAK,EAAgB,SAAS,EAAE,MAAM,MAAM,CAAC;AAapD,OAAO,EAGL,KAAK,uBAAuB,EAC7B,MAAM,qBAAqB,CAAC;AAuB7B,KAAK,4BAA4B,GAAG;IAClC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,SAAS,CAAC;CACvB,CAAC;AAEF;;;;;;;;;;;GAWG;AACH,wBAAsB,wBAAwB,CAC5C,KAAK,EAAE,gBAAgB,EACvB,UAAU,EAAE,MAAM,EAClB,eAAe,EAAE,uBAAuB,EACxC,IAAI,GAAE,4BAAiC,GACtC,OAAO,CAAC,kBAAkB,CAAC,CAsV7B"}

package/dist/src/exact/facilitator.js

@@ -13,6 +13,18 @@ function parseSignature(signature) {
     const v = parseInt(sig.slice(128, 130), 16);
     return { v, r, s };
 }
+/**
+ * Creates a facilitator handler for the EVM exact payment scheme.
+ *
+ * The handler verifies EIP-3009 authorization signatures and executes
+ * the transferWithAuthorization call on the token contract.
+ *
+ * @param chain - Chain configuration including RPC URLs
+ * @param privateKey - Private key for signing settlement transactions
+ * @param assetNameOrInfo - Asset name or contract info for the token
+ * @param opts - Optional configuration for network and transport
+ * @returns A FacilitatorHandler for processing EVM exact payments
+ */
 export async function createFacilitatorHandler(chain, privateKey, assetNameOrInfo, opts = {}) {
     if (!isPrivateKey(privateKey)) {
         throw new Error(`Invalid private key: ${privateKey}`);
@@ -71,13 +83,13 @@ export async function createFacilitatorHandler(chain, privateKey, assetNameOrInf
     const getSupported = () => {
         return [
             Promise.resolve({
-                x402Version: 1,
+                x402Version: 2,
                 network,
                 scheme: X402_EXACT_SCHEME,
             }),
         ];
     };
-    const getRequirements = async (req) => {
+    const getRequirements = async ({ accepts: req, }) => {
         return req.filter(isMatchingRequirement).map((x) => ({
             ...x,
             asset,
@@ -104,7 +116,7 @@ export async function createFacilitatorHandler(chain, privateKey, assetNameOrInf
             return errorResponse("Payment authorized to wrong address");
         }
         // Check if the amount matches
-        if (authorization.value !== requirements.maxAmountRequired) {
+        if (authorization.value !== requirements.amount) {
             return errorResponse("Incorrect payment amount");
         }
         // Check if the authorization is still valid (time-wise)
@@ -204,9 +216,9 @@ export async function createFacilitatorHandler(chain, privateKey, assetNameOrInf
         const errorResponse = (msg) => {
             return {
                 success: false,
-                error: msg,
-                txHash: null,
-                networkId: null,
+                errorReason: msg,
+                transaction: "",
+                network: requirements.network,
             };
         };
         const verifyResult = await verifyTransaction(requirements, payment);
@@ -264,9 +276,8 @@ export async function createFacilitatorHandler(chain, privateKey, assetNameOrInf
             }
             return {
                 success: true,
-                error: null,
-                txHash,
-                networkId: chainId.toString(),
+                transaction: txHash,
+                network: payment.accepted.network,
             };
         }
         catch (cause) {

package/dist/src/index.d.ts

@@ -1,3 +1,19 @@
+/**
+ * @title EVM Payment Package
+ * @sidebarTitle Payment EVM
+ * @description EVM payment handlers for ERC-20 and exact payment schemes
+ * @packageDocumentation
+ */
+/**
+ * @title EVM Exact Payment Scheme
+ * @sidebarTitle Payment EVM / Exact
+ * @description EIP-3009 transferWithAuthorization payment handlers
+ */
 export * as exact from "./exact/index.js";
+/**
+ * @title ERC-20 Utilities
+ * @sidebarTitle Payment EVM / ERC-20
+ * @description ERC-20 token balance and transfer utilities
+ */
 export * as erc20 from "./erc20.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/index.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AACH;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC;AACjC;;;;GAIG;AACH,OAAO,KAAK,KAAK,MAAM,SAAS,CAAC"}

package/dist/src/index.js

@@ -1,2 +1,18 @@
+/**
+ * @title EVM Payment Package
+ * @sidebarTitle Payment EVM
+ * @description EVM payment handlers for ERC-20 and exact payment schemes
+ * @packageDocumentation
+ */
+/**
+ * @title EVM Exact Payment Scheme
+ * @sidebarTitle Payment EVM / Exact
+ * @description EIP-3009 transferWithAuthorization payment handlers
+ */
 export * as exact from "./exact/index.js";
+/**
+ * @title ERC-20 Utilities
+ * @sidebarTitle Payment EVM / ERC-20
+ * @description ERC-20 token balance and transfer utilities
+ */
 export * as erc20 from "./erc20.js";