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.
Set Federation Configurations
The only real difference between the leader and the followers is that the leader initiates the setup establishes the consensus configuration, which then 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:
- Federation Name: The name of the federation. This should be easily identifiable by your community and can be changed after setup is complete, but the change must be voted on by a threshold number of guardians.
- Number of Guardians (including the leader!): Fedimint supports running in Solo mode with 1 guardian (not recommended for production or with mainnet), or with any of the Byzantine Fault Tolerant consensus sizes so 4, 7, 10, etc. Choose from the list 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.
- Bitcoin Settings - Additional Block Confirmations: Fedimint's Peg-In mechanism for onchain deposits cannot currently 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 set this to 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.
- Bitcoin Settings - Environment Variables: These correspond to the settings you configured when Provisioning a Guardian and cannot be changed from the UI. Carefully review these settings before proceeding. If you need to make changes, you can provision a new server and start over from the beginning of this guide.
- Guardian Name: A random guardian name is generated by default. You can change his to anything you like but it should be unique so it is not confused with other guardian names during the setup ceremony. This name cannot be changed after the setup ceremony.
- Admin Password: The password is used to encrypt the guardian's private key, so it should be kept secret and not shared with anyone. Make sure that no one is watching your screen while you reveal the password to copy it to safe place.
The password is not recoverable, so if you lose it you won't be able to access your fedimint guardian server!
Carefully read ALL of the following prompts to confirm that you have saved your password in a secure location.
Start the Setup Ceremony and Run the Distributed Key Generation
After confirming the password has been backed up, the leader kicks off the setup ceremony by clicking Next. This will create a websocket link like wss://some-random-text.wnext.app/ws/
that the followers will use to join the ceremony. The leader sends this link to the followers (be sure to use a secure messenger like Signal or Fedi), and the followers will 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 each follower guardian reviews the configuration 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 swervers will generate the keys for the federation. This is a synchronous process and should take 30-60 seconds once you see the 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.