feat: mpp-channel Anchor program and session method (PR #201 spec)

[alexanderattar]

Summary

• Implements the mpp-channel Anchor escrow program for on-chain payment channel settlement
• Aligns the TypeScript session method with PR #201 of the mpp-specs
• Adds localnet integration tests and devnet verification with real transactions

Anchor program

PaymentChannel account binds payer, payee, token mint, authorized signer, deposit, settled amount, grace period, forced-close timestamp, finalization status, and salt.

PDA seeds: ["mpp-channel", payer, payee, token, salt_le, authorized_signer]

Instructions:

Instruction	Description
open	Creates channel PDA, transfers SPL tokens into vault ATA
settle	Verifies Ed25519 voucher on-chain, transfers delta to payee
close	Like settle, but also refunds remaining deposit and finalizes
top_up	Increases vault deposit, cancels any pending forced close
request_close	Payer initiates forced close, records timestamp
withdraw	Payer recovers deposit after grace period expires

The Ed25519 precompile is not CPI-callable. The program validates signatures by reading the instructions sysvar at the index passed in settle/close args, then parsing the raw JCS JSON bytes to extract channelId and cumulativeAmount. This is the same byte sequence signed for the HTTP credential, so no format translation is needed.

Program ID: 21fLdahqKtVAt4V2JLwVrRb7tuqPADjjPVCU9bK3MFPQ

Session method changes

Aligned to PR #201:

• Voucher schema: three fields only (channelId, cumulativeAmount, expiresAt)
• Signing: raw JCS bytes, no domain separator
• Credential actions: update → voucher, topup → topUp
• Open and topUp carry a partially-signed transaction (pull mode)
• Close voucher is optional — supports refund-only cooperative close
• Channel state uses acceptedCumulative/spentAmount
• Idempotent vouchers: cumulativeAmount <= acceptedCumulative succeeds silently with no state change
• Server rejects vouchers when a forced close is pending

New files:

• src/anchor/MppChannelClient.ts — instruction builders and PDA derivation
• src/anchor/TransactionHandler.ts — server-side on-chain transaction verification
• src/utils/ed25519.ts — Ed25519 instruction serialization (layout: 2-byte header + 14-byte descriptor, DATA_START=16)
• src/session/BinaryVoucher.ts — compact 48-byte voucher representation

Tests

• anchor-channel.test.ts: 5 localnet integration tests (open, settle with Ed25519, full lifecycle, requestClose/withdraw, topUp + forced-close cancellation). Starts solana-test-validator with the compiled .so.
• binary-voucher.test.ts: round-trip tests for the JCS parser and compact voucher format
• session.test.ts: 62 unit tests for server/client session logic
• vitest.config.anchor.ts: separate config for anchor tests (120s timeout, single worker)

Run anchor tests: anchor test (requires Anchor CLI and Rust toolchain)
Run unit tests: pnpm exec vitest run --config vitest.config.ts

Devnet verification

All instructions exercised against the deployed program with real transactions.

Setup

• Fund payee
• Create mint
• Create ATAs
• Mint 10M tokens

Channel lifecycle (open → settle → settle → close)

• Open channel, deposit 1M tokens
• Settle 300k (Ed25519 voucher verified on-chain)
• Settle 600k
• Close 800k (payee gets final delta, payer refunded 200k)

Forced close (requestClose → grace period → withdraw)

• Open channel, deposit 500k, 5s grace period
• Request close
• Withdraw after grace period (full 500k recovered)

Balances verified: payee received exactly 800,000 tokens, payer holds 9,200,000 (started 10M, deposited 1M, refunded 200k). Forced close recovered the full 500,000 deposit.

[alexanderattar]

Hey @lgalabru, I noticed you've done a lot of work on this repo since I opened the PR and that sessions are going through Swig now instead of a standalone Anchor program. Would an Anchor version still be useful as an alternative, or should I just close this out? Happy to rebase and fix the conflicts if it would, otherwise no worries.

[lgalabru]

hey @alexanderattar, thanks for opening this PR!
We're still actively researching and tweaking the session spec. I conducted some experiments in this repo, if you have some additional thoughts that's probably the right place.
We should have another repo we can share soon.

Note: the final program won't be hosted in this repo, it'll be a dedicated repo hosted on solana-program - supporting MPP and some other protocols we have in our radar.