Version: 1.0 · Status: Stable
Runners. The canonical runner is being migrated to Rust (ADR-037, R4):
engines/banza-conformance(banza-conformance-rs) ports the offline vector-integrity + invariant-consistency + report + golden-parity scope. Live-operator HTTP execution and the federation runner remain in the Pythontools/banza-conformance/runner until Rust parity + R5 crypto land. A PASS is technical conformance evidence, not production certification.
This directory contains the canonical conformance system for the BANZA protocol ecosystem. It defines how candidate operator implementations and protocol artifacts are tested against BANZA contracts and invariants.
Conformance means an implementation correctly implements the BANZA protocol:
- Protocol compatibility — request/response shapes match the canonical schemas
- Invariant correctness — financial invariants hold (zero-sum ledger, no negative balance, idempotency, immutable postings, atomicity)
- Interoperability readiness — another conformant implementation can communicate with yours predictably
Conformance is tested against canonical test vectors — deterministic, human-readable JSON descriptions of inputs, expected outputs, expected events, expected ledger effects, and expected trace structures.
╔════════════════════════════════════════════════════════════╗
║ CONFORMANCE DOES NOT MEAN: ║
║ ║
║ ✗ Regulatory approval ║
║ ✗ Legal compliance ║
║ ✗ Financial institution authorization ║
║ ✗ Production security certification ║
║ ✗ Banking license ║
║ ║
║ Conformance produces technical evidence of protocol interoperability. It does not certify an operator, approve an operator, or replace any legal, regulatory, banking, KYC or KYB obligation. ║
╚════════════════════════════════════════════════════════════╝
Any operator implementation deploying BANZA-compatible services in production is solely responsible for its own regulatory compliance, security posture, and legal obligations.
| Level | Name | What it evidences |
|---|---|---|
| L0 | Protocol Sandbox | Health, valid manifest, simulated=true sandbox-safety, MON-001 |
| L1 | Core Payment Capability | All L0 + wallets, transfers, double-entry ledger, idempotency, traceability (trace_id, GET /traces) |
| L2 | Payment Initiation Capability | All L1 + payment requests, dynamic QR, instant execution, INV-QR |
| L3 | Inter-Operator Interoperability | All L2 + federation routing, reconciliation, inter-operator settlement, conformance evidence |
| L4 | External Interoperability | All L3 + external-rail acquiring (profile-defined) |
Levels are additive — every level requires all lower levels to pass.
The level names and per-level capabilities above are canonical and match docs/governance/certification-boundary.md § Conformance level model and ADR-021. Traceability is verified at L1; payment initiation (payment requests, dynamic QR, instant execution) at L2. The single-operator conformance runner produces evidence at L0–L2; L3 (federation) and L4 (external) require multi-operator / external-rail evidence and are not produced by the single-operator runner. Conformance evidence at any level is technical validation only and does not constitute certification, authorization, or approval of an operator.
There is no reference operator in this repository. Conformance is validated against published contracts, vectors, fixtures and candidate operator endpoints. Examples are illustrative only and are not certification targets. Conformance produces technical evidence; it does not create a certified operator.
conformance/
├── README.md This file
├── report-schema.json Canonical report format for conformance results
├── vectors/ Canonical test vectors (deterministic, language-neutral)
│ ├── transfers.json
│ ├── qr-payloads.json
│ ├── payment-requests.json
│ ├── settlement-batches.json
│ ├── event-envelopes.json
│ ├── wallet-balances.json
│ ├── ledger-postings.json
│ └── operator-manifests.json
├── operators/ Operator conformance suite
│ └── suite.json
├── sdk/ SDK conformance suite
│ └── suite.json
├── qr/ QR runtime conformance suite
│ └── suite.json
├── events/ Event schema validation suite
│ └── suite.json
├── ledger/ Ledger invariant suite
│ └── suite.json
├── settlement/ Settlement conformance suite
│ └── suite.json
├── manifests/ Operator manifest validation
│ └── schema.json
├── capabilities/ Capability descriptor validation
│ └── schema.json
└── badges/ Compatibility badge SVGs
Run suites against any operator:
./tools/banza-conformance/run.sh --url http://localhost:3100See tools/banza-conformance/README.md for full usage.
Suites are authored in JSON and executed by the conformance runner. Each vector is:
- Deterministic — same input always produces the same expected output
- Stable — vectors are immutable once published; new cases get new IDs
- Human-readable — JSON, no binary formats
- Language-neutral — the runner is Python stdlib; vectors work against any HTTP operator
- Choose the correct vector file in
vectors/ - Assign a monotonically increasing ID (
TRF-010,QR-003, etc.) - Fill all required fields:
id,title,certification_level,input,expected - Add the vector to the relevant suite in
operators/suite.jsonor domain-specific suite - Run the conformance runner to verify that the selected candidate endpoint or fixture satisfies the published vectors
- Open a PR — vectors require review by one maintainer
Vector IDs are immutable. If a vector becomes invalid, mark it deprecated: true.
The conformance system is designed to extend to multi-operator federation:
- Cross-operator routing vectors
- Inter-operator settlement vectors
- Identity resolution vectors
- CBDC operator conformance
- Government sandbox conformance
- Offline payment mode conformance
Federation conformance will be added when the cross-operator routing protocol reaches Stable status. Until then, and while the repository is pre-production, there is no certified operator and no active production certificate.