Architecture
How a transfer travels from a signature to a sealed, logged and published block.
The path of a transfer
- 1
Sign
The sender's wallet builds the transfer message and signs it with the sender's secp256k1 key using EIP-191
personal_sign. See Signing transfers. - 2
Submit
The wallet sends the transfer to
POST /tx. The API recovers the signer from the signature, and rejects the transfer unless the signer is the sender, the nonce is the account's next nonce, neither party is frozen and the balance covers amount plus fee. - 3
Sequence
Accepted transfers enter the mempool. The sequencer takes a lock, drains the mempool in arrival order and re-checks every transfer against the latest balances, so two transfers can never spend the same dollars.
- 4
Seal
The included transfers become a block. The block records its height, the previous block's hash, the time, the transfer hashes, a root over them, the fees collected and the new log size. Its hash is signed with the sequencer's Ed25519 key.
- 5
Log
The block hash is appended as a leaf to the transparency log. The log's new root is part of the block itself, and the latest size and root can be fetched at any time as a signed checkpoint.
- 6
Publish
The block, its transfers and the updated accounts are immediately readable on the explorer and API.
Block structure
{
"height": 1,
"prevHash": "88434e65…d799e784",
"time": 1793730989320,
"txs": [],
"txRoot": "4f53cda1…1202b945",
"logSize": 2,
"logRoot": "f28c233d…c644e19afa",
"proposer": "usd.net",
"fees": "0",
"hash": "ce3d9150…e4d94a12",
"sig": "d513cb88…98d1f52105",
"transactions": []
}| Field | Meaning |
|---|---|
height | Block number, starting at 0 for genesis |
prevHash | Hash of the previous block, all zeros for genesis |
txs | Transfer hashes, in the order they were applied |
txRoot | SHA-256 of the canonical JSON array of txs |
logSize | Size of the transparency log once this block is appended |
logRoot | Root of the log at logSize, so every block is also a log commitment |
fees | USD₮ collected in fees in this block |
hash | SHA-256 of the block's canonical JSON, see below |
sig | Ed25519 signature over the 32 raw bytes of hash, by the sequencer key from GET /info |
To recompute hash, take every field except hash and sig, set logRoot to the empty string (the root is computed after the hash), add "chain": "usdnet-testnet-1", and hash the canonical JSON: keys sorted, no whitespace, absent fields omitted.
Heartbeat blocks
Blocks are sealed whenever transfers arrive. When the network is idle, an empty heartbeat block is sealed once an hour so that the log keeps advancing and stale checkpoints are easy to spot.
Storage
The testnet ledger is stored in a replicated Redis database. A block and every account it changes are written in a single multi-key write, and block production is serialised by a lock, so the ledger cannot fork even under concurrent submissions.