Quickstart

Local demo (no Bitcoin needed)

Runs a 3-member cluster on one machine with pretend balances, no bitcoind required:

coalesce-node init -dir ./demo -nodes 3 -base-port 9000 -balance 100000000

Then, in three separate terminals:

coalesce-node run -config ./demo/node0.json
coalesce-node run -config ./demo/node1.json
coalesce-node run -config ./demo/node2.json

At any node's prompt:

> bal
> send node1 5000
> propose
> bal
> quit

Real flow, on signet

This needs a running bitcoind -signet and a funded wallet. See Installation. You can't literally run a multi-party cluster alone, but these are the real commands, and this is what an actual session looks like.

1. Bootstrap the cluster

Every member runs bootstrap with the same -peers list. It exchanges public identity bundles over authenticated connections (no private key ever crosses the wire, no manual file copying) and continues straight into running your node, with no separate run step.

export COALESCE_BTC_NET=signet
export COALESCE_BTC_HOST=localhost:38332

coalesce-node bootstrap -dir ./me -addr 1.2.3.4:9000 \
  -peers "1.2.3.4:9000,5.6.7.8:9001,9.10.11.12:9002" \
  -wallet mywallet -enforce

-enforce (self-protection, recommended) is safe to pass now; it activates automatically once the cluster is funded. Forgot -wallet? Type attach-wallet <name> at the prompt later, no restart needed.

2. Generate the group key

Once everyone is running, any member types:

> keygen

Dealerless: no machine ever holds the full key. Each node restarts itself automatically to load its share. See Concepts: Dealerless Keygen.

3. Fund the cluster

Every member independently types dfund <sats> with whatever amount they want to commit (any value up to their wallet balance). Your payout destination defaults to this same wallet; override with dfund <sats> [fee] <address>.

> dfund 5000000

Once every member has run dfund, each node restarts automatically into the funded channel.

4. Transact

> bal
> send bob 250000

Checkpoints finalize automatically (propose forces one early). See Concepts: Checkpoints.

5. Close cooperatively

> coopclose

Everyone co-signs one closing transaction; the full settlement prints before broadcasting, and your node reports your final payout once it confirms. The cluster is then permanently closed: bal shows the final on-chain payouts, further sends/closes are refused, and this survives restarts.

Other ways to form a cluster

Method	When	Trade-off
`bootstrap -discover -want <n> [-room <name>]`	You don't know the other members	Proves key ownership via signed challenge-response, not real-world identity; see Guides: Discovery
`identity` + `assemble`	You want to inspect every bundle yourself, or you're air-gapped	Manual file passing; same no-shared-private-keys property
`init -distributed -hosts ...`	One trusted operator sets up everyone (demos)	That machine transiently holds every member's identity key

These produce config files only. Start your node afterward with coalesce-node run -config nodeI.json -wallet mywallet -enforce. See CLI Reference for every flag.

On this page