Version 1.2 · SupraSage Conglomerate
SupraBullion is a peer-to-peer file network and JSON database engine embedded inside a
fiat-backed blockchain written in GNU C11. Every coin minted on the network carries an
optional, cryptographically-sealed JSON schema — the Nano NoSQL layer — that travels
with the coin through every transfer and persists in a queryable on-node database. Receipts
are locked to designated parties, giving industries the power to define their own transaction
schemas and accumulate structured, auditable data without centralised intermediaries.
The result is a Truth-Currency: money whose purpose, route, and provenance are encoded
at mint time and verifiable by every authorised party in a supply chain, crowdfund, levy, or
investment round.
Modern financial systems generate enormous transaction data, yet almost none of it is
accessible to the parties who need it most. A non-profit cannot prove in real time that a
donation was spent on a specific project. A crowdfund cannot show a backer which milestone
their contribution funded. A supply-chain operator cannot embed a product’s provenance into
the payment that settles a shipment. Data and money flow through separate silos; reconciling
them requires expensive middleware, audit firms, or trust in a platform.
Blockchains improved auditability but introduced new problems: fixed schemas, limited
throughput, smart-contract complexity, and no native support for arbitrary JSON schemas
attached per-coin.
SupraBullion collapses the gap between money and data by making every coin a first-class JSON
document carrier. When a user mints a coin they define a schema — field names, types,
and validation rules. That schema is embedded in the receipt chain and enforced on every
subsequent transfer. The coin carries its own database record, locked to the
parties the minter authorises.
The on-node Nano NoSQL engine stores every receipt in a queryable JSON document store.
Users can run SQL-like SELECT, INSERT, UPDATE, DELETE, and now JOIN queries across
multiple collections directly from the REST API, turning the blockchain node into a
full-featured data platform.
A SupraBullion node spawns five cooperating OS processes connected via POSIX named pipes:
| Process | Channel | Role |
|---|---|---|
bullion_event_loop |
CH_EVENT |
REST API host; event dispatcher |
bullion_ssl_client |
CH_CLIENT |
Outbound peer SSL; blockchain operations |
bullion_ssl_server |
CH_SERVER |
Inbound peer SSL; port 4433 |
bullion_file_client |
CH_FCLIENT |
P2P file retrieval |
bullion_file_server |
CH_FSERVER |
P2P file serving; port 9001 |
All inter-process data passes through struct bullion_kv_pair — a fixed-layout key/value
store with up to 28 slots — ensuring every process operates on well-typed, bounded messages
without shared-memory race conditions.
POST /terminals (libmicrohttpd, port 8888)
└─ bullion_db_api.c (JSON parse → event queue)
└─ bullion_event_loop (IPC dispatch)
└─ bullion_ssl_client (blockchain logic per request_type)
└─ workqueue (REST response delivery)
The REST API is non-blocking; every request returns a {"request_id":N} immediately. The
client polls GET /terminals/<N> until "complete":1.
Each block in the chain is a linked list of assets, each of which contains a linked list of
receipts:
bullion_blockchain
└─ bullion_block (height, nonce, SHA256 hash, prev_hash, Merkle root)
└─ bullion_asset* (LIQUID / NONLIQUID / CONTRACT; minted, reserve, value)
└─ bullion_receipt* (DEPOSIT / WITHDRAWAL / TRANSIT; amount, schema)
Consensus operates at three levels:
buy_reserve isolated from syntheticmint_reserve; bonding-curve sell quote capped at buy_reserve onlyblock->shash; broadcast to all lock ownersAfter INTEGRITY consensus build_and_store_merkle constructs an 8-leaf tree:
shash hex strings from the block’s receipt chain"R:<buy_reserve>:<mint_reserve>:<ttime>" (Upgrade C)block->transactions[0], then folded into block->shashThis seals the entire fiat-reserve split into every block hash, making synthetic-reserve
inflation detectable on-chain without any external oracle.
Setting "coin_nano_nosql":1 in a buy request attaches a typed JSON schema to the minted
coin. Required fields:
| Field | Description |
|---|---|
nosql_schema_keys |
Comma-separated field names |
nosql_schema_vtypes |
Type per field (string, int, double, bool) |
nosql_schema_vreqs |
Required flag per field (true/false) |
nosql_schema_vreq_opts |
Validation options per field |
nosql_schema_vreq_opacity |
Opacity annotation per field (OPAQUE, GOSSAMER, CLEAR) — stored as metadata |
nosql_schema_doc_url |
URL to the schema documentation |
The schema is validated on every subsequent transfer. A coin carrying a required field
rejects any transfer that does not supply a conforming value for that field. The opacity
annotation is stored with each field in the receipt but per-field enforcement is not yet
implemented.
Every node runs a file-backed JSON document store under ~/.suprabullion/database/. The
query engine accepts SQL-like syntax via the query request type and supports:
| Statement | Example |
|---|---|
CREATE COLLECTION |
CREATE COLLECTION Shipments {Parcel=noschema} |
CREATE (object) |
CREATE Shipments.Parcel {"id":1,"origin":"NYC","weight":4.5} |
SELECT {fields} |
SELECT {id,origin} FROM Shipments.Parcel WHERE {origin='NYC'} |
SELECT * |
SELECT * FROM Shipments.Parcel (bare wildcard, no braces required) |
SELECT … JOIN |
SELECT {*} FROM Orders.Item JOIN Inventory.Stock ON sku=sku |
UPDATE |
UPDATE Shipments.Parcel SET {weight=5.0} WHERE id = 1 |
INSERT |
INSERT INTO Shipments.Parcel {weight} VALUES {6.0} WHERE id = 1 |
DELETE |
DELETE {*} FROM Shipments.Parcel WHERE {id=1} |
Dot notation is fully supported in SELECT projections and WHERE clauses. A query such as
SELECT {address.city, address.zip} FROM Customers.Profile WHERE {address.country='US'}
traverses nested JSON objects and returns only the specified leaf values.
JOIN aggregation merges two collections on a shared key and returns an array of flat,
merged objects. The syntax mirrors SQL: SELECT {*} FROM Col1.Obj JOIN Col2.Obj ON key=key.
Primary document fields take precedence over secondary fields with the same name.
The buy_reserve — the pool of real fiat dollars backing outstanding coins — is protected by
six independent layers:
| Layer | Mechanism |
|---|---|
| 0 | Reserve bifurcation: buy_reserve ≠ mint_reserve in struct |
| 1 | Merkle reserve commitment in block->shash (Upgrade C) |
| 2 | Gateway attestation pool: GOLD+ peers attest live Stripe balance |
| 3 | Rolling 100-block mint cap: mint ≤ 25% of buy delta (dead code; MINT removed from REST) |
| 4 | Adaptive mint reward: effective amount = requested × buy/total ratio (dead code) |
| 5 | MINT removed from REST API surface entirely |
Eight fiat-reserve milestones ($10K → $2.5M) lock the spot price (price_floor) as real
fiat grows. The floor is a one-way ratchet — SELL transactions cannot lower it. A
sell-pressure brake applies a sliding fee (0–7%) when sell_volume / milestone_hwm > 0.30,
protecting the reserve from coordinated sell-off attacks.
Contracts are JavaScript programs stored in system.contracts and executed by an embedded
QuickJS runtime. They fire automatically on every TRANSFER
that touches the owner’s wallet.
function execute(msg) {
let r = dbQuery("SELECT {balance} FROM Wallets.User WHERE {id=" + msg.key + "}");
let data = JSON.parse(r);
if (data.objects.length === 0) return { ok: false, message: "wallet not found" };
if (parseFloat(msg.amount) > 1000) return { ok: false, message: "over limit" };
return { ok: true };
}
Each execution runs in an isolated JSRuntime with 8 MB memory and 256 KB stack. The only
host bridge is dbQuery(sql) — no network, no filesystem, no randomness. This guarantees
deterministic, sandboxed execution that cannot reach outside the node’s own data store.
startup → suprabullion.com/api/peers (central registry)
→ GET :8888/api/peers (fallback: local peers)
SSL HANDSHAKE on 4433 → peer list gossip (bidirectional)
POST :8888/api/peers → direct announce (no central server)
UPnP at startup → auto-forward 4433/8888/9001
Peers carry a lvl field (enum bullion_level: BULL=0 through MANNA=5) that is stored,
serialised, and gossiped across the network. The level is assigned by the central registry or
carried in peer gossip messages. Automatic tier advancement based on transaction success
percentiles is not yet implemented. The one enforced gate is that only GOLD+ peers contribute
to the network-attested reserve (GET /api/reserve → network_attested_buy_reserve).
Each node queries its own Stripe balance via bullion_reserve_attest_self, stores the result
on its peer record, and broadcasts it to all peers via POST /api/reserve_attest. Aggregated
GOLD+ attestations form the network_attested_buy_reserve field — a soft, self-reported
signal cross-checked against the on-chain Merkle reserve commitment.
SupraBullion ships native integrations for five fiat gateways. The payment_provider field
on any register, add_pm, buy, or sell request selects the active gateway:
| Provider | Direction | Notes |
|---|---|---|
| Stripe (default) | BUY + SELL | Full KYC; bank account, card, CashApp |
| PayPal | BUY + SELL | Orders v2 + Payouts v1; buyer approval URL returned |
| MoonPay | BUY | Hosted widget URL; server-side API requires MoonPay approval |
| MoneyGram | SELL only | Cash pickup or bank deposit worldwide |
| Flutterwave | BUY + SELL | Card, bank transfer, mobile money; NGN/USD/GHS |
All gateway credentials are stored in user.conf and read at startup. No recompile is needed
to switch between sandbox and production keys.
A charity mints coins with a schema carrying {"project":"clean_water","region":"KE"}.
Donors receive coins; every subsequent transfer is validated against the schema. The on-chain
receipt proves — to donors, regulators, and auditors — exactly which project received which
funds, with no manual reporting required.
A startup defines a schema with {"milestone":"seed","equity_pct":2.5,"vesting_months":24}.
Investors mint coins against each milestone; the smart contract fires on TRANSFER and rejects
disbursement if the milestone condition stored in the NoSQL DB is not yet marked complete.
The entire cap table is queryable on-chain.
Local co-ops, community development funds, and participatory budgeting programs can issue
coins with governance schemas. Voting weight, contribution history, and payout entitlement
are embedded in receipt data and updated via on-node SQL queries — no external database or
voting platform required.
A manufacturer mints a coin for each production batch with a schema:
{"batch":"A1042","origin":"factory_sg","grade":"A","expiry":"2027-06"}.
Every handler in the supply chain receives and retransfers the coin, accumulating a receipt
chain that is the full chain of custody. A retailer can query
SELECT {batch,grade} FROM Inventory.Batch WHERE {grade='A'} directly from their own node.
Industry bodies, royalty administrators, and tax authorities can define collection schemas
on coins before they circulate. Every transfer triggers the smart contract, which enforces
levy deduction rules and routes a configured percentage to the designated wallet without
any manual intervention.
Beyond finance, the on-node JSON database is a full-featured document store queryable over
HTTP. Developers can use SupraBullion as a tamper-evident, cryptographically-checksummed
JSON database with built-in compression, transparent encryption, and P2P replication — for
any application that benefits from audit trails attached to data records.
| Property | Value |
|---|---|
| Language | GNU C11 (-std=c11 -D_POSIX_C_SOURCE=200809L) |
| Consensus | SHA256 proof-of-work + Merkle receipt commitment |
| Block structure | Linked list of assets → receipts |
| Key crypto | OpenSSL: RSA, AES-GCM, AES-CCM, prime256v1 EC |
| TLS | Self-signed X.509v3 (prime256v1, SAN) auto-generated |
| Compression | LZ4 (default), zlib, RLE, X-compressor, LZ77, BLNH |
| Smart contracts | QuickJS (ECMA-2020); 8 MB / 256 KB sandbox |
| REST API | libmicrohttpd; port 8888 |
| Peer SSL | port 4433 (ssl_server / ssl_client) |
| P2P file | port 9001 (file_server / file_client) |
| Database | File-backed JSON documents; per-document SHA256 checksum |
| UPnP | libupnp; auto-maps 4433, 8888, 9001 on startup |
| GUI | raylib 5.5 + raygui; compiled with -DBULLION_GUI |
SELECT * FROM Collection.Object
SELECT * FROM Collection.Object WHERE {field=value}
The * operator does not require curly braces. Both forms are equivalent to
SELECT {*} FROM ....
SELECT {address.city, address.zip} FROM Customers.Profile WHERE {country='US'}
Dot notation traverses nested JSON objects. The returned key name is the leaf component
(city, zip). Dot notation is also supported in WHERE clauses.
SELECT {*} FROM Orders.Item JOIN Inventory.Stock ON sku=sku
SELECT * FROM Receipts.TRANSIT JOIN Persons.Client ON pkey_hash=pkey_hash
Returns an array of merged objects. For each primary document that passes the optional WHERE
filter, all secondary documents where secondary.right_key == primary.left_key are found and
merged. Primary fields take precedence on key collision. The secondary collection is always
projected with {*} semantics.
| Collection | Content |
|---|---|
blockchain.blocks |
One document per mined block |
blockchain.receipts |
All receipts; receipt in path triggers DB_RECEIPT_SELECT |
blockchain.assets |
All assets |
stripe_clients.clients |
Stripe customer/account records |
system.contracts |
Deployed QuickJS smart contracts |
# Ubuntu / Debian
sudo apt-get install build-essential libssl-dev libcurl4-openssl-dev \
libmicrohttpd-dev libcjson-dev libupnp-dev zlib1g-dev libexpat1-dev
git clone <repo-url>
cd suprabullion_c-1.2.2
cp example.user.conf user.conf # add gateway API keys
make
./suprabullion
Node data is stored under ~/.suprabullion/. TLS certificates are generated automatically
on first run.
# Register a peer
curl -s -X POST -d 'json={
"request_type":"register","rest_sec":0,"coin_nano_nosql":0,
"ip":"127.0.0.1","ip_server":"127.0.0.1:4433","ip_fserver":"127.0.0.1:9001",
"email":"user@example.com","fname":"Alice","lname":"Smith",
"username":"alice","password":"password",
"hostname":"peer.example.com","description":"my node",
"node_ip":"127.0.0.1","node_port":"5000"
}' http://localhost:8888/terminals
# → {"request_id":1}
curl -s http://localhost:8888/terminals/1
# → {"complete":1,"data":{"public_key":"<WALLET>",...}}
# Mint coins with a Nano NoSQL schema
curl -s -X POST -d "json={
\"request_type\":\"buy\",\"rest_sec\":0,\"coin_nano_nosql\":1,
\"payment_method\":\"cashapp\",\"transaction_type\":\"buy\",
\"transaction_to\":\"$WALLET\",\"lock\":\"$WALLET\",\"key\":\"$WALLET\",
\"amount\":100,\"payment_currency\":\"usd\",\"encryption\":\"rapid\",
\"nosql_schema_keys\":\"project,region,milestone\",
\"nosql_schema_vtypes\":\"string,string,string\",
\"nosql_schema_vreqs\":\"true,true,false\",
\"nosql_schema_vreq_opts\":\"none,none,none\",
\"nosql_schema_vreq_opacity\":\"CLEAR,CLEAR,CLEAR\",
\"nosql_schema_doc_url\":\"https://example.com/schema\"
}" http://localhost:8888/terminals
# Join two collections on a shared key
curl -s -X POST -d "json={
\"request_type\":\"query\",\"rest_sec\":0,\"coin_nano_nosql\":0,
\"key\":\"$WALLET\",
\"query\":\"SELECT {*} FROM Orders.Item JOIN Inventory.Stock ON sku=sku\"
}" http://localhost:8888/terminals
The following parameters require governance review before modification:
BULLION_HALVING_MILESTONES[])buy_reserve cap on bonding-curve sell quotes| Milestone | Description |
|---|---|
| v1.3 | Multi-node sync stress testing; UPnP reliability hardening |
| v1.4 | Peer tier advancement: transaction-success percentile calculation and enforcement |
| v1.5 | Per-field opacity enforcement (OPAQUE encryption, GOSSAMER elision at query time) |
| v1.6 | NoSQL replication between peers over P2P file channels |
| v1.7 | Governance proposal voting backed by on-chain coin-weighted receipts |
| v2.0 | Layer-2 state channels for high-frequency NoSQL writes |
SupraBullion makes money data-aware at the protocol level. By embedding typed JSON schemas
into every coin and providing a queryable on-node document store, it enables industries that
have long depended on manual reporting, auditors, and siloed databases to replace that
infrastructure with a single, self-auditing financial primitive.
The coin becomes the receipt. The receipt carries the schema. The schema enforces the
purpose. Smart contracts govern the rules. The Nano NoSQL engine answers the questions.
This is the architecture of accountable money.
SupraSage Conglomerate · SupraBullion v1.2.2 · GNU C11 · MIT License