94 lines
5.5 KiB
Markdown
94 lines
5.5 KiB
Markdown
# 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.**
|
||
|
||
> **New to the term "HSM"?** A *Hardware Security Module* is a dedicated, tamper-resistant device that holds a
|
||
> private key and signs with it **on the device** — the key is generated inside the chip and can never be
|
||
> extracted, even by the computer it's attached to. Banks and certificate authorities have relied on HSMs for
|
||
> decades to keep signing keys out of reach of a compromised server. Here, each of the three signers is a
|
||
> **Coldcard running in HSM mode**, and a spend needs two of them to independently approve it under policy.
|
||
|
||
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.com](https://multisighsm.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.
|
||
|
||
📧 **[info@mineracks.com](mailto:info@mineracks.com?subject=Multisig%20HSM%20consultancy)** ·
|
||
📅 **book a call: [calendar.mineracks.com/piers](https://calendar.mineracks.com/piers/)**
|
||
|
||
---
|
||
|
||
## 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).
|