Mapping of Software to M2 deliverables

--- tags: Roadmap --- # Mapping of Software to M2 deliverables This document's aim is to clearly map the Farcaster Core & Node repositories to the deliverables we promised in the second milestone of our funded [CCS proposal for BTC/XMR atomic swaps](https://ccs.getmonero.org/proposals/h4sh3d-atomic-swap-implementation.html). ## How to use this document Whether formally assessing our delivered milestone or just ratifying it to sleep well at night, in the peace of knowing the project is on track, we recommend following the RFCs linearly, as described in the [RFC readme](https://github.com/farcaster-project/RFCs/blob/master/README.md), to get a complete overview, before reverting to this document to cross-check against the deliveries. The milestone is copied over literally, and the mapping to RFCs is described in the comments. ## Changes since the proposal ### Milestone 2 (implementation of core architecture): 45% [14 weeks] * **Minimal functionality:** at completion-time of milestone 2, all components for executing atomic swaps successfully are implemented using our libraries as proposed in the presented architecture. * **BETA STATE:** the software released is considered to be beta software and not ready for deployment. This milestone achieves the initial implementation of all the components (without GUI client) interacting with each other. It implements only the minimally required functionalities specified in the specifications (Milestone 1). > no state recovery, no taproot #### A. Cryptographic libraries [7.5% of M2] [1 week] For milestone 2 we intend to use Lloyd's experimental library for ECSA adaptor signatures (`ecdsa-adaptor-sig`) and DLEQ proofs (`xgroup-dleq-lib`). We postpone the integration of a production-grade ECDSA adaptor signatures to the end of the project, namely milestone 3, as it is highly complex, and this gives tooling more time to mature. In case Bitcoin incorporates Schnorr signatures soon (BIP 340), ECDSA adaptor signatures may also not be needed and would then be replaced with Schnorr adaptor signatures. At completion, we provide generic cryptographic libraries that expose a high level API, comparable to how `rust-secp256k1` exposes a high level API for ECDSA signatures over `secp256k1`. #### A.1 `xgroup-dleq-lib` Experimental discrete-log equality across groups library using secp256kfun. At completion, this library enables zk-proving discrete log equality across groups `secp256k1` and `ed25519` for arbitrary private keys. #### A.2 `ecdsa-adaptor-sig` Experimental ecdsa-adaptor signature library using secp256kfun. At completion, this library enables producing and verifying ecdsa-adaptor signatures, and extracting secrets from clear and encrypted signatures. #### B. `swap-lib` [25% of M2] [4 weeks] `swap-lib` is the core for adding support for a new chain, either via the Bitcoin-like template or the Monero-like template. At completion, this library is an interface for enforcing the requirements of `swap-daemon` and `swap-client` for a selected chain, and the requirements for each `chain-syncer` type. #### B.1 `xmr-swap-lib` A concrete implementation of `swap-lib` that allows the creation of a `swap-daemon` and a `swap-client` for exchanging monero for bitcoin. #### B.2 `btc-swap-lib` A concrete implementation of `swap-lib` that allows the creation of a `swap-daemon` and a `swap-client` for exchanging bitcoin for monero. #### C. `swap-client`s [12.5% of M2] [2 weeks] At completion of Milestone 2, we provide only the `swap-cli` client. #### C.1 `swap-cli` A CLI client utilizing `swap-daemon`'s API for executing swaps. At completion, a minimal CLI client for running Bitcoin and Monero swaps will be delivered. * `swap-cli` can initialize a `swap-daemon` with parameters for a swap (swap-pair, swap-direction, counterparty daemon address, swap-amount, exchange-rate). * `swap-cli` can sign transactions the `swap-daemon` provides. * `swap-cli` sends signed transactions back to the `swap-daemon`. #### D. `swap-daemon` [30% of M2] [4 weeks] At completion, `swap-daemon` enables `swap-client` to successfully swap bitcoin for monero. It coordinates all aspects of the swap by communicating with `swap-client`, `chain-syncer`s and the counterparty's `swap-daemon`. It exposes an RPC server for client interaction. At this stage: - `swap-daemon` understands the semantics of all the public keys, unsigned, signed and partially-signed transactions, hash pre-images, and encrypted signatures involved in the protocol. - has the full picture of the state of the cross-chain-swap, as it's aware of the events on both chains; each `chain-syncer` only has a partial view. `swap-daemon` knows the off-chain events as well. - protocol implemented in 2 varieties: (1) one for executing btc-sender/xmr-receiver protocol (`btc->xmr`) and (2) another for xmr-sender/btc-receiver protocol (`xmr->btc`). In conjunction these 2 protocols cover the full protocol. - at run-time, each `swap-daemon` instantiates a state-machine of only one of the varieties: either `xmr->btc` or `btc->xmr`. - at run-time, the daemon can start in a master or slave mode. In master mode, `swap-daemon` accepts entering connections, in slave mode `swap-daemon` tries to connect to a counterparty daemon. - reveals a high level API that lets `swap-client`s run the protocol. #### E. `chain-syncer`s [25% of M2] [3 weeks] At completion, `chain-syncer` exposes enough functionality to permit the `swap-daemon` to carry out swaps between Monero and Bitcoin. It does not publish transactions on behalf of its client yet (e.g. `do X once Y`), just listens to transactions of interest and blocks, process them and push events to the `swap-daemon` (i.e. `chain-syncer`'s client). It also exposes functionality for clients to publish transactions to the blockchain, if needed. All `chain-syncer`s implement the base functionality: * interface to `swap-daemon` * read transactions (arriving in the mempool, or with a number of confirmations) * read new blocks * detect block re-orgs #### E.1 `btc-chain-syncer` A bitcoin concrete implementation of the `chain-syncer`. In addition to the base functionality, `btc-chain-syncer`: * connects to bitcoin full-node * broadcasts transactions #### E.2 `xmr-chain-syncer` A monero concrete implementation of the `chain-syncer`. In addition to the base functionality, `xmr-chain-syncer`: * connects to monero full-node ---- #### A. Specification of `swap-daemon` Detailed description and specification of the `swap-daemon`, internal and external. #### `DONE` A.1 User-facing [35% of M1] [2 weeks] * Specify `swap-daemon`'s outer API layer of user interaction (`swap-client`s & counterparty `swap-daemon`) first to guide design of inner dependencies (`swap-lib` & `chain-syncer`) to match desired UX. This includes protocol messages exchanged between swap participants, that is: interactions with the counterparty `swap-daemon`.  > [RFC: 02. User Stories](https://github.com/farcaster-project/RFCs/blob/master/02-user-stories.md) contains a mockup of user interaction in a swap both via a GUI and a CLI, and also both from maker and taker perspectives. The individual steps of the user interaction throughout a swap are linked back to the relevant protocol messages of the API specified in [RFC: 04. Protocol Messages](https://github.com/farcaster-project/RFCs/blob/master/04-protocol-messages.md). > [color=violet] > - [ ] `ENHANCEMENT`: link user stories not only to inter-daemon messages, but also client<->daemon messages * Specify the API that `swap-cli` and `swap-gui` consume from `swap-daemon`. > `swap-cli` and `swap-gui` consume the same interface specified in > [RFC: 06. Datum & Instructions](https://github.com/farcaster-project/RFCs/blob/master/06-datum-and-instructions.md) * Specify the networking stack between `swap-daemon` and: `swap-daemon` counterparty and `swap-client`s. > [RFC: 03. Farcaster Architecture](https://github.com/farcaster-project/RFCs/blob/master/03-farcaster-architecture.md) provides a detailed overview of component interactions. The networking messages between counterparty daemons are specified down to the TLV level in [RFC: 04. Protocol Messages](https://github.com/farcaster-project/RFCs/blob/master/04-protocol-messages.md). The networking messages between `swap-daemon` and `swap-client`s are specified down to the TLV level in [RFC: 06. Datum & Instructions](https://github.com/farcaster-project/RFCs/blob/master/06-datum-and-instructions.md) #### `DONE` A.2 Service internals [16.25% of M1] [1 week] Specify links between `swap-daemon` and the other deliverables it requires to facilitate a swap, but that are not user-facing, i.e. `swap-lib` and `chain-syncer`s: * Specify the subset of `swap-lib`'s API strictly required for `swap-daemon`'s operation `swap-lib` has to provide `swap-daemon` with cryptographic primitives, transaction construction and parsing, and a recovery mechanism for an interrupted swap. > Covered by the more encompassing requirements of `M1.B.1` The cryptographic primitives `swap-lib` has to provide to `swap-daemon` are specified in [RFC: 07. Cryptographic Setup] > The transactions involved in a swap are specified in [RFC: 08. Transactions](https://github.com/farcaster-project/RFCs/blob/master/08-transactions.md) > Recovery from an interrupted swap is specified in [RFC: 09. Swap State](https://github.com/farcaster-project/RFCs/blob/master/09-swap-state.md) * Specify API and network stack for `swap-daemon`'s required calls to `chain-syncer`s > Both are included and described in the more encompassing specifation of `M1.C` #### B. Specification of `swap-lib` (core protocol) Detailed description and specification of all the libraries that, in conjunction, form `swap-lib`, including stateless transaction construction libraries, crypto-libraries and their wrappers, and state-machine libraries for executing the protocol. #### `DONE` B.1 External specification of `swap-lib` [16.25% of M1] [1 week] * Specify `swap-lib`'s public API to be consumed by `swap-daemon` only. Preliminarily, covers `InitTx()`, `VrfyTx()`, `Vrfy()`, and `EncVrfy()` from the whitepaper. > [RFC: 07. Cryptographic Setup: Adaptor Signatures](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md#adaptor-signatures) specifies `Vrfy()`, `EncVrfy()` scripts for both Taproot and ECDSA. The script structures of transactions (for `InitTx()` and `VrfyTx()`) are specified in [RFC: 08. Transactions](https://github.com/farcaster-project/RFCs/blob/master/08-transactions.md). * Specify `swap-lib`'s public API to be consumed by `swap-client`s only. Preliminarily, covers `Sign()`, `EncSign()`, `DecSig()`, `RecKey()`, and `Rec()` from the whitepaper. > [RFC: 07. Cryptographic Setup: Signatures](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md#signatures) specifies the constraints on `Sign()` > [RFC: 07. Cryptographic Setup: Adaptor Signatures](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md#adaptor-signatures) specifies `EncSig()`, `DecSig()` and `Rec()` scripts, both for ECDSA and Taproot. * Specify `swap-lib`'s public API to be consumed by both `swap-daemon` and `swap-client`s. > `swap-client`s also verify transaction validity before signing, so use the same verification functions exposed to the `daemon`. > Relevant RFCs: > [RFC: 07. Cryptographic Setup](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md) > [RFC: 08. Transactions](https://github.com/farcaster-project/RFCs/blob/master/08-transactions.md) > [RFC: 09. Swap State](https://github.com/farcaster-project/RFCs/blob/master/09-swap-state.md) #### `DONE` B.2 Internal specification of `swap-lib` [16.25% of M1] [1 week] * Specify internal function calls of `swap-lib`. > [RFC: 07. Cryptographic Setup](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md) specifies the cryptographic functions called to satisfy the API exposed to `swap-daemon` and `swap-client`.  * Specify a concrete implementation to support a chain, including all cryptographic primitives that must be supported. > Cryptographic primitives are described in [RFC: 07. Cryptographic Setup](https://github.com/farcaster-project/RFCs/blob/master/07-cryptographic-setup.md), while [RFC: 08. Transactions](https://github.com/farcaster-project/RFCs/blob/master/08-transactions.md) covers the transactions necessary for a swap #### `DONE` C. Specification of `chain-syncer` [16.25% of M1] [1 week] * Specify the functionality and interface `chain-syncer` has to expose in order to permit the `swap-daemon` to carry out swaps. Describe what jobs are, and what jobs must be supported. > Jobs have been renamed to tasks, and are described in [RFC: 05. Tasks & Blockchain Events](https://github.com/farcaster-project/RFCs/blob/master/05-tasks-and-events.md) * Specify the networking stack between `swap-daemon` and `chain-syncer`s. > [RFC: 03. Farcaster Architecture](https://github.com/farcaster-project/RFCs/blob/master/03-farcaster-architecture.md) > The networking messages between `swap-daemon` and `chain-syncer`s are specified down to the TLV level in [RFC: 05. Tasks & Blockchain Events](https://github.com/farcaster-project/RFCs/blob/master/05-tasks-and-events.md) # Concrete design choices ## Taproot ## LNP-BP As proposed at the end of our first milestone, we've continued with building on top of LNPBP, and this design decision has paid off immensely! While getting microservices to play together nicely is much harder than adopting a monolithic approach, the resilience gains pay off. Most importantly, it permits the segregation of services across devices (say, swap-cli running from your laptop with only an intermittent internet connection, while farcasterd, its children, and the Monero & Bitcoin full nodes run elsewhere), as well delegation of select services to third parties (in particular the syncer daemons, which can only process instructions, and are firmly segregated from private key material).