/ README.md
README.md
1 <h1 align="center"> 2 <a href="https://fedimint.org"> 3 Fedimint 4 </a> 5 </h1> 6 7 <p align="center"> 8 <img src="docs/banner.png"> 9 </p> 10 11 <p align="center"> 12 <a href="https://github.com/fedimint/fedimint/actions/workflows/ci-nix.yml"> 13 <img src="https://github.com/fedimint/fedimint/actions/workflows/ci-nix.yml/badge.svg" alt="GitHub Actions CI Build Status"> 14 </a> 15 <a href="https://chat.fedimint.org"><img alt="Developer Discord Chat" src="https://img.shields.io/discord/990354215060795454?label=dev%20chat"></a> 16 <a href="https://github.com/fedimint/fedimint/discussions"> 17 <img src="https://img.shields.io/badge/community-discussion-blue" alt="GitHub Discussion"> 18 </a> 19 <a href="https://docs.fedimint.org"> 20 <img src="https://img.shields.io/static/v1?label=Docs&message=master&color=007ec6&logo=GitBook&logoColor=ffffff" alt="docs built from master"> 21 </a> 22 <a href="https://app.radicle.xyz/nodes/radicle.fedimint.org/rad:z2eeB9LF8fDNJQaEcvAWxQmU7h2PG"> 23 <img src="https://img.shields.io/badge/Radicle-explore-blue" alt="View on Radicle"> 24 </a> 25 <img alt="Lines of code" src="https://tokei.rs/b1/github/fedimint/fedimint"> 26 </p> 27 28 [Fedimint](https://fedimint.org) is a module based system for building federated applications. It is designed to be a 29 trust-minimized, censorship-resistant, and private alternative to centralized applications. 30 31 > **Fedimint is beta software released under 32 an [MIT License](https://github.com/fedimint/fedimint/blob/master/LICENSE). This means that the software here is 33 provided "as is", without warranty of any kind. We are a small development team with limited resources. If you 34 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 35 recommend you run Fedimint on testnets like mutinynet, or on mainnet with small amounts of money. You can find our 36 latest release [here](https://github.com/fedimint/fedimint/releases/latest).** 37 38 Fedimint ships with 3 default 39 modules - [Bitcoin](https://github.com/bitcoin/bitcoin), [Lightning](https://github.com/lightning/bolts), 40 and [Chaumian Ecash](https://en.wikipedia.org/wiki/Ecash) - for out-of-the-box best practices for private and 41 trust-minimized payments. [You can write custom modules](https://github.com/fedimint/fedimint-custom-modules-example) 42 that define further consensus items and transaction types leveraging the payments modules to build your own federated 43 applications. 44 45 The Fedimint Developer Discord is the best place to get help and ask 46 questions. [Join the Discord](https://discord.gg/cEVEmqCgWG) and say hi! We are extremely active and work to onboard 47 developers of all skill levels to Fedimint and associated open-source Bitcoin projects. Fedimint touches many different 48 areas of Bitcoin development, so there is something for everyone. See below for more information on how to get involved. 49 50 ## Running your own Fedimint 51 52 It's easy to set up and run your own federations. Fedimint is designed to 53 be [Byzantine Fault Tolerant](https://en.wikipedia.org/wiki/Byzantine_fault) so is resilient to `m` malicious nodes in a 54 federation of `3m + 1` nodes. If you run a federation of 4 guardians you are resilient to 1 malicious guardian, if you 55 run a federation of 7 guardians you are resilient to 2 guardians, etc. 56 57 Fedimint can also be run in "solo mode" with a single guardian. This is useful for testing and development, but is not 58 recommended for production use. 59 60 To do lightning payments, Fedimint requires 61 a [Lightning Gateway](https://github.com/fedimint/fedimint/blob/master/docs/gateway.md): a user of the federation that 62 is willing to swap ecash in exchange for sending/receiving lightning payments. The Lightning Gateway is not a guardian 63 and acts as an untrusted economic actor serving the federation. 64 65 ### Running Fedimint on Mutinynet 66 67 See the [Fedimint Mutinynet Setup Guide](./docs/setup-docs.md). You can modify the configuration options to deploy it 68 with. 69 70 ## For Developers 71 72 We are actively looking for developers to help build Fedimint and associated open-source Bitcoin projects. Fedimint 73 touches many different areas of Bitcoin development, so there is something for everyone. The best places to get started 74 are: 75 76 - [The Fedimint Developer Discord](https://discord.gg/cEVEmqCgWG): the best place to get help and ask questions. 77 - [Fedimint Technical Reference Documentation](https://docs.fedimint.org) 78 - [Fedimint Contributor Calendar](https://calendar.google.com/calendar/u/0/embed?src=fedimintcalendar@gmail.com): This 79 calendar contains all the developer calls and events. 80 - [Fedimint Developer Calls](https://meet.jit.si/fedimintdevcall): We have developer calls every Monday at 4PM UTC to 81 review PRs and discuss current development priorities. As a new developer, this is a great place to find good first 82 issues and mentorship from the core team on how to get started contributing to Fedimint. 83 - [PR Review Club](https://meet.jit.si/fedimintdevcall): We have PR review calls every Tuesday at 4PM UTC. 84 - [Weekly Deep Dive](https://meet.jit.si/fedimintdevcall): We have a deep dive every Thursday at 4PM UTC to discuss 85 technical topics relating to Fedimint in depth: cryptography, Rust programming, consensus, networking, etc. This is a 86 great place to learn about the internals of Fedimint and Bitcoin. We normally plan these calls based off requests from 87 contributors on aspects of Fedimint they want to learn more about, so please reach out if you have a topic you want to 88 learn more about. 89 90 For contribution guidelines, Areas of contributions and how to get involved, please refer to 91 the [Contributing Guidelines](CONTRIBUTING.md). 92 93 ### Fedimint Repos and Projects to Contribute To 94 95 - [Fedimint](https://github.com/fedimint/fedimint/issues?q=is%3Aissue+is%3Aopen+label%3A%22good+first+issue%22): The 96 core Fedimint repository. This is where the core consensus and networking code lives. Fedimint is an advanced Rust 97 project and is a great place to learn Rust, cryptography, networking, consensus, and bitcoin development. We have a 98 lot of good first issues, are happy to mentor new developers, and are always looking for experienced Rust developers 99 to help with the core codebase. 100 - [UI](https://github.com/fedimint/ui): The default Fedimint Guardian and Lightning Gateway UIs. These are Typescript 101 and React projects. Contributing to this repo helps with UI/UX design and development to make Fedimint more user 102 friendly. 103 - [Lightning Gateway](https://github.com/fedimint/fedimint/issues?q=is%3Aissue+is%3Aopen+label%3Alightning): Fedimint's 104 Lightning Gateway is implemented as an HTLC interceptor and currently works with CLN, LND, and LDK's sample-node 105 implementations. We are always looking for lightning developers to help with the Lightning Gateway, especially around 106 improving payment reliability and to add support for more lightning implementations. 107 - [Custom Modules](https://github.com/fedimint/fedimint-custom-modules-example): Fedimint ships with 3 default modules: 108 Bitcoin, Lightning, and Chaumian Ecash. You can write custom modules that define further consensus items and 109 transaction types leveraging the payments modules to build your own federated applications. We are always looking for 110 developers to help build custom modules and to help improve the module system. 111 - [Fedimint Web SDK](https://github.com/fedimint/fedimint-web-sdk): The Fedimint Web SDK is a Typescript library for 112 building Fedimint applications. We are looking for developers to help improve the SDK and add support for more features. 113 114 ## Spinning up the Fedimint Developer Environment 115 116 Fedimint is a Rust project and uses the [Nix package manager](https://nixos.org/) to manage dependencies and build the 117 project. 118 119 ### Local Development 120 121 We have a detailed tutorial on how to use the cli to send/receive ecash, lightning payments, and perform other developer 122 operations in the [Fedimint Developer Tutorial](https://github.com/fedimint/fedimint/blob/master/docs/tutorial.md). 123 124 Fedimint's developer environment and rust build pipeline is managed 125 through [Nix Flakebox](https://github.com/rustshop/flakebox). To get started, install Nix. 126 127 ```bash 128 curl --proto '=https' --tlsv1.2 -sSf -L https://install.determinate.systems/nix | sh -s -- install 129 ``` 130 131 Then fork and clone the Fedimint repo. 132 133 ```bash 134 git clone https://github.com/your-username/fedimint.git 135 ``` 136 137 Then enter the nix developer environment. 138 139 ```bash 140 nix develop 141 ``` 142 143 and use this command to start a local regtest network with 4 guardians, a bitcoin node, and a lightning gateway. 144 145 ```bash 146 just mprocs 147 ``` 148 149 You can then interact with the guardians and lightning gateway using the cli. For more details on how to use the cli, 150 see the [Fedimint Developer Tutorial](https://github.com/fedimint/fedimint/blob/master/docs/tutorial.md). 151 152 If you want to run with UIs, see the [UI](https://github.com/fedimint/ui) repo for developer environment instructions. 153 154 # Maintainers 155 156 | Area | Lead-Maintainer | Co-Maintainers | Status | 157 |-------------------|--------------------|------------------------------|---------------------------------------| 158 | Project Lead | @elsirion | @dpc @joschisan | X | 159 | Core Server | @joschisan | X | mostly well factored, no known issues | 160 | Core Consensus | @joschisan | @bradleystachurski | polished and documented | 161 | Lightning Module | @joschisan | @m1sterc001guy | active development, known issues | 162 | Mint Module | @joschisan | X | active development, known issues | 163 | Wallet Module | @bradleystachurski | @dpc @joschisan | active development, critical issues | 164 | Core Client | @dpc | X | X | 165 | Lightning Gateway | @m1sterc001guy | @joschisan | X | 166 | Database | @m1sterc001guy | X | X | 167 | Networking | X | X | X | 168 | CI / Nix | @dpc | @maan2003 @bradleystachurski | X | 169 | Testing | @bradleystachurski | X | X | 170 | Devimint | @maan2003 | X | X | 171 | Config Generation | X | X | X |