Aurum 1.0

Aurum is a compact custodial digital-asset exchange reference system built to demonstrate the parts that are hardest to get right:

• deterministic price-time matching;
• reservation-based financial accounting;
• atomic two-asset settlement;
• idempotent commands under lost/duplicate network delivery;
• Ethereum deposit indexing, finality, and reorg handling;
• durable outbound withdrawals with persist-before-broadcast signing;
• reconciliation between canonical chain evidence, indexed state, and internal liabilities.

It is deliberately not a broad crypto product. The value of the project is that one engineer can understand the complete money path and explain every transaction boundary and failure mode.

Status: verified local engineering showcase. Not production custody software.

Architecture in one picture

                 external settlement authority

                       Ethereum / ERC-20
                              |
                      logs / receipts / calls
                              |
                              v
                    +-------------------+
                    | Go Chain Gateway  |
                    | chain.*           |
                    +---------+---------+
                              |
                   idempotent gRPC commands
                              |
                              v
                    +-------------------+
                    | Rust Exchange Core|
                    | exchange.*        |
                    +----+---------+----+
                         |         |
                  PostgreSQL   in-memory
                    truth      OrderBook

The key boundary is authority:

• Rust owns internal financial truth.
• Go owns Ethereum interpretation and external settlement workflows.
• PostgreSQL owns durable state.
• The order book is rebuildable execution state.
• Reconciliation independently compares the views.

What is implemented

Rust exchange core

• GOLD/USDC limit-order market;
• integer atomic units only;
• explicit available / reserved balances;
• durable reservation ownership;
• deterministic price-time priority;
• maker-price execution;
• partial fills and cancellation;
• BUY quote reservation at limit price with price-improvement release;
• idempotent external deposit credit;
• idempotent client order IDs;
• atomic trade settlement and immutable ledger deltas;
• restart reconstruction of open/partially-filled orders;
• durable withdrawal requests and internal settlement;
• gRPC API with chain-agnostic external identities.

Go chain gateway

• Ethereum JSON-RPC;
• ERC-20 Transfer decoding;
• token and watched-address configuration;
• durable block hash/checkpoint indexing;
• deposit states: Observed -> Pending -> Safe -> Finalized -> Credited;
• retry/backoff under RPC/gRPC uncertainty;
• bounded shallow-reorg handling;
• reconciliation-required stop for financially ambiguous reorgs;
• durable withdrawal jobs;
• signer abstraction with development Foundry signer;
• nonce + raw signed transaction + tx hash persisted before broadcast;
• exact signed-transaction rebroadcast after unknown outcome/reorg;
• receipt/inclusion/finality tracking;
• reconciliation runs/findings;
• canonical deposit/withdrawal evidence checks;
• on-chain custody vs internal liability checks.

Quick start

Requirements:

• Rust 1.97.1 (cargo, rustc, rustfmt, clippy), pinned by rust-toolchain.toml;
• Go 1.25+;
• PostgreSQL;
• GNU Make;
• Foundry (anvil, forge, cast) for chain demos.

Check tools:

make doctor
make doctor-chain

Create two disposable PostgreSQL databases:

aurum_test
aurum_demo

Then:

export AURUM_TEST_DATABASE_URL='postgres://aurum:aurum_dev@127.0.0.1:5432/aurum_test'
export AURUM_DATABASE_URL='postgres://aurum:aurum_dev@127.0.0.1:5432/aurum_demo'

Run the complete verification suite:

make verify-full

That is the release-level command. It is non-interactive and intentionally exercises the real databases and local EVM.

Demos

Full system

Use this for the main presentation:

make demo

Normal mode is automatic: it never asks for confirmation. The output is concise and colorized on a terminal, and it distinguishes presentation pacing from real state waits.

For a live walkthrough where you want time to explain each subsystem boundary:

make demo-guided

Guided mode pauses only before Deposit, Trade, Withdrawal, and Reconciliation. Setup, block mining, service polling, and finality waits remain automatic.

For CI-like speed:

make demo-fast

To see the exact CLI/workflow records in addition to the human summary:

make demo-verbose

The audience-facing story is intentionally compact:

Setup
  local Ethereum + real Rust/Go services + durable checkpoint

[1] DEPOSIT
  10 GOLD: pending -> safe -> finalized -> 10 GOLD internal

[2] TRADE
  Alice sells 2 GOLD for 6,000 USDC
  custody stays at 10 GOLD because ownership changed internally

[3] WITHDRAWAL
  Bob: 2 GOLD -> 1 available + 1 reserved
  Go persists the exact signed transaction before broadcast
  after finality: Bob external 1 GOLD; custody 9 GOLD

[4] RECONCILIATION
  canonical deposit evidence + canonical withdrawal evidence
  + indexed workflow state + Rust liabilities
  findings = 0
  9 GOLD internal liability = 9 GOLD on-chain custody

The script still asserts against exact atomic-unit values internally; the normal presentation simply does not flood the terminal with those records. See docs/05-learning/03-demo-guide.md for the full narration and control model.

Exchange correctness only

No Foundry required:

make demo-exchange

It demonstrates partial fills, maker-price execution, price improvement, restart recovery, cancellation, and idempotent cancellation retry.

Deliberate failures

make demo-failure

It intentionally proves:

• Rust commits a deposit and loses the response;
• Go retries with one financial effect;
• Ethereum RPC outage freezes checkpoint and triggers backoff;
• Go restarts with a pending deposit and resumes;
• a pending deposit disappears in a shallow reorg and is never credited.

Core design rules

1. Rust owns internal money.
2. Go owns Ethereum.
3. Money is integer atomic units, never floats.
4. PostgreSQL is durable truth.
5. The matcher performs no I/O.
6. Plan before mutation; commit before in-memory apply.
7. One market has one serialized execution stream in this version.
8. Assume at-least-once delivery and unknown responses.
9. Stable business identities make financial retries idempotent.
10. Persist signed withdrawals before broadcast.
11. Reorgs are automatically handled only while financially safe.
12. Reconciliation detects; it does not silently repair.
13. Infrastructure must earn its complexity.

Repository

aurum/
├── core/          Rust domain, matcher, financial persistence, gRPC service
├── chain/         Go EVM gateway, withdrawal worker, reconciliation, CLIs
├── contracts/     minimal local-only TestGold ERC-20
├── proto/         versioned gRPC service contract
├── migrations/    Rust-owned exchange schema migrations
├── docs/          complete technical + study + presentation manual
├── scripts/       deterministic demos and invariant checks
├── Makefile       human-facing command surface
└── VERSION        1.0.0

Documentation

Start at docs/00-index.md. The documentation is deliberately organized into numbered folders and numbered files so there is one obvious reading order.

The most useful paths are:

• Start: 00-start-here/00-index.md
• Architecture: 01-architecture/00-index.md
• Exchange core: 02-exchange-core/00-index.md
• Chain gateway: 03-chain-gateway/00-index.md
• Operate and verify: 04-operations/00-index.md
• Master and present: 05-learning/00-index.md

Useful commands

make help
make version
make doctor
make doctor-chain
make fmt
make verify
make test-db
make build
make demo-exchange
make demo-failure
make demo
make demo-guided
make demo-fast
make verify-db-invariants
make verify-full
make clean

Release baseline

Aurum keeps the full Git commit history for engineering traceability, but this repository intentionally uses no Git tags. VERSION is the product-version source of truth.

make version

See docs/04-operations/07-release-and-reproducibility.md for verification status, toolchain policy, and dependency-locking notes.