[Advanced] MPP session-budget client + runnable example (ed25519 vouchers, one on-chain close)

[Eras256]

Difficulty: Advanced (senior · 7–8/10). ~16–24h. Requires Stellar/Soroban, ed25519, and a working grasp of the MPP Channel/Session protocol.

Context

Nirium implements MPP (Machine Payment Protocol). Unlike x402 (one payment per request), an MPP session lets an agent open a budget once, issue many off-chain signed commitments, and settle everything with a single on-chain transaction — ideal for high-frequency agent loops. The public toolkit has no clean MPP session client or runnable example yet.

Goal

A reusable MPP session helper plus a runnable example under examples/mpp-session/ that opens a channel with a capped budget, issues cumulative ed25519-signed vouchers per request, and closes once on-chain.

Scope / Deliverables

1. Client helper: open/fund the channel (or use a configured one), sign cumulative commitments with an ed25519 key, and track the highest voucher.
2. Server side of the example: return a 402 challenge (channel id, amount, cumulative total); verify each voucher by simulation (no on-chain call per request); track the highest seen.
3. Close flow: a single on-chain close() with the highest cumulative amount + signature; remaining funds return to the funder.
4. Example loop: make N paid calls within budget; refuse once the cap is hit and say so.
5. Tests: voucher signing/verification + budget-cap enforcement (payment layer mocked).
6. README: the three phases (setup → vouchers → close) + a short diagram.

Acceptance criteria

• Runs end-to-end on testnet: one channel, ≥3 cumulative vouchers, one close tx that resolves on stellar.expert (include the hash in the PR).
• Budget cap provably enforced (test + a short demo of the "budget reached" path).
• No secrets committed; keys via env only; public API typed.

Pointers

• @stellar/mpp (channel/server, channel/client), mppx — align versions with the nirium SDK.
• StrKey.encodeEd25519PublicKey(), Keypair.fromRawEd25519Seed().

Reward

Eligibility is subject to GrantFox review after the campaign (Official Campaign | FWC26). Rewards are decided by GrantFox based on quality and available budget and are not guaranteed.

[Phantomcall]

I'd like to take this on. I have experience building Rust and TypeScript applications on the Stellar ecosystem, including Soroban smart contracts, wallet integrations, ed25519 signing flows, and payment infrastructure. I've worked on multi-component blockchain systems where protocol correctness, deterministic state transitions, and clean SDK abstractions are critical.

For this issue, I'll implement a reusable MPP session helper that cleanly abstracts channel lifecycle management, cumulative voucher generation, and session tracking while keeping the public API strongly typed and suitable for reuse outside the example application. The helper will support opening or attaching to an existing channel, signing cumulative commitments with ed25519 keys loaded from environment configuration, and maintaining the highest valid voucher throughout the session.

I'll also build the complete examples/mpp-session/ reference implementation. The server will issue proper 402 payment challenges, verify cumulative vouchers off-chain through simulation, maintain the highest accepted commitment, enforce the configured spending cap, and reject requests once the session budget is exhausted. The client will demonstrate a realistic agent loop making multiple paid requests within a single channel before performing one final on-chain settlement that returns any remaining balance to the funder.

To ensure reliability, I'll add comprehensive tests covering voucher signing and verification, cumulative amount validation, replay protection, highest-voucher tracking, budget-cap enforcement, and mocked payment-layer behavior. I'll also document the complete session lifecycle—from setup, voucher exchange, and off-chain verification to final settlement—with architecture diagrams and clear setup instructions.

Before submitting the PR, I'll verify the full flow on Stellar Testnet, include the resulting close transaction hash, run the complete test suite, and ensure the implementation follows the repository's conventions without exposing any secrets or private keys.

GitHub: @PHANTOM_CALL