Coldtill threat model

What we protect

Trust boundaries

1. Internet to Caddy to api. The api process holds no private keys. It can create payouts, but it cannot sign them.
2. api to Postgres to payouts and sweeper. These communicate only through the database. A compromised api can write rows, but signing processes re-check everything they need (see below).
3. Coldtill to RPC nodes. Nodes are untrusted for anything that moves money. Chain IDs are signed into EVM transactions, and Solana genesis hashes are pinned.
4. Coldtill to the merchant's browser wallet. Factory deployment and Solana config initialisation are signed in the merchant's wallet. The server never sees those keys.

Key design decisions

• Funds cannot be redirected, even by a fully compromised server.
  • The EVM DepositFactory stores the cold wallet as an immutable, and deposit addresses are CREATE2 clones of an implementation that can only flush to it.
  • Solana deposit PDAs can only be swept to the treasury in their config, which is enforced by has_one, and there is no instruction that changes it.
  • Bitcoin addresses come from the merchant's xpub, so the server never holds a Bitcoin key.
• The hot key's blast radius is its own balance. Keep the float small: roughly a week of gas plus expected payouts.
• Payout controls (all server-side):
  • per-project auto-approve amount, a minimum, and hourly and daily limits counted across the whole project (every user and API key, in-flight payouts included);
  • an address book that can only be edited in the dashboard with 2FA;
  • admin approval needs 2FA plus a one-time code emailed to that admin, at most 5 attempts, valid for 10 minutes and bound to the payout;
  • idempotency keys;
  • signing and persisting happen before broadcast, so a crash cannot double-send;
  • fee bumps reuse the same nonce, recipient and amount;
  • a payout is only marked failed once it provably can't land; when Coldtill can't tell, it becomes needs-review for a human to resolve with 2FA.
• Nonce safety. The sweeper and payouts processes share hot wallets. Nonces are reserved under a Postgres advisory lock on the wallet address, inside the transaction that stores the signed transaction. If a lower nonce is abandoned while a higher one is in flight, the gap is filled with a zero-value self-transfer.
• Address checks.
  • EVM addresses are EIP-55 validated. A lowercase address is accepted, but a wrong mixed-case checksum is rejected.
  • Solana payouts to token accounts are refused (funds would be stranded), and native transfers below rent-exemption to new accounts are refused.
  • Deposit addresses are re-derived from the xpub, factory or program, and cross-checked when wallets are set up.

Threats and mitigations

Residual risks

• R1. DB write access can approve payouts. Approval state lives in Postgres, which the payouts process trusts. Mitigations:
  • keep the hot float small;
  • keep Postgres private (it is not exposed by the compose file);
  • consider a separate DB role for payouts with read access to configuration.
• R2. Swap providers (auto-convert) hold customer funds for the duration of a swap. A provider that fails to deliver or refund loses the customer's money, not the merchant's: the payment is never credited without an on-chain delivery. Auto-convert is off by default, and THORChain is a separate opt-in.
• R3. Bitcoin deposits depend on the merchant's xpub being correct. Coldtill checks the first derived address against the merchant's own wallet during setup.
• R4. EIP-6780 and future EVM changes. If SELFDESTRUCT stops clearing code, clones persist. They are then flushed in place, which is still safe but less gas-efficient (covered by test_persistedCloneIsFlushedInPlace).
• R5. Deposits trust the answering node. Coldtill doesn't require several nodes to agree before crediting a deposit, so a malicious node could report a fake one. Use your own or paid nodes from several providers, and check large orders on a block explorer before shipping.
• R6. Admins can approve their own payouts. Single-admin installs need this. Teams should agree that someone else approves.
• R7. Underpayment tolerance. A payment within 1% of the amount counts as filled, to absorb wallet rounding and fees.
• R8. Batched swap deliveries. A provider that delivers several conversions in one transaction gets a mismatch on the later ones, which an operator resolves by hand.
• R9. In-memory 2FA lockout. The lockout resets if the api process restarts. Login rate limits still apply.