# Multisig HSM — a distributed, policy-enforced 2-of-3 threshold signer

**An automated treasury tier that signs its own cold→hot refills under on-device policy — with no human
in the loop, and no single machine able to move a satoshi.**

Three hardware signers (Coldcards in HSM mode), each on a separate host — ideally a separate site. A
**keyless** coordinator builds the refill transaction and fans it to any two of the three. Each device checks
the transaction against **its own on-device spending policy** (per-transaction cap, velocity limit, address
whitelist) and auto-signs or refuses. The signed refill broadcasts to your hot wallet. Lose any one signer
and refills carry on; lose two and funds simply freeze — safe by design.

The novel combination is **threshold + per-device programmable policy + unattended auto-signing** — an
automated treasury with cryptographic, physically-distributed guardrails, where the coordinator holds no keys
and the hardware is the final authority.

> 🔭 **Live reference deployment:** a working 2-of-3 runs on real Bitcoin **signet** at
> **[multisighsm.mineracks.com](https://multisighsm.mineracks.com)** — every spend is a genuine on-chain
> co-signature, and every policy decision is inspectable on a public explorer. *Simulators + signet only;
> never a real seed, no real funds.*

---

## Two ways to use this

### 1 · Run it yourself — open source
Everything you need to build and operate this is in here: the **full recipe book**
([`docs/OPERATOR-MANUAL.md`](docs/OPERATOR-MANUAL.md) + [`docs/QUICK-START.md`](docs/QUICK-START.md)), the
reference coordinator + signing code ([`reference/`](reference/)), and a signer-host bootstrap
([`ansible/`](ansible/)). MIT-licensed — fork it, run it, harden it.

If it's useful to you, **support the project with sats** ⚡ — Lightning address
**`multisighsm@mineracks.com`** (self-hosted, no middleman). Thank you.

### 2 · Get a helping hand — mineracks consultancy
Standing this up for a **business treasury, exchange, or fund** and want it done right? **mineracks** offers
guided design + execution: failure-domain placement, policy/velocity sizing, the signer-agent + coordinator
deployment, backup/DR rehearsal, and an operations runbook tailored to you.

> **What we do *not* do — by design:**
> - **We do not supply the Coldcards.** You buy your own hardware, direct from the manufacturer.
> - **We never see, hold, or generate your keys or seeds.** They are created on *your* devices, by *you*,
>   and never leave their secure elements. Our work is the architecture, policy, and operations *around*
>   your hardware — never the key material itself.

📧 **[hello@mineracks.com](mailto:hello@mineracks.com?subject=Multisig%20HSM%20consultancy)** ·
📅 **book a call: [calendar.mineracks.com](https://calendar.mineracks.com)**

---

## What's in here

```
docs/        OPERATOR-MANUAL.md — the full security model + setup + operations guide
             QUICK-START.md     — the one-page provisioning + on-call checklist
reference/   The coordinator (orchestrator.py) + wallet/HSM/signing scripts and the
             simulator demo rig — the working reference behind the live signet demo
ansible/     Signer-host bootstrap skeleton (Tailscale + ckcc-protocol + signer agent)
config.example.env   Copy to .env and fill in your node RPC details
```

## Quick start (read the manual first)
1. Read [`docs/OPERATOR-MANUAL.md`](docs/OPERATOR-MANUAL.md) §1–§3 — the **safety model is not optional
   context**; it is the reason the design is shaped the way it is.
2. **Do the whole provisioning run on signet/testnet first.** Only move to mainnet after you have rehearsed
   a refill, a failover, a policy change, and a restore-from-backup.
3. `cp config.example.env .env` and set your watch-only node's RPC host/credentials.
4. Build the `wsh(sortedmulti(2,k1,k2,k3))` descriptor from **your own** three signer xpubs, register it on
   each Coldcard, load each device's HSM policy, and start the coordinator.

## You bring
- **3× Coldcard Mk5** (or Q) — bought by you, direct from Coinkite. HSM mode + multisig co-signing are
  supported in firmware.
- **3 distinct seeds**, generated on the devices, steel-backed, geographically separated. Never in this repo,
  never on the coordinator.
- A watch-only-capable **Bitcoin full node** (descriptor wallets).

## Security & disclaimers
- This repository contains **no keys, no seeds, and no secrets.** The reference code reads any secret material
  from local files / environment at runtime (see [`.gitignore`](.gitignore)); the placeholders
  (`tpubREPLACE_WITH_YOUR_SIGNER_n_XPUB`, the policy whitelist address) **must** be replaced with your own.
- The reference deployment uses Coldcard **firmware simulators** on **signet** — for functional validation,
  not custody. **Never hold mainnet value on a single host running more than one signer.**
- *Coldcard® is a trademark of Coinkite. This is an independent project, not affiliated with or endorsed by
  Coinkite.* Built by **[mineracks](https://mineracks.com)**.

## License
[MIT](LICENSE).