Skip to main content
Glama
SAP MultiHopper Mandate Vault MCP Server

SAP MultiHopper Mandate Vault MCP Server

by LBCron
README.md
# SAP MultiHopper Mandate Vault (`@lbcron/sap-multihopper-vault`)

Non-custodial **Rust Solana Mandate Vault**, **TypeScript SDK**, **JSON-RPC 2.0 MCP Server**, and **Interactive Web Console** purpose-built for **Steve Capital (`OOBE Protocol SAP v2`)** and **MultiHopper Programmable Asset Routing** on Solana Mainnet.

- **Live Interactive Console**: `https://lbcron.github.io/sap-multihopper-vault/`
- **Integrator & Rewards Wallet (Solana Mainnet)**: `32647Bri8KhJQE11x26iF7fpae9nouCJSZ8Y2VPpq5yM`
- **Author**: Ronan Chen Lopes (`@LBCron`)

---

## Architecture Overview

```mermaid
flowchart LR
  Owner["Human Owner Wallet"] -->|Initialize 234B Borsh State| Vault["Rust SAP Mandate Vault (crates/sap-mandate-program)"]
  Steve["Steve Capital MCP Workspace"] -->|JSON-RPC 2.0 stdio| MCP["MCP Server (src/mcpServer.ts)"]
  MCP -->|Evaluate >=20 USDC Gate, 24h Cap & Anti-Wash| Vault
  MCP -->|Partial-Sign v0 Preserving Server Ephemeral Sig| Router["MultiHopper Core (3jLoS2wb...spFh)"]
  Router -->|Atomic 0.25% Integrator RevShare| Treasury["32647Bri8KhJQE11x26iF7fpae9nouCJSZ8Y2VPpq5yM"]
```

### Core Capabilities

1. **Deterministic Rust On-Chain Mandate Engine (`crates/sap-mandate-program/`)**
   - Implements `MandateVaultState` (`234` bytes deterministic Borsh layout with 8-byte FIPS 180-4 SHA-256 Anchor discriminators) and `SubAgentDelegateState`.
   - Enforces the **Steve Capital `>= 20.00 USDC` (`20,000,000` micro-USDC) Arena readiness invariant**, per-route principal caps, rolling `86,400s` (`24h`) ceilings, monotonic clock progression, owner-only emergency pause, and specialist sub-agent protocol/expiry scopes.
   - Blocks self-transfers, circular intermediate hops, duplicate dispersion wallets, and `> 20` Multi-Send bundles (`MH_041`) while counting routed principal **strictly once** per route.

2. **Byte-Exact TypeScript SDK & Crash-Safe v0 Signer (`src/`)**
   - Derives deterministic PDAs across **OOBE SAP v2** (`SAPpUhsWLJG1FfkGRcXagEDMrMsWGjbky7AyhGpFETZ`), **MultiHopper Core** (`3jLoS2wbNgtKzieUUxwg6Xhdv6gbZkHDtPWA9ZAgspFh`), **MultiHopper Orchestrator** (`4TPCmR2uN3hDM1FbTsf7ZtFXwXGSz4u1Kxv5YHj6eruX`), and **Token-2022 Transfer Hook Guard** (`2JEv3pD6nczEvn1xDXaEzehkJofPPjoQQpnW5nGY3r52`).
   - Computes exact `BigInt` MultiHopper `0.50%` (`50 bps`) fees and `0.25%` (`25 bps`) atomic integrator revenue shares (`993,905,472` lamports -> `4,969,527` total fee / `2,484,763` integrator share) with zero lost dust across `<= 20` weighted Multi-Send recipients.
   - Preserves server-side ephemeral partial signatures on `VersionedTransaction (v0)` (`signPreservingPartialV0`) and verifies `x-multihopper-signature` webhooks via constant-time `HMAC-SHA256`.

3. **Drop-In Steve Capital MCP Server (`src/mcpServer.ts`)**
   - Exposes `sap_derive_hierarchy`, `mandate_evaluate_and_encode`, `multihopper_quote_fee_split`, `multihopper_verify_webhook`, and `solana_verify_mainnet_programs` over JSON-RPC 2.0 (`protocolVersion: "2025-06-18"`).

---

## Quickstart & Verification

```bash
# Install dependencies
npm install

# Run full Rust crate tests + TypeScript strict check + Vitest suite (including live Solana Mainnet RPC check)
npm test

# Verify live Solana Mainnet-Beta program deployment directly
npm run verify:mainnet

# Start JSON-RPC 2.0 MCP server for Steve Capital MCP Workspace
npm run mcp
```

## License

MIT — Copyright (c) 2026 Ronan Chen Lopes (`@LBCron`).

TDQS

B3/5.0

Scored across 5 tools

Disambiguation4/5

Each tool targets a clearly different operation: PDA derivation, mandate policy evaluation plus instruction encoding, fee-split BigInt math, HMAC webhook verification, and on-chain program status checks. The only mild overlap is between sap_derive_hierarchy and solana_verify_mainnet_programs, which both touch on-chain program/PDA state, but their purposes remain distinct.

Naming Consistency4/5

All names are snake_case and follow a subsystem-prefix + verb_noun pattern (sap_derive_hierarchy, mandate_evaluate_and_encode, multihopper_quote_fee_split, multihopper_verify_webhook, solana_verify_mainnet_programs). The prefixes vary by subsystem (sap_/mandate_/multihopper_/solana_), which is readable but slightly less uniform than a single global verb_noun convention.

Tool Count5/5

Five tools is well-scoped for a narrow, specialized mandate-vault/fee-quoting workflow. Each tool covers a distinct piece of the pipeline (derive, evaluate/encode, quote, verify webhook, verify programs) with no filler.

Completeness3/5

The surface covers derivation, policy evaluation/encoding, fee quoting, and two verification paths, but there is no read/query tool for mandate state, rolling 24h usage, or existing routes, and no way to sign/dispatch or check the status of an encoded instruction. Agents can work around some of this off-chain, but key lifecycle steps are missing.

Maintenance

ActivityMaintained
ResponsivenessNo recent community issues