Transaction Flow

This document describes the common transaction flow that applies across all supported chains (BTC, BCH, ETH, XRP). For chain-specific details, see the documentation under docs/chains/.

Architecture Overview

The system uses three wallet types running on separate machines:

Wallet	Environment	Role
Watch Wallet	Online	Creates unsigned transactions, broadcasts signed transactions, monitors status
Keygen Wallet	Offline (air-gapped)	Generates keys and addresses; sole signer for single-sig transactions
Sign Wallet	Offline (air-gapped)	Provides additional signatures for multisig transactions only

Single-sig vs Multisig wallet requirements:

• Single-sig: Only Watch + Keygen wallets are needed. The Sign Wallet is not required.
• Multisig (M-of-N): All three wallets are used. Keygen provides the first signature; Sign Wallet(s) provide the remaining signatures.

Key design principles:

• Only Watch Wallet connects to the network — Keygen and Sign Wallets are always offline
• Transaction files are transferred between machines via secure offline methods (e.g., USB drives)
• Each wallet maintains its own independent database

---

1. Setup Flow

Before sending any transaction, each wallet must be initialized and addresses must be shared with Watch Wallet.

Single-sig Setup

Multisig Setup (BTC / BCH / XRP)

ETH Note: Ethereum Safe multisig does not use BIP32 multisig address derivation or fullpubkey exchange. Instead, a Safe smart contract is deployed on-chain with a list of owner EOA addresses. See ETH Safe Multisig Setup below.

ETH Safe Multisig Setup

Ethereum multisig is implemented via Gnosis Safe v1.4.1. Each owner is a regular EOA. Setup requires deploying a Safe proxy contract on-chain with the owner list and threshold.

---

2. Transaction Operation Flow

Single-sig Flow

Used when the address is controlled by a single key (Keygen Wallet only).

Multisig Flow (BTC / BCH / XRP — M-of-N)

Used when the address requires multiple signatures. Signing is repeated until the required threshold M is met.

ETH Note: Ethereum Safe multisig uses a different signing flow. See ETH Safe Multisig Flow below.

Note: The signing loop continues until isCompleted: true is returned. For a 2-of-3 multisig, only 2 signatures are needed; Sign Wallet 2 can be skipped once the threshold is met.

ETH Safe Multisig Flow

Ethereum multisig uses Gnosis Safe v1.4.1. Key differences from BTC-style multisig:

• Proposal: Watch Wallet calls watch create multisig (not create deposit/payment/transfer) to produce an unsigned JSON proposal file containing an EIP-712 safeTxHash
• Signing: Each signer calls sign signature --signer-address (keygen or sign wallet). The wallet recomputes the safeTxHash offline from the file fields and appends a 65-byte EIP-712 signature
• Submission: Watch Wallet calls watch send multisig send-eth which passes the packed signatures to execTransaction on the Safe contract — not eth_sendRawTransaction
• File counter: Each signing step writes a new file with an incremented counter (_0.json → _1.json → _2.json)

For full details see docs/chains/eth/multisig.md.

ETH MPC-TSS Flow (Pattern 4: 2-of-3 Threshold Signing)

Ethereum MPC-TSS uses threshold ECDSA (tss-lib) where N nodes each hold a key shard — no single node ever holds the full private key. Key differences from Safe multisig:

• Setup: A one-time DKG ceremony produces key shards (one per node) and a shared ETH address
• Signing: Watch Wallet coordinates signing over gRPC — signing nodes receive the tx hash and return partial signatures; no file transfer between wallets
• Broadcast: Watch Wallet reconstructs the full ECDSA signature and broadcasts the raw transaction

MPC Setup Flow (one-time DKG)

MPC Transaction Flow

For full details see docs/chains/eth/transaction-patterns.md.

---

3. Transaction Types

All transaction types follow the same signing flow above. They differ only in how Watch Wallet selects UTXOs/sources and destinations.

Type	Description	Typical Signing
Deposit	Consolidates funds received at client addresses into a managed cold wallet address	Single-sig or Multisig
Payment	Sends funds to an external address based on a withdrawal request	Multisig (recommended)
Transfer	Moves funds between internal accounts (e.g., deposit → payment account)	Single-sig or Multisig

---

4. Monitoring Flow

After broadcasting, Watch Wallet tracks confirmation status automatically.

Transaction Status Lifecycle

TxTypeSent ──(confirmations >= threshold)──> TxTypeDone ──(notified)──> TxTypeNotified

---

5. Security Model

Principle	Description
Network isolation	Keygen and Sign Wallets never connect to the internet
Private key separation	Watch Wallet holds no private keys; it only works with public addresses
Multisig	Multiple independent offline machines must cooperate to authorize transactions
Offline file transfer	Transaction files move between machines via physically controlled media
Role separation	Key generation, transaction signing, and broadcasting are handled by distinct wallets

---

Chain-Specific Documentation

For chain-specific details (address formats, transaction formats, signing algorithms, etc.), see:

Chain	Documentation
Bitcoin (BTC)	docs/chains/btc/operations/wallet-flow.md
Bitcoin Cash (BCH)	docs/chains/bch/README.md
Ethereum (ETH)	docs/chains/eth/README.md
Ripple (XRP)	docs/chains/xrp/README.md