docs: Combine docs into less pages, update overview, and finality ren…

…aming (#178)

README.md

@@ -1,62 +1,36 @@
-# BTC-Validator
+# Finality Provider
 
-## 1. Overview
-
-BTC-Validator is a standalone program crafted for the creation and management of BTC
-validators. The program includes a CLI functionality for the creation, management,
-and storage of validator keys, as well as the creation and registration of validators
-on the consumer chain.
-
-Once a validator is registered on the chain, BTC-Validator consistently polls for new
-blocks. It actively engages with the blockchain by sending finality signatures and
-committing public randomness at regular intervals.
-
-The program consists of two essential components: the **EOTS manager Daemon** and the
-**Validator Daemon**.
-
-#### 1. EOTS Manager Daemon
-
-The EOTS Daemon is responsible for managing EOTS keys, producing EOTS randomness and
-EOTS signatures
-
-**Note:** EOTS stands for Extractable One Time Signature. You can read more about it
-in
-the [Babylon BTC Staking Litepaper](https://docs.babylonchain.io/assets/files/btc_staking_litepaper-32bfea0c243773f0bfac63e148387aef.pdf).
-The BTC validator will commit a unique EOTS randomness at each future height it needs
-to vote. If the BTC validator votes for two blocks using the same committed EOTS
-randomness, then its secret key will be extracted and all of its BTC delegations will
-be slashed on Bitcoin, ensuring slashable safety.
+A toolset crafted for the creation and
+management of Finality Providers.
 
-1. **EOTS Key Management:**
-    - Generates [Schnorr](https://en.wikipedia.org/wiki/Schnorr_signature) key pairs
-      for the validator using the
-      [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
-      standard.
-    - Persists generated key pairs in the
-      internal [bolt db](https://github.com/etcd-io/bbolt) storage.
-
-2. **Randomness Generation:**
-    - Generates lists of EOTS randomness pairs based on the EOTS key, chainID, and
-      block height.
-    - The randomness is deterministically generated and tied to specific parameters.
-
-3. **Signature Generation:**
-    - Signs EOTS using the private key of the validator and corresponding secret
-      randomness for a given chain at a specified height.
-    - Signs Schnorr signatures using the private key of the validator.
-
-#### 2. Validator Daemon
-
-The Validator Daemon is responsible for committing public randomness and submitting
-finality signatures.
+## 1. Overview
 
-1. **Finality Signatures:**
-    - Sends the finality signature to the consumer chain (Babylon) for each
-      registered validator and for each block there's an EOTS randomness commitment.
+Finality providers are responsible for voting
+at a finality round on top of [CometBFT](https://github.com/cometbft/cometbft).
+Similar to any native PoS validator,
+a finality provider can receive voting power delegations from BTC stakers, and
+can earn commission from the staking rewards denominated in Babylon tokens.
+
+The finality provider toolset does not have
+any special hardware requirements
+and can operate on standard mid-sized machines
+running a UNIX-flavored operating system.
+It consists of the following programs:
+- *Babylon full node*: An instance of a Babylon node connecting to
+  the Babylon network. Running one is not a strict requirement,
+  but it is recommended for security compared to trusting a third-party RPC node.
+- *Extractable One-Time Signature (EOTS) manager*:
+  A daemon responsible for securely maintaining the finality provider’s
+  private key and producing extractable one time signatures from it.
+- *Finality Provider*: A daemon managing the finality provider.
+  It connects to the EOTS manager to generate EOTS public randomness and
+  finality votes for Babylon blocks, which it submits to Babylon through
+  the node connection.
+
+The following graphic demonstrates the interconnections between the above programs:
+
+![Finality Provider Interconnections](./docs/finality-toolset.png)
 
-2. **EOTS Randomness Commitment:**
-    - Ensures the generation of EOTS randomness commitment on the Babylon ledger for
-      each block the BTC validator intends to vote for.
 
 ## 2. Installation
 
@@ -72,22 +46,22 @@ the [official Go installation guide](https://golang.org/doc/install).
 To get started, clone the repository to your local machine from Github:
 
 ```bash
-$ git clone [email protected]:babylonchain/btc-validator.git
+$ git clone [email protected]:babylonchain/finality-provider.git
 ```
 
 You can choose a specific version from
-the [official releases page](https://github.com/babylonchain/btc-validator/releases)
+the [official releases page](https://github.com/babylonchain/finality-provider/releases)
 
 ```bash
-$ cd btc-validator # cd into the project directory
+$ cd finality-provider # cd into the project directory
 $ git checkout <release-tag>
 ```
 
 #### Building and installing the binary
 
 ```bash
 # cd into the project directory
-$ cd btc-validator 
+$ cd finality-provider
 
 # installs the compiled binaries to your
 # $GOPATH/bin directory allowing access
@@ -98,39 +72,63 @@ $ make install
 The above will produce the following binaries:
 
 - `eotsd`: The daemon program for the EOTS manager.
-- `vald`: The daemon program for the btc-validator.
-- `valcli`: The CLI tool for interacting with the btc-validator daemon.
-- `covd`: The daemon program for the covenant emulator.
+- `fpd`: The daemon program for the finality-provider.
+- `fpcli`: The CLI tool for interacting with the finality-provider daemon.
 
 To build locally,
 
 ```bash
-$ cd btc-validator # cd into the project directory
+$ cd finality-provider # cd into the project directory
 $ make build
 ```
 
 The above will lead to a build directory having the following structure:
 
 ```bash
 $ ls build
-    ├── covd
     ├── eotsd
-    ├── valcli
-    └── vald
+    ├── fpcli
+    └── fpd
 ```
 
-## 3. EOTS Daemon Configuration
+## 3. Setting up a finality provider
+
+#### 3.1. Setting up a Babylon Full Node
+
+Before setting up the finality provider toolset,
+an operator must ensure a working connection with a Babylon full node.
+It is highly recommended that operators run their own node to avoid
+trusting third parties. Instructions on how to set up a full Babylon node
+can be found in 
+[the Babylon documentation](https://docs.babylonchain.io/docs/user-guides/btc-timestamping-testnet/setup-node).
 
-Follow the [eots configuration guide](docs/eotsd/eotsd-config.md).
+The finality provider requires a Babylon keyring with loaded funds to be attached to it
+in order to be able to send transactions to Babylon.
+To setup such a keyring, follow the instructions in
+[the Babylon documentation](https://docs.babylonchain.io/docs/user-guides/btc-timestamping-testnet/getting-funds).
 
-## 4. Starting the EOTS Daemon
+#### 3.2. Setting up the EOTS Manager
 
-Follow the  [eots startup guide](docs/eotsd/eotsd-startup-guide.md).
+After a node and a keyring have been set up,
+the operator can set up and run the
+Extractable One Time Signature (EOTS) manager daemon.
+A complete overview of the EOTS manager, its operation, and
+its configuration options can be found in the
+[EOTS Manager page](docs/eots.md)
 
-## 5. Validator Daemon Configuration
+#### 3.3. Setting up a Finality Provider 
 
-Follow the [vald configuration guide](docs/vald/vald-config.md).
+The last step is to set up and run
+the finality daemon.
+A complete overview of the finality daemon, its operation, and
+its configuration options can be found in the
+[Finality page](docs/finality-provider.md).
 
-## 6. Starting the Validator Daemon
+## 4. Delegations & Rewards
 
-Follow the [vald startup guide](docs/vald/vald-startup-guide.md).
+A finality provider receives BTC delegations through delegators
+interacting with Babylon and choosing it as the recipient of their delegations.
+To perform a self-delegation,
+the operator can either visit the staking web app we provide,
+or run the Babylon [BTC Staker program](https://github.com/babylonchain/btc-staker) once.
+The BTC staker connects to a Bitcoin wallet and Babylon to perform delegations.

docs/eots.md

@@ -0,0 +1,111 @@
+# EOTS Manager
+
+## 1. Overview
+
+The EOTS daemon is responsible for managing EOTS keys,
+producing EOTS randomness, and using them to produce EOTS signatures.
+
+**Note:** EOTS stands for Extractable One Time Signature. You can read more about it
+in
+the [Babylon BTC Staking Litepaper](https://docs.babylonchain.io/assets/files/btc_staking_litepaper-32bfea0c243773f0bfac63e148387aef.pdf).
+In short, the EOTS manager produces EOTS public/private randomness pairs.
+The finality provider commits the public part of this pairs to Babylon for
+every future block height that they intend to provide a finality signature for.
+If the finality provider votes for two different blocks on the same height,
+they will have to reuse the same private randomness which will lead to their
+underlying private key being exposed, leading to the slashing of them and all their delegators.
+
+The EOTS manager is responsible for the following operations:
+1. **EOTS Key Management:**
+    - Generates [Schnorr](https://en.wikipedia.org/wiki/Schnorr_signature) key pairs
+      for a given finality provider using the
+      [BIP-340](https://github.com/bitcoin/bips/blob/master/bip-0340.mediawiki)
+      standard.
+    - Persists generated key pairs in the
+      internal Cosmos keyring.
+2. **Randomness Generation:**
+    - Generates lists of EOTS randomness pairs based on the EOTS key, chainID, and
+      block height.
+    - The randomness is deterministically generated and tied to specific parameters.
+3. **Signature Generation:**
+    - Signs EOTS using the private key of the finality provider and the corresponding secret
+      randomness for a given chain at a specified height.
+    - Signs Schnorr signatures using the private key of the finality provider.
+
+The EOTS manager functions as a daemon controlled by the `eotsd` tool.
+
+## 2. Configuration
+
+The `eotsd init` command initializes a home directory for the EOTS
+manager. This directory is created in the default home location or in a location
+specified by the `--home` flag.
+
+```bash
+$ eotsd init --home /path/to/eotsd/home/
+```
+
+After initialization, the home directory will have the following structure
+
+```bash
+$ ls /path/to/eotsd/home/
+  ├── eotsd.conf # Eotsd-specific configuration file.
+  ├── logs       # Eotsd logs
+```
+
+If the `--home` flag is not specified, then the default home location will
+be used. For different operating systems, those are:
+
+- **MacOS** `~/Library/Application Support/Eotsd`
+- **Linux** `~/.Eotsd`
+- **Windows** `C:\Users\<username>\AppData\Local\Eotsd`
+
+Below are some of the important parameters in the `eotsd.conf` file.
+
+```bash
+# Default address to listen for RPC connections
+RpcListener = localhost:15813
+
+# Type of keyring to use,
+# supported backends - (os|file|kwallet|pass|test|memory)
+# ref https://docs.cosmos.network/v0.46/run-node/keyring.html#available-backends-for-the-keyring
+KeyringBackend = file
+
+# Possible database to choose as backend
+Backend = bbolt
+
+# Path to the database
+Path = bbolt-eots.db
+
+# Name of the database
+Name = default
+```
+
+To see the complete list of configuration options, check the `eotsd.conf` file.
+
+## 3. Starting the EOTS Daemon
+
+You can start the EOTS daemon using the following command:
+
+```bash
+$ eotsd --home /path/to/eotsd/home
+```
+
+This will start the rpc server at the address specified in the configuration under
+the `RpcListener` field. It can also be overridden with custom address using
+the `--rpclistener` flag.
+
+```bash
+$ eotsd --rpclistener 'localhost:8081'
+
+time="2023-11-26T16:35:04-05:00" level=info msg="RPC server listening on 127.0.0.1:8081"
+time="2023-11-26T16:35:04-05:00" level=info msg="EOTS Manager Daemon is fully active!"
+```
+
+All the available cli options can be viewed using the `--help` flag. These options
+can also be set in the configuration file.
+
+**Note**: It is recommended to run the `eotsd` daemon on a separate machine or
+network segment to enhance security. This helps isolate the key management
+functionality and reduces the potential attack surface. You can edit the
+`EOTSManagerAddress` in  the configuration file of the finality provider
+to reference the address of the machine where `eotsd` is running.