@faremeter/payment-solana 0.15.0 → 0.17.0

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

@@ -0,0 +1,12 @@
+import type { Signature } from "@solana/kit";
+export declare class TransactionStore {
+    private maxAge;
+    private sigToBlock;
+    private highestBlock;
+    constructor(maxAge?: number);
+    add(signature: Signature, blockHeight: number): void;
+    has(signature: Signature): boolean;
+    private prune;
+    get size(): number;
+}
+//# sourceMappingURL=cache.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"cache.d.ts","sourceRoot":"","sources":["../../../src/exact/cache.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAE7C,qBAAa,gBAAgB;IAC3B,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,UAAU,CAAyB;IAC3C,OAAO,CAAC,YAAY,CAAS;gBAEjB,MAAM,SAAM;IAMxB,GAAG,CAAC,SAAS,EAAE,SAAS,EAAE,WAAW,EAAE,MAAM,GAAG,IAAI;IASpD,GAAG,CAAC,SAAS,EAAE,SAAS,GAAG,OAAO;IAIlC,OAAO,CAAC,KAAK;IASb,IAAI,IAAI,WAEP;CACF"}

package/dist/src/exact/cache.js

@@ -0,0 +1,31 @@
+export class TransactionStore {
+    maxAge;
+    sigToBlock;
+    highestBlock;
+    constructor(maxAge = 150) {
+        this.maxAge = maxAge;
+        this.sigToBlock = new Map();
+        this.highestBlock = 0;
+    }
+    add(signature, blockHeight) {
+        if (blockHeight > this.highestBlock) {
+            this.highestBlock = blockHeight;
+            this.prune();
+        }
+        this.sigToBlock.set(signature, blockHeight);
+    }
+    has(signature) {
+        return this.sigToBlock.has(signature);
+    }
+    prune() {
+        const cutoff = this.highestBlock - this.maxAge;
+        for (const [sig, height] of this.sigToBlock) {
+            if (height < cutoff) {
+                this.sigToBlock.delete(sig);
+            }
+        }
+    }
+    get size() {
+        return this.sigToBlock.size;
+    }
+}

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

@@ -1,9 +1,11 @@
 import type { PaymentHandler } from "@faremeter/types/client";
+import type { SolanaCAIP2Network } from "@faremeter/info/solana";
 import { Connection, PublicKey, TransactionInstruction, VersionedTransaction } from "@solana/web3.js";
 export type Wallet = {
-    network: string;
+    network: string | SolanaCAIP2Network;
     publicKey: PublicKey;
     buildTransaction?: (instructions: TransactionInstruction[], recentBlockHash: string) => Promise<VersionedTransaction>;
+    partiallySignTransaction?: (tx: VersionedTransaction) => Promise<VersionedTransaction>;
     updateTransaction?: (tx: VersionedTransaction) => Promise<VersionedTransaction>;
     sendTransaction?: (tx: VersionedTransaction) => Promise<string>;
 };
@@ -14,10 +16,23 @@ interface GetAssociatedTokenAddressSyncOptions {
 }
 interface CreatePaymentHandlerOptions {
     token?: GetAssociatedTokenAddressSyncOptions;
+    settlementRentDestination?: string;
     features?: {
         enableSettlementAccounts?: boolean;
     };
 }
+/**
+ * Creates a payment handler for the Solana exact payment scheme.
+ *
+ * The handler builds SPL token transfer transactions that can be signed
+ * and submitted by the client to fulfill x402 payment requirements.
+ *
+ * @param wallet - Wallet providing signing capabilities
+ * @param mint - SPL token mint public key
+ * @param connection - Optional Solana connection for fetching blockhash and mint info
+ * @param options - Optional configuration for token address and features
+ * @returns A PaymentHandler function for use with the x402 client
+ */
 export declare function createPaymentHandler(wallet: Wallet, mint: PublicKey, connection?: Connection, options?: CreatePaymentHandlerOptions): 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":"AAEA,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,yBAAyB,CAAC;AAYjC,OAAO,EAEL,UAAU,EACV,SAAS,EACT,sBAAsB,EAEtB,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAIzB,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,SAAS,CAAC;IACrB,gBAAgB,CAAC,EAAE,CACjB,YAAY,EAAE,sBAAsB,EAAE,EACtC,eAAe,EAAE,MAAM,KACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,CAClB,EAAE,EAAE,oBAAoB,KACrB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE,CAAC;AAEF,UAAU,oCAAoC;IAC5C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wBAAwB,CAAC,EAAE,SAAS,CAAC;CACtC;AAiFD,UAAU,2BAA2B;IACnC,KAAK,CAAC,EAAE,oCAAoC,CAAC;IAC7C,QAAQ,CAAC,EAAE;QACT,wBAAwB,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACH;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,UAAU,CAAC,EAAE,UAAU,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,cAAc,CAwKhB"}
+{"version":3,"file":"client.d.ts","sourceRoot":"","sources":["../../../src/exact/client.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,yBAAyB,CAAC;AACjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,wBAAwB,CAAC;AAYjE,OAAO,EAEL,UAAU,EACV,SAAS,EACT,sBAAsB,EAEtB,oBAAoB,EAErB,MAAM,iBAAiB,CAAC;AAKzB,MAAM,MAAM,MAAM,GAAG;IACnB,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAAC;IACrC,SAAS,EAAE,SAAS,CAAC;IACrB,gBAAgB,CAAC,EAAE,CACjB,YAAY,EAAE,sBAAsB,EAAE,EACtC,eAAe,EAAE,MAAM,KACpB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,wBAAwB,CAAC,EAAE,CACzB,EAAE,EAAE,oBAAoB,KACrB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,iBAAiB,CAAC,EAAE,CAClB,EAAE,EAAE,oBAAoB,KACrB,OAAO,CAAC,oBAAoB,CAAC,CAAC;IACnC,eAAe,CAAC,EAAE,CAAC,EAAE,EAAE,oBAAoB,KAAK,OAAO,CAAC,MAAM,CAAC,CAAC;CACjE,CAAC;AAEF,UAAU,oCAAoC;IAC5C,kBAAkB,CAAC,EAAE,OAAO,CAAC;IAC7B,SAAS,CAAC,EAAE,SAAS,CAAC;IACtB,wBAAwB,CAAC,EAAE,SAAS,CAAC;CACtC;AAiFD,UAAU,2BAA2B;IACnC,KAAK,CAAC,EAAE,oCAAoC,CAAC;IAC7C,yBAAyB,CAAC,EAAE,MAAM,CAAC;IACnC,QAAQ,CAAC,EAAE;QACT,wBAAwB,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACH;AAED;;;;;;;;;;;GAWG;AACH,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,UAAU,CAAC,EAAE,UAAU,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,cAAc,CA2LhB"}

package/dist/src/exact/client.js

@@ -4,6 +4,7 @@ import { getBase64EncodedWireTransaction, } from "@solana/transactions";
 import { ComputeBudgetProgram, Connection, PublicKey, TransactionInstruction, TransactionMessage, VersionedTransaction, Keypair, } from "@solana/web3.js";
 import { PaymentRequirementsExtra } from "./facilitator.js";
 import { generateMatcher } from "./common.js";
+import { logger } from "./logger.js";
 function generateGetAssociatedTokenAddressSyncRest(tokenConfig) {
     const { allowOwnerOffCurve, programId, associatedTokenProgramId } = tokenConfig;
     // NOTE: These map to the trailing default args of
@@ -45,7 +46,7 @@ async function extractMetadata(args) {
     }
     const payerKey = new PublicKey(extra.feePayer);
     const payTo = new PublicKey(requirements.payTo);
-    const amount = Number(requirements.maxAmountRequired);
+    const amount = Number(requirements.amount);
     let paymentMode = PaymentMode.ToSpec;
     if (options?.features?.enableSettlementAccounts &&
         extra.features?.xSettlementAccountSupported &&
@@ -61,11 +62,38 @@ async function extractMetadata(args) {
         paymentMode,
     };
 }
+/**
+ * Creates a payment handler for the Solana exact payment scheme.
+ *
+ * The handler builds SPL token transfer transactions that can be signed
+ * and submitted by the client to fulfill x402 payment requirements.
+ *
+ * @param wallet - Wallet providing signing capabilities
+ * @param mint - SPL token mint public key
+ * @param connection - Optional Solana connection for fetching blockhash and mint info
+ * @param options - Optional configuration for token address and features
+ * @returns A PaymentHandler function for use with the x402 client
+ */
 export function createPaymentHandler(wallet, mint, connection, options) {
     const getAssociatedTokenAddressSyncRest = generateGetAssociatedTokenAddressSyncRest(options?.token ?? {});
+    let hasWarnedAboutDeprecation = false;
+    const signTransaction = async (tx) => {
+        if (wallet.partiallySignTransaction) {
+            return wallet.partiallySignTransaction(tx);
+        }
+        if (wallet.updateTransaction) {
+            if (!hasWarnedAboutDeprecation) {
+                logger.warning("wallet.partiallySignTransaction is not available, falling back to updateTransaction");
+                hasWarnedAboutDeprecation = true;
+            }
+            return wallet.updateTransaction(tx);
+        }
+        return tx;
+    };
     const { isMatchingRequirement } = generateMatcher(wallet.network, mint ? mint.toBase58() : "sol");
     return async (_context, accepts) => {
-        const res = accepts.filter(isMatchingRequirement).map((requirements) => {
+        const compatibleRequirements = accepts.filter(isMatchingRequirement);
+        const res = compatibleRequirements.map((requirements) => {
             const exec = async () => {
                 const { recentBlockhash, decimals, payTo, amount, payerKey, paymentMode, } = await extractMetadata({
                     connection,
@@ -99,9 +127,7 @@ export function createPaymentHandler(wallet, mint, connection, options) {
                             }).compileToV0Message();
                             tx = new VersionedTransaction(message);
                         }
-                        if (wallet.updateTransaction) {
-                            tx = await wallet.updateTransaction(tx);
-                        }
+                        tx = await signTransaction(tx);
                         const base64EncodedWireTransaction = getBase64EncodedWireTransaction({
                             messageBytes: tx.message.serialize(),
                             signatures: tx.signatures,
@@ -127,17 +153,17 @@ export function createPaymentHandler(wallet, mint, connection, options) {
                             }).compileToV0Message();
                             tx = new VersionedTransaction(message);
                         }
-                        if (wallet.updateTransaction) {
-                            tx = await wallet.updateTransaction(tx);
-                        }
+                        tx = await signTransaction(tx);
                         if (!wallet.sendTransaction) {
                             throw new Error("wallet must support sending transactions to use settlement accounts with exact");
                         }
                         const transactionSignature = await wallet.sendTransaction(tx);
                         const settleSecretKey = Buffer.from(settleKeypair.secretKey).toString("base64");
+                        const settlementRentDestination = options?.settlementRentDestination ?? wallet.publicKey.toBase58();
                         const payload = {
                             settleSecretKey,
                             transactionSignature,
+                            settlementRentDestination,
                         };
                         return { payload };
                     }

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

@@ -1,5 +1,6 @@
+import { type SolanaCAIP2Network } from "@faremeter/info/solana";
 export declare const x402Scheme = "exact";
-export declare function generateMatcher(network: string, asset: string): {
+export declare function generateMatcher(network: string | SolanaCAIP2Network, asset: string): {
     matchTuple: import("arktype/internal/methods/object.ts").ObjectType<{
         scheme: (In: string) => import("arktype/internal/attributes.ts").To<Lowercase<string>>;
         network: (In: string) => import("arktype/internal/attributes.ts").To<Lowercase<string>>;

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

@@ -1 +1 @@
-{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/exact/common.ts"],"names":[],"mappings":"AAGA,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,wBAAgB,eAAe,CAAC,OAAO,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM;;;;;;;;;;;EAI7D"}
+{"version":3,"file":"common.d.ts","sourceRoot":"","sources":["../../../src/exact/common.ts"],"names":[],"mappings":"AACA,OAAO,EAEL,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAC;AAEhC,eAAO,MAAM,UAAU,UAAU,CAAC;AAElC,wBAAgB,eAAe,CAC7B,OAAO,EAAE,MAAM,GAAG,kBAAkB,EACpC,KAAK,EAAE,MAAM;;;;;;;;;;;EASd"}

package/dist/src/exact/common.js

@@ -1,8 +1,7 @@
 import { generateRequirementsMatcher } from "@faremeter/types/x402";
-import { lookupX402Network } from "@faremeter/info/solana";
+import { lookupX402Network, } from "@faremeter/info/solana";
 export const x402Scheme = "exact";
 export function generateMatcher(network, asset) {
-    return generateRequirementsMatcher([x402Scheme], lookupX402Network(network), [
-        asset,
-    ]);
+    const solanaNetwork = lookupX402Network(network);
+    return generateRequirementsMatcher([x402Scheme], [solanaNetwork.caip2], [asset]);
 }

package/dist/src/exact/common.test.js

@@ -1,7 +1,7 @@
 #!/usr/bin/env pnpm tsx
 import t from "tap";
 import { isValidationError as iVE } from "@faremeter/types";
-import { lookupKnownSPLToken } from "@faremeter/info/solana";
+import { lookupKnownSPLToken, clusterToCAIP2 } from "@faremeter/info/solana";
 import { generateMatcher } from "./common.js";
 await t.test("testBasicMatching", async (t) => {
     {
@@ -11,13 +11,21 @@ await t.test("testBasicMatching", async (t) => {
             return;
         }
         const { matchTuple } = generateMatcher("mainnet-beta", tokenInfo.address);
+        const network = clusterToCAIP2("mainnet-beta");
         const req = {
-            network: "solana-mainnet-beta",
+            network: network.caip2,
             scheme: "exact",
             asset: tokenInfo.address,
         };
+        // CAIP-2 network identifier should match
         t.ok(!iVE(matchTuple(req)));
-        t.ok(!iVE(matchTuple({
+        // Legacy network names should not match (normalization happens in
+        // the routes layer before dispatch, not in the handler matcher)
+        t.ok(iVE(matchTuple({
+            ...req,
+            network: "solana-mainnet-beta",
+        })));
+        t.ok(iVE(matchTuple({
             ...req,
             network: "solana",
         })));

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

@@ -1,7 +1,29 @@
+import { type x402PaymentRequirements, type x402PaymentPayload, type x402SettleResponse, type x402VerifyResponse } from "@faremeter/types/x402v2";
 import type { FacilitatorHandler } from "@faremeter/types/facilitator";
+import { type SolanaCAIP2Network } from "@faremeter/info/solana";
+import { fetchMint } from "@solana-program/token";
 import { type Rpc, type SolanaRpcApi } from "@solana/kit";
 import type { TransactionError } from "@solana/rpc-types";
 import { Keypair, PublicKey } from "@solana/web3.js";
+import { logger } from "./logger.js";
+export interface HookBaseArgs {
+    network: string | SolanaCAIP2Network;
+    rpc: Rpc<SolanaRpcApi>;
+    feePayerKeypair: Keypair;
+    mint: PublicKey;
+    mintInfo: Awaited<ReturnType<typeof fetchMint>>;
+    requirements: x402PaymentRequirements;
+    payment: x402PaymentPayload;
+    logger: typeof logger;
+}
+export type HookResponseArgs<Response> = HookBaseArgs & {
+    response: Response;
+};
+export type HookResponseFuncs<Response> = (args: HookResponseArgs<Response>) => Promise<Response> | Promise<void>;
+export interface FacilitatorHooks {
+    afterVerify?: HookResponseFuncs<x402VerifyResponse>;
+    afterSettle?: HookResponseFuncs<x402SettleResponse>;
+}
 export declare const PaymentRequirementsExtraFeatures: import("arktype/internal/methods/object.ts").ObjectType<{
     xSettlementAccountSupported?: boolean;
 }, {}>;
@@ -18,9 +40,12 @@ interface FacilitatorOptions {
     maxRetries?: number;
     retryDelayMs?: number;
     maxPriorityFee?: number;
+    maxTransactionAge?: number;
     features?: {
         enableSettlementAccounts?: boolean;
+        enableDuplicateCheck?: boolean;
     };
+    hooks?: readonly FacilitatorHooks[];
 }
 export declare const PaymentPayloadTransaction: import("arktype/internal/methods/object.ts").ObjectType<{
     transaction: (In: string) => import("arktype").Out<Readonly<{
@@ -32,9 +57,23 @@ export type PaymentPayloadTransaction = typeof PaymentPayloadTransaction.infer;
 export declare const PaymentPayloadSettlementAccount: import("arktype/internal/methods/object.ts").ObjectType<{
     transactionSignature: string;
     settleSecretKey: (In: string) => import("arktype").Out<Uint8Array<ArrayBuffer>>;
+    settlementRentDestination?: string;
 }, {}>;
 export type PaymentPayloadSettlementAccount = typeof PaymentPayloadSettlementAccount.infer;
 export declare function transactionErrorToString(t: TransactionError): string;
-export declare const createFacilitatorHandler: (network: string, rpc: Rpc<SolanaRpcApi>, feePayerKeypair: Keypair, mint: PublicKey, config?: FacilitatorOptions) => Promise<FacilitatorHandler>;
+/**
+ * Creates a facilitator handler for the Solana exact payment scheme.
+ *
+ * The handler validates incoming payment transactions, signs them with the
+ * fee payer keypair, and submits them to the Solana network.
+ *
+ * @param network - Solana network identifier (cluster name, CAIP-2 string, or SolanaCAIP2Network object)
+ * @param rpc - Solana RPC client
+ * @param feePayerKeypair - Keypair for paying transaction fees
+ * @param mint - SPL token mint public key
+ * @param config - Optional configuration for retries, fees, and hooks
+ * @returns A FacilitatorHandler for processing Solana exact payments
+ */
+export declare const createFacilitatorHandler: (network: string | SolanaCAIP2Network, rpc: Rpc<SolanaRpcApi>, feePayerKeypair: Keypair, mint: PublicKey, config?: FacilitatorOptions) => 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":"AAOA,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AAGvE,OAAO,EAYL,KAAK,GAAG,EACR,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAMrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAerD,eAAO,MAAM,gCAAgC;;MAE3C,CAAC;AAEH,MAAM,MAAM,gCAAgC,GAC1C,OAAO,gCAAgC,CAAC,KAAK,CAAC;AAEhD,eAAO,MAAM,wBAAwB;;;;;;;MAKnC,CAAC;AAEH,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,EAAE;QACT,wBAAwB,CAAC,EAAE,OAAO,CAAC;KACpC,CAAC;CACH;AASD,eAAO,MAAM,yBAAyB;;;;;MAEpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,KAAK,CAAC;AAE/E,eAAO,MAAM,+BAA+B;;;MAK1C,CAAC;AACH,MAAM,MAAM,+BAA+B,GACzC,OAAO,+BAA+B,CAAC,KAAK,CAAC;AAE/C,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,gBAAgB,UAY3D;AAiDD,eAAO,MAAM,wBAAwB,GACnC,SAAS,MAAM,EACf,KAAK,GAAG,CAAC,YAAY,CAAC,EACtB,iBAAiB,OAAO,EACxB,MAAM,SAAS,EACf,SAAS,kBAAkB,KAC1B,OAAO,CAAC,kBAAkB,CA+T5B,CAAC"}
+{"version":3,"file":"facilitator.d.ts","sourceRoot":"","sources":["../../../src/exact/facilitator.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,uBAAuB,EAC5B,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EACvB,KAAK,kBAAkB,EAExB,MAAM,yBAAyB,CAAC;AAEjC,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,8BAA8B,CAAC;AACvE,OAAO,EAML,KAAK,kBAAkB,EACxB,MAAM,wBAAwB,CAAC;AAChC,OAAO,EAAE,SAAS,EAAE,MAAM,uBAAuB,CAAC;AAClD,OAAO,EAYL,KAAK,GAAG,EACR,KAAK,YAAY,EAElB,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAGrD,OAAO,EAAE,MAAM,EAAE,MAAM,UAAU,CAAC;AAalC,MAAM,WAAW,YAAY;IAC3B,OAAO,EAAE,MAAM,GAAG,kBAAkB,CAAC;IACrC,GAAG,EAAE,GAAG,CAAC,YAAY,CAAC,CAAC;IACvB,eAAe,EAAE,OAAO,CAAC;IACzB,IAAI,EAAE,SAAS,CAAC;IAChB,QAAQ,EAAE,OAAO,CAAC,UAAU,CAAC,OAAO,SAAS,CAAC,CAAC,CAAC;IAChD,YAAY,EAAE,uBAAuB,CAAC;IACtC,OAAO,EAAE,kBAAkB,CAAC;IAC5B,MAAM,EAAE,OAAO,MAAM,CAAC;CACvB;AAED,MAAM,MAAM,gBAAgB,CAAC,QAAQ,IAAI,YAAY,GAAG;IAAE,QAAQ,EAAE,QAAQ,CAAA;CAAE,CAAC;AAE/E,MAAM,MAAM,iBAAiB,CAAC,QAAQ,IAAI,CACxC,IAAI,EAAE,gBAAgB,CAAC,QAAQ,CAAC,KAC7B,OAAO,CAAC,QAAQ,CAAC,GAAG,OAAO,CAAC,IAAI,CAAC,CAAC;AAEvC,MAAM,WAAW,gBAAgB;IAC/B,WAAW,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;IACpD,WAAW,CAAC,EAAE,iBAAiB,CAAC,kBAAkB,CAAC,CAAC;CACrD;AAED,eAAO,MAAM,gCAAgC;;MAE3C,CAAC;AAEH,MAAM,MAAM,gCAAgC,GAC1C,OAAO,gCAAgC,CAAC,KAAK,CAAC;AAEhD,eAAO,MAAM,wBAAwB;;;;;;;MAKnC,CAAC;AAEH,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,iBAAiB,CAAC,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,EAAE;QACT,wBAAwB,CAAC,EAAE,OAAO,CAAC;QACnC,oBAAoB,CAAC,EAAE,OAAO,CAAC;KAChC,CAAC;IACF,KAAK,CAAC,EAAE,SAAS,gBAAgB,EAAE,CAAC;CACrC;AASD,eAAO,MAAM,yBAAyB;;;;;MAEpC,CAAC;AACH,MAAM,MAAM,yBAAyB,GAAG,OAAO,yBAAyB,CAAC,KAAK,CAAC;AAE/E,eAAO,MAAM,+BAA+B;;;;MAM1C,CAAC;AACH,MAAM,MAAM,+BAA+B,GACzC,OAAO,+BAA+B,CAAC,KAAK,CAAC;AAE/C,wBAAgB,wBAAwB,CAAC,CAAC,EAAE,gBAAgB,UAY3D;AAiDD;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,MAAM,GAAG,kBAAkB,EACpC,KAAK,GAAG,CAAC,YAAY,CAAC,EACtB,iBAAiB,OAAO,EACxB,MAAM,SAAS,EACf,SAAS,kBAAkB,KAC1B,OAAO,CAAC,kBAAkB,CAub5B,CAAC"}

package/dist/src/exact/facilitator.js

@@ -1,9 +1,9 @@
-import { x402PaymentRequirements, } from "@faremeter/types/x402";
+import {} from "@faremeter/types/x402v2";
 import { isValidationError } from "@faremeter/types";
-import { lookupX402Network } from "@faremeter/info/solana";
+import { clusterToCAIP2, isKnownCluster, caip2ToCluster, isSolanaCAIP2Network, } from "@faremeter/info/solana";
 import { fetchMint } from "@solana-program/token";
 import { address, createKeyPairSignerFromBytes, decompileTransactionMessage, getBase64Encoder, getCompiledTransactionMessageDecoder, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, pipe, } from "@solana/kit";
-import { getBase64EncodedWireTransaction, getTransactionDecoder, partiallySignTransaction, } from "@solana/transactions";
+import { getBase64EncodedWireTransaction, getSignatureFromTransaction, getTransactionDecoder, partiallySignTransaction, } from "@solana/transactions";
 import { Keypair, PublicKey } from "@solana/web3.js";
 import { type } from "arktype";
 import { isValidTransaction } from "./verify.js";
@@ -11,6 +11,7 @@ import { logger } from "./logger.js";
 import { x402Scheme, generateMatcher } from "./common.js";
 import { TOKEN_PROGRAM_ADDRESS, findAssociatedTokenPda, getTransferCheckedInstruction, getCloseAccountInstruction, } from "@solana-program/token";
 import { getAddMemoInstruction } from "@solana-program/memo";
+import { TransactionStore } from "./cache.js";
 export const PaymentRequirementsExtraFeatures = type({
     xSettlementAccountSupported: "boolean?",
 });
@@ -32,6 +33,7 @@ export const PaymentPayloadTransaction = type({
 export const PaymentPayloadSettlementAccount = type({
     transactionSignature: "string",
     settleSecretKey: type("string.base64").pipe.try((s) => Uint8Array.from(Buffer.from(s, "base64"))),
+    "settlementRentDestination?": "string",
 });
 export function transactionErrorToString(t) {
     if (typeof t == "string") {
@@ -50,7 +52,7 @@ const sendTransaction = async (rpc, signedTransaction, maxRetries, retryDelayMs)
     })
         .send();
     if (simResult.value.err) {
-        logger.error("transaction simulation failed: {*}", simResult.value);
+        logger.error("transaction simulation failed", simResult.value);
         return { success: false, error: "Transaction simulation failed" };
     }
     const signature = await rpc
@@ -74,14 +76,36 @@ const sendTransaction = async (rpc, signedTransaction, maxRetries, retryDelayMs)
     }
     return { success: false, error: "Transaction confirmation timeout" };
 };
+/**
+ * Creates a facilitator handler for the Solana exact payment scheme.
+ *
+ * The handler validates incoming payment transactions, signs them with the
+ * fee payer keypair, and submits them to the Solana network.
+ *
+ * @param network - Solana network identifier (cluster name, CAIP-2 string, or SolanaCAIP2Network object)
+ * @param rpc - Solana RPC client
+ * @param feePayerKeypair - Keypair for paying transaction fees
+ * @param mint - SPL token mint public key
+ * @param config - Optional configuration for retries, fees, and hooks
+ * @returns A FacilitatorHandler for processing Solana exact payments
+ */
 export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mint, config) => {
     const { isMatchingRequirement } = generateMatcher(network, mint.toBase58());
-    const { maxRetries = 30, retryDelayMs = 1000, maxPriorityFee = 100_000, } = config ?? {};
+    const { maxRetries = 30, retryDelayMs = 1000, maxPriorityFee = 100_000, maxTransactionAge = 150, } = config ?? {};
     const mintInfo = await fetchMint(rpc, address(mint.toBase58()));
+    const hookArgs = {
+        network,
+        rpc,
+        feePayerKeypair,
+        mint,
+        mintInfo,
+        logger,
+    };
     const features = {};
     if (config?.features?.enableSettlementAccounts) {
         features.xSettlementAccountSupported = true;
     }
+    const seenTxs = new TransactionStore(maxTransactionAge);
     const processSettlementAccount = async (requirements, paymentPayload) => {
         const errorResponse = (error) => ({ error });
         // XXX - It would be nicer to do this check in the arktype
@@ -101,12 +125,12 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         const { value: accountBalance } = await rpc
             .getTokenAccountBalance(settleATA, { commitment: "confirmed" })
             .send();
-        logger.debug("settlement account info: {*}", {
+        logger.debug("settlement account info", {
             settleOwner,
             settleATA,
             accountBalance,
         });
-        if (BigInt(accountBalance.amount) !== BigInt(requirements.maxAmountRequired)) {
+        if (BigInt(accountBalance.amount) !== BigInt(requirements.amount)) {
             return errorResponse("settlement account balance didn't match payment requirements");
         }
         const settle = async () => {
@@ -116,6 +140,9 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                 owner: address(requirements.payTo),
                 tokenProgram: TOKEN_PROGRAM_ADDRESS,
             });
+            const closeDestination = paymentPayload.settlementRentDestination
+                ? address(paymentPayload.settlementRentDestination)
+                : feePayerSigner.address;
             const instructions = [
                 getAddMemoInstruction({ memo: crypto.randomUUID() }),
                 getTransferCheckedInstruction({
@@ -123,12 +150,12 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                     mint: address(mint.toBase58()),
                     destination: payToATA,
                     authority: settleSigner,
-                    amount: BigInt(requirements.maxAmountRequired),
+                    amount: BigInt(requirements.amount),
                     decimals: mintInfo.data.decimals,
                 }),
                 getCloseAccountInstruction({
                     account: settleATA,
-                    destination: feePayerSigner.address,
+                    destination: closeDestination,
                     owner: settleSigner,
                 }),
             ];
@@ -141,22 +168,32 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
             };
         };
         return {
+            payer: settleOwner,
             settle,
         };
     };
     const processTransaction = async (requirements, paymentPayload) => {
         const errorResponse = (error) => ({ error });
-        let transactionMessage, transaction;
+        let transactionMessage, transaction, blockHeight;
         try {
             transaction = paymentPayload.transaction;
             const compiledTransactionMessage = getCompiledTransactionMessageDecoder().decode(transaction.messageBytes);
             transactionMessage = decompileTransactionMessage(compiledTransactionMessage);
+            const lifetimeConstraint = transactionMessage.lifetimeConstraint;
+            if ("blockhash" in lifetimeConstraint) {
+                blockHeight = Number(lifetimeConstraint.lastValidBlockHeight) - 150;
+            }
+            else {
+                return errorResponse("Transaction cannot include a nonce account");
+            }
         }
         catch (cause) {
             throw new Error("Failed to get compiled transaction message", { cause });
         }
+        let validResult;
         try {
-            if (!(await isValidTransaction(transactionMessage, requirements, feePayerKeypair.publicKey, maxPriorityFee))) {
+            validResult = await isValidTransaction(transactionMessage, requirements, feePayerKeypair.publicKey.toBase58(), maxPriorityFee);
+            if (!validResult) {
                 logger.error("Invalid transaction");
                 return errorResponse("Invalid transaction");
             }
@@ -164,7 +201,10 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         catch (cause) {
             throw new Error("Failed to validate transaction", { cause });
         }
+        const { payer } = validResult;
         return {
+            payer,
+            blockHeight,
             settle: async () => {
                 let signedTransaction;
                 try {
@@ -174,9 +214,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                 catch (cause) {
                     throw new Error("Failed to partially sign transaction", { cause });
                 }
-                return {
-                    signedTransaction,
-                };
+                return { signedTransaction };
             },
         };
     };
@@ -201,18 +239,37 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
             return processTransaction(requirements, paymentPayload);
         }
     };
+    const resolveCluster = () => {
+        if (isSolanaCAIP2Network(network)) {
+            const resolved = caip2ToCluster(network.caip2);
+            if (resolved) {
+                return resolved;
+            }
+            throw new Error(`Unknown Solana network: ${network.caip2}`);
+        }
+        if (isKnownCluster(network)) {
+            return network;
+        }
+        const resolved = caip2ToCluster(network);
+        if (resolved) {
+            return resolved;
+        }
+        throw new Error(`Unknown Solana network: ${network}`);
+    };
     const getSupported = () => {
-        return lookupX402Network(network).map((network) => Promise.resolve({
-            x402Version: 1,
-            scheme: x402Scheme,
-            network,
-            extra: {
-                feePayer: feePayerKeypair.publicKey.toString(),
-                features,
-            },
-        }));
+        return [
+            Promise.resolve({
+                x402Version: 2,
+                scheme: x402Scheme,
+                network: clusterToCAIP2(resolveCluster()).caip2,
+                extra: {
+                    feePayer: feePayerKeypair.publicKey.toString(),
+                    features,
+                },
+            }),
+        ];
     };
-    const getRequirements = async (req) => {
+    const getRequirements = async ({ accepts: req, }) => {
         const recentBlockhash = (await rpc.getLatestBlockhash().send()).value
             .blockhash;
         return req.filter(isMatchingRequirement).map((x) => {
@@ -244,7 +301,32 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         if ("error" in verifyResult) {
             return errorResponse(verifyResult.error);
         }
-        return { isValid: true };
+        let response = {
+            isValid: true,
+            payer: verifyResult.payer,
+        };
+        const hooks = config?.hooks;
+        if (hooks !== undefined) {
+            const args = {
+                ...hookArgs,
+                requirements,
+                payment,
+                response,
+            };
+            for (const hook of hooks) {
+                if (hook.afterVerify === undefined) {
+                    continue;
+                }
+                const res = await hook.afterVerify({
+                    ...args,
+                    response,
+                });
+                if (res !== undefined) {
+                    response = res;
+                }
+            }
+        }
+        return response;
     };
     const handleSettle = async (requirements, payment) => {
         if (!isMatchingRequirement(requirements)) {
@@ -254,9 +336,9 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
             logger.error(msg);
             return {
                 success: false,
-                error: msg,
-                txHash: null,
-                networkId: null,
+                errorReason: msg,
+                transaction: "",
+                network: requirements.network,
             };
         };
         const processor = determinePaymentPayload(requirements, payment.payload);
@@ -267,7 +349,18 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         if ("error" in verifyResult) {
             return errorResponse(verifyResult.error);
         }
+        const { payer } = verifyResult;
         const { signedTransaction } = await verifyResult.settle();
+        if (config?.features?.enableDuplicateCheck &&
+            "blockHeight" in verifyResult) {
+            const signature = getSignatureFromTransaction(signedTransaction);
+            const { blockHeight } = verifyResult;
+            if (seenTxs.has(signature)) {
+                logger.warning("Duplicate transaction rejected", { signature });
+                return errorResponse("Duplicate transaction");
+            }
+            seenTxs.add(signature, blockHeight);
+        }
         let result;
         try {
             result = await sendTransaction(rpc, signedTransaction, maxRetries, retryDelayMs);
@@ -278,12 +371,34 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         if (!result.success) {
             return errorResponse(result.error);
         }
-        return {
+        let response = {
             success: true,
-            error: null,
-            txHash: result.signature,
-            networkId: payment.network,
+            transaction: result.signature,
+            network: payment.accepted.network,
+            payer,
         };
+        const hooks = config?.hooks;
+        if (hooks !== undefined) {
+            const args = {
+                ...hookArgs,
+                requirements,
+                payment,
+                response,
+            };
+            for (const hook of hooks) {
+                if (hook.afterSettle === undefined) {
+                    continue;
+                }
+                const res = await hook.afterSettle({
+                    ...args,
+                    response,
+                });
+                if (res !== undefined) {
+                    response = res;
+                }
+            }
+        }
+        return response;
     };
     return {
         getSupported,