CNG · Financial Market Infrastructure — Clearing & Settlement
cNGN Stablecoin Settlement Hub
A C++23 clearing-and-settlement engine for a cNGN regional settlement hub: double-entry internal clearing, multilateral netting and CCP-style default management. Not production-ready as delivered.
Maturity. Pre-production. Vlaander's internal review (7 October 2026) verified one critical and five high-severity defects in the source you receive, and none of them is fixed in it. Sharded mode can create or destroy money when a command id is reused. The on-chain connector treats a reverted ERC-20 transfer as confirmed. A failed disk sync is still reported as durable. Network ingress has no authentication or TLS, and the debtor account is taken from the message itself. Do not use this code to move real funds until those defects are fixed and an external security audit is done.
Overview
CNG is a C++23 settlement core for a hub where member institutions clear cNGN obligations against one another internally, and only the net positions are settled on-chain and over Nigerian bank rails at the end of a cycle.
At its centre is a single-writer, event-sourced double-entry ledger. It uses integer money and checked arithmetic, and checks conservation of value and non-negative balances on every command. Around it sit a compliance gate at ingress, a write-ahead log with replay recovery, a multilateral netting engine, a settlement-cycle orchestrator, connector code for an EVM chain and for NIBSS, and a default-management module (loss waterfall, settlement unwind and a Cover-N adequacy test).
The performance figures below come from building the exact source archive buyers receive and running it on the machine named, with the compiler and the archive's SHA-256 recorded.
The problem
A stablecoin hub that settles every payment gross on-chain pays settlement cost and needs intraday liquidity in proportion to gross volume. A hub that nets internally also needs a way to absorb a member that fails to fund its position. CNG is designed to provide internal clearing, netting and default handling in one codebase.
What it does
- Internal clearing on a single-writer double-entry ledger, with conservation and non-negativity checked on every transfer and integer money throughout. The sharded router has an open defect (see the notice above).
- Multilateral netting: net positions always sum to zero, and the settlement plan has at most k−1 instructions for k members with a non-zero position (property-tested).
- Compliance gate at ingress: KYB member registry, sanctions and watchlist screening, AML monitoring (large value, velocity, structuring), FATF Travel Rule (IVMS101) completeness and per-transaction, daily and counterparty limits, with each decision appended to a SHA-256 hash-chained log.
- Settlement-cycle orchestration with a cNGN ERC-20 connector (EVM JSON-RPC client, confirmation depth and reorg handling) and a NIBSS NIP client with NIP or RTGS chosen by amount. The HTTP/TLS transport and the transaction signer are interfaces: only test mocks are included.
- Default management: loss waterfall across prefunded tranches, settlement unwind that re-nets the surviving members, and a Cover-N adequacy test (Cover-2 is the usual setting).
- ISO 20022 pain.001 ingest with a strict cNGN profile. Other ISO 20022 messages (pacs, camt) are not implemented.
- Write-ahead log with CRC-checked records and recovery by replay to the same hash-chain head.
Performance
Measured 2026-10-04| Metric | Figure | Basis |
|---|---|---|
| Clearing decision latency, per transfer | 1,173 ns median, 3,255 ns p99 | Measured by Vlaander |
| Clearing throughput, single core | 690,000 transfers per second | Measured by Vlaander |
| Hub end to end (pain.001 in, compliance gate, ledger applied, WAL group commit) | 90,000 messages per second | Measured by Vlaander |
| Ledger apply latency inside the hub | 2,048 ns median, 6,656 ns p99, 61,440 ns p99.9 | Measured by Vlaander |
| Recovery | Ledger rebuilt from the WAL has the same hash-chain head as the live ledger | Measured by Vlaander |
| Test suite | 192 test cases and 4 end-to-end smoke programs, 0 failures | Measured by Vlaander |
| Fuzzing (Release build) | 1,000,000 inputs, 0 failures | Measured by Vlaander |
- Date
- 2026-10-04
- Hardware
- AMD EPYC 7763, Azure VM, 4 vCPU (2 cores), 15 GiB
- Toolchain
- g++ 14.2.0 (Ubuntu), -std=c++23, in ghcr.io/vlaander-ltd/engines:2026.10.0
- Source archive SHA-256
- aa5832b7bddf760c5265011f2a73258ba4450f269d5def1a7dc194c9131c21b3
- Method
- Clearing: cngn_clearing_bench, 1,000,000 in-memory transfers across 64 accounts, each timed, median of 5 runs. Hub: cngn_hub, 20,000 ISO 20022 messages end to end, then a fresh ledger recovered from the WAL and its hash-chain head compared with the live ledger. Tests: cngn_tests plus the settlement, compliance, go-live and default-management smoke programs. Fuzz: cngn_fuzz in a Release build without sanitizers.
- Each clearing decision includes two software SHA-256 hashes for the audit chain.
- The README inside the archive still quotes older, faster clearing figures. Vlaander could not reproduce them on this machine and does not publish them.
- Vlaander's review re-ran the clearing benchmark on a heavily loaded machine with the same CPU model on 7 October 2026 and got figures about 1.7 times slower. That run neither confirms nor refutes the figures above; no other quiet re-run has been done.
Value in your own metrics
- Clearing decision latency
- Measured 1,173 ns median and 3,255 ns p99 per transfer, including two SHA-256 audit hashes.
- Throughput
- Measured 690,000 transfers per second on one core in memory; 90,000 ISO 20022 messages per second through the hub with WAL group commit.
- Recovery
- A ledger rebuilt from the WAL reached the same hash-chain head as the live ledger (measured 4 October 2026).
- On-chain settlement volume
- Only net positions are settled, rather than every gross obligation.
Assurance and build
- Language
- C++23 with CMake; no third-party dependencies for the core and tests; liburing optional for the io_uring TCP ingress
- Measured build
- g++ 14.2.0 -std=c++23, image ghcr.io/vlaander-ltd/engines:2026.10.0
- Compilers
- Builds with g++ 14. Clang does not build this archive: clang 20 fails in json.hpp and hub.cpp, and clang 16 lacks std::expected (checked by Vlaander, October 2026), although the README says Clang 17+
- Benchmark hardware
- AMD EPYC 7763, Azure VM, 4 vCPU (2 cores), 15 GiB
- Source archive SHA-256
- aa5832b7bddf760c5265011f2a73258ba4450f269d5def1a7dc194c9131c21b3
- Formal specification
- TLA+ specs for the ledger (conservation, non-negativity) and netting (zero sum, gross bound); the included CI configuration model-checks them with TLC, but Vlaander has not run TLC on them
- Sanitizers in CI
- AddressSanitizer and UndefinedBehaviorSanitizer jobs in the included CI configuration; no ThreadSanitizer job
- Fuzzing
- 1,000,000 inputs, 0 failures (measured 2026-10-04, Release build). The fuzzer is mutation-based, not coverage-guided, and few inputs get past the XML and JSON layers
- Test surface
- 192 test cases and 4 end-to-end smoke programs, 0 failures (measured 2026-10-04)
- Developer's review
- docs/FORENSIC-REVIEW.md records the developer's own review and 17 findings it fixed before delivery; Vlaander has not verified who carried it out
- Internal review
- Vlaander quality gate, 7 October 2026: 1 critical, 5 high and 6 medium findings verified, all open in the delivered source.
- Decision records
- Architecture decision records in docs/adr, one per design decision listed in the README
- Licence
- Proprietary; Vlaander's rights in the asset are assigned to the single buyer under the Sale and Assignment Agreement
Releases are not yet cryptographically signed, and no release manifests or external audit summaries are published. Check the source tarball you receive against its SHA-256 in Schedule 1 of your Sale and Assignment Agreement, which you see before you sign.
Scope and maturity
What is real today, what is deliberately excluded, and what is pending — published unprompted.
Included today
- The source archive above: the ledger core, WAL and recovery, compliance gate, netting, settlement orchestration, default management, the EVM and NIBSS connector code, and the reference programs (hub, settle, comply, go-live, default demo, fuzz, clearing benchmark).
- Unit, property, differential and simulation tests, TLA+ specs, a CI configuration, architecture decision records, a runbook, a threat model and a go-live checklist.
Explicitly scoped out
- A production HTTP/TLS transport and a transaction signer (RLP and secp256k1). These are interfaces only, so the buyer must supply them, for example backed by a custody HSM.
- Outbound ISO 20022 messages (pacs.008, pacs.002, camt statements).
- A network replication protocol and failover. The included replica is an in-process follower fed the same ordered commands.
Pending
- Critical (open in the delivered source): a cross-shard transfer that reuses a command id can credit the payee with no debit, or debit the payer with no credit. The reference hub does not use sharded mode.
- High (open in the delivered source): the EVM connector counts confirmations for a reverted ERC-20 transfer, so the bridge can mark a failed settlement final.
- High (open in the delivered source): a failed fdatasync is still counted as durable, so callers can acknowledge data that is not on disk.
- High (open in the delivered source): replayed instructions use up a member's daily and counterparty limits again before the core rejects them as duplicates.
- High (open): the io_uring TCP ingress binds all interfaces with no TLS or authentication, and the debtor account is taken from the message itself.
- High (open): command ids are chosen by the sender in one global namespace, so one member can block another's instructions. The same lever caused a 56-fold slowdown in Vlaander's measurement, because colliding ids make every apply walk a hash-table chain.
- Medium (open): settlement approval counts bare signer ids; the Shamir key custody is used only in tests. The audit hash chain has no key, signature or external anchor, so anyone who can rewrite the log can recompute it.
- Medium (open in the delivered source): a torn WAL write followed by more appends makes the log unrecoverable on the next restart. Shamir split and combine accept bad parameters and short shares (an out-of-bounds read).
- Medium (performance, open): the WAL writes each record with two system calls. In Vlaander's durable test this gave about half the throughput of TigerBeetle 0.16.78 on the same core.
Who it's for
- Licensed Nigerian financial institutions or consortia planning to operate a regional cNGN settlement hub, with an engineering team able to finish and harden it.
- Industry-utility or central-bank-adjacent vehicles evaluating CCP-style default management for digital-asset settlement.
- Regional clearing houses extending into digital-asset settlement.
Before you buy
- The open review findings are listed above; budget for fixing them yourself, since the delivered archive does not contain fixes.
- Budget for the open work before any live use: authenticated, encrypted ingress; internal command ids; signed settlement approvals; an anchored audit chain; a production HTTP/TLS transport and transaction signer.
- The clearing figures above were measured by Vlaander on the stated hardware from the archive whose fingerprint is published above. The benchmark ships with the source, so you can rerun it after delivery; there is no way to run it before purchase, and no refund is available after delivery, except where a remedy cannot lawfully be excluded.
- Commission an external security audit before the system holds or moves real funds.
- Have counsel confirm the regulatory perimeter the hub would operate under, including CBN payment licensing and settlement-finality treatment; jurisdictional compliance risk sits with the buyer.
- Test the Cover-2 adequacy model against your intended member set and concentration profile, not the reference configuration.
What transfers
- The asset's sourceSubject to the Sale and Assignment Agreement, Vlaander assigns to the verified Buyer the transferable right, title and interest that Vlaander owns in the specified Asset. The assignment excludes Third Party Materials, open-source components, Vlaander’s pre-existing tools, generic know-how, development methods, trademarks, confidential information and any rights that cannot lawfully be assigned.
- Its testsThe test suite the published assurance claims rest on, as delivered in the source archive.
- Its audit artefactsSpecifications, model-checking output, reviews and the software bill of materials, where the asset has them.
- Not includedThird-party and open-source materials are not sold or assigned by Vlaander. They remain under their own licences, listed in each asset’s software bill of materials (SBOM.md in the archive), and the Buyer is responsible for complying with those licences.
First described in: VLA-GEN catalogue, 3 August 2026, §3.2. Revised by Vlaander against the delivered source; every figure is labelled with its basis.
From test to source
- 01
Check
Read the engine's page: what Vlaander measured and on which hardware, what it has not measured, and the open review findings. Nothing runs before purchase.
- 02
Buy
Verified businesses only. Place the order, give your company's details, have your authorised signatory sign the Sale and Assignment Agreement, then pay the invoice in naira by bank transfer, or in USDC on Polygon. Once the payment is verified, your account shows Paid.
- 03
Receive
We confirm the funds and release the source tarball to you. Delivering, then Download ready. Check it against the SHA-256 in Schedule 1, then rerun the tests and benchmarks yourself.