USD Network

Architecture

How a transfer travels from a signature to a sealed, logged and published block.

The path of a transfer

  1. 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. 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. 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. 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. 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. 6

    Publish

    The block, its transfers and the updated accounts are immediately readable on the explorer and API.

Block structure

GET /block/1
{
  "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": []
}
FieldMeaning
heightBlock number, starting at 0 for genesis
prevHashHash of the previous block, all zeros for genesis
txsTransfer hashes, in the order they were applied
txRootSHA-256 of the canonical JSON array of txs
logSizeSize of the transparency log once this block is appended
logRootRoot of the log at logSize, so every block is also a log commitment
feesUSD₮ collected in fees in this block
hashSHA-256 of the block's canonical JSON, see below
sigEd25519 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.