Bitcoin for Builders Lightning and Fedimint

Fedimint: federations, ecash and guardians

How a group of guardians can hold bitcoin together and issue private ecash, and where Lightning gateways fit in.

45 minIntermediate5 / 8

Draft: this lesson is still waiting for review.

What you'll learn

Explain what a federation, a guardian and a gateway do
Describe how blind signatures make ecash private
Weigh the trust trade-offs of a federation against self-custody and custodial wallets

Key terms

Fedimint: Open-source software that lets a community run a federation that holds bitcoin together and issues ecash.
federation (shirikisho): A group of guardians who hold bitcoin together; most of them must agree before money moves.
guardian (mlinzi): A member of a federation who runs a server and holds part of the keys.
ecash: Digital notes that stand for bitcoin held by a federation. Payments with them are private.
multisig: A setup where several signatures are needed to spend bitcoin, for example 2 of 3.

The savers path introduced Fedimint as community custody. This lesson looks at how it works underneath, so you can build on it.

Step 1: The parts

Part	Role
Guardians	Run the federation's servers, hold key shares and agree on every state change
Federation	The guardians together: a multisig wallet plus a mint
Ecash notes	Bearer tokens users hold, each worth a fixed number of millisats
Gateway	A Lightning node that swaps ecash for Lightning payments, in both directions
Client	The user's app, which stores ecash notes and talks to guardians and gateways

Step 2: Consensus

Guardians run a Byzantine-fault-tolerant consensus. With n guardians, the federation keeps working as long as fewer than a third are faulty: four guardians tolerate one bad or offline guardian, seven tolerate two. Every deposit, note issuance and withdrawal is agreed by the threshold before it happens.

Done when: you can say how many faulty guardians a federation of 10 tolerates. (Answer: 3.)

Step 3: Why ecash is private

When you mint ecash, your client blinds a random note before sending it to the guardians to sign, like putting it in a carbon-lined envelope. The guardians sign without seeing the note. Later, when anyone redeems it, the guardians can check their signature is valid but can't link it to the moment it was issued. That is the classic Chaumian ecash idea, run by a federation instead of a single bank.

Step 4: Money in and out

Peg-in: a user deposits on-chain bitcoin to the federation's multisig address and receives the same value in ecash, minus fees.
Peg-out: the user hands back ecash and the federation pays on-chain.
Lightning: to pay an invoice, the client gives ecash to a gateway, which pays the invoice from its own channels. To receive, the gateway is paid over Lightning and hands the user ecash. A contract makes sure the gateway is only paid if it actually completes the payment.

Lab

Clone the Fedimint repository and read its README and module list. Find the code for the mint, the on-chain wallet and Lightning.
Draw a diagram of a four-guardian federation with one gateway, and trace a Lightning payment from a user's ecash to a shop's invoice.
If you want to run one locally, follow the development setup in the repository's docs; it starts a test federation on regtest.

Lab evidence

Your diagram, with the peg-in, ecash and Lightning flows labelled.
The fault tolerance of federations with 4, 7 and 10 guardians.

Reflect

Write your answer down, or talk it over with a friend or your chama.

Which people in your community would make good guardians, and what would you ask them to promise?
What would a federation of four guardians do if one went offline? If two did?