fedimint/ui

Fedimint

Fedimint is a module based system for building federated applications. It is designed to be a trust-minimized, censorship-resistant, and private alternative to centralized applications.

Fedimint is alpha software released under an MIT License. This means that the software here is provided "as is", without warranty of any kind. We are a small development team with limited resources. If you experience a loss of funds due to a bug in this software, we may not have the means to help you recover the funds. We recommend you run Fedimint on testnets like mutinynet, or on mainnet with small amounts of money. You can find our latest release here.

Fedimint ships with 3 default modules - Bitcoin, Lightning, and Chaumian Ecash - for out-of-the-box best practices for private and trust-minimized payments. You can write custom modules that define further consensus items and transaction types leveraging the payments modules to build your own federated applications.

The Fedimint Developer Discord is the best place to get help and ask questions. Join the Discord and say hi! We are extremely active and work to onboard developers of all skill levels to Fedimint and associated open-source Bitcoin projects. Fedimint touches many different areas of Bitcoin development, so there is something for everyone. See below for more information on how to get involved.

Running your own Fedimint

It's easy to set up and run your own federations. Fedimint is designed to be Byzantine Fault Tolerant so is resilient to m malicious nodes in a federation of 3m + 1 nodes. If you run a federation of 4 guardians you are resilient to 1 malicious guardian, if you run a federation of 7 guardians you are resilient to 2 guardians, etc.

Fedimint can also be run in "solo mode" with a single guardian. This is useful for testing and development, but is not recommended for production use.

To do lightning payments, Fedimint requires a Lightning Gateway: a user of the federation that is willing to swap ecash in exchange for sending/receiving lightning payments. The Lightning Gateway is not a guardian and acts as an untrusted economic actor serving the federation.

Running Fedimint on Mutinynet

See the Fedimint Mutinynet Setup Guide. You can modify the configuration options to deploy it with.

For Developers

We are actively looking for developers to help build Fedimint and associated open-source Bitcoin projects. Fedimint touches many different areas of Bitcoin development, so there is something for everyone. The best places to get started are:

• The Fedimint Developer Discord: the best place to get help and ask questions.
• Fedimint Technical Reference Documentation
• Fedimint Contributor Calendar: This calendar contains all the developer calls and events.
• Fedimint Developer Calls: We have developer calls every Monday at 4PM UTC to review PRs and discuss current development priorities. As a new developer, this is a great place to find good first issues and mentorship from the core team on how to get started contributing to Fedimint.
• PR Review Club: We have PR review calls every Tuesday at 4PM UTC.
• Weekly Deep Dive: We have a deep dive every Thursday at 4PM UTC to discuss technical topics relating to Fedimint in depth: cryptography, Rust programming, consensus, networking, etc. This is a great place to learn about the internals of Fedimint and Bitcoin. We normally plan these calls based off requests from contributors on aspects of Fedimint they want to learn more about, so please reach out if you have a topic you want to learn more about.

For contribution guidelines, Areas of contributions and how to get involved, please refer to the Contributing Guidelines.

Fedimint Repos and Projects to Contribute To

• Fedimint: The core Fedimint repository. This is where the core consensus and networking code lives. Fedimint is an advanced Rust project and is a great place to learn Rust, cryptography, networking, consensus, and bitcoin development. We have a lot of good first issues, are happy to mentor new developers, and are always looking for experienced Rust developers to help with the core codebase.
• UI: The default Fedimint Guardian and Lightning Gateway UIs. These are Typescript and React projects. Contributing to this repo helps with UI/UX design and development to make Fedimint more user friendly.
• Lightning Gateway: Fedimint's Lightning Gateway is implemented as an HTLC interceptor and currently works with CLN, LND, and LDK's sample-node implementations. We are always looking for lightning developers to help with the Lightning Gateway, especially around improving payment reliability and to add support for more lightning implementations.
• Custom Modules: Fedimint ships with 3 default modules: Bitcoin, Lightning, and Chaumian Ecash. You can write custom modules that define further consensus items and transaction types leveraging the payments modules to build your own federated applications. We are always looking for developers to help build custom modules and to help improve the module system.

Spinning up the Fedimint Developer Environment

Fedimint is a Rust project and uses the Nix package manager to manage dependencies and build the project.

Local Development

We have a detailed tutorial on how to use the cli to send/receive ecash, lightning payments, and perform other developer operations in the Fedimint Developer Tutorial.

Fedimint's developer environment and rust build pipeline is managed through Nix Flakebox. To get started, install Nix.

curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install

Then fork and clone the Fedimint repo.

git clone https://github.com/your-username/fedimint.git

Then enter the nix developer environment.

nix develop

and use this command to start a local regtest network with 4 guardians, a bitcoin node, and a lightning gateway.

just mprocs

You can then interact with the guardians and lightning gateway using the cli. For more details on how to use the cli, see the Fedimint Developer Tutorial.

If you want to run with UIs, see the UI repo for developer environment instructions.

Maintainers

Area	Lead-Maintainer	Co-Maintainers	Status
Project Lead	@elsirion	@dpc @joschisan	X
Core Server	@joschisan	X	mostly well factored, no known issues
Core Consensus	@joschisan	@bradleystachurski	polished and documented
Lightning Module	@joschisan	@m1sterc001guy	active development, known issues
Mint Module	@joschisan	X	active development, known issues
Wallet Module	@bradleystachurski	@dpc @joschisan	active development, critical issues
Core Client	@dpc	X	X
Lightning Gateway	@m1sterc001guy	@joschisan	X
Database	@m1sterc001guy	X	X
Networking	X	X	X
CI / Nix	@dpc	@maan2003 @bradleystachurski	X
Testing	@bradleystachurski	X	X
Devimint	@maan2003	X	X
Config Generation	X	X	X

ui's Issues

Internationalization of UI

Lay some framework for translating.

fwiw, I've seen json files work nicely for this.
i.e.

en.json

{
    "dashboard": {
        "title": "Fedimint Guardian Dashbaord"
    }
}

es.json

{
    "dashboard": {
        "title": "Panel de Guardian de Fedimint"
    }
}

It's then reference in typescript:

<Text>
    {i18n.dashboard.title}
</Text>

Don't hardcode modules in SetConfiguration.tsx

See TODO in SetConfiguration.tsx

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Authentication

Gateway webserver has authentication mechanics. For MVP, let's make the user to enter in this password instead of reading it from the environment. We'll need to make sure our MVP deployment scripts don't hardcode password so I can login to @okjodom's gateway :)

This may require fedimint changes but making the issue here so we get the end-to-end change.

Gateway UI: Type route hints

define types for gateway route hints

Docker-compose Gatewayd <-> LND

Currently the gatewayd doesn't connect to LND in the dev docker-compose setup.

Gateway UI: Gatewayd API Integration

Mintgate defines and uses mock Gatewayd API which is really nice for development without starting a real Gatewayd instance.

Here is how it selects an API to use based on environment variable.

We need to plug in to the real Gatewayd API

Gateway UI: loading state for federation list

After you've joined a federation and load the guardian UI page, there is no loading state while it's fetching the list of federations. But once the call completes they show up.

Move password storage to Context from API

Consolidate local storage keys to GuardianContext.tsx
Any other "state" should be handled here as well.

TBH I would like to get the password storage out of the API file altogether and move it in here. I'd much prefer that to just be a dumb class that takes all its inputs explicitly, rather than having some magic internal stuff going on.

Originally posted by @wbobeirne in fedimint/fedimint#2360 (comment)

Gateway: Connect federation

This functionality exists, but we need to update it to the new designs.

• Connect screen
• Loading state

Support multiple networks configured vis SetupUI

Setup UI should support setting up federations on

• Testnet
• Regtest
• Signet
• Mainnet

type guard API methods

          We can type guard this using `'status' | 'set_password' | etc. etc.` so only certain strings can be used when making the call. It then also serves as a one stop point of reference for what RPC methods are supported. I believe that to be especially important if there's ever a time when we export this API as a package/library for use in other apps.

Originally posted by @EthnTuttle in #28 (comment)

Handle when a guardian starts consensus before sharing verification code

If you're setting up a federation, and one guardian starts consensus before sharing their verification code, you run into a problem where now they are no longer able to see their verification code, and all other guardians will be stuck on the VerifyGuardians step.

We should fix this in at least one of two ways, but probably both:

1. Warn the user before proceeding that they must share their code, make them confirm they have
2. Show the verification code somewhere after setup so they can rectify this if someone is stuck

Guardian: Reset Setup State

We should look to clear or reset SetupState persisted in local storage once the guardian UI transition from setup mode to Admin dashboard experience

Number of Guardian Math on User Input

When inputting number of guardians, a user should be made aware of the 3*f+1=n where n is the total number of guardians, and f is the number of potential malicious guardians. Perhaps a link to the reasoning behind this can be included.

Create Paneled Experience in Federation Admin UI

Ref: Figma

Initialize side main panel experience of the admin ui dashboard. Main panel would just contain the elements we presently have prototyped in the admin ui

Add `eslint-plugin-react-hooks` to eslint config

https://www.npmjs.com/package/eslint-plugin-react-hooks is a really valuable eslint plugin to have, it will catch common stale closure issues in hooks. We've probably got a few offending hooks as it is, so we'll also want to fix those.

Dockerfile.guardian-ui builds static assets at runtime

This is memory intensive. Failed on $6 digital ocean server. Eventually just embed the build/ directory when we create the container. This line:

CMD if [ ! -z "$REACT_APP_FM_CONFIG_API" ]; then yarn build;fi && serve -s apps/guardian-ui/build/

Remove dark mode color scheme

No attention was paid to dark mode while building out the initial guardian setup UI. We'll need to tweak theme.ts to have values for dark mode, and likely need to tweak a few components that use the theme object to style various things.

Chakra docs on color modes: https://chakra-ui.com/docs/styled-system/color-mode

Improve fetching of own PeerId

/**
 * Given a map of peers, determine which one is you.
 */
export function getMyPeerId(peers: Record<string, Peer>) {
  // TODO: Find a better way to do this than using env var?
  const myApiUrl = new URL(process.env.REACT_APP_FM_CONFIG_API as string);
  return Object.entries(peers).find((peer) => {
    const apiUrl = new URL(peer[1].api_url);
    return myApiUrl.origin === apiUrl.origin;
  })?.[0];
}

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Guardian UI: Don't show error on field during setup until touched / submitted

This pops up first thing on the setup form, which instantly draws your eyes to it. It shouldn't show an error until the user has touched the field, or the user has attempted to submit while it's empty.

Gracefully Handle Setup to Consensus API switch

In apps/guardian-ui/src/GuardianApi.ts the startConsensus method is flaky due to how we currently handle the API switch. The UI gets caught in a "setup" state but in reality, consensus has already started running. A refresh of the UI leads to "method not found" errors as it tries to determine where in the setup process is it.

I have tried a few approaches but none have yielded consistent results.

relevant Discord conversations:
https://discord.com/channels/990354215060795454/990354215878688860/1122657638388338819
https://discord.com/channels/990354215060795454/990354215878688860/1124158861876674571
https://discord.com/channels/990354215060795454/1105908596614627428/1121760876286976071

Gateway admin UI packaged as an LnBits extension

We should explore building a gateway Admin interface packaged as an LnBits extension.

Gateway UI should return more useful error when gatewayd API isn't running

Dynamically handle unknown modules

With Fedimint's modules, the Guardian UI needs to account for any additional modules and display their configuration properly for setup.

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Guardian and Gateway front end logic tests

We currently don't have unit tests on our Guardian UI components or logic. It seems the gateway UI is set up to use Jest but also doesn't have a lot of tests.

• Settle on Jest or some other framework
• Implement reusable testing patterns
• Mock backend API calls for use in tests
• Integration tests

Local Storage invalid between federation clear and restart

I believe this should only impact dev environments since reproducing this is pretty far out there for an edge cases.

We default to local storage to hydrate SetupContext so if you restart/clear a federation in the middle of setup, the UI will see that there is already SetupContext state in local storage and hydrate the context. This will not match the actual state of the backend.

To reproduce:

1. startup a local federation and continue through only part of the setup flow (stopping around verify guardians or some other intermediary step)
2. Stop the fedimintd instances and clear the federation data.
3. Restart fedimintd instances.
4. Browse to Setup UI and refresh. You should see an error (The websocket is not opened) or similar.
5. Check local storage cache and observe.

Clarify UI handling of Setup API teardown

The config server shuts down as we finalize the configuration of the federation, currently, we just use a timer to wait for the transition to happen on the backend.

Yeah so the tricky thing is that once you start consensus, the config server shuts down and the regular api starts up, so it necessarily kills the socket. Ideally the config server would stay up long enough to respond to the rpc, indicating that it successfully started the server, and then shuts down. Worth an issue to improve the understandability of the code IMO.

I haven't spent enough time here to know if this is a reasonable timeout, but you are correct that it could hypothetically not be enough time. Unfortunately while I was working on this, this part of starting consensus would cause the backend to panic and crash. Might be worth some retries if we find it's prone to taking longer than this.

Originally posted by @wbobeirne in fedimint/fedimint#2360 (comment)

Docker-compose should provide 3 fedimintds

We recommend people setup with 2n + 1 fedimintd instances, and certain bugs (e.g. #83) only rear their ugly heads with 3 or more guardians in a federation. We should make this the default, and update our README instructions to reflect a 3 guardian setup.

Surface non-401 error to user

Most users won't check console logs, so we should present them with an error another way. Ideally with recommendations to fix it.

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

CI builds preview deployments for UI-related pull requests

Could probably use something like Vercel to deploy the UI itself. But we'd need a backend to run against which would be a little tougher. But gateway UI has mock API implementation so for starters we could just used a mocked-out backend.

Guardian UI: Use find / replace for FM_CONFIG_API env var instead of rebuilding project in docker

https://github.com/fedimint/ui/blob/master/Dockerfile.guardian-ui#L5-L7

This site should be able to run on really lean & weak hardware since it's just a basic web app, but doing the build can blow out memory on some smaller machines. A quick find / replace would be much more efficient than doing a full build. Should also improve start-up times dramatically when not using the default env var.

Guardian UI: Followers should watch for Leader to kick off DKG

We've run into a problem during some of our test setups that is easy to miss when you're developing solo, or setting up a 1 of 1 or 2 of 2 federation. Right now followers attempt to run DKG as soon as they approve the configuration. This is problematic if in e.g. a 2 of 3 federation, only the leader and follower 1 have joined. Follower 1 has not yet gotten any information about Follower 2 who will join shortly, so their DKG is incomplete. Once follower 2 attempts to run DKG, it'll fail because follower 1 will reject them.

We need to re-architect this so that followers go through the following flow:

1. Follower pastes in leaders WS API URL
2. Follower is presented with configuration from leader
3. Follower hits approve on configuration
4. Follower is presented with a screen that shows the status of all peers, and says that it's waiting for the leader to continue
5. Follower sees that the leader's status has gone from SharingConfigGenParams to ReadyForConfigGen
6. Follower transitions to the RunDKG screen and attempts to run DKG

Followers will not know how many guardians the leader intends for the federation to have, so they will not see the rows that indicate guardians that have not joined yet like the leader does.

Confirm error is auth error

Per comment in GuardianApi.ts, we should confirm the error is related to and handle it appropriately.

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Guardian: Ability to restart setup state

If something goes wrong, we currently have no way to restart short of restarting fedimintd. Would be nice if we had a button + backend API to accomplish this.

Remove default component for Setup.tsx

We should ideally never been in the state where they're rendered so should remove the default basics. At a minimum, we should remove the button that advances.

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Optimize Docker container size

https://hub.docker.com/layers/fedimintui/guardian-ui/ is current ~1k Mb
We should improve on this.

Guardian: Show information about connected lightning nodes / gateway

For each lightning node connected to the federation, we should show public node and routing information

• Fetch list of connected gateways using guardian api : #69
• Update lightning node info UX and show info
  • title gateways using gateway id
  • view gateway node using node id

Gateway toasts don't seem to do anything

This code gets run, but I don't see anything show up

CopyInput doesn't allow viewing hyper-long strings

connectionCode in apps/guardian-ui/src/components/FederationDashboard.tsx is an example. The connection info string is very long cannot be viewed in full in the CopyInput element.

Select bitcoin node to use in Guardian Setup

Enable a Guardian to input a node for their instance to use:

• input node URL
• show default node url from local config gen
• confirm node connection w/ feedback
• frontend ability to switch FM_BITCOIN_RPC_KIND

Dynamic Graphing ability

From @justinmoon

One thing I would really like is a simple way to build little dashboard from a federation or gateway rockdb.

I would love to just have a jupyter notebook that I could easily write little scripts to measure things like:

• graph of federation balances over time
• lightning payment success rate over time
• what percent of epochs does guardian N get into over time
• average size of lightning payment over time
• how frequently do lightning payments enter refund case

@elsirion mentioned promethius, too, but I'm not very familiar with it

What I'd like to avoid is really long development cycles where someone thinks of a graph while prototyping dashboard in figma, then it's implemented in admin API, then implemented in frontend, then deployed. The feedback loop there will be really slow that way.

Guardian: Implement no members or connected lightning nodes experience

When there's no members or a connected lightning node, guardian ui should show two message bars showing how to gateway operators can connect to the federation.

Tasks:

• Implement message bar UX
• Add appropriate message to show the guardian (clarify messaging and copy)
• Detect state using guardian api and show / hide message bars

Ref:

• Figma

Gateway: Authentication

This requires backend change to fully work.

• Create password screen
• Authenticate later with ^^ password. This needs a design. Initial screen has options to "login" or "create password".

ConnectGuardians.tsx displays wrong value

        <CopyInput
          value={process.env.REACT_APP_FM_CONFIG_API || ''}
          size='lg'
          buttonLeftIcon={<Icon as={CopyIcon} />}
        />

We currently use the UI enviroment variable as the connection. However, this is incorrect and should be the FM_API_URL passed into the Coordinators config for fedimintd.

Enable lint-stage for the whole Fedimint UI workspace

fedimint/fedimint#2485 (comment)

useTheme Consistently

To ensure a consistent UI experience, we should be using useTheme everywhere there are style props passed to a component.

Should useTheme here for button sizes.

Originally posted by @garyray-k in fedimint/fedimint#2360 (comment)

Dockerfiles are copying and building all apps unnecessarily

Each Dockerfile for each app should only copy and build the app in question. Running yarn install in the root directory installs all of the dependencies necessary for all packages and apps, and running yarn build in the root directory builds all apps. We should only copy and build the apps and packages that we need per app.

Query current fedimint release and warn if the one being set up is outdated

(once we have releases)

Gateway: don't generates a new address every time the page is loaded

This will cause an excessive number of state machines to be spawned

Gateway UI: Testing

Here is my preferences and recommendation for all Fedimint UI projects

fedimint/fedimint#1266 (comment)