architecture.md
1 # Fedimint Architecture 2 3 Fedimint is a general framework for building federated financial applications. 4 5 The current implementation allows users to make private and low-cost payments through a federated blinded mint that issues [e-cash](https://en.wikipedia.org/wiki/Ecash). 6 All e-cash is backed by bitcoin with deposits and withdrawals that can occur on-chain or via Lightning. 7 8 ## Crate organization 9 The [Fedimint federation](#Federation-Nodes) consists of nodes that are primarily built from the following crates: 10 * `fedimint` - the main consensus code for processing transactions and REST API 11 * `fedimint-derive` - helper macros for serialization 12 * `crypto/tbs` - helper cryptography library for threshold blind signatures 13 14 [Modules](#Modules) can be added to the `FedimintConsensus` to allow for new types of transactions and federated actions: 15 * `modules/fedimint-wallet` - an on-chain bitcoin wallet 16 * `modules/fedimint-mint` - a blinded mint that issues e-cash 17 * `modules/fedimint-ln` - a Lightning payment service 18 19 * `fedimint-core` - common code used by both client and server 20 21 The [user client](#User-Client): 22 * `fedimint-client` - provides a library for sending transactions to the federation 23 * `fedimint-cli` - cli wrapper around the client library 24 25 The [LN gateway](#LN-Gateway): 26 * `gateway/ln-gateway` - allows a Lightning node operator to receive or pay Lightning invoices on behalf of users 27 * `gateway/cli` - provides cli access and control of a running gatewayd instance 28 29 ## Federation Nodes 30 Each of the nodes spawns three long-running tasks in parallel: an API task, an [AlephBFT protocol](https://docs.rs/aleph-bft/latest/aleph_bft/) task, and a Fedimint consensus task. 31 32 The API task in `net:api:run_server` allows clients to submit a `Transaction` and retrieve its `TransactionStatus`. 33 Transactions are validated by the `FedimintConsensus` logic before being stored as proposals in the database. 34 The proposed list of `ConsensusItem`s includes all possible consensus state changes, such as mint transactions or updates to the agreed-upon block height. 35 36 The AlephBFT protocol task handles communication between federation nodes, combining different `ConsensusItem` proposals from each node into an identical `ConsensusOutcome` during an epoch. 37 So long as enough nodes can communicate, epochs will be continually generated, and every node will share the same sequence of `ConsensusOutcome` data. 38 39 The `FedimintConsensus` task processes each `ConsensusOutcome` by validating the proposals, updating the database, and performing any necessary actions. 40 For instance, the consensus thread may receive a peg-out proposal, validate the PSBT signature and transaction balances, then sign and submit the transaction to the Bitcoin network. 41 42 ## Modules 43 There currently are three `FederationModule`s used in `FedimintConsensus` that exist in the [crates](#Crate-organization) previously described: 44 * [Wallet module](wallet_module.md) - handles bitcoin on-chain `PegInProof` inputs and `PegOut` outputs 45 * `Mint` module - verifies `Note` input signatures and issues `BlindNote` outputs of different denominations 46 * `LightningModule` - creates `ContractInput` inputs and `ContractOrOfferOutput` outputs representing a payment sent or received by a gateway on behalf of a user 47 48 Any module can contribute inputs and outputs in the same `Transaction`. 49 For instance, if users wish to convert on-chain bitcoin to Fedimint notes they can create a transaction with `PegInProof` inputs from `modules/fedimint-wallet` and `BlindNote` outputs from `modules/fedimint-mint`. 50 51 In the future other modules can be added, for instance to enable smart contracts or even a federated marketplace. 52 Existing `ConsensusItem` representations are documented in the [database schema](database.md). 53 54 A diagram of the module transaction processing: 55 56  57 58 ## User Client 59 The `UserClient` communicates with federation members via an asynchronous REST API. 60 Clients are expected to communicate with as many members as necessary to overcome malicious federation nodes. 61 Requests are delegated to an underlying `LnClient`, `MintClient`, or `WalletClient` depending on what `FederationModule` the client needs to perform an action. 62 63 A submitted `Transaction` often requires multiple epochs to become spendable, usually because they require signatures from a quorum of federation members. 64 Clients query for the `TransactionStatus` by unique `OutPoint` that includes the `TransactionId`. 65 66 After enough epochs have passed, the `TransactionStatus` resolves either to an `Error` message or the `OutputOutcome` indicating how the inputs were spent and possibly returning data to the user such as blind-signed notes. 67 68 ## LN Gateway 69 The `LnGateway` communicates with a local Lightning node in order to provide an API that can pay invoices. 70 The gateway uses a `GatewayClient` to communicate with the federation, which delegates to the same underlying `LnClient` or `MintClient` used by the `UserClient`. 71 72 When a user submits a pay invoice request, the gateway uses the `GatewayClient` to confirm the user has locked funds into a valid `ContractAccount`. 73 The gateway then pays the LN invoice and provides the preimage to the federation as proof the payment succeeded, at which point the federation will release the funds to the gateway. 74 75 Read [more about the lightning gateway](./gateway.md)