Skip to content

Threat Model

This page lays out the threats joinmarket-ng aims to mitigate, the adversaries assumed in each scenario, and where those mitigations live in the codebase and documentation. It complements Security (controls summary), Privacy (cryptographic primitives), and Protocol (wire-level behaviour). When in doubt, the linked canonical page is authoritative.

Scope

joinmarket-ng targets the JoinMarket CoinJoin protocol: a multi-party Bitcoin transaction where a taker pays makers a small fee in exchange for combining inputs and producing several equal-value outputs. Linkability between inputs and equal-value outputs is the privacy property we defend.

The threat model covers:

  • the maker, taker, and tumbler runtimes,
  • the directory server and orderbook watcher,
  • the wire protocol between them, including direct maker-taker channels,
  • the wallet backends (descriptor wallet, neutrino) only insofar as they affect CoinJoin privacy and key custody.

It does not cover:

  • the security of the underlying Bitcoin node, the operating system, or the Tor binary,
  • physical compromise or coercion of an operator,
  • attacks on the user's hardware wallet firmware itself.

Assets

  • Funds. Wallet UTXOs across all mixdepths, including fidelity bond UTXOs.
  • Privacy. Lack of linkability between inputs and equal-value outputs of a CoinJoin, and between separate CoinJoin sessions.
  • Identity unlinkability. The mapping between an operator's real-world identity, network endpoints (onion addresses, nicks), and on-chain UTXOs.
  • Availability. The ability of makers and takers to complete CoinJoins in a reasonable time.

Adversaries

We assume an adversary can do at least one of:

  1. Run malicious peers as makers, takers, or both.
  2. Run or observe directory servers. Directories see offers, bonds, and peerlists.
  3. Observe network traffic outside Tor, or operate Tor relays. Hidden services are assumed not to leak server location, but exit-side traffic analysis is in scope where applicable.
  4. Observe the public Bitcoin blockchain.
  5. Combine the above to correlate on-chain UTXOs with directory data and network observations.

We do not assume the adversary has compromised the operator's wallet keys or hardware wallet directly. If they have, the protocol cannot defend funds; backups and mnemonic hygiene are out of scope here and live in Best Practices.

Threats and Mitigations

Theft of Funds

  • Threat: A malicious taker proposes a CoinJoin transaction that does not return the maker's CoinJoin output, change output, or fee.
  • Mitigation: Makers run every proposed transaction through the strict pre-sign invariants in Maker Verification Checklist. Any failed check refuses to sign. This is the most safety-critical code path; bugs here lose money directly.

Sybil Orderbook Pollution

  • Threat: One operator announces many low-quality offers to bias taker selection or starve real makers.
  • Mitigations:
    • Fidelity bonds. Bond weight raises the cost of running many identities; takers weight maker selection by bond value. See Privacy: Fidelity Bonds.
    • Bondless-zero-fee policy. Bondless offers with a non-zero absolute fee are filtered out by default (Protocol).
    • Feature stats over bonded makers only in the orderbook watcher (issue #483) so a sybil cannot skew "% of makers supporting X".

Costless UTXO Probing

  • Threat: An attacker requests CoinJoin offers from many makers, collects the UTXOs each maker reveals, and aborts. With enough repetitions they correlate maker UTXOs without paying any fee.
  • Mitigations:
    • PoDLE commitments. Takers must commit to ownership of a UTXO before makers reveal theirs (Privacy: PoDLE).
    • Rate limiting in directory and maker code paths.
    • Operational guidance to rotate mixdepths and treat revealed UTXOs as semi-public (Best Practices). See also issue #47 for ongoing mitigation work.

Subset-Sum Linkage of Equal-Output CoinJoins

  • Threat: An on-chain observer enumerates input subsets whose sum equals an equal-value output, hoping to uniquely link inputs to outputs.
  • Mitigations:
    • Equal-value outputs across multiple participants make multiple subset solutions plausible.
    • Running multiple smaller CoinJoins over time, rather than one large one, raises the cost of subset analysis (Best Practices).
    • Ongoing research in issue #114 (subset sum mitigations).

Malicious or Compromised Directory

  • Threat: A directory drops or fabricates offers, partitions the view of the orderbook, or silently censors specific makers.
  • Mitigations:
    • Multi-directory aggregation. Run the orderbook watcher against several directories and treat each one's peerlist as authoritative only for itself (Architecture).
    • Per-directory trust model. Offers are dropped from a directory when its own peerlist stops reporting the maker, rather than relying on a cross-directory union that masks censorship.
    • Direct maker reachability. The orderbook watcher actively probes maker onion addresses and signals direct reachability in the UI (issue #105) so a taker can prefer makers whose presence does not depend on a single directory.

Session Confusion and Channel Hijack

  • Threat: A peer or relay tries to mix messages from different CoinJoin sessions or replay messages from another channel.
  • Mitigations:
    • Signature binding. Every private message is signed by the sender's nick key, and the maker enforces a strict state machine so out-of-order or replayed messages are dropped. Anti-replay uses a fixed hostid (onion-network) shared by all onion transports, so a relay cannot replay a message onto an attacker-chosen channel.
    • Strict state machine. Makers only accept the expected message for the current session state.
    • Transport flexibility. A taker may legitimately switch between directory relay and a direct connection mid-session (the reference taker routes each message opportunistically), so the maker tracks but does not reject such switches (Protocol).

Network-Level Identity Linkage

  • Threat: An observer correlates an operator's network endpoint (clearnet IP, onion address) with their on-chain UTXOs or nick.
  • Mitigations:
    • Tor by default for all transport, including hidden services for makers (Security).
    • Ephemeral onion services for maker sessions when Tor control is enabled.
    • Operational guidance to anonymize fidelity bond UTXOs before locking them, since the bond UTXO is published per identity (Best Practices).

Hot Bond Key Compromise

  • Threat: A maker's hot wallet is compromised; the attacker uses the bond key to impersonate the maker.
  • Mitigations:
    • Bond locktime bounds the damage window: impersonation lasts only until bond expiry; spending the bond requires the bond's private key, not the hot wallet's signing key alone, when using a dedicated bond mnemonic (Privacy).
    • Best practice: use a dedicated mnemonic for hot bonds so a hot-wallet compromise does not expose main-wallet funds.

Denial of Service

  • Threat: Spam connections or message floods overwhelm a directory or maker.
  • Mitigations:
    • Rate limiting and message validation in directory and maker paths (Security).
    • PoDLE commitments also raise the cost of one specific DoS vector (probing every maker without paying).

Out-of-Scope but Important

  • Operating-system and Bitcoin-node security. A compromised Bitcoin node can lie to your wallet about UTXOs and feerates. Run a node you trust.
  • Mnemonic and bond backup. The protocol cannot recover funds lost to a missing mnemonic. See Best Practices.
  • Hardware wallet firmware. Where a hardware wallet cannot sign bond redemptions (Trezor, Coldcard, BitBox02, KeepKey today), the bond is effectively a hot bond. See Privacy for the support matrix.
  • External services: mempool.space, neutrino backends, and third-party Tor relays. Pick infrastructure you trust and pin TLS where available (Neutrino TLS).

Disclosure

Security issues should be reported through the channels documented in the repository's SECURITY.md (tracked in issue #117 until published). Do not file public GitHub issues for unpatched vulnerabilities affecting funds.