Leader Fedimint Setup Guide
Fedimint Guardians have to run a 'setup ceremony' to generate their keys and start the Fedimint consensus. This ceremony is a one-time process required to start the Fedimint, and is the only time that the guardians will need to be online at the same time. Once the ceremony is complete, Guardians can simply leave the server running with no further intervention required, just monitoring to ensure that it's online and healthy.
The setup ceremony follows a leader-follower model: the Setup Leader inputs the consensus configuration parameters like Name, Block Confirmations, etc, and kicks off the ceremony. The followers join the ceremony and verify the leader's configuration. There is no functional difference between the leader and the followers, and the leader can be any of the guardians. The leader is simply the first guardian to join the ceremony and inputs the consensus settings.
Here's a 2 minute end-to-end video of the setup ceremony as the Setup Leader, using a SimpleX group chat to coordinate among the gaurdians. We'll walk through it step by step below.
Leading the Setup Ceremony
The setup ceremony is a one-time process that is required to start the Fedimint where you'll connect the guardians and generate the keys for the Fedimint. Before getting started, make sure that:
- Each guardian has their server provisioned and is on the Guardian Setup Page.
- You have a secure way to communicate with each other like Signal or SimpleX. You'll need to share verification codes with each other to complete the ceremony as a check that you're all safely connected before kicking off the consensus.
- The setup leader has the meta configurations for the Federation ready to go. For a complete list of Fedi's supported meta fields, see Fedi's Meta Fields.
Confirm all guardians are ready to run the ceremony!
A big problem we've seen is that the leader starts the ceremony before the other guardians are ready to join. This can cause the ceremony to fail and require you to start over. Make sure that the other guardians are ready to join the ceremony before you start! Remember, the key generation is a synchronous process, so you'll all need to be online at the same time to complete the ceremony.
Best practice is to use a group chat like Signal or SimpleX to coordinate the ceremony. The leader should send a message to the group chat to make sure that everyone is ready to join the ceremony before starting.
Input the Federation Consensus Metadata
The only real difference between the leader and the followers is that the leader inputs the consensus metadata, which gets verified by the followers. These are the parameters that will be used to configure the Fedimint consensus. The leader should input the following parameters:
- Guardian Name and Password: The name and password of the guardian. This should be a unique name that identifies the guardian, and a strong password that is kept secret. The password is used to encrypt the guardian's private key, so it should be kept secret and not shared with anyone.
The password is not recoverable, so if you lose it you won't be able to access your fedimint guardian server!
- Federation Name: The name of the federation. This should be easily identifiable by your community.
- Bitcoin Network and RPC: The Bitcoin network that you're running on and where to get block data from. Clovyr defaults to mutinynet for the network and the Mutinynet.com Esplora API for the RPC, but you can change this to mainnet and your own Explora API if you're running on mainnet. Clovyr CAN support running pruned or full bitcoin nodes for Fedimint, if you're interested in this please let us know by emailing k@fedi.xyz!
- Block Confirmations: Fedimint's Peg-In mechanism for onchain deposits cannot handle block reorganizations, Fedimint's
consensus_block_heighttrails the chain tip by some number of blocks to minimize the risk of reorganizations. If you're running on Mutinynet or another Signet it's fine to leave this at 3+ blocks.
If you're running on Mainnet with real Bitcoin, NEVER set block confirmations below 6 blocks, and we recommend 10 by default. It is extremely risky and may result in peg-in deposits being reorged, causing the fedimint to go fractional reserve.
- Number of Guardians (including the leader!): Fedimint supports running in Solo mode with 1 guardian (not recommended for production or with mainnet), or with 4+ guardians. We recommend Byzantine Fault Tolerant consensus sizes so 4, 7, 10, etc., based off what works best for **YOUR** community. Fedimint currently does not support dynamic resizing or removing guardians of the federation after setup, so you'll need to start with the number of guardians that you want to run with long term.
6. Meta Fields
These are optional fields that you can use to add additional metadata to the federation like a chat server, a Federation Icon, etc. These cannot be changed after the setup ceremony, so make sure that you're happy with them before starting the ceremony. Fedimint has an option to set a meta_override_url which points client applications to a separate metadata file that can be updated after the setup ceremony. This is useful if you want to update the metadata after the setup ceremony, but it's not required. For a complete list of Fedi's supported meta fields, see Fedi's Meta Fields.
Start the Setup Ceremony and Run the Distributed Key Generation
After inputting the metadata, the leader kicks off the setup ceremony by clicking Next. This will create a websocket link like wss://some-random-strings.wnext.app/
that the followers will use to join the ceremony. The leader sends this link to the followers, and they use it to join the ceremony.
As the followers join, the leader will see their names appear on the screen under Federation Guardians and flip from Pending, while the guardian reviews the metadata and verifies that it's correct, to Approved when they're ready to proceed.
Once all the guardians have connected and approved the metadata, the Fedimint servers will generate the keys for the federation. This is a synchronous process and should take 30-60 seconds once you see Generating Codes.
Verify the Key Generation
Once the key generation is complete, each guardian will have to give their verification code to the other guardians. This is a check that the guardians are all connected to the same ceremony and that the key generation was successful.
Each guardian should copy and paste their verification code into the group chat, and the other guardians should verify that the codes match by pasting them into the dashboard next to that guardian's name. If the codes match, a green Verified or checkmark will appear next to the guardian's name. If the codes don't match, a red Unverified or X will appear next to the guardian's name. If you see that, clear the input and make sure you copy the codes correctly and strip out any extra spaces or characters that might've been picked up when copying from the chat app!
Once all guardians have verified all the codes, their dashboards' Next button will enable, completing the ceremony.
Congratulations! You're now a Fedimint Guardian!
You've successfully completed the setup ceremony and started the Fedimint for your community! At this point there is no distinction between the leader and followers, you're all equal guardians of the Fedimint. Your Fedimint server can be left running, and you can monitor it's health and status on the dashboard. You can use the Invite Code (text or QR) to invite Fedi users and Gateways to connect to your Fedimint. See the Maintain Your Guardian Documentation for more details.