@faremeter/payment-solana 0.12.0 → 0.14.0

package/README.md

@@ -0,0 +1,33 @@
+# @faremeter/payment-solana
+
+Solana payment scheme implementations for the x402 protocol, supporting SPL token transfers.
+
+## Installation
+
+```bash
+pnpm install @faremeter/payment-solana
+```
+
+## Features
+
+- SPL token payments (USDC, etc.)
+- Devnet, testnet, and mainnet support
+- Automatic fee payer handling
+- Transaction verification
+- Works with any SPL token
+
+## API Reference
+
+<!-- TSDOC_START -->
+
+<!-- TSDOC_END -->
+
+## Related Packages
+
+- [@faremeter/wallet-solana](https://www.npmjs.com/package/@faremeter/wallet-solana) - Solana wallet adapter
+- [@faremeter/fetch](https://www.npmjs.com/package/@faremeter/fetch) - Client fetch wrapper
+- [@faremeter/facilitator](https://www.npmjs.com/package/@faremeter/facilitator) - Payment facilitator
+
+## License
+
+LGPL-3.0-only

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

@@ -14,6 +14,9 @@ interface GetAssociatedTokenAddressSyncOptions {
 }
 interface CreatePaymentHandlerOptions {
     token?: GetAssociatedTokenAddressSyncOptions;
+    features?: {
+        enableSettlementAccounts?: boolean;
+    };
 }
 export declare function createPaymentHandler(wallet: Wallet, mint: PublicKey, connection?: Connection, options?: CreatePaymentHandlerOptions): PaymentHandler;
 export {};

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;AAWjC,OAAO,EAEL,UAAU,EACV,SAAS,EACT,sBAAsB,EAEtB,oBAAoB,EACrB,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;AAgBD,UAAU,2BAA2B;IACnC,KAAK,CAAC,EAAE,oCAAoC,CAAC;CAC9C;AAED,wBAAgB,oBAAoB,CAClC,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,SAAS,EACf,UAAU,CAAC,EAAE,UAAU,EACvB,OAAO,CAAC,EAAE,2BAA2B,GACpC,cAAc,CAuHhB"}
+{"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"}

package/dist/src/exact/client.js

@@ -1,7 +1,7 @@
 import { isValidationError, throwValidationError } from "@faremeter/types";
-import { createTransferCheckedInstruction, getAssociatedTokenAddressSync, getMint, } from "@solana/spl-token";
+import { createAssociatedTokenAccountIdempotentInstruction, createTransferCheckedInstruction, getAssociatedTokenAddressSync, getMint, } from "@solana/spl-token";
 import { getBase64EncodedWireTransaction, } from "@solana/transactions";
-import { ComputeBudgetProgram, Connection, PublicKey, TransactionInstruction, TransactionMessage, VersionedTransaction, } from "@solana/web3.js";
+import { ComputeBudgetProgram, Connection, PublicKey, TransactionInstruction, TransactionMessage, VersionedTransaction, Keypair, } from "@solana/web3.js";
 import { PaymentRequirementsExtra } from "./facilitator.js";
 import { generateMatcher } from "./common.js";
 function generateGetAssociatedTokenAddressSyncRest(tokenConfig) {
@@ -12,44 +12,68 @@ function generateGetAssociatedTokenAddressSyncRest(tokenConfig) {
     // implementation.
     return [allowOwnerOffCurve, programId, associatedTokenProgramId];
 }
+const PaymentMode = {
+    ToSpec: "toSpec",
+    SettlementAccount: "settlementAccount",
+};
+async function extractMetadata(args) {
+    const { connection, mint, requirements, wallet, options } = args;
+    const extra = PaymentRequirementsExtra(requirements.extra);
+    if (isValidationError(extra)) {
+        throwValidationError("couldn't validate requirements extra field", extra);
+    }
+    let recentBlockhash;
+    if (extra.recentBlockhash !== undefined) {
+        recentBlockhash = extra.recentBlockhash;
+    }
+    else if (connection !== undefined) {
+        recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
+    }
+    else {
+        throw new Error("couldn't get the latest Solana network block hash");
+    }
+    let decimals;
+    if (extra.decimals !== undefined) {
+        decimals = extra.decimals;
+    }
+    else if (connection !== undefined) {
+        const mintInfo = await getMint(connection, mint);
+        decimals = mintInfo.decimals;
+    }
+    else {
+        throw new Error("couldn't get the decimal information for the mint");
+    }
+    const payerKey = new PublicKey(extra.feePayer);
+    const payTo = new PublicKey(requirements.payTo);
+    const amount = Number(requirements.maxAmountRequired);
+    let paymentMode = PaymentMode.ToSpec;
+    if (options?.features?.enableSettlementAccounts &&
+        extra.features?.xSettlementAccountSupported &&
+        wallet.sendTransaction) {
+        paymentMode = PaymentMode.SettlementAccount;
+    }
+    return {
+        recentBlockhash,
+        decimals,
+        payTo,
+        amount,
+        payerKey,
+        paymentMode,
+    };
+}
 export function createPaymentHandler(wallet, mint, connection, options) {
     const getAssociatedTokenAddressSyncRest = generateGetAssociatedTokenAddressSyncRest(options?.token ?? {});
     const { isMatchingRequirement } = generateMatcher(wallet.network, mint ? mint.toBase58() : "sol");
     return async (_context, accepts) => {
         const res = accepts.filter(isMatchingRequirement).map((requirements) => {
-            const extra = PaymentRequirementsExtra(requirements.extra);
-            if (isValidationError(extra)) {
-                throwValidationError("couldn't validate requirements extra field", extra);
-            }
             const exec = async () => {
-                let recentBlockhash;
-                if (extra.recentBlockhash !== undefined) {
-                    recentBlockhash = extra.recentBlockhash;
-                }
-                else if (connection !== undefined) {
-                    recentBlockhash = (await connection.getLatestBlockhash()).blockhash;
-                }
-                else {
-                    throw new Error("couldn't get the latest Solana network block hash");
-                }
-                let decimals;
-                if (extra.decimals !== undefined) {
-                    decimals = extra.decimals;
-                }
-                else if (connection !== undefined) {
-                    const mintInfo = await getMint(connection, mint);
-                    decimals = mintInfo.decimals;
-                }
-                else {
-                    throw new Error("couldn't get the decimal information for the mint");
-                }
-                const paymentRequirements = {
-                    ...extra,
-                    amount: Number(requirements.maxAmountRequired),
-                    receiver: new PublicKey(requirements.payTo),
-                };
-                const sourceAccount = getAssociatedTokenAddressSync(mint, wallet.publicKey, ...getAssociatedTokenAddressSyncRest);
-                const receiverAccount = getAssociatedTokenAddressSync(mint, paymentRequirements.receiver, ...getAssociatedTokenAddressSyncRest);
+                const { recentBlockhash, decimals, payTo, amount, payerKey, paymentMode, } = await extractMetadata({
+                    connection,
+                    mint,
+                    requirements,
+                    wallet,
+                    options,
+                });
                 const instructions = [
                     ComputeBudgetProgram.setComputeUnitLimit({
                         units: 50_000,
@@ -57,31 +81,67 @@ export function createPaymentHandler(wallet, mint, connection, options) {
                     ComputeBudgetProgram.setComputeUnitPrice({
                         microLamports: 1,
                     }),
-                    createTransferCheckedInstruction(sourceAccount, mint, receiverAccount, wallet.publicKey, paymentRequirements.amount, decimals),
                 ];
-                let tx;
-                if (wallet.buildTransaction) {
-                    tx = await wallet.buildTransaction(instructions, recentBlockhash);
-                }
-                else {
-                    const message = new TransactionMessage({
-                        instructions,
-                        payerKey: new PublicKey(paymentRequirements.feePayer),
-                        recentBlockhash,
-                    }).compileToV0Message();
-                    tx = new VersionedTransaction(message);
-                }
-                if (wallet.updateTransaction) {
-                    tx = await wallet.updateTransaction(tx);
+                const sourceAccount = getAssociatedTokenAddressSync(mint, wallet.publicKey, ...getAssociatedTokenAddressSyncRest);
+                switch (paymentMode) {
+                    case PaymentMode.ToSpec: {
+                        const receiverAccount = getAssociatedTokenAddressSync(mint, payTo, ...getAssociatedTokenAddressSyncRest);
+                        instructions.push(createTransferCheckedInstruction(sourceAccount, mint, receiverAccount, wallet.publicKey, amount, decimals));
+                        let tx;
+                        if (wallet.buildTransaction) {
+                            tx = await wallet.buildTransaction(instructions, recentBlockhash);
+                        }
+                        else {
+                            const message = new TransactionMessage({
+                                instructions,
+                                payerKey,
+                                recentBlockhash,
+                            }).compileToV0Message();
+                            tx = new VersionedTransaction(message);
+                        }
+                        if (wallet.updateTransaction) {
+                            tx = await wallet.updateTransaction(tx);
+                        }
+                        const base64EncodedWireTransaction = getBase64EncodedWireTransaction({
+                            messageBytes: tx.message.serialize(),
+                            signatures: tx.signatures,
+                        });
+                        const payload = {
+                            transaction: base64EncodedWireTransaction,
+                        };
+                        return { payload };
+                    }
+                    case PaymentMode.SettlementAccount: {
+                        const settleKeypair = Keypair.generate();
+                        const settleATA = getAssociatedTokenAddressSync(mint, settleKeypair.publicKey, ...getAssociatedTokenAddressSyncRest);
+                        instructions.push(createAssociatedTokenAccountIdempotentInstruction(wallet.publicKey, settleATA, settleKeypair.publicKey, mint), createTransferCheckedInstruction(sourceAccount, mint, settleATA, wallet.publicKey, amount, decimals));
+                        let tx;
+                        if (wallet.buildTransaction) {
+                            tx = await wallet.buildTransaction(instructions, recentBlockhash);
+                        }
+                        else {
+                            const message = new TransactionMessage({
+                                instructions,
+                                payerKey,
+                                recentBlockhash,
+                            }).compileToV0Message();
+                            tx = new VersionedTransaction(message);
+                        }
+                        if (wallet.updateTransaction) {
+                            tx = await wallet.updateTransaction(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 payload = {
+                            settleSecretKey,
+                            transactionSignature,
+                        };
+                        return { payload };
+                    }
                 }
-                const base64EncodedWireTransaction = getBase64EncodedWireTransaction({
-                    messageBytes: tx.message.serialize(),
-                    signatures: tx.signatures,
-                });
-                const payload = {
-                    transaction: base64EncodedWireTransaction,
-                };
-                return { payload };
             };
             return {
                 exec,

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

@@ -1,24 +1,40 @@
 import type { FacilitatorHandler } from "@faremeter/types/facilitator";
 import { type Rpc, type SolanaRpcApi } from "@solana/kit";
 import type { TransactionError } from "@solana/rpc-types";
-import { Keypair, type PublicKey } from "@solana/web3.js";
+import { Keypair, PublicKey } from "@solana/web3.js";
+export declare const PaymentRequirementsExtraFeatures: import("arktype/internal/methods/object.ts").ObjectType<{
+    xSettlementAccountSupported?: boolean;
+}, {}>;
+export type PaymentRequirementsExtraFeatures = typeof PaymentRequirementsExtraFeatures.infer;
 export declare const PaymentRequirementsExtra: import("arktype/internal/methods/object.ts").ObjectType<{
     feePayer: string;
     decimals?: number;
     recentBlockhash?: string;
+    features?: {
+        xSettlementAccountSupported?: boolean;
+    };
 }, {}>;
 interface FacilitatorOptions {
     maxRetries?: number;
     retryDelayMs?: number;
     maxPriorityFee?: number;
+    features?: {
+        enableSettlementAccounts?: boolean;
+    };
 }
-export declare const PaymentPayload: import("arktype/internal/methods/object.ts").ObjectType<{
+export declare const PaymentPayloadTransaction: import("arktype/internal/methods/object.ts").ObjectType<{
     transaction: (In: string) => import("arktype").Out<Readonly<{
         messageBytes: import("@solana/transactions").TransactionMessageBytes;
         signatures: import("@solana/transactions").SignaturesMap;
     }>>;
 }, {}>;
+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>>;
+}, {}>;
+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) => FacilitatorHandler;
+export declare const createFacilitatorHandler: (network: string, 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,EAML,KAAK,GAAG,EACR,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AAOrB,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,EAAE,OAAO,EAAE,KAAK,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAM1D,eAAO,MAAM,wBAAwB;;;;MAInC,CAAC;AAEH,UAAU,kBAAkB;IAC1B,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,YAAY,CAAC,EAAE,MAAM,CAAC;IAGtB,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAmBD,eAAO,MAAM,cAAc;;;;;MAEzB,CAAC;AAEH,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,kBA0HF,CAAC"}
+{"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"}

package/dist/src/exact/facilitator.js

@@ -1,36 +1,38 @@
+import { x402PaymentRequirements, } from "@faremeter/types/x402";
 import { isValidationError } from "@faremeter/types";
 import { lookupX402Network } from "@faremeter/info/solana";
 import { fetchMint } from "@solana-program/token";
-import { address, createKeyPairSignerFromBytes, decompileTransactionMessage, getBase64Encoder, getCompiledTransactionMessageDecoder, } from "@solana/kit";
+import { address, createKeyPairSignerFromBytes, decompileTransactionMessage, getBase64Encoder, getCompiledTransactionMessageDecoder, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, pipe, } from "@solana/kit";
 import { getBase64EncodedWireTransaction, getTransactionDecoder, partiallySignTransaction, } from "@solana/transactions";
-import { Keypair } from "@solana/web3.js";
+import { Keypair, PublicKey } from "@solana/web3.js";
 import { type } from "arktype";
 import { isValidTransaction } from "./verify.js";
 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";
+export const PaymentRequirementsExtraFeatures = type({
+    xSettlementAccountSupported: "boolean?",
+});
 export const PaymentRequirementsExtra = type({
     feePayer: "string",
     decimals: "number?",
     recentBlockhash: "string?",
+    features: PaymentRequirementsExtraFeatures.optional(),
 });
-function errorResponse(msg) {
-    logger.error(msg);
-    return {
-        success: false,
-        error: msg,
-        txHash: null,
-        networkId: null,
-    };
-}
 const TransactionString = type("string").pipe.try((tx) => {
     const decoder = getTransactionDecoder();
     const base64Encoder = getBase64Encoder();
     const transactionBytes = base64Encoder.encode(tx);
     return decoder.decode(transactionBytes);
 });
-export const PaymentPayload = type({
+export const PaymentPayloadTransaction = type({
     transaction: TransactionString,
 });
+export const PaymentPayloadSettlementAccount = type({
+    transactionSignature: "string",
+    settleSecretKey: type("string.base64").pipe.try((s) => Uint8Array.from(Buffer.from(s, "base64"))),
+});
 export function transactionErrorToString(t) {
     if (typeof t == "string") {
         return t;
@@ -72,9 +74,133 @@ const sendTransaction = async (rpc, signedTransaction, maxRetries, retryDelayMs)
     }
     return { success: false, error: "Transaction confirmation timeout" };
 };
-export const createFacilitatorHandler = (network, rpc, feePayerKeypair, mint, config) => {
+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 mintInfo = await fetchMint(rpc, address(mint.toBase58()));
+    const features = {};
+    if (config?.features?.enableSettlementAccounts) {
+        features.xSettlementAccountSupported = true;
+    }
+    const processSettlementAccount = async (requirements, paymentPayload) => {
+        const errorResponse = (error) => ({ error });
+        // XXX - It would be nicer to do this check in the arktype
+        // validation.  Unfortunately getting match to generate things
+        // properly turned out to create excessive TypeScript types
+        // that caused tsc to error out.
+        if (!config?.features?.enableSettlementAccounts) {
+            return errorResponse("settlement accounts are not accepted");
+        }
+        const settleSigner = await createKeyPairSignerFromBytes(paymentPayload.settleSecretKey);
+        const settleOwner = settleSigner.address;
+        const [settleATA] = await findAssociatedTokenPda({
+            mint: address(mint.toBase58()),
+            owner: settleOwner,
+            tokenProgram: TOKEN_PROGRAM_ADDRESS,
+        });
+        const { value: accountBalance } = await rpc
+            .getTokenAccountBalance(settleATA, { commitment: "confirmed" })
+            .send();
+        logger.debug("settlement account info: {*}", {
+            settleOwner,
+            settleATA,
+            accountBalance,
+        });
+        if (BigInt(accountBalance.amount) !== BigInt(requirements.maxAmountRequired)) {
+            return errorResponse("settlement account balance didn't match payment requirements");
+        }
+        const settle = async () => {
+            const feePayerSigner = await createKeyPairSignerFromBytes(feePayerKeypair.secretKey);
+            const [payToATA] = await findAssociatedTokenPda({
+                mint: address(mint.toBase58()),
+                owner: address(requirements.payTo),
+                tokenProgram: TOKEN_PROGRAM_ADDRESS,
+            });
+            const instructions = [
+                getAddMemoInstruction({ memo: crypto.randomUUID() }),
+                getTransferCheckedInstruction({
+                    source: settleATA,
+                    mint: address(mint.toBase58()),
+                    destination: payToATA,
+                    authority: settleSigner,
+                    amount: BigInt(requirements.maxAmountRequired),
+                    decimals: mintInfo.data.decimals,
+                }),
+                getCloseAccountInstruction({
+                    account: settleATA,
+                    destination: feePayerSigner.address,
+                    owner: settleSigner,
+                }),
+            ];
+            const { value: latestBlockhash } = await rpc.getLatestBlockhash().send();
+            // Build the transaction message
+            const transactionMessage = pipe(createTransactionMessage({ version: 0 }), (msg) => setTransactionMessageFeePayerSigner(feePayerSigner, msg), (msg) => setTransactionMessageLifetimeUsingBlockhash(latestBlockhash, msg), (msg) => appendTransactionMessageInstructions(instructions, msg));
+            const signedTransaction = await signTransactionMessageWithSigners(transactionMessage);
+            return {
+                signedTransaction,
+            };
+        };
+        return {
+            settle,
+        };
+    };
+    const processTransaction = async (requirements, paymentPayload) => {
+        const errorResponse = (error) => ({ error });
+        let transactionMessage, transaction;
+        try {
+            transaction = paymentPayload.transaction;
+            const compiledTransactionMessage = getCompiledTransactionMessageDecoder().decode(transaction.messageBytes);
+            transactionMessage = decompileTransactionMessage(compiledTransactionMessage);
+        }
+        catch (cause) {
+            throw new Error("Failed to get compiled transaction message", { cause });
+        }
+        try {
+            if (!(await isValidTransaction(transactionMessage, requirements, feePayerKeypair.publicKey, maxPriorityFee))) {
+                logger.error("Invalid transaction");
+                return errorResponse("Invalid transaction");
+            }
+        }
+        catch (cause) {
+            throw new Error("Failed to validate transaction", { cause });
+        }
+        return {
+            settle: async () => {
+                let signedTransaction;
+                try {
+                    const kitKeypair = await createKeyPairSignerFromBytes(feePayerKeypair.secretKey);
+                    signedTransaction = await partiallySignTransaction([kitKeypair.keyPair], transaction);
+                }
+                catch (cause) {
+                    throw new Error("Failed to partially sign transaction", { cause });
+                }
+                return {
+                    signedTransaction,
+                };
+            },
+        };
+    };
+    const determinePaymentPayload = function (requirements, possiblePayload) {
+        // XXX - It would be great to do this automatically using arktype,
+        // but because of the overlapping input types and the morphs, this
+        // ends up being more annoying than you'd think.  So instead, use
+        // hints to do the correct validation.
+        if (config?.features?.enableSettlementAccounts &&
+            "settleSecretKey" in possiblePayload) {
+            const paymentPayload = PaymentPayloadSettlementAccount(possiblePayload);
+            if (isValidationError(paymentPayload)) {
+                return paymentPayload;
+            }
+            return processSettlementAccount(requirements, paymentPayload);
+        }
+        else {
+            const paymentPayload = PaymentPayloadTransaction(possiblePayload);
+            if (isValidationError(paymentPayload)) {
+                return paymentPayload;
+            }
+            return processTransaction(requirements, paymentPayload);
+        }
+    };
     const getSupported = () => {
         return lookupX402Network(network).map((network) => Promise.resolve({
             x402Version: 1,
@@ -82,13 +208,13 @@ export const createFacilitatorHandler = (network, rpc, feePayerKeypair, mint, co
             network,
             extra: {
                 feePayer: feePayerKeypair.publicKey.toString(),
+                features,
             },
         }));
     };
     const getRequirements = async (req) => {
         const recentBlockhash = (await rpc.getLatestBlockhash().send()).value
             .blockhash;
-        const mintInfo = await fetchMint(rpc, address(mint.toBase58()));
         return req.filter(isMatchingRequirement).map((x) => {
             return {
                 ...x,
@@ -97,44 +223,51 @@ export const createFacilitatorHandler = (network, rpc, feePayerKeypair, mint, co
                     feePayer: feePayerKeypair.publicKey.toString(),
                     decimals: mintInfo.data.decimals,
                     recentBlockhash,
+                    features,
                 },
             };
         });
     };
-    const handleSettle = async (requirements, payment) => {
+    const handleVerify = async (requirements, payment) => {
         if (!isMatchingRequirement(requirements)) {
             return null;
         }
-        const paymentPayload = PaymentPayload(payment.payload);
-        if (isValidationError(paymentPayload)) {
-            return errorResponse(paymentPayload.summary);
-        }
-        let transactionMessage, transaction;
-        try {
-            transaction = paymentPayload.transaction;
-            const compiledTransactionMessage = getCompiledTransactionMessageDecoder().decode(transaction.messageBytes);
-            transactionMessage = decompileTransactionMessage(compiledTransactionMessage);
-        }
-        catch (cause) {
-            throw new Error("Failed to get compiled transaction message", { cause });
+        const errorResponse = (invalidReason) => ({
+            isValid: false,
+            invalidReason,
+        });
+        const processor = determinePaymentPayload(requirements, payment.payload);
+        if (isValidationError(processor)) {
+            return errorResponse(processor.summary);
         }
-        try {
-            if (!(await isValidTransaction(transactionMessage, requirements, feePayerKeypair.publicKey, maxPriorityFee))) {
-                logger.error("Invalid transaction");
-                return errorResponse("Invalid transaction");
-            }
+        const verifyResult = await processor;
+        if ("error" in verifyResult) {
+            return errorResponse(verifyResult.error);
         }
-        catch (cause) {
-            throw new Error("Failed to validate transaction", { cause });
+        return { isValid: true };
+    };
+    const handleSettle = async (requirements, payment) => {
+        if (!isMatchingRequirement(requirements)) {
+            return null;
         }
-        let signedTransaction;
-        try {
-            const kitKeypair = await createKeyPairSignerFromBytes(feePayerKeypair.secretKey);
-            signedTransaction = await partiallySignTransaction([kitKeypair.keyPair], transaction);
+        const errorResponse = (msg) => {
+            logger.error(msg);
+            return {
+                success: false,
+                error: msg,
+                txHash: null,
+                networkId: null,
+            };
+        };
+        const processor = determinePaymentPayload(requirements, payment.payload);
+        if (isValidationError(processor)) {
+            return errorResponse(processor.summary);
         }
-        catch (cause) {
-            throw new Error("Failed to partially sign transaction", { cause });
+        const verifyResult = await processor;
+        if ("error" in verifyResult) {
+            return errorResponse(verifyResult.error);
         }
+        const { signedTransaction } = await verifyResult.settle();
         let result;
         try {
             result = await sendTransaction(rpc, signedTransaction, maxRetries, retryDelayMs);
@@ -155,6 +288,7 @@ export const createFacilitatorHandler = (network, rpc, feePayerKeypair, mint, co
     return {
         getSupported,
         getRequirements,
+        handleVerify,
         handleSettle,
     };
 };