@faremeter/payment-solana 0.20.1 → 0.21.0

package/dist/src/exact/facilitator.js

@@ -4,9 +4,9 @@ import { clusterToCAIP2, isKnownCluster, caip2ToCluster, isSolanaCAIP2Network, }
 import { fetchMint, findAssociatedTokenPda, getTransferCheckedInstruction, getCloseAccountInstruction, } from "@solana-program/token";
 import { address, createKeyPairSignerFromBytes, decompileTransactionMessage, getBase64Encoder, getCompiledTransactionMessageDecoder, createTransactionMessage, setTransactionMessageFeePayerSigner, setTransactionMessageLifetimeUsingBlockhash, appendTransactionMessageInstructions, signTransactionMessageWithSigners, pipe, } from "@solana/kit";
 import { getBase64EncodedWireTransaction, getSignatureFromTransaction, getTransactionDecoder, partiallySignTransaction, } from "@solana/transactions";
-import { Keypair, PublicKey } from "@solana/web3.js";
 import { type } from "arktype";
 import { isValidTransaction } from "./verify.js";
+import { toAddress, toKeyPairSigner, toRpc } from "../compat.js";
 import { logger } from "./logger.js";
 import { x402Scheme, generateMatcher } from "./common.js";
 import { getAddMemoInstruction } from "@solana-program/memo";
@@ -84,21 +84,24 @@ const sendTransaction = async (rpc, signedTransaction, maxRetries, retryDelayMs)
  * 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 rpcInput - Solana RPC client
+ * @param feePayerSignerInput - Keypair or signer for paying transaction fees
+ * @param mintInput - 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());
+export const createFacilitatorHandler = async (network, rpcInput, feePayerSignerInput, mintInput, config) => {
+    const rpc = toRpc(rpcInput);
+    const mint = toAddress(mintInput);
+    const feePayerSigner = await toKeyPairSigner(feePayerSignerInput);
+    const { isMatchingRequirement } = generateMatcher(network, mint);
     const { maxRetries = 30, retryDelayMs = 1000, maxPriorityFee = 100_000, maxTransactionAge = 150, } = config ?? {};
-    const mintInfo = await fetchMint(rpc, address(mint.toBase58()));
+    const mintInfo = await fetchMint(rpc, mint);
     const tokenProgram = mintInfo.programAddress;
     const hookArgs = {
         network,
         rpc,
-        feePayerKeypair,
+        feePayerSigner,
         mint,
         mintInfo,
         logger,
@@ -120,7 +123,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         const settleSigner = await createKeyPairSignerFromBytes(paymentPayload.settleSecretKey);
         const settleOwner = settleSigner.address;
         const [settleATA] = await findAssociatedTokenPda({
-            mint: address(mint.toBase58()),
+            mint,
             owner: settleOwner,
             tokenProgram,
         });
@@ -136,9 +139,8 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
             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()),
+                mint,
                 owner: address(requirements.payTo),
                 tokenProgram,
             });
@@ -150,7 +152,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                 getAddMemoInstruction({ memo: crypto.randomUUID() }),
                 getTransferCheckedInstruction({
                     source: settleATA,
-                    mint: address(mint.toBase58()),
+                    mint,
                     destination: payToATA,
                     authority: settleSigner,
                     amount: BigInt(requirements.amount),
@@ -195,7 +197,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         }
         let validResult;
         try {
-            validResult = await isValidTransaction(transactionMessage, requirements, feePayerKeypair.publicKey.toBase58(), tokenProgram, maxPriorityFee);
+            validResult = await isValidTransaction(transactionMessage, requirements, feePayerSigner.address, tokenProgram, { maxPriorityFee, requireMemo: config?.requireMemo ?? true });
             if (!validResult) {
                 logger.error("Invalid transaction");
                 return errorResponse("Invalid transaction");
@@ -211,8 +213,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
             settle: async () => {
                 let signedTransaction;
                 try {
-                    const kitKeypair = await createKeyPairSignerFromBytes(feePayerKeypair.secretKey);
-                    signedTransaction = await partiallySignTransaction([kitKeypair.keyPair], transaction);
+                    signedTransaction = await partiallySignTransaction([feePayerSigner.keyPair], transaction);
                 }
                 catch (cause) {
                     throw new Error("Failed to partially sign transaction", { cause });
@@ -266,7 +267,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                 scheme: x402Scheme,
                 network: clusterToCAIP2(resolveCluster()).caip2,
                 extra: {
-                    feePayer: feePayerKeypair.publicKey.toString(),
+                    feePayer: feePayerSigner.address,
                     tokenProgram,
                     features,
                 },
@@ -283,9 +284,9 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                 : {};
             return {
                 ...x,
-                asset: mint.toBase58(),
+                asset: mint,
                 extra: {
-                    feePayer: feePayerKeypair.publicKey.toString(),
+                    feePayer: feePayerSigner.address,
                     decimals: mintInfo.data.decimals,
                     recentBlockhash,
                     ...memo,

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

@@ -1,4 +1,2 @@
-import { TransactionInstruction } from "@solana/web3.js";
 export declare function generateMemoNonce(): string;
-export declare function createMemoInstruction(memo: string): TransactionInstruction;
 //# sourceMappingURL=memo.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../../src/exact/memo.ts"],"names":[],"mappings":"AAAA,OAAO,EAAa,sBAAsB,EAAE,MAAM,iBAAiB,CAAC;AAGpE,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C;AAED,wBAAgB,qBAAqB,CAAC,IAAI,EAAE,MAAM,GAAG,sBAAsB,CAM1E"}
+{"version":3,"file":"memo.d.ts","sourceRoot":"","sources":["../../../src/exact/memo.ts"],"names":[],"mappings":"AAAA,wBAAgB,iBAAiB,IAAI,MAAM,CAM1C"}

package/dist/src/exact/memo.js

@@ -1,5 +1,3 @@
-import { PublicKey, TransactionInstruction } from "@solana/web3.js";
-import { MEMO_PROGRAM_ADDRESS } from "@solana-program/memo";
 export function generateMemoNonce() {
     const bytes = new Uint8Array(16);
     crypto.getRandomValues(bytes);
@@ -7,10 +5,3 @@ export function generateMemoNonce() {
         .map((b) => b.toString(16).padStart(2, "0"))
         .join("");
 }
-export function createMemoInstruction(memo) {
-    return new TransactionInstruction({
-        programId: new PublicKey(MEMO_PROGRAM_ADDRESS),
-        keys: [],
-        data: Buffer.from(memo, "utf-8"),
-    });
-}

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

@@ -1,7 +1,11 @@
 import type { x402PaymentRequirements } from "@faremeter/types/x402v2";
 import { type Address } from "@solana/kit";
 import type { CompilableTransactionMessage } from "../common.js";
-export declare function isValidTransaction(transactionMessage: CompilableTransactionMessage, paymentRequirements: x402PaymentRequirements, facilitatorAddress: string, tokenProgram: Address, maxPriorityFee?: number): Promise<{
+export interface TransactionValidationOptions {
+    maxPriorityFee?: number;
+    requireMemo?: boolean;
+}
+export declare function isValidTransaction(transactionMessage: CompilableTransactionMessage, paymentRequirements: x402PaymentRequirements, facilitatorAddress: string, tokenProgram: Address, options?: TransactionValidationOptions): Promise<{
     payer: string;
 } | false>;
 //# sourceMappingURL=verify.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/exact/verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAUvE,OAAO,EAAW,KAAK,OAAO,EAAoB,MAAM,aAAa,CAAC;AAGtE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC;AA0H9D,wBAAsB,kBAAkB,CACtC,kBAAkB,EAAE,4BAA4B,EAChD,mBAAmB,EAAE,uBAAuB,EAC5C,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,OAAO,EACrB,cAAc,CAAC,EAAE,MAAM,GACtB,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAC,CAkGpC"}
+{"version":3,"file":"verify.d.ts","sourceRoot":"","sources":["../../../src/exact/verify.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,uBAAuB,EAAE,MAAM,yBAAyB,CAAC;AAUvE,OAAO,EAAW,KAAK,OAAO,EAAoB,MAAM,aAAa,CAAC;AAGtE,OAAO,KAAK,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC;AA0H9D,MAAM,WAAW,4BAA4B;IAC3C,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED,wBAAsB,kBAAkB,CACtC,kBAAkB,EAAE,4BAA4B,EAChD,mBAAmB,EAAE,uBAAuB,EAC5C,kBAAkB,EAAE,MAAM,EAC1B,YAAY,EAAE,OAAO,EACrB,OAAO,CAAC,EAAE,4BAA4B,GACrC,OAAO,CAAC;IAAE,KAAK,EAAE,MAAM,CAAA;CAAE,GAAG,KAAK,CAAC,CA0GpC"}

package/dist/src/exact/verify.js

@@ -93,7 +93,7 @@ async function verifyTransferInstruction(instruction, paymentRequirements, desti
     }
     return false;
 }
-export async function isValidTransaction(transactionMessage, paymentRequirements, facilitatorAddress, tokenProgram, maxPriorityFee) {
+export async function isValidTransaction(transactionMessage, paymentRequirements, facilitatorAddress, tokenProgram, options) {
     const extra = PaymentRequirementsExtra(paymentRequirements.extra);
     if (isValidationError(extra)) {
         throw new Error("feePayer is required");
@@ -119,6 +119,7 @@ export async function isValidTransaction(transactionMessage, paymentRequirements
     if (!limitResult.valid || !priceResult.valid) {
         return false;
     }
+    const { maxPriorityFee, requireMemo = true } = options ?? {};
     if (maxPriorityFee !== undefined &&
         limitResult.units !== undefined &&
         priceResult.microLamports !== undefined) {
@@ -144,13 +145,18 @@ export async function isValidTransaction(transactionMessage, paymentRequirements
         }
     }
     const memoInstructions = rest.filter(isMemoInstruction);
-    if (memoInstructions.length !== 1) {
+    if (memoInstructions.length > 1) {
+        logger.error("Expected at most one Memo instruction");
+        return false;
+    }
+    if (requireMemo && memoInstructions.length !== 1) {
         logger.error("Expected exactly one Memo instruction");
         return false;
     }
     if (extra.memo !== undefined) {
         const memoIx = memoInstructions[0];
         if (!memoIx) {
+            logger.error("extra.memo is set but no Memo instruction found");
             return false;
         }
         const memoData = getMemoData(memoIx);

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

@@ -175,7 +175,7 @@ await t.test("isValidTransaction", async (t) => {
     await t.test("accepts transaction within priority fee limit", async (t) => {
         const f = await createFixtures();
         const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, makeMemoIx("nonce")], f.facilitator);
-        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, 100_000);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { maxPriorityFee: 100_000 });
         t.ok(result);
         t.equal(result && result.payer, f.sender.address);
         t.end();
@@ -189,7 +189,7 @@ await t.test("isValidTransaction", async (t) => {
             microLamports: 10000000n,
         });
         const txMsg = buildTxMessage([highLimitIx, highPriceIx, f.transferIx, makeMemoIx("nonce")], f.facilitator);
-        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, 100), false);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { maxPriorityFee: 100 }), false);
         t.end();
     });
     await t.test("rejects transaction exceeding priority fee limit with lighthouse ixs", async (t) => {
@@ -207,7 +207,7 @@ await t.test("isValidTransaction", async (t) => {
             makeLighthouseIx(),
             makeMemoIx("nonce"),
         ], f.facilitator);
-        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, 100), false);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { maxPriorityFee: 100 }), false);
         t.end();
     });
     await t.test("rejects trailing non-lighthouse instruction", async (t) => {
@@ -448,5 +448,82 @@ await t.test("isValidTransaction", async (t) => {
         t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
+    await t.test("rejects transaction without memo when requireMemo defaults to true", async (t) => {
+        const f = await createFixtures();
+        // Older clients build exactly 3 instructions:
+        //   1. SetComputeUnitLimit
+        //   2. SetComputeUnitPrice
+        //   3. TransferChecked
+        // No memo instruction is included.  With requireMemo defaulting to
+        // true, the facilitator rejects these transactions.
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { requireMemo: true }), false);
+        t.end();
+    });
+    await t.test("accepts transaction without memo when requireMemo is false", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false });
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts transaction with lighthouse but no memo when requireMemo is false", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, makeLighthouseIx()], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false });
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts transaction with memo when requireMemo is false", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, makeMemoIx("nonce")], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false });
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("rejects multiple memos even when requireMemo is false", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("a"),
+            makeMemoIx("b"),
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false }), false);
+        t.end();
+    });
+    await t.test("rejects memo mismatch when requireMemo is false and extra.memo is set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "expected-value" },
+        };
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("wrong-value"),
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false }), false);
+        t.end();
+    });
+    await t.test("rejects missing memo when requireMemo is false but extra.memo is set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "invoice-789" },
+        };
+        // An older client cannot supply a memo instruction, so a seller
+        // that requires a specific memo value should still reject the
+        // transaction regardless of the requireMemo setting.
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram, { requireMemo: false }), false);
+        t.end();
+    });
     t.end();
 });

package/dist/src/flex/client/handler.d.ts

@@ -0,0 +1,31 @@
+import { type Address } from "@solana/kit";
+import type { PaymentHandler } from "@faremeter/types/client";
+import { fetchEscrowAccount } from "@faremeter/flex-solana";
+import type { webcrypto } from "node:crypto";
+type CryptoKeyPair = webcrypto.CryptoKeyPair;
+type Rpc = Parameters<typeof fetchEscrowAccount>[0];
+type SlotProvider = {
+    getSlot(): {
+        send(): Promise<bigint>;
+    };
+};
+/** Configuration for `createPaymentHandler`. */
+export type CreateFlexPaymentHandlerOpts = {
+    network: string;
+    escrow: Address;
+    mint: Address;
+    sessionKeyPair: CryptoKeyPair;
+    sessionKeyAddress: Address;
+    rpc: Rpc & SlotProvider;
+    programAddress?: Address;
+};
+/**
+ * Creates a client-side `PaymentHandler` that signs Flex payment
+ * authorizations against compatible x402 requirements.
+ *
+ * @param opts - Escrow, session key, and RPC configuration
+ * @returns A handler that produces signed payment payloads
+ */
+export declare function createPaymentHandler(opts: CreateFlexPaymentHandlerOpts): PaymentHandler;
+export {};
+//# sourceMappingURL=handler.d.ts.map

package/dist/src/flex/client/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/flex/client/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,OAAO,EAAW,MAAM,aAAa,CAAC;AAEpD,OAAO,KAAK,EAEV,cAAc,EAEf,MAAM,yBAAyB,CAAC;AAIjC,OAAO,EAGL,kBAAkB,EAGnB,MAAM,wBAAwB,CAAC;AAEhC,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,aAAa,CAAC;AAG7C,KAAK,aAAa,GAAG,SAAS,CAAC,aAAa,CAAC;AAE7C,KAAK,GAAG,GAAG,UAAU,CAAC,OAAO,kBAAkB,CAAC,CAAC,CAAC,CAAC,CAAC;AAEpD,KAAK,YAAY,GAAG;IAAE,OAAO,IAAI;QAAE,IAAI,IAAI,OAAO,CAAC,MAAM,CAAC,CAAA;KAAE,CAAA;CAAE,CAAC;AAE/D,gDAAgD;AAChD,MAAM,MAAM,4BAA4B,GAAG;IACzC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,OAAO,CAAC;IAChB,IAAI,EAAE,OAAO,CAAC;IACd,cAAc,EAAE,aAAa,CAAC;IAC9B,iBAAiB,EAAE,OAAO,CAAC;IAC3B,GAAG,EAAE,GAAG,GAAG,YAAY,CAAC;IACxB,cAAc,CAAC,EAAE,OAAO,CAAC;CAC1B,CAAC;AAKF;;;;;;GAMG;AACH,wBAAgB,oBAAoB,CAClC,IAAI,EAAE,4BAA4B,GACjC,cAAc,CAsHhB"}

package/dist/src/flex/client/handler.js

@@ -0,0 +1,104 @@
+import { address } from "@solana/kit";
+import { isValidationError } from "@faremeter/types";
+import { serializePaymentAuthorization, signPaymentAuthorization, fetchEscrowAccount, FlexPaymentRequirementsExtra, FLEX_PROGRAM_ADDRESS, } from "@faremeter/flex-solana";
+import { generateMatcher } from "../common.js";
+import { logger } from "../logger.js";
+const MS_PER_SLOT = 400;
+const EXPIRY_BUFFER_SLOTS = 20n;
+/**
+ * Creates a client-side `PaymentHandler` that signs Flex payment
+ * authorizations against compatible x402 requirements.
+ *
+ * @param opts - Escrow, session key, and RPC configuration
+ * @returns A handler that produces signed payment payloads
+ */
+export function createPaymentHandler(opts) {
+    const { escrow, mint, sessionKeyPair, sessionKeyAddress, rpc, programAddress = FLEX_PROGRAM_ADDRESS, } = opts;
+    const { isMatchingRequirement } = generateMatcher(opts.network, mint);
+    let cachedRefundTimeoutSlots = null;
+    let refundTimeoutPromise = null;
+    async function getRefundTimeoutSlots() {
+        if (cachedRefundTimeoutSlots !== null)
+            return cachedRefundTimeoutSlots;
+        refundTimeoutPromise ??= fetchEscrowAccount(rpc, escrow)
+            .then((account) => {
+            if (!account) {
+                throw new Error("Escrow account not found on-chain");
+            }
+            cachedRefundTimeoutSlots = account.refundTimeoutSlots;
+            return account.refundTimeoutSlots;
+        })
+            .catch((cause) => {
+            refundTimeoutPromise = null;
+            throw cause;
+        });
+        return refundTimeoutPromise;
+    }
+    let lastKnownSlot = 0n;
+    let lastSlotFetchedAtMs = 0;
+    async function getCurrentSlot() {
+        const elapsed = Date.now() - lastSlotFetchedAtMs;
+        if (lastKnownSlot > 0n && elapsed < 5_000) {
+            return lastKnownSlot + BigInt(Math.floor(elapsed / MS_PER_SLOT));
+        }
+        lastKnownSlot = await rpc.getSlot().send();
+        lastSlotFetchedAtMs = Date.now();
+        return lastKnownSlot;
+    }
+    function randomU64() {
+        const buf = new Uint8Array(8);
+        crypto.getRandomValues(buf);
+        const view = new DataView(buf.buffer, buf.byteOffset, buf.byteLength);
+        return view.getBigUint64(0, true);
+    }
+    return async (_context, accepts) => {
+        const compatible = accepts.filter(isMatchingRequirement);
+        return compatible.map((requirements) => {
+            const exec = async () => {
+                const extraResult = FlexPaymentRequirementsExtra(requirements.extra);
+                if (isValidationError(extraResult)) {
+                    throw new Error(`Invalid flex requirements extra: ${extraResult.summary}`);
+                }
+                const refundTimeoutSlots = await getRefundTimeoutSlots();
+                const currentSlot = await getCurrentSlot();
+                const authorizationId = randomU64();
+                const expiresAtSlot = currentSlot + refundTimeoutSlots - EXPIRY_BUFFER_SLOTS;
+                const maxAmount = BigInt(requirements.amount);
+                const message = serializePaymentAuthorization({
+                    programId: programAddress,
+                    escrow,
+                    mint,
+                    maxAmount,
+                    authorizationId,
+                    expiresAtSlot,
+                    splits: extraResult.splits.map((s) => ({
+                        recipient: address(s.recipient),
+                        bps: s.bps,
+                    })),
+                });
+                const signature = await signPaymentAuthorization({
+                    message,
+                    keyPair: sessionKeyPair,
+                });
+                const signatureBase64 = btoa(String.fromCharCode(...signature));
+                logger.debug("signed payment authorization", {
+                    escrow,
+                    authorizationId: authorizationId.toString(),
+                    maxAmount: maxAmount.toString(),
+                });
+                const payload = {
+                    escrow,
+                    mint,
+                    maxAmount: maxAmount.toString(),
+                    authorizationId: authorizationId.toString(),
+                    expiresAtSlot: expiresAtSlot.toString(),
+                    splits: extraResult.splits,
+                    sessionKey: sessionKeyAddress,
+                    signature: signatureBase64,
+                };
+                return { payload };
+            };
+            return { exec, requirements };
+        });
+    };
+}

package/dist/src/flex/client/index.d.ts

@@ -0,0 +1,3 @@
+export { createPaymentHandler } from "./handler.js";
+export type { CreateFlexPaymentHandlerOpts } from "./handler.js";
+//# sourceMappingURL=index.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../../src/flex/client/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,WAAW,CAAC;AACjD,YAAY,EAAE,4BAA4B,EAAE,MAAM,WAAW,CAAC"}

package/dist/src/flex/client/index.js

@@ -0,0 +1 @@
+export { createPaymentHandler } from "./handler.js";

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

@@ -0,0 +1,15 @@
+import { type SolanaCAIP2Network } from "@faremeter/info/solana";
+export declare const FLEX_SCHEME = "flex";
+export declare function generateMatcher(network: string | SolanaCAIP2Network, asset: string): {
+    matchTuple: import("arktype/internal/variants/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>>;
+        asset: (In: string) => import("arktype/internal/attributes.ts").To<Lowercase<string>>;
+    }, {}>;
+    isMatchingRequirement: (req: {
+        scheme: string;
+        network: string;
+        asset: string;
+    }) => boolean;
+};
+//# sourceMappingURL=common.d.ts.map

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

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

package/dist/src/flex/common.js

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

package/dist/src/flex/facilitator/handler.d.ts

@@ -0,0 +1,48 @@
+import { type Address, type TransactionSigner, type Rpc, type SolanaRpcApi } from "@solana/kit";
+import type { FacilitatorHandler } from "@faremeter/types/facilitator";
+import { type HoldManager } from "@faremeter/flex-solana/facilitator";
+type FlexFacilitatorConfig = {
+    supportedMints: Address[];
+    defaultSplits: {
+        recipient: string;
+        bps: number;
+    }[];
+    maxSubmitRetries?: number;
+    submitRetryDelayMs?: number;
+    minGracePeriodSlots?: bigint;
+    confirmationBufferSlots?: bigint;
+    snapshotMaxAgeMs?: number;
+    flushIntervalMs?: number;
+};
+/** Outcome of submitting a single hold to the on-chain program. */
+export type FlushResult = {
+    authorizationId: bigint;
+    success: boolean;
+    transaction?: string;
+    error?: string;
+};
+/**
+ * Extended `FacilitatorHandler` with Flex-specific lifecycle
+ * methods for flushing holds to chain and inspecting the hold manager.
+ */
+export type FlexFacilitator = FacilitatorHandler & {
+    flush(): Promise<FlushResult[]>;
+    getHoldManager(): HoldManager;
+    stop(): void;
+};
+/**
+ * Creates a facilitator handler that verifies Flex payment authorizations,
+ * manages in-memory holds, and submits/finalizes settlements on-chain.
+ *
+ * Starts a background interval that periodically flushes settled holds
+ * and finalizes confirmed transactions. Call `stop()` to clear it.
+ *
+ * @param network - Solana cluster name (e.g. "mainnet", "devnet")
+ * @param rpc - Solana RPC client
+ * @param facilitatorSigner - Transaction signer for the facilitator
+ * @param config - Supported mints, splits, and timing configuration
+ * @returns A `FlexFacilitator` with verify/settle/flush/stop methods
+ */
+export declare const createFacilitatorHandler: (network: string, rpc: Rpc<SolanaRpcApi>, facilitatorSigner: TransactionSigner, config: FlexFacilitatorConfig) => Promise<FlexFacilitator>;
+export {};
+//# sourceMappingURL=handler.d.ts.map

package/dist/src/flex/facilitator/handler.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"handler.d.ts","sourceRoot":"","sources":["../../../../src/flex/facilitator/handler.ts"],"names":[],"mappings":"AAAA,OAAO,EACL,KAAK,OAAO,EAaZ,KAAK,iBAAiB,EACtB,KAAK,GAAG,EACR,KAAK,YAAY,EAClB,MAAM,aAAa,CAAC;AASrB,OAAO,KAAK,EACV,kBAAkB,EAEnB,MAAM,8BAA8B,CAAC;AAiBtC,OAAO,EAIL,KAAK,WAAW,EACjB,MAAM,oCAAoC,CAAC;AAiC5C,KAAK,qBAAqB,GAAG;IAC3B,cAAc,EAAE,OAAO,EAAE,CAAC;IAC1B,aAAa,EAAE;QAAE,SAAS,EAAE,MAAM,CAAC;QAAC,GAAG,EAAE,MAAM,CAAA;KAAE,EAAE,CAAC;IACpD,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,mBAAmB,CAAC,EAAE,MAAM,CAAC;IAC7B,uBAAuB,CAAC,EAAE,MAAM,CAAC;IACjC,gBAAgB,CAAC,EAAE,MAAM,CAAC;IAC1B,eAAe,CAAC,EAAE,MAAM,CAAC;CAC1B,CAAC;AAcF,mEAAmE;AACnE,MAAM,MAAM,WAAW,GAAG;IACxB,eAAe,EAAE,MAAM,CAAC;IACxB,OAAO,EAAE,OAAO,CAAC;IACjB,WAAW,CAAC,EAAE,MAAM,CAAC;IACrB,KAAK,CAAC,EAAE,MAAM,CAAC;CAChB,CAAC;AAUF;;;GAGG;AACH,MAAM,MAAM,eAAe,GAAG,kBAAkB,GAAG;IACjD,KAAK,IAAI,OAAO,CAAC,WAAW,EAAE,CAAC,CAAC;IAChC,cAAc,IAAI,WAAW,CAAC;IAC9B,IAAI,IAAI,IAAI,CAAC;CACd,CAAC;AAEF;;;;;;;;;;;;GAYG;AACH,eAAO,MAAM,wBAAwB,GACnC,SAAS,MAAM,EACf,KAAK,GAAG,CAAC,YAAY,CAAC,EACtB,mBAAmB,iBAAiB,EACpC,QAAQ,qBAAqB,KAC5B,OAAO,CAAC,eAAe,CA83BzB,CAAC"}