fix: add health check on startup, increase gas adjustment and update docs (#117)

* fix: add health check on startup, increase gas adjustment and update docs

* CHANGELOG

* fix: set default gas adjustment to 5

Author: Vvaradinov

CHANGELOG.md

@@ -39,6 +39,8 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/)
 
 ### Improvements
 
+* [#117](https://github.com/babylonlabs-io/covenant-emulator/pull/117) Add health check on startup, increase gas adjustment and update docs.
+
 ## v0.14.0
 
 * [#114](https://github.com/babylonlabs-io/covenant-emulator/pull/114) bump babylon to v1.0.0-rc.8

README.md

@@ -35,10 +35,10 @@ duty or power. If it has a dishonest super majority, then
 
 * it cannot:
 
-  * steal the staker’s bitcoins, because all the spending transactions
+  * steal the staker's bitcoins, because all the spending transactions
     require the staker's signature;
 
-  * slash the staker’s bitcoins by itself, because slashing requires the 
+  * slash the staker's bitcoins by itself, because slashing requires the 
     secret key of the finality provider, which the covenant committee does 
     not know in advance, and
 
@@ -47,8 +47,8 @@ duty or power. If it has a dishonest super majority, then
 
 In other words, there is no way the committee can act against the stakers, 
 except rejecting their staking requests. Furthermore, the dishonest actions 
-of the covenant committee can be contained by 1) including the staker’s 
-counterparty in the committee, such as the PoS system’s foundation, or 2) 
+of the covenant committee can be contained by 1) including the staker's 
+counterparty in the committee, such as the PoS system's foundation, or 2) 
 implementing a governance proposal to re-elect the committee.
 
 This rule-enforcing committee is necessary for now because the current BTC 
@@ -110,6 +110,21 @@ This flow ensures that all private key operations remain isolated within the
 secure Covenant Signer while the emulator handles the blockchain interaction 
 and validation logic.
 
+## Boot Order and Dependencies
+
+The Covenant Emulator requires the Covenant Signer to be running and unlocked 
+before it can start. This is because the emulator performs a health check
+during startup to ensure the signer is accessible and ready to handle signing requests.
+If the signer is not running or is locked, the emulator will fail to start with a clear error message.
+
+The required boot sequence is:
+1. Start and unlock the Covenant Signer
+2. Verify the signer is running and accessible
+3. Start the Covenant Emulator
+
+The emulator will automatically verify the signer's availability 
+during startup and will not proceed if the signer is not ready.
+
 ![Covenant Architecture](./static/covenant.png)
 
 ## Covenant Emulator Stack Setup
@@ -118,3 +133,10 @@ please follow the instructions in the following documents
 (in sequence):
 1. [Covenant Signer Setup](./docs/covenant-signer-setup.md)
 2. [Covenant Emulator Setup](./docs/covenant-emulator-setup.md)
+
+## Important Limitations
+
+**Keyring Backend**: The covenant emulator only supports the `test` 
+keyring backend. This limitation exists because the emulator requires automated
+signing capabilities without manual passphrase entry. Other keyring backends 
+will cause the emulator to fail at startup.

cmd/covd/start.go

@@ -45,7 +45,7 @@ func start(ctx *cli.Context) error {
 	}
 
 	if cfg.BabylonConfig.KeyringBackend != keyring.BackendTest {
-		return fmt.Errorf("the keyring backend in config must be `test` for automatic signing, got %s", cfg.BabylonConfig.KeyringBackend)
+		return fmt.Errorf("the keyring backend in config must be `test` for automatic signing, got %s. Other keyring backends are not supported as they require manual passphrase entry", cfg.BabylonConfig.KeyringBackend)
 	}
 
 	logger, err := log.NewRootLoggerWithFile(covcfg.LogFile(homePath), cfg.LogLevel)
@@ -63,6 +63,13 @@ func start(ctx *cli.Context) error {
 		return fmt.Errorf("failed to create remote signer from config: %w", err)
 	}
 
+	// Perform health check on the remote signer
+	logger.Info("Performing health check on remote signer...")
+	if _, err := signer.PubKey(); err != nil {
+		return fmt.Errorf("remote signer health check failed - ensure the signer is running and unlocked: %w", err)
+	}
+	logger.Info("Remote signer health check passed")
+
 	ce, err := covenant.NewCovenantEmulator(cfg, bbnClient, logger, signer)
 	if err != nil {
 		return fmt.Errorf("failed to start the covenant emulator: %w", err)

config/babylon.go

@@ -12,7 +12,7 @@ type BBNConfig struct {
 	RPCAddr        string        `long:"rpc-address" description:"address of the rpc server to connect to"`
 	GRPCAddr       string        `long:"grpc-address" description:"address of the grpc server to connect to"`
 	AccountPrefix  string        `long:"acc-prefix" description:"account prefix to use for addresses"`
-	KeyringBackend string        `long:"keyring-type" description:"type of keyring to use"`
+	KeyringBackend string        `long:"keyring-type" description:"type of keyring to use"` // IMPORTANT: Only 'test' backend is supported due to automated signing requirements
 	GasAdjustment  float64       `long:"gas-adjustment" description:"adjustment factor when using gas estimation"`
 	GasPrices      string        `long:"gas-prices" description:"comma separated minimum gas prices to accept for transactions"`
 	KeyDirectory   string        `long:"key-dir" description:"directory to store keys in"`
@@ -33,7 +33,7 @@ func DefaultBBNConfig() BBNConfig {
 		GRPCAddr:       dc.GRPCAddr,
 		AccountPrefix:  dc.AccountPrefix,
 		KeyringBackend: dc.KeyringBackend,
-		GasAdjustment:  dc.GasAdjustment,
+		GasAdjustment:  5, // Increased from default to ensure sufficient gas
 		GasPrices:      dc.GasPrices,
 		Debug:          dc.Debug,
 		Timeout:        dc.Timeout,

docs/covenant-emulator-setup.md

@@ -6,12 +6,13 @@ daemon program.
 ## Table of Contents
 
 1. [Prerequesites](#1-prerequisites)
-2. [Install Covenant Emulator Binary](#2-install-covenant-emulator-binary)
-3. [Setting up the Covenant Emulator Program](#3-setting-up-the-covenant-emulator-program)
-	1. [Initialize directories](#31-initialize-directories)
-	2. [Configure the covenant emulator](#32-configure-the-covenant-emulator)
-4. [Generate key pairs](#4-generate-key-pairs)
-5. [Start the emulator daemon](#5-start-the-emulator-daemon)
+2. [Boot Order and Signer Dependency](#2-boot-order-and-signer-dependency)
+3. [Install Covenant Emulator Binary](#3-install-covenant-emulator-binary)
+4. [Setting up the Covenant Emulator Program](#4-setting-up-the-covenant-emulator-program)
+	1. [Initialize directories](#41-initialize-directories)
+	2. [Configure the covenant emulator](#42-configure-the-covenant-emulator)
+5. [Generate key pairs](#5-generate-key-pairs)
+6. [Start the emulator daemon](#6-start-the-emulator-daemon)
 
 ## 1. Prerequisites
 
@@ -26,7 +27,36 @@ To successfully complete this guide, you will need:
 2. A connection to a Babylon node. To run your own node, please refer to the
   [Babylon Node Setup Guide](https://github.com/babylonlabs-io/networks/blob/main/bbn-test-5/bbn-test-5/babylon-node/README.md).
 
-## 2. Install covenant emulator binary
+## 2. Boot Order and Signer Dependency
+
+The Covenant Emulator requires the Covenant Signer to be running and
+unlocked before it can start. This is a critical dependency that is enforced 
+through a health check during the emulator's startup process.
+
+### Required Boot Sequence
+
+1. Start the Covenant Signer:
+2. Unlock the Covenant Signer:
+3. Verify the signer is running and accessible:
+4. Start the Covenant Emulator:
+
+### Health Check Behavior
+
+The emulator performs an automatic health check during startup by attempting 
+to fetch the signer's public key. If this check fails, the emulator will:
+- Log an error message indicating the signer is not accessible
+- Provide guidance to ensure the signer is running and unlocked
+- Exit with a non-zero status code
+
+### Troubleshooting
+
+If the emulator fails to start with a signer-related error:
+1. Verify the signer is running and accessible at the configured URL
+2. Check if the signer is locked and needs to be unlocked
+3. Verify the HMAC key in the emulator's configuration matches the signer's configuration
+4. Check the signer's logs for any errors or issues
+
+## 3. Install covenant emulator binary
 
 If you haven't already, download [Golang 1.23](https://go.dev/dl).
 
@@ -65,9 +95,9 @@ export PATH=$HOME/go/bin:$PATH
 echo 'export PATH=$HOME/go/bin:$PATH' >> ~/.profile
 ```
 
-## 3. Setting up the covenant emulator program
+## 4. Setting up the covenant emulator program
 
-### 3.1. Initialize directories
+### 4.1. Initialize directories
 
 Next, initialize the node and home directory by generating all of the
 necessary files such as `covd.conf`. These files will live in the `<path>`
@@ -85,7 +115,7 @@ $ ls <path>
   ├── logs      # Covd logs
 ```
 
-### 3.2. Configure the covenant emulator
+### 4.2. Configure the covenant emulator
 
 Use the following parameters to configure the `covd.conf` file.
 
@@ -140,11 +170,19 @@ Below are brief explanations of the configuration entries:
 - `GRPCAddr` - gRPC endpoint for connecting to a Babylon node
 - `Key` - Name of the key in the keyring used for transaction signing
 - `KeyringBackend` - Storage backend for the keyring (os, file, kwallet, pass, test, memory)
+
+> **IMPORTANT LIMITATION**: The covenant emulator only supports the `test` 
+keyring backend. This limitation exists because the emulator requires automated
+signing capabilities and the test backend is the only one that supports this
+feature without manual passphrase entry. Other keyring backends 
+(os, file, kwallet, pass, memory) will not work and will
+cause the emulator to fail at startup.
+
 - `URL` - Endpoint where the remote signing service is running
 - `Timeout` - Maximum time to wait for remote signer responses
 - `HMACKey` - Secret key for HMAC authentication with the covenant-signer
 
-### 3.3. Configure HMAC Authentication (Recommended for Production)
+### 4.3. Configure HMAC Authentication (Recommended for Production)
 
 HMAC (Hash-based Message Authentication Code) authentication provides an additional layer of security for the communication between the covenant-emulator and covenant-signer by ensuring that only authenticated requests are processed.
 
@@ -174,7 +212,7 @@ HMAC (Hash-based Message Authentication Code) authentication provides an additio
 When HMAC authentication is properly configured, all requests between the covenant-emulator and covenant-signer will include an authentication header. If there's a key mismatch or other authentication issues, you'll see error messages in the logs.
 
 
-## 4. Generate key pairs
+## 5. Generate key pairs
 
 The covenant emulator daemon requires the existence of a Babylon keyring that
 signs signatures and interacts with Babylon. Use the following command to generate
@@ -209,7 +247,7 @@ To check your balance, View your account on the
 address.
 
 
-## 5. Start the emulator daemon
+## 6. Start the emulator daemon
 
 You can start the covenant emulator daemon using the following command: