Architecture
Observe-only by construction
The core invariant: the app never signs, never custodies, never moves funds. It builds a payment
request for the merchant's address and watches the chain for settlement. Every rail fails closed on an
unreachable or unparseable endpoint, and settles each invoice exactly once.
1 The money never touches the app
CUSTOMER CRYPTO-POS TERMINAL MERCHANT WALLET
(their wallet) (this app — holds NO keys) (merchant controls keys)
| | |
| cashier rings up a sale | |
| <---- scans payment QR -------- | builds a standards URI |
| BIP-21 / Solana Pay / | for the MERCHANT address |
| EIP-681 | |
| | |
| -------- pays on-chain ------------------------------------> |
| | |
| | WATCHES the chain (read-only) |
| | keyless watcher / view-key |
| | <----- settlement confirmed ----|
| | |
| | books the sale + prints receipt
| | (fail-closed, idempotent) |
The app cannot spend, refund, or move funds. It only observes.
2 The payment state machine
+--------+ generate QR +-------------------+
| IDLE | ---------------> | AWAITING PAYMENT |
+--------+ +---------+---------+
^ | tx seen in mempool
| cancel / new sale v
| +-------------------+
| | MEMPOOL DETECTED |
| +---------+---------+
| | included in a block
| v
| +-------------------+
| | CONFIRMING | count confs vs a trusted tip
| +----+---------+----+
| enough confs | | unreachable / wrong amount / expiry
| +-----------+ +-----------+
| v v
| +--------------+ +--------------+
+----- | CONFIRMED | | FAILED |
settle | settle ONCE, | | fail closed, |
then idle | write 1 row | | no ledger row|
+--------------+ +--------------+
3 One router, six rails, one settlement chokepoint
+------------------------------+
| initiateCheckout (router) |
+--------------+---------------+
+-----------+----------+-------+-------+----------+-----------+
v v v v v v
+---------+ +----------+ +---------+ +----------+ +---------+ +-----------+
| BTC/SOL | | EVM | | Monero | | Ootle L2 | |Minotari | | (demo |
| keyless | | Wallet- | | view-key| | indexer | | L1 view-| | stub if |
| watcher | | Connect | | subaddr | | receipt | | key gRPC| | unconfig)|
+----+----+ +----+-----+ +----+----+ +----+-----+ +----+----+ +-----+-----+
+----------+---------+--------------+----------+-----------+
|
every rail fails closed; settles ONCE
v
settleActiveInvoice -> SettlementMath -> Room ledger (+ CSV)
4 Going live is a checklist, not a switch
tap MAINNET --> GO-LIVE CHECKLIST --> all accepted rails READY? --> type "MAINNET" --> LIVE
per-rail status: | no (typed confirm,
READY / exact blocker v unchanged hard gate)
switch off rails you Continue DISABLED
don't sell yet (fails closed)
5 The Tari Ootle L2 retail contracts (settlement / loyalty / refund)
Generated from the on-chain template design docs. The app only
reconciles these — refunds pay the buyer directly; the terminal never moves funds.
Package map, the full settle-gate rules per rail, and the test layout
live in the engineering docs:
ARCHITECTURE.md ·
RAILS.md ·
INVARIANTS.md.
