@faremeter/payment-solana 0.19.0 → 0.20.0

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 { createMemoInstruction, generateMemoNonce } from "./memo.js";
 import { logger } from "./logger.js";
 function generateGetAssociatedTokenAddressSyncRest(tokenConfig) {
     const { allowOwnerOffCurve, programId, associatedTokenProgramId } = tokenConfig;
@@ -56,6 +57,7 @@ async function extractMetadata(args) {
     const tokenProgramId = extra.tokenProgram
         ? new PublicKey(extra.tokenProgram)
         : (options?.token?.programId ?? TOKEN_PROGRAM_ID);
+    const memo = extra.memo;
     return {
         recentBlockhash,
         decimals,
@@ -64,6 +66,7 @@ async function extractMetadata(args) {
         payerKey,
         paymentMode,
         tokenProgramId,
+        memo,
     };
 }
 /**
@@ -99,7 +102,7 @@ export function createPaymentHandler(wallet, mint, connection, options) {
         const compatibleRequirements = accepts.filter(isMatchingRequirement);
         const res = compatibleRequirements.map((requirements) => {
             const exec = async () => {
-                const { recentBlockhash, decimals, payTo, amount, payerKey, paymentMode, tokenProgramId, } = await extractMetadata({
+                const { recentBlockhash, decimals, payTo, amount, payerKey, paymentMode, tokenProgramId, memo, } = await extractMetadata({
                     connection,
                     mint,
                     requirements,
@@ -122,7 +125,7 @@ export function createPaymentHandler(wallet, mint, connection, options) {
                 switch (paymentMode) {
                     case PaymentMode.ToSpec: {
                         const receiverAccount = getAssociatedTokenAddressSync(mint, payTo, ...getAssociatedTokenAddressSyncRest);
-                        instructions.push(createTransferCheckedInstruction(sourceAccount, mint, receiverAccount, wallet.publicKey, amount, decimals, undefined, tokenProgramId));
+                        instructions.push(createTransferCheckedInstruction(sourceAccount, mint, receiverAccount, wallet.publicKey, amount, decimals, undefined, tokenProgramId), createMemoInstruction(memo ?? generateMemoNonce()));
                         let tx;
                         if (wallet.buildTransaction) {
                             tx = await wallet.buildTransaction(instructions, recentBlockhash);

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

@@ -32,6 +32,7 @@ export declare const PaymentRequirementsExtra: import("arktype/internal/methods/
     feePayer: string;
     decimals?: number;
     recentBlockhash?: string;
+    memo?: string;
     tokenProgram?: string;
     features?: {
         xSettlementAccountSupported?: boolean;

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

@@ -1 +1 @@
-{"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,EACL,SAAS,EAIV,MAAM,uBAAuB,CAAC;AAC/B,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;AAKlC,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;;;;;;;;MAMnC,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,CAmc5B,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,EACL,SAAS,EAIV,MAAM,uBAAuB,CAAC;AAC/B,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;AAKlC,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;;;;;;;;;MAOnC,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,CA0c5B,CAAC"}

package/dist/src/exact/facilitator.js

@@ -18,6 +18,7 @@ export const PaymentRequirementsExtra = type({
     feePayer: "string",
     decimals: "number?",
     recentBlockhash: "string?",
+    "memo?": "string",
     "tokenProgram?": "string",
     features: PaymentRequirementsExtraFeatures.optional(),
 });
@@ -276,6 +277,10 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
         const recentBlockhash = (await rpc.getLatestBlockhash().send()).value
             .blockhash;
         return req.filter(isMatchingRequirement).map((x) => {
+            const incomingExtra = PaymentRequirementsExtra(x.extra);
+            const memo = !isValidationError(incomingExtra) && incomingExtra.memo !== undefined
+                ? { memo: incomingExtra.memo }
+                : {};
             return {
                 ...x,
                 asset: mint.toBase58(),
@@ -283,6 +288,7 @@ export const createFacilitatorHandler = async (network, rpc, feePayerKeypair, mi
                     feePayer: feePayerKeypair.publicKey.toString(),
                     decimals: mintInfo.data.decimals,
                     recentBlockhash,
+                    ...memo,
                     tokenProgram,
                     features,
                 },

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

@@ -1,3 +1,3 @@
-export { createPaymentHandler } from "./client.js";
+export { createPaymentHandler, type Wallet } from "./client.js";
 export { createFacilitatorHandler } from "./facilitator.js";
 //# sourceMappingURL=index.d.ts.map

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

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/exact/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,MAAM,UAAU,CAAC;AAChD,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../../src/exact/index.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,oBAAoB,EAAE,KAAK,MAAM,EAAE,MAAM,UAAU,CAAC;AAC7D,OAAO,EAAE,wBAAwB,EAAE,MAAM,eAAe,CAAC"}

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

@@ -0,0 +1,4 @@
+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

@@ -0,0 +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"}

package/dist/src/exact/memo.js

@@ -0,0 +1,16 @@
+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);
+    return Array.from(bytes)
+        .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,5 +1,6 @@
 import type { x402PaymentRequirements } from "@faremeter/types/x402v2";
-import { type Address, type CompilableTransactionMessage } from "@solana/kit";
+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<{
     payer: string;
 } | false>;

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,EAEL,KAAK,OAAO,EACZ,KAAK,4BAA4B,EAElC,MAAM,aAAa,CAAC;AAwGrB,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,CAmEpC"}
+{"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"}

package/dist/src/exact/verify.js

@@ -1,13 +1,26 @@
 import { isValidationError } from "@faremeter/types";
 import { parseSetComputeUnitLimitInstruction, parseSetComputeUnitPriceInstruction, } from "@solana-program/compute-budget";
 import { findAssociatedTokenPda, parseTransferCheckedInstruction, } from "@solana-program/token";
-import { address, } from "@solana/kit";
+import { address } from "@solana/kit";
+import { MEMO_PROGRAM_ADDRESS } from "@solana-program/memo";
 import { PaymentRequirementsExtra } from "./facilitator.js";
 import { logger } from "./logger.js";
 const LIGHTHOUSE_PROGRAM_ADDRESS = address("L2TExMFKdjpN9kozasaurPirfHy9P8sbXoAN1qA3S95");
 function isLighthouseInstruction(instruction) {
     return instruction.programAddress === LIGHTHOUSE_PROGRAM_ADDRESS;
 }
+function isMemoInstruction(instruction) {
+    return instruction.programAddress === MEMO_PROGRAM_ADDRESS;
+}
+function isAllowedTrailingInstruction(instruction) {
+    return isLighthouseInstruction(instruction) || isMemoInstruction(instruction);
+}
+function getMemoData(instruction) {
+    if (!isMemoInstruction(instruction) || !instruction.data) {
+        return undefined;
+    }
+    return new TextDecoder().decode(new Uint8Array(instruction.data));
+}
 function verifyComputeUnitLimitInstruction(instruction) {
     if (!instruction.data) {
         return { valid: false };
@@ -38,6 +51,10 @@ function verifyComputeUnitPriceInstruction(instruction) {
         return { valid: false };
     }
 }
+// The upstream spec caps the per-CU price (<=5 lamports/CU), but that still
+// allows an attacker to inflate the CU limit to the Solana maximum and drain
+// the facilitator's SOL.  A total-fee cap closes that vector because the
+// facilitator is the one paying the priority fee.
 function calculatePriorityFee(units, microLamports) {
     return (units * Number(microLamports)) / 1_000_000;
 }
@@ -90,7 +107,7 @@ export async function isValidTransaction(transactionMessage, paymentRequirements
         tokenProgram,
     });
     const instructions = transactionMessage.instructions;
-    if (instructions.length < 3 || instructions.length > 5) {
+    if (instructions.length < 3 || instructions.length > 6) {
         return false;
     }
     const [ix0, ix1, ix2, ...rest] = instructions;
@@ -111,10 +128,37 @@ export async function isValidTransaction(transactionMessage, paymentRequirements
             return false;
         }
     }
-    if (!rest.every(isLighthouseInstruction)) {
-        logger.error("Dropping transaction with non-Lighthouse trailing instructions");
+    if (!rest.every(isAllowedTrailingInstruction)) {
+        logger.error("Dropping transaction with unexpected trailing instructions");
         return false;
     }
+    const facilitator = address(facilitatorAddress);
+    for (const ix of instructions) {
+        if (!ix.accounts)
+            continue;
+        for (const account of ix.accounts) {
+            if (account.address === facilitator) {
+                logger.error("Dropping transaction where the facilitator appears in instruction accounts");
+                return false;
+            }
+        }
+    }
+    const memoInstructions = rest.filter(isMemoInstruction);
+    if (memoInstructions.length !== 1) {
+        logger.error("Expected exactly one Memo instruction");
+        return false;
+    }
+    if (extra.memo !== undefined) {
+        const memoIx = memoInstructions[0];
+        if (!memoIx) {
+            return false;
+        }
+        const memoData = getMemoData(memoIx);
+        if (memoData !== extra.memo) {
+            logger.error("Memo instruction data does not match extra.memo");
+            return false;
+        }
+    }
     const payer = await verifyTransferInstruction(ix2, paymentRequirements, destination, facilitatorAddress, tokenProgram);
     if (!payer)
         return false;

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

@@ -3,6 +3,7 @@ import t from "tap";
 import { isValidTransaction } from "./verify.js";
 import { getSetComputeUnitLimitInstruction, getSetComputeUnitPriceInstruction, } from "@solana-program/compute-budget";
 import { findAssociatedTokenPda, getTransferCheckedInstruction, TOKEN_PROGRAM_ADDRESS, } from "@solana-program/token";
+import { MEMO_PROGRAM_ADDRESS } from "@solana-program/memo";
 import { TOKEN_2022_PROGRAM_ADDRESS } from "../splToken.js";
 import { address, appendTransactionMessageInstructions, createTransactionMessage, generateKeyPairSigner, pipe, setTransactionMessageFeePayer, setTransactionMessageLifetimeUsingBlockhash, } from "@solana/kit";
 function createRequirements(overrides) {
@@ -85,24 +86,36 @@ function makeLighthouseIx(data) {
         data: new Uint8Array(data ?? [0]),
     };
 }
+function makeMemoIx(memo) {
+    return {
+        programAddress: MEMO_PROGRAM_ADDRESS,
+        data: new TextEncoder().encode(memo),
+    };
+}
 await t.test("isValidTransaction", async (t) => {
-    await t.test("accepts valid 3-instruction transaction", async (t) => {
+    await t.test("accepts valid 4-instruction transaction", async (t) => {
         const f = await createFixtures();
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        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);
         t.ok(result);
         t.equal(result && result.payer, f.sender.address);
         t.end();
     });
-    await t.test("accepts valid 4-instruction transaction with one lighthouse ix", async (t) => {
+    await t.test("accepts valid 5-instruction transaction with one lighthouse ix", async (t) => {
         const f = await createFixtures();
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, makeLighthouseIx()], f.facilitator);
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeLighthouseIx(),
+            makeMemoIx("nonce"),
+        ], f.facilitator);
         const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram);
         t.ok(result);
         t.equal(result && result.payer, f.sender.address);
         t.end();
     });
-    await t.test("accepts valid 5-instruction transaction with two lighthouse ixs", async (t) => {
+    await t.test("accepts valid 6-instruction transaction with two lighthouse ixs", async (t) => {
         const f = await createFixtures();
         const txMsg = buildTxMessage([
             f.computeLimitIx,
@@ -110,6 +123,7 @@ await t.test("isValidTransaction", async (t) => {
             f.transferIx,
             makeLighthouseIx([1]),
             makeLighthouseIx([2]),
+            makeMemoIx("nonce"),
         ], f.facilitator);
         const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram);
         t.ok(result);
@@ -122,13 +136,19 @@ await t.test("isValidTransaction", async (t) => {
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
-    await t.test("rejects transaction with more than 5 instructions", async (t) => {
+    await t.test("rejects transaction with more than 6 instructions", async (t) => {
         const f = await createFixtures();
-        const extras = Array.from({ length: 3 }, (_, i) => makeLighthouseIx([i]));
+        const extras = Array.from({ length: 4 }, (_, i) => makeLighthouseIx([i]));
         const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, ...extras], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
+    await t.test("rejects transaction without memo instruction", async (t) => {
+        const f = await createFixtures();
+        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.end();
+    });
     await t.test("rejects transaction with wrong fee payer", async (t) => {
         const f = await createFixtures();
         const wrongPayer = await generateKeyPairSigner();
@@ -154,7 +174,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], f.facilitator);
+        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);
         t.ok(result);
         t.equal(result && result.payer, f.sender.address);
@@ -168,7 +188,7 @@ await t.test("isValidTransaction", async (t) => {
         const highPriceIx = getSetComputeUnitPriceInstruction({
             microLamports: 10000000n,
         });
-        const txMsg = buildTxMessage([highLimitIx, highPriceIx, f.transferIx], f.facilitator);
+        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.end();
     });
@@ -180,7 +200,13 @@ await t.test("isValidTransaction", async (t) => {
         const highPriceIx = getSetComputeUnitPriceInstruction({
             microLamports: 10000000n,
         });
-        const txMsg = buildTxMessage([highLimitIx, highPriceIx, f.transferIx, makeLighthouseIx()], f.facilitator);
+        const txMsg = buildTxMessage([
+            highLimitIx,
+            highPriceIx,
+            f.transferIx,
+            makeLighthouseIx(),
+            makeMemoIx("nonce"),
+        ], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram, 100), false);
         t.end();
     });
@@ -222,7 +248,7 @@ await t.test("isValidTransaction", async (t) => {
             amount: f.amount + 1n,
             decimals: f.decimals,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongAmountIx], f.facilitator);
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongAmountIx, makeMemoIx("nonce")], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
@@ -247,7 +273,7 @@ await t.test("isValidTransaction", async (t) => {
             amount: f.amount,
             decimals: f.decimals,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongMintIx], f.facilitator);
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongMintIx, makeMemoIx("nonce")], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
@@ -267,7 +293,7 @@ await t.test("isValidTransaction", async (t) => {
             amount: f.amount,
             decimals: f.decimals,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongDestIx], f.facilitator);
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, wrongDestIx, makeMemoIx("nonce")], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
@@ -281,7 +307,7 @@ await t.test("isValidTransaction", async (t) => {
             amount: f.amount,
             decimals: f.decimals,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx], f.facilitator);
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx, makeMemoIx("nonce")], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
@@ -295,7 +321,7 @@ await t.test("isValidTransaction", async (t) => {
             amount: f.amount,
             decimals: f.decimals,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx], f.facilitator);
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, badIx, makeMemoIx("nonce")], f.facilitator);
         t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
         t.end();
     });
@@ -303,11 +329,124 @@ await t.test("isValidTransaction", async (t) => {
         const f = await createFixtures({
             tokenProgram: TOKEN_2022_PROGRAM_ADDRESS,
         });
-        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        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);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts transaction with memo instruction", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("some-random-nonce"),
+        ], f.facilitator);
+        const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("accepts transaction with lighthouse and memo instructions", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeLighthouseIx(),
+            makeMemoIx("nonce-123"),
+        ], f.facilitator);
         const result = await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram);
         t.ok(result);
         t.equal(result && result.payer, f.sender.address);
         t.end();
     });
+    await t.test("validates memo matches extra.memo when set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "invoice-456" },
+        };
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("invoice-456"),
+        ], f.facilitator);
+        const result = await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram);
+        t.ok(result);
+        t.equal(result && result.payer, f.sender.address);
+        t.end();
+    });
+    await t.test("rejects memo mismatch when extra.memo is set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "invoice-456" },
+        };
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("wrong-memo"),
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram), false);
+        t.end();
+    });
+    await t.test("rejects transaction where facilitator appears in trailing instruction accounts", async (t) => {
+        const f = await createFixtures();
+        const badMemoIx = {
+            programAddress: MEMO_PROGRAM_ADDRESS,
+            data: new TextEncoder().encode("nonce"),
+            accounts: [
+                {
+                    address: f.facilitator.address,
+                    role: 0,
+                },
+            ],
+        };
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx, badMemoIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
+        t.end();
+    });
+    await t.test("rejects transaction with multiple memo instructions", async (t) => {
+        const f = await createFixtures();
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("nonce-1"),
+            makeMemoIx("nonce-2"),
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, f.requirements, f.facilitator.address, f.tokenProgram), false);
+        t.end();
+    });
+    await t.test("rejects missing memo when extra.memo is set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "invoice-456" },
+        };
+        const txMsg = buildTxMessage([f.computeLimitIx, f.computePriceIx, f.transferIx], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram), false);
+        t.end();
+    });
+    await t.test("rejects multiple memo instructions when extra.memo is set", async (t) => {
+        const f = await createFixtures();
+        const requirements = {
+            ...f.requirements,
+            extra: { ...f.requirements.extra, memo: "invoice-456" },
+        };
+        const txMsg = buildTxMessage([
+            f.computeLimitIx,
+            f.computePriceIx,
+            f.transferIx,
+            makeMemoIx("invoice-456"),
+            makeMemoIx("invoice-456"),
+        ], f.facilitator);
+        t.equal(await isValidTransaction(txMsg, requirements, f.facilitator.address, f.tokenProgram), false);
+        t.end();
+    });
     t.end();
 });

package/dist/src/index.d.ts

@@ -10,6 +10,12 @@
  * @description SPL token transfer payment handlers for Solana
  */
 export * as exact from "./exact/index.js";
+/**
+ * @title Solana Charge Payment Scheme
+ * @sidebarTitle Payment Solana / Charge
+ * @description MPP charge-based payment handlers for Solana
+ */
+export * as charge from "./charge/index.js";
 /**
  * @title SPL Token Utilities
  * @sidebarTitle Payment Solana / SPL Token

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

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

package/dist/src/index.js

@@ -10,6 +10,12 @@
  * @description SPL token transfer payment handlers for Solana
  */
 export * as exact from "./exact/index.js";
+/**
+ * @title Solana Charge Payment Scheme
+ * @sidebarTitle Payment Solana / Charge
+ * @description MPP charge-based payment handlers for Solana
+ */
+export * as charge from "./charge/index.js";
 /**
  * @title SPL Token Utilities
  * @sidebarTitle Payment Solana / SPL Token