Skip to content

Architecture

Vauban Pay sits as a thin layer between three things you already have:

  1. A chain (Starknet first ; chain-agnostic by invariant per ADR-ECO-031, multi-chain Phase 4+)
  2. A proving system (Stwo Circle STARK M31, production-deployed Starknet mainnet)
  3. An HTTP-native payment wire format (x402 V2 Linux Foundation)

And imposes one constraint on top: every payment artifact (intent, receipt, refund, delegation) is a typed Claim in the Vauban Claim Algebra (VPSF).

High-level flow

                                         ┌─────────────────────────────┐
   Payer                                  │   Vauban Claim Algebra      │
   ────►  PaymentIntent (Claim)  ────►   │   (VPSF, chain-agnostic)    │
                                         │                             │
                                         │  ∧  same-subject conjunction│
                                         │  ⊕  K-aggregation            │
                                         │  ▷  revelation restriction  │
                                         │  ¬  revocation               │
                                         │  →  delegation (Phase Agentic)│
                                         └─────────────┬───────────────┘
                                                       │
                                  Stwo STARK proof + signature
                                                       │
                              x402 V2 wire (HTTP, CBOR canonical)
                                                       │
                                                       ▼
                                          Merchant verifier middleware
                                                       │
                              SettlementReceipt (Claim) ────► back to Payer
                                                       │
                                                       ▼
                              Starknet L2 (VaubanSettlement extension)
                              Anchor → L3 Madara (ProofChainAnchor.cairo)

Five layers, strict boundary discipline

Layer Component Chain-coupling Notes
L3 — Grammar vauban-claim core (VPSF) AGNOSTIC by invariant Vauban-unique keystone (ADR-ECO-031)
L4 — Vertical vauban-zkpay Rust crates Starknet-first reference impl This protocol, Phase 0-3
L1 — Per-chain adapter vauban-zkpay-starknet (current) ; -evm, -solana, -bitcoin Phase 4+ Chain-specific Adapter pattern strict, no chain types in L3/L4 core
L0 — Chain primitive STRK20, strkBTC, USDC, future ERC-20 / SPL Chain-specific Consume, don't build
L–1 — Settlement contract VaubanSettlement.cairo extension + ProofChainAnchor.cairo (L3 Madara) Starknet Reuse existing (ADR-ECO-010) — no parallel CreditRegistry

The chain-agnostic invariant (ADR-ECO-031) is non-negotiable: no Starknet/EVM/Solana/Bitcoin types ever appear in vauban-claim core or vauban-zkpay vertical core crates. CI lint enforces it. Per-chain primitives live in adapter sub-crates only.

The four traits you'll touch

If you're integrating Vauban Pay, you'll deal with these traits — see Integration Ports for details:

Trait Status Default backend
Claim HARD vauban-claim v0.1.0
ShieldingBackend INTERFACE Transparent → Strk20 (Phase 2a) → Vpp ML-KEM-768 (Phase 2b)
HumanityGate INTERFACE optional Null (default) or Glacis V1 admin-attest (default) / V2 trustless opt-in via GLACIS_PATH=v2, mainnet live 2026-05-18
PaymentSigner INTERFACE VaubanAuthSigner (default) ; Starknet/EVM/Solana adapters Phase 4+
ClaimExporter [ROADMAP] INTERFACE future SD-JWT-VC + BBS-2023 + mDoc (Phase 2b hard deadline)

Each trait is modular auditable. The Phase 5 audit scope budgets the Stwo-cairo verifier separately from the main code audit precisely because the boundaries are clean.

What this isn't

  • Not a new ZK system. Stwo is the prover. Vauban Pay does not invent cryptography.
  • Not a chain. Settlement happens on Starknet L2 today, with extension points for adapters Phase 4+.
  • Not a privacy pool. Privacy is wallet-side (STRK20, VPP). Vauban Pay consumes wallet primitives via the ShieldingBackend trait.

Next reading