Architecture

Coldtill is one static Go binary with the React dashboard embedded. It runs as four processes that share a PostgreSQL database and never call each other directly.

flowchart LR
  customer[Customer browser] --> caddy[Caddy TLS]
  shop[Merchant backend] --> caddy
  caddy --> api
  api --> pg[(PostgreSQL)]
  watcher --> pg
  sweeper --> pg
  payouts --> pg
  watcher --> rpc[RPC nodes]
  sweeper --> rpc
  payouts --> rpc
  watcher --> hooks[Merchant webhooks]
  api --> swap[Swap providers]

The split matters for security: the process exposed to the internet (api) holds no private key, and the processes that hold keys accept no network connections. See Security.

Source layout

Data model

The main tables, simplified:

• projects: settings, branding, sweep thresholds, payout limits, auto-convert options.
• customers: one row per merchant customer ID within a project.
• customer_addresses: each customer's permanent deposit address per chain family, with its derivation index.
• payments: amount in USD, status, filled and pending USD, expiry. A customer has at most one open payment.
• deposits: every incoming transfer, with block number, confirmations and status (pending, confirmed, orphaned).
• deposit_wallets: per project and family, the cold wallet, factory or program config, and per-network deployment state.
• sweeps and sweep_addresses: batched sweep transactions and the addresses they covered.
• hot_wallets: encrypted keys. project_hot_wallets assigns them to projects.
• payouts and address_book: outgoing payments and approved destinations.
• conversions: auto-convert swaps, their quotes, provider status and verified delivery.
• webhook_endpoints and webhook_deliveries: endpoints with sealed secrets, and the delivery queue.
• rpc_nodes and networks: node pools and per-network settings (confirmations, enabled, last processed block).
• audit_log: who did what, for every sensitive dashboard action.

Payment lifecycle

1. Create. POST /api/v1/payment upserts the customer and replaces their previous open payment, unless that payment has a deposit still confirming, in which case the request is refused with 409.
2. Address. When the customer picks a chain at checkout, Coldtill assigns their permanent address for that family, deriving it if needed. EVM addresses are counterfactual: the contract is only deployed when the first sweep needs it.
3. Detect.
   • EVM: the watcher scans blocks in bounded ranges for ERC-20 Transfer logs to watched addresses, and periodically reconciles native balances.
   • Solana: the watcher polls signatures for each deposit address and reads token balance changes on the canonical token account.
   • Bitcoin: the watcher polls Esplora for each watched address.
4. Confirm. Deposits become confirmed after the network's configured confirmations, with block hashes re-checked. A deposit whose block disappears in a reorg goes back to pending; one whose transaction vanishes is orphaned and reversed.
5. Fill. Confirmed USD is compared with the amount owed, with a 1% tolerance: PARTIALLY_FILLED, FILLED or OVER_FILLED. Prices come from CoinGecko with Coinbase as fallback; stablecoins count as $1.
6. Notify. Every change queues a webhook. Closing a payment sends exactly one final event.
7. Expire. Open payments past their expiry (24 hours by default) become CANCELLED. Late deposits still count toward the filled amount, but don't reopen the payment.

Sweeps

The sweeper runs per project and network:

1. It lists deposit addresses holding at least the project's activation minimum in confirmed, unswept value.
2. It sweeps when any trigger fires: the total reaches the sweep amount ($100 by default), enough addresses hold funds (20), or the oldest unswept deposit has waited the sweep interval (24 hours). Gas must also be a small enough share of the value, and a failed sweep backs off for 10 minutes.
3. EVM: a single transaction to your factory deploys any missing deposit contracts and flushes each one. Tokens that fail to transfer emit FlushFailed; those addresses stay unswept and are retried later.
4. Solana: a transaction with one sweep_sol or sweep_token instruction per account, sized to fit the 1232-byte limit. The canonical token account is always swept; at most three other token accounts worth at least $1 each are included, so dust accounts can't block a sweep.
5. Every sweep is signed and stored before it's broadcast, then tracked until it's confirmed, replaced or failed.

Payouts

Payouts are created by the dashboard or the API, checked against limits and the address book, held for approval if needed, then picked up by the payouts process. It signs, stores, broadcasts, fee-bumps and confirms. See Payouts.

Nonces and shared hot wallets

The sweeper and payouts processes can share an EVM hot wallet. Nonces are reserved under a Postgres advisory lock per wallet and network, inside the same transaction that stores the signed transaction. If a transaction fails permanently while a later nonce is already in flight, Coldtill fills the gap with a zero-value self-transfer so the later transaction can still be mined.

Node pools

Each network has a pool of RPC nodes (Esplora for Bitcoin). The preferred node is tried first, and a failing node is skipped for a cool-down period. A health loop probes every node so the dashboard can show status and the last processed block. URLs are redacted in errors, since providers often embed API keys in them. Decisions where one node's word isn't enough ("this payout never landed", "this Bitcoin deposit was dropped") ask every node.