@solana/mpp 0.1.0-beta.0 → 0.1.0

package/{sdk/src → src}/server/Charge.ts

@@ -27,7 +27,7 @@ import { coSignBase64Transaction } from '../utils/transactions.js';
  * const mppx = Mppx.create({
  *   methods: [solana.charge({
  *     recipient: 'RecipientPubkey...',
- *     splToken: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
+ *     spl: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
  *     decimals: 6,
  *     network: 'devnet',
  *   })],
@@ -43,18 +43,25 @@ import { coSignBase64Transaction } from '../utils/transactions.js';
 export function charge(parameters: charge.Parameters) {
     const {
         recipient,
-        splToken,
+        currency,
         decimals,
         tokenProgram = TOKEN_PROGRAM,
         network = 'mainnet-beta',
         store = Store.memory(),
+        splits,
         signer,
     } = parameters;
 
+    const isSplToken = currency !== undefined && currency !== 'sol';
+
     const rpcUrl = parameters.rpcUrl ?? DEFAULT_RPC_URLS[network] ?? DEFAULT_RPC_URLS['mainnet-beta'];
 
-    if (splToken && decimals === undefined) {
-        throw new Error('decimals is required when splToken is set');
+    if (isSplToken && decimals === undefined) {
+        throw new Error('decimals is required when currency is a token mint address');
+    }
+
+    if (splits && splits.length > 8) {
+        throw new Error('splits cannot exceed 8 entries');
     }
 
     if (signer && !isTransactionPartialSigner(signer)) {
@@ -65,10 +72,8 @@ export function charge(parameters: charge.Parameters) {
 
     return Method.toServer(Methods.charge, {
         defaults: {
-            currency: splToken ? 'token' : 'SOL',
-            methodDetails: {
-                reference: '',
-            },
+            currency: currency ?? 'sol',
+            methodDetails: {},
             recipient: '',
         },
 
@@ -77,8 +82,6 @@ export function charge(parameters: charge.Parameters) {
                 return credential.challenge.request as typeof request;
             }
 
-            const reference = crypto.randomUUID();
-
             // Pre-fetch a recent blockhash so the client can skip an RPC call.
             let recentBlockhash: string | undefined;
             try {
@@ -102,9 +105,9 @@ export function charge(parameters: charge.Parameters) {
                 ...request,
                 methodDetails: {
                     network,
-                    reference,
-                    ...(splToken ? { decimals, splToken, tokenProgram } : {}),
+                    ...(isSplToken ? { decimals, tokenProgram } : {}),
                     ...(signer ? { feePayer: true, feePayerKey: signer.address } : {}),
+                    ...(splits?.length ? { splits } : {}),
                     ...(recentBlockhash ? { recentBlockhash } : {}),
                 },
                 recipient,
@@ -243,61 +246,99 @@ async function verifyOnChain(rpcUrl: string, signature: string, challenge: Chall
 }
 
 async function verifyInstructions(instructions: ParsedInstruction[], challenge: ChallengeRequest, recipient: string) {
-    const expectedAmount = challenge.amount;
+    const splits = challenge.methodDetails.splits ?? [];
+    const splitsTotal = splits.reduce((sum, s) => sum + BigInt(s.amount), 0n);
+    const primaryAmount = BigInt(challenge.amount) - splitsTotal;
+
+    if (primaryAmount <= 0n) {
+        throw new Error('Splits consume the entire amount — primary recipient must receive a positive amount');
+    }
 
-    if (challenge.methodDetails.splToken) {
-        // ── SPL token transfer verification ──
-        const transfer = instructions.find(
+    const mint = challenge.currency !== 'sol' ? challenge.currency : undefined;
+
+    if (mint) {
+        // ── SPL token transfers verification ──
+        const transfers = instructions.filter(
             ix =>
                 ix.parsed?.type === 'transferChecked' &&
                 (ix.programId === TOKEN_PROGRAM || ix.programId === TOKEN_2022_PROGRAM),
         );
-        if (!transfer) {
-            throw new Error('No TransferChecked instruction found in transaction');
-        }
-
-        const info = transfer.parsed!.info as {
-            destination: string;
-            mint: string;
-            tokenAmount: { amount: string };
-        };
-        if (info.mint !== challenge.methodDetails.splToken) {
-            throw new Error(`Token mint mismatch: expected ${challenge.methodDetails.splToken}, got ${info.mint}`);
-        }
-        if (info.tokenAmount.amount !== expectedAmount) {
-            throw new Error(`Amount mismatch: expected ${expectedAmount}, got ${info.tokenAmount.amount}`);
-        }
 
-        // Verify destination ATA belongs to the expected recipient.
         const expectedTokenProgram = challenge.methodDetails.tokenProgram || TOKEN_PROGRAM;
-        const [expectedAta] = await findAssociatedTokenPda({
-            mint: address(challenge.methodDetails.splToken),
-            owner: address(recipient),
-            tokenProgram: address(expectedTokenProgram),
-        });
-        if (info.destination !== expectedAta) {
-            throw new Error('Destination token account does not belong to expected recipient');
+
+        // Verify primary transfer to recipient.
+        await verifySplTransfer(transfers, recipient, String(primaryAmount), mint, expectedTokenProgram);
+
+        // Verify each split transfer.
+        for (const split of splits) {
+            await verifySplTransfer(transfers, split.recipient, split.amount, mint, expectedTokenProgram);
         }
     } else {
-        // ── Native SOL transfer verification ──
-        const transfer = instructions.find(ix => ix.parsed?.type === 'transfer' && ix.program === 'system');
-        if (!transfer) {
-            throw new Error('No system transfer instruction found in transaction');
-        }
+        // ── Native SOL transfers verification ──
+        const transfers = instructions.filter(ix => ix.parsed?.type === 'transfer' && ix.program === 'system');
 
-        const info = transfer.parsed!.info as {
-            destination: string;
-            lamports: number;
-        };
-        if (info.destination !== recipient) {
-            throw new Error(`Recipient mismatch: expected ${recipient}, got ${info.destination}`);
-        }
-        if (String(info.lamports) !== expectedAmount) {
-            throw new Error(`Amount mismatch: expected ${expectedAmount} lamports, got ${info.lamports}`);
+        // Verify primary transfer to recipient.
+        verifySolTransfer(transfers, recipient, String(primaryAmount));
+
+        // Verify each split transfer.
+        for (const split of splits) {
+            verifySolTransfer(transfers, split.recipient, split.amount);
         }
     }
 }
 
+async function verifySplTransfer(
+    transfers: ParsedInstruction[],
+    recipientAddress: string,
+    expectedAmount: string,
+    spl: string,
+    tokenProgram: string,
+) {
+    const [expectedAta] = await findAssociatedTokenPda({
+        mint: address(spl),
+        owner: address(recipientAddress),
+        tokenProgram: address(tokenProgram),
+    });
+
+    const index = transfers.findIndex(ix => {
+        const info = ix.parsed!.info as { destination: string; mint: string; tokenAmount: { amount: string } };
+        return info.destination === expectedAta && info.mint === spl;
+    });
+
+    if (index === -1) {
+        throw new Error(`No TransferChecked instruction found for recipient ${recipientAddress}`);
+    }
+
+    const [transfer] = transfers.splice(index, 1);
+
+    const info = transfer.parsed!.info as { destination: string; mint: string; tokenAmount: { amount: string } };
+    if (info.tokenAmount.amount !== expectedAmount) {
+        throw new Error(
+            `Amount mismatch for ${recipientAddress}: expected ${expectedAmount}, got ${info.tokenAmount.amount}`,
+        );
+    }
+}
+
+function verifySolTransfer(transfers: ParsedInstruction[], recipientAddress: string, expectedAmount: string) {
+    const index = transfers.findIndex(ix => {
+        const info = ix.parsed!.info as { destination: string };
+        return info.destination === recipientAddress;
+    });
+
+    if (index === -1) {
+        throw new Error(`No system transfer instruction found for recipient ${recipientAddress}`);
+    }
+
+    const [transfer] = transfers.splice(index, 1);
+
+    const info = transfer.parsed!.info as { destination: string; lamports: number };
+    if (String(info.lamports) !== expectedAmount) {
+        throw new Error(
+            `Amount mismatch for ${recipientAddress}: expected ${expectedAmount} lamports, got ${info.lamports}`,
+        );
+    }
+}
+
 // ── Types ──
 
 /** Credential payload from the mppx framework. */
@@ -323,8 +364,7 @@ type ChallengeRequest = {
         feePayerKey?: string;
         network?: string;
         recentBlockhash?: string;
-        reference: string;
-        splToken?: string;
+        splits?: Array<{ amount: string; memo?: string; recipient: string }>;
         tokenProgram?: string;
     };
     recipient: string;
@@ -396,6 +436,9 @@ async function simulateTransaction(rpcUrl: string, base64Tx: string): Promise<vo
     if (data.error) throw new Error(`RPC error: ${data.error.message}`);
     const simErr = data.result?.value?.err;
     if (simErr) {
+        const logs = data.result?.value?.logs ?? [];
+        console.error('[solana-mpp] Simulation failed:', JSON.stringify(simErr));
+        for (const log of logs) console.error('[solana-mpp]', log);
         throw new Error(`Transaction simulation failed: ${JSON.stringify(simErr)}`);
     }
 }
@@ -454,7 +497,12 @@ async function waitForConfirmation(rpcUrl: string, signature: string, timeoutMs
 
 export declare namespace charge {
     type Parameters = {
-        /** Token decimals (required when splToken is set). */
+        /**
+         * Currency identifier. "SOL" for native SOL, or a base58-encoded
+         * SPL token mint address (e.g. USDC mint). Defaults to "SOL".
+         */
+        currency?: string;
+        /** Token decimals (required when currency is a mint address). */
         decimals?: number;
         /** Solana network. Defaults to 'mainnet-beta'. */
         network?: 'devnet' | 'localnet' | 'mainnet-beta' | (string & {});
@@ -471,14 +519,21 @@ export declare namespace charge {
          * Accepts any TransactionPartialSigner — KeyPairSigner, Keychain SolanaSigner, etc.
          */
         signer?: TransactionPartialSigner;
-        /** SPL token mint address. If absent, payments are in native SOL. */
-        splToken?: string;
+        /** Additional payment splits. Same asset as primary payment. Max 8 entries. */
+        splits?: Array<{
+            /** Amount in base units (same asset as primary). */
+            amount: string;
+            /** Optional memo (max 566 bytes). */
+            memo?: string;
+            /** Base58-encoded recipient of this split. */
+            recipient: string;
+        }>;
         /**
          * Pluggable key-value store for consumed-signature tracking (replay prevention).
          * Defaults to in-memory. Use a persistent store in production.
          */
         store?: Store.Store;
-        /** Token program address. Defaults to TOKEN_PROGRAM. Set to TOKEN_2022_PROGRAM for Token-2022 mints. */
+        /** Token program hint. If omitted, clients fetch the mint owner and fail closed on lookup errors. */
         tokenProgram?: string;
     };
 }

package/src/utils/transactions.ts

@@ -0,0 +1,46 @@
+import {
+    type Base64EncodedWireTransaction,
+    getBase64Codec,
+    getBase64EncodedWireTransaction,
+    getTransactionDecoder,
+    type TransactionPartialSigner,
+} from '@solana/kit';
+
+/**
+ * Decode a base64 wire transaction, co-sign it with a TransactionPartialSigner,
+ * and return the co-signed base64 wire transaction.
+ *
+ * Uses the signer's `signTransactions()` to obtain the signature, then merges
+ * it into the decoded transaction. This bridges decoded wire transactions with
+ * any signer interface (Keychain, Privy, Turnkey, AWS KMS, etc.).
+ */
+export async function coSignBase64Transaction(
+    signer: TransactionPartialSigner,
+    clientTxBase64: string,
+): Promise<Base64EncodedWireTransaction> {
+    const txBytes = getBase64Codec().encode(clientTxBase64);
+    const decoded = getTransactionDecoder().decode(txBytes);
+
+    // The signer must already be listed in the transaction's signatures map.
+    if (decoded.signatures[signer.address] === undefined) {
+        throw new Error(`Signer ${signer.address} is not an expected signer for this transaction`);
+    }
+
+    // Use the TransactionPartialSigner interface to sign.
+    // Cast needed: decoded wire transaction lacks Kit's branded nominal types
+    // but is structurally identical (messageBytes + signatures).
+    const [signatureMap] = await signer.signTransactions([decoded as Parameters<typeof signer.signTransactions>[0][0]]);
+    const signature = signatureMap[signer.address];
+    if (!signature) {
+        throw new Error(`Signer ${signer.address} did not return a signature`);
+    }
+
+    // Create a new transaction with the merged signature.
+    // Force-cast to preserve Kit's branded nominal types that getBase64EncodedWireTransaction requires.
+    const cosigned = {
+        ...decoded,
+        signatures: Object.freeze({ ...decoded.signatures, [signer.address]: signature }),
+    } as Parameters<typeof getBase64EncodedWireTransaction>[0];
+
+    return getBase64EncodedWireTransaction(cosigned);
+}

package/LICENSE

@@ -1,21 +0,0 @@
-MIT License
-
-Copyright (c) 2026 solana-mpp-sdk contributors
-
-Permission is hereby granted, free of charge, to any person obtaining a copy
-of this software and associated documentation files (the "Software"), to deal
-in the Software without restriction, including without limitation the rights
-to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
-copies of the Software, and to permit persons to whom the Software is
-furnished to do so, subject to the following conditions:
-
-The above copyright notice and this permission notice shall be included in all
-copies or substantial portions of the Software.
-
-THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
-IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
-FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
-AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
-LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
-OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
-SOFTWARE.

package/README.md

@@ -1,227 +0,0 @@
-<p align="center">
-  <img src="assets/banner.png" alt="MPP" width="100%" />
-</p>
-
-# @solana/mpp
-
-Solana payment method for the [Machine Payments Protocol](https://mpp.dev).
-
-**MPP** is [an open protocol proposal](https://paymentauth.org) that lets any HTTP API accept payments using the `402 Payment Required` flow.
-
-> [!IMPORTANT]
-> This repository is under active development. The [Solana MPP spec](https://github.com/tempoxyz/mpp-specs/pull/188) is not yet finalized — APIs and wire formats are subject to change.
-
-## Install
-
-```bash
-pnpm add @solana/mpp
-```
-
-Peer dependencies:
-
-```bash
-pnpm add @solana/kit mppx
-# Optional — for Swig session authorization:
-pnpm add @swig-wallet/kit
-```
-
-## Features
-
-**Charge** (one-time payments)
-- Native SOL and SPL token transfers (USDC, PYUSD, Token-2022, etc.)
-- Two settlement modes: pull (`type="transaction"`, default) and push (`type="signature"`)
-- Fee sponsorship: server pays transaction fees on behalf of clients
-- Replay protection via consumed transaction signatures
-
-**Session** (metered / streaming payments)
-- Voucher-based payment channels with monotonic cumulative amounts
-- Multiple authorization modes: `unbounded`, `regular_budget`, `swig_session`
-- Auto-open, auto-topup, and close lifecycle
-- [Swig](https://build.onswig.com) smart wallet integration for on-chain spend limits
-
-**General**
-- Works with [ConnectorKit](https://www.connectorkit.dev), `@solana/kit` keypair signers, and [Solana Keychain](https://github.com/solana-foundation/solana-keychain) remote signers
-- Server pre-fetches `recentBlockhash` to save client an RPC round-trip
-- Transaction simulation before broadcast to prevent wasted fees
-
-## Architecture
-
-```
-sdk/src/
-├── Methods.ts              # Shared charge + session schemas
-├── constants.ts            # Token programs, USDC mints, RPC URLs
-├── server/
-│   ├── Charge.ts           # Server: challenge, verify, broadcast
-│   └── Session.ts          # Server: session channel management
-├── client/
-│   ├── Charge.ts           # Client: build tx, sign, send
-│   └── Session.ts          # Client: session lifecycle
-└── session/
-    ├── Types.ts            # Session types and interfaces
-    ├── Voucher.ts          # Voucher signing and verification
-    ├── ChannelStore.ts     # Persistent channel state
-    └── authorizers/        # Pluggable authorization strategies
-        ├── UnboundedAuthorizer.ts
-        ├── BudgetAuthorizer.ts
-        └── SwigSessionAuthorizer.ts
-```
-
-**Exports:**
-- `@solana/mpp` — shared schemas, session types, and authorizers
-- `@solana/mpp/server` — server-side charge + session, `Mppx`, `Store`
-- `@solana/mpp/client` — client-side charge + session, `Mppx`
-
-## Quick Start
-
-### Charge (one-time payment)
-
-**Server:**
-
-```ts
-import { Mppx, solana } from '@solana/mpp/server'
-
-const mppx = Mppx.create({
-  secretKey: process.env.MPP_SECRET_KEY,
-  methods: [
-    solana.charge({
-      recipient: 'RecipientPubkey...',
-      splToken: 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v',
-      decimals: 6,
-    }),
-  ],
-})
-
-const result = await mppx.charge({
-  amount: '1000000', // 1 USDC
-  currency: 'USDC',
-})(request)
-
-if (result.status === 402) return result.challenge
-return result.withReceipt(Response.json({ data: '...' }))
-```
-
-**Client:**
-
-```ts
-import { Mppx, solana } from '@solana/mpp/client'
-
-const mppx = Mppx.create({
-  methods: [solana.charge({ signer })], // any TransactionSigner
-})
-
-const response = await mppx.fetch('https://api.example.com/paid-endpoint')
-```
-
-### Session (metered payments)
-
-**Server:**
-
-```ts
-import { Mppx, solana } from '@solana/mpp/server'
-
-const mppx = Mppx.create({
-  secretKey: process.env.MPP_SECRET_KEY,
-  methods: [
-    solana.session({
-      recipient: 'RecipientPubkey...',
-      asset: { kind: 'sol', decimals: 9 },
-      channelProgram: 'ChannelProgramId...',
-      pricing: { unit: 'request', amountPerUnit: '10', meter: 'api_calls' },
-      sessionDefaults: { suggestedDeposit: '1000', ttlSeconds: 60 },
-    }),
-  ],
-})
-```
-
-**Client:**
-
-```ts
-import { Mppx, solana } from '@solana/mpp/client'
-import { UnboundedAuthorizer } from '@solana/mpp'
-
-const mppx = Mppx.create({
-  methods: [
-    solana.session({
-      signer,
-      authorizer: new UnboundedAuthorizer({ signer, buildOpenTx, buildTopupTx }),
-    }),
-  ],
-})
-
-const response = await mppx.fetch('https://api.example.com/metered-endpoint')
-```
-
-### Fee Sponsorship (charge)
-
-The server can pay transaction fees on behalf of clients:
-
-```ts
-// Server — pass a TransactionPartialSigner to cover fees
-solana.charge({
-  recipient: '...',
-  signer: feePayerSigner, // KeyPairSigner, Keychain SolanaSigner, etc.
-})
-
-// Client — no changes needed, fee payer is handled automatically
-```
-
-## How It Works
-
-### Charge Flow
-
-1. Client requests a resource
-2. Server returns **402 Payment Required** with a challenge (`recipient`, `amount`, `currency`, `recentBlockhash`)
-3. Client builds and signs a Solana transfer transaction
-4. Server simulates, broadcasts, confirms on-chain, and verifies the transfer
-5. Server returns the resource with a `Payment-Receipt` header
-
-With fee sponsorship, the client partially signs (transfer authority only) and the server co-signs as fee payer before broadcasting.
-
-### Session Flow
-
-1. First request: server returns 402, client opens a channel (deposit + voucher)
-2. Subsequent requests: client sends updated vouchers with monotonic cumulative amounts
-3. Server deducts from the channel balance per its pricing config
-4. When balance runs low: client tops up the channel
-5. On close: final voucher settles the channel
-
-## Demo
-
-An interactive playground with a React frontend and Express backend, running against [Surfpool](https://surfpool.run).
-
-- Charge flow demo: `http://localhost:5173/charges`
-- Session flow demo: `http://localhost:5173/sessions`
-
-```bash
-surfpool start
-pnpm demo:install
-pnpm demo:server
-pnpm demo:app
-```
-
-See [demo/README.md](demo/README.md) for full details.
-
-## Development
-
-```bash
-pnpm install
-
-just fmt              # Format and lint
-just build            # Typecheck
-just test             # Unit tests (charge + session, no network)
-just test-integration # Integration tests (requires Surfpool)
-just test-all         # All tests
-just pre-commit       # fmt + typecheck + unit tests
-```
-
-## Spec
-
-This SDK implements the [Solana Charge Intent](https://github.com/tempoxyz/mpp-specs/pull/188) for the [HTTP Payment Authentication Scheme](https://paymentauth.org).
-
-Session method docs and implementation notes:
-
-- [docs/methods/sessions.md](docs/methods/sessions.md)
-
-## License
-
-MIT

package/sdk/src/utils/transactions.ts

@@ -1,26 +0,0 @@
-import {
-    type Base64EncodedWireTransaction,
-    getBase64Codec,
-    getBase64EncodedWireTransaction,
-    getTransactionDecoder,
-    partiallySignTransactionWithSigners,
-    type TransactionPartialSigner,
-} from '@solana/kit';
-
-/**
- * Decode a base64 wire transaction, co-sign it with a TransactionPartialSigner,
- * and return the co-signed base64 wire transaction.
- *
- * Uses Kit's `partiallySignTransactionWithSigners` to handle signature merging
- * and validation. This bridges decoded wire transactions with the signer
- * interface (Keychain, Privy, Turnkey, AWS KMS, etc.).
- */
-export async function coSignBase64Transaction(
-    signer: TransactionPartialSigner,
-    clientTxBase64: string,
-): Promise<Base64EncodedWireTransaction> {
-    const txBytes = getBase64Codec().encode(clientTxBase64);
-    const tx = getTransactionDecoder().decode(txBytes);
-    const cosigned = await partiallySignTransactionWithSigners([signer], tx);
-    return getBase64EncodedWireTransaction(cosigned);
-}