solana-enterprise-payment-gateway

# Solana Enterprise Payment Gateway

**High-Throughput HTTP 402 Payment Channel Middleware**

<p align="left">
  <img alt="Java 21" src="https://img.shields.io/badge/Java-21-007396?logo=openjdk&logoColor=white" />
  <img alt="Spring Boot 3.4" src="https://img.shields.io/badge/Spring_Boot-3.4.3-6DB33F?logo=springboot&logoColor=white" />
  <img alt="PostgreSQL 16" src="https://img.shields.io/badge/PostgreSQL-16-4169E1?logo=postgresql&logoColor=white" />
  <img alt="Flyway" src="https://img.shields.io/badge/Flyway-Schema_Migrations-CC0200?logo=flyway&logoColor=white" />
  <img alt="Docker Compose" src="https://img.shields.io/badge/Docker_Compose-2496ED?logo=docker&logoColor=white" />
  <img alt="x402 v2" src="https://img.shields.io/badge/x402-v2-9945FF" />
  <img alt="Ed25519" src="https://img.shields.io/badge/Ed25519-BouncyCastle-000000" />
  <img alt="Tests 47" src="https://img.shields.io/badge/Tests-47_passed-brightgreen" />
</p>

> **Language / runtime note.** The Maven build targets **Java 21** bytecode
> (`<java.version>21</java.version>`), the Spring Boot 3.4 baseline. Container
> images build and run on **Eclipse Temurin JDK 25** (`eclipse-temurin:25-jdk` /
> `25-jre-alpine`). Both are stated explicitly because the host toolchain is JDK
> 25 while the source level remains Java 21.

An institutional-grade, **zero-Web3-SDK** middleware that meters HTTP APIs with
the [x402](https://github.com/x402-foundation/x402) protocol and
[RFC 9110 §15.5.3](https://www.rfc-editor.org/rfc/rfc9110#section-15.5.3)
`402 Payment Required` semantics. It validates Ed25519-signed, off-chain payment
vouchers **in-memory in under 5ms** on the request hot path, persists every
verification to an append-only PostgreSQL audit ledger, and sweeps cumulative
channel balances on-chain in batched settlement transactions — all without any
Node.js sidecar, Python bridge, or generic Web3 Java wrapper.

## AI Agent Integration (Model Context Protocol)

Autonomous AI agents can screen Solana addresses and settle compliance
micro-payments through our published [Model Context Protocol](https://modelcontextprotocol.io)
(MCP) server. The server is a **zero-dependency** x402 compliance tool: it speaks
the RFC 9110 `402 Payment Required` challenge-and-response protocol natively,
signs Ed25519 channel vouchers in-memory (Node.js built-in `crypto`, no Web3
SDK), and negotiates settlement on every call.

### Direct Execution

```bash
npx -y @msantagiulianab/x402-mcp-server
```

### Configuration

The server reads two environment variables:

| Variable | Value | Purpose |
| --- | --- | --- |
| `X402_GATEWAY_URL` | `https://msb-solana-enterprise-payment-gateway.duckdns.org` | Gateway root URL |
| `X402_CHANNEL_ID` | `chan_smoke_test_001` | x402 payment channel id |

#### Claude Desktop

Add an entry to `claude_desktop_config.json`.

**macOS / Linux**

```json
{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}
```

**Windows**

```json
{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "cmd",
      "args": ["/c", "npx", "-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}
```

#### VS Code Cline

Add the server to `cline_mcp_settings.json`:

```json
{
  "mcpServers": {
    "solana-x402-compliance": {
      "command": "npx",
      "args": ["-y", "@msantagiulianab/x402-mcp-server"],
      "env": {
        "X402_GATEWAY_URL": "https://msb-solana-enterprise-payment-gateway.duckdns.org",
        "X402_CHANNEL_ID": "chan_smoke_test_001"
      }
    }
  }
}
```

### Verified Dual Compliance Screening Outcomes

The `screen_solana_address` tool returns one of two verified outcomes:

| Counterparty | Risk score | Verdict | Flags |
| --- | --- | --- | --- |
| Clear counterparty | `0` | `CLEAR_TO_TRANSACT` | none |
| Malicious / sanctioned counterparty | `100` | `BLOCKED` | `OFAC_SANCTIONED` / drainer detection (`EXPLOIT_DRAINER`) |


## Model Context Protocol (MCP) Server

This repository contains the official open-source MCP server implementation located at [`/agent-tools/mcp-server`](./agent-tools/mcp-server).

- **Implementation:** TypeScript ([`agent-tools/mcp-server/src`](./agent-tools/mcp-server/src))
- **NPM Package:** [`@msantagiulianab/x402-mcp-server`](https://www.npmjs.com/package/@msantagiulianab/x402-mcp-server)
- **Executable:** `npx -y @msantagiulianab/x402-mcp-server`

---

## Table of Contents

1. [Executive Architecture & Core Thesis](#1-executive-architecture--core-thesis)
2. [System Components](#2-system-components)
3. [Complete Protocol Sequence Diagram](#3-complete-protocol-sequence-diagram)
4. [Cryptographic & Voucher Wire Specification](#4-cryptographic--voucher-wire-specification)
5. [HTTP Wire Headers & JSON Schemas](#5-http-wire-headers--json-schemas)
6. [Database Schema & State Transitions](#6-database-schema--state-transitions)
7. [Quickstart & Verification](#7-quickstart--verification)
8. [Configuration Parameters](#8-configuration-parameters)
9. [Production Extension & Customization Guide](#9-production-extension--customization-guide)
10. [Project Layout](#10-project-layout)
11. [Testing](#11-testing)
12. [Security & Compliance Posture](#12-security--compliance-posture)

## 1. Executive Architecture & Core Thesis

### Problem

Base-layer blockchain latency and per-transaction fees are fundamentally
incompatible with high-throughput, **micro-metered** HTTP APIs. Use cases such
as:

- **AI inference** billed per token or per call,
- **RWA (real-world asset) valuation feeds** billed per oracle read,
- **Compliance / sanctions screening** billed per address,

…each issue millions of sub-cent requests per day. Settling every call directly
on Solana would impose block-confirmation latency (hundreds of milliseconds to
seconds) and a per-transaction fee that dwarfs the price of a single metered
call. The economics do not close, and the user experience collapses.

### Solution

The gateway decouples the **metering decision** from the **settlement
transaction** using the x402 HTTP challenge-and-response protocol:

1. **Monotonic unidirectional off-chain state channels.** A client presents a
   signed voucher whose `cumulativeAmountAtomic` only ever increases for a
   channel. The gateway trusts the voucher only insofar as (a) it is signed by
   the channel owner, (b) its nonce is strictly monotonic, and (c) its
   cumulative spend does not exceed the verified on-chain escrow deposit.
2. **RFC 9110 `402 Payment Required` filter.** A Spring `OncePerRequestFilter`
   issues a `PAYMENT-REQUIRED` challenge to unauthenticated callers and accepts a
   `PAYMENT-SIGNATURE` voucher on retry, attaching a `PAYMENT-RESPONSE` receipt
   on success.
3. **< 5ms hot path.** Voucher verification is pure in-memory Ed25519 crypto plus
   a short-TTL cache of the escrow balance. **No synchronous Solana RPC call is
   ever made on the HTTP request path.**
4. **Batched on-chain settlement.** An administrative endpoint sweeps a channel's
   highest-nonce verified cumulative amount to the treasury in a single signed
   transaction, recorded atomically in the audit ledger.

The result is deterministic, single-digit-millisecond payment gating with
fail-closed rejection, a complete audit trail, and on-chain finality only where
it matters: at settlement.

### Zero-Dependency Philosophy

The gateway deliberately avoids all generic Web3 SDK baggage:

| Concern | Implementation | Dependency |
| --- | --- | --- |
| Ed25519 signing/verification | `Ed25519Signer` (BouncyCastle) | `bcprov-jdk18on` only |
| Base58 codec | Hand-rolled `Base58` (no alphabet mistakes) | zero |
| `compact-u16` (shortvec) | Hand-rolled `CompactU16` | zero |
| Canonical account sorting | `SolanaWireTransactionBuilder` | zero |
| Transaction serialization & signing | `SolanaWireTransactionBuilder` + `SolanaKeypairService` | zero |
| Solana RPC | JDK `java.net.http.HttpClient` + Jackson JSON-RPC 2.0 | zero |

There is **no** `@solana/web3.js`, **no** `solana4j`/`p4j`, and **no** runtime
invocation of an external process. Wire transactions are serialized byte-by-byte
from first principles, and the JVM-native crypto stack is the only third-party
cryptographic primitive.

## 2. System Components

The gateway follows a strict layered separation:

```
HTTP Request
   │
   ▼
X402PaymentFilter (OncePerRequestFilter)          ── 402 challenge / 403 reject / pass-through
   │
   ├──▶ ChannelVoucherVerifier (service)          ── in-memory nonce watermark + Ed25519 + ceiling check
   │        └──▶ EscrowBalanceProvider            ── SolanaEscrowVerifier (short-TTL cache)
   │
   ├──▶ PaymentAuditService (service)             ── append VERIFIED record
   │        └──▶ PaymentAuditRepository (JPA)     ── append-only PostgreSQL ledger
   │
   └──▶ downstream @RestController               ── compliance screening, (your) metered APIs

Settlement (admin, off hot path):
   POST /api/v1/settlement/channels/{id}/sweep
   │
   ▼
ChannelSettlementService (service)
   ├──▶ SolanaRpcClient                          ── getLatestBlockhash / sendTransaction (JSON-RPC 2.0)
   ├──▶ SolanaWireTransactionBuilder             ── serialize + sign (in-process)
   └──▶ PaymentAuditRepository                   ── VERIFIED → SETTLED (markSettled)
```

| Component | Package | Responsibility |
| --- | --- | --- |
| `X402PaymentFilter` | `filter` | 402 challenge, header decode, 403 fail-closed, receipt attach |
| `ChannelVoucherVerifier` | `service` | in-memory anti-replay + signature + escrow-ceiling checks |
| `SolanaEscrowVerifier` | `service` | on-chain escrow balance with short-TTL cache (`EscrowBalanceProvider`)