ling-wallet

# ling-wallet threat model

What LNG protects against, what it doesn't, and what is up to you. Read
this before trusting it with anything you can't afford to lose: **LNG is a
new, unaudited, experimental coin.**

## Who we assume is attacking

| Adversary | Capabilities we design for |
|---|---|
| Passive network observer (ISP, backbone tap) | Sees all packets to/from your machine: IPs, timing, sizes |
| Active network attacker | Can drop, delay, modify, inject, redirect traffic; run many fake nodes |
| Malicious peers | Send malformed data, lie about the chain, try to isolate you (eclipse) |
| Blockchain analyst | Reads the entire chain forever, correlates with exchange/KYC data |
| Quantum adversary (future) | Breaks X25519 / elliptic curves; records traffic today to decrypt later |
| A party you've paid, or who paid you | Knows details of the transactions they took part in |

## Out of scope (no software can fix these)

- **Malware on your computer.** If an attacker controls your machine they
  can read keys as you type your password. Use a dedicated, updated,
  full-disk-encrypted machine.
- **Physical coercion or legal compulsion.**
- **A brand-new chain's small crowd.** Ring signatures hide your coin among
  others *of the same denomination*. While few people use LNG, there are few
  others to hide among. The wallet flags "reduced ring" spends.

## What is protected, and how

### Your keys
- Master seed encrypted with **Argon2id (256 MiB, 3 passes)** + XChaCha20-Poly1305;
  no plaintext balances or history on disk (re-derived by scanning).
- Secrets zeroized after use; wallet auto-locks; password re-checked before every spend.
- **[standard]** ML-DSA-87, ML-KEM-1024, X25519, XChaCha20-Poly1305, SHA-3, Argon2id.

### Who you pay / who pays you (receiver privacy)
- Every output goes to a fresh **one-time key** derived through a hybrid
  **X25519 + ML-KEM-1024** exchange. Outsiders can't tell two outputs go to
  the same address, now or after quantum computers (both halves must break).

### Which coin you spent (sender privacy) — **[experimental]**
- Each input is signed with an **LRS-87 lattice ring signature** over 11
  same-denomination outputs; key images stop double-spends.
- **Known leak — sender tracing:** whoever *paid you* can recognize when you
  later spend the coins they sent (the key image is linear in a value the
  payer knows). They learn *when* and *in which transaction*, not where the
  money went. Nobody else learns this. A fix needs a non-linear lattice key
  image (open research); a "linear but per-output" variant was rejected
  because it would let a payer recover your spend key.
  *Mitigation today:* after receiving from someone you don't trust, send the
  coins to yourself once ("churn"); the payer then only sees the churn.
- **Linkability gap:** a sufficiently strong lattice attacker might create a
  second key image for one output (double-spend). Bounded by the consensus
  supply-audit rule (key images per denomination ≤ outputs) and visible in
  the wallet's Supply Audit panel.
- No independent cryptanalysis yet.

### Amounts
- Every output is a standard denomination (1, 2, 5 × 10ⁿ). Amounts are
  public per output but a payment's total isn't (outputs aren't linked to
  each other). Post-quantum hidden amounts need lattice range proofs, which
  aren't practical yet.

### The network
- **Mutually authenticated hybrid PQ handshake** (X25519 + ML-KEM-1024,
  ML-DSA-87 signatures) — "harvest now, decrypt later" doesn't work.
- XChaCha20-Poly1305 frames inside a DICE-42 layer, **padded to fixed
  buckets** with **cover traffic**, so sizes and idle periods reveal little.
- **Dandelion++**: your transactions *and your address publication* first
  travel a random stem before broadcast, hiding which node created them.
- **Tor/SOCKS5** for all outbound connections; no DNS leaks.
- **Eclipse resistance:** signed seed list (compiled-in ML-DSA-87 authority
  key — a tampered list is ignored), seed identities pinned (no silent
  re-learning), outbound peers from distinct network groups, anchors, ban scores.
- Outbound connections use **ephemeral identities** by default, so your node
  can't be tracked across IP changes.

### Sending to the right person
- Short addresses (`lng1…`) are **hashes of the full key bundle** with a
  checksum; the bundle is **ML-DSA-87 signed**. A peer can refuse to serve a
  bundle but cannot forge or swap one. The wallet shows the recipient's
  fingerprint + identicon before you confirm — compare it with them over a
  second channel.

### Mining
- **HyperTorus [novel]** PoW ends in SHAKE256, so a flaw in the walk could
  at worst speed up mining; it can't forge or steal anything.

## Your checklist

1. Dedicated machine, full-disk encryption, updates on, nothing else installed.
2. Run Tor and start the wallet with the SOCKS5 proxy setting.
3. Write the 24 words on paper; store them somewhere physically safe; never photograph them.
4. Use a long unique password.
5. Compare recipient fingerprints out of band before large payments.
6. Don't link LNG to identity-verified exchanges; don't reuse addresses publicly.
7. Churn coins received from parties you don't trust.