feat(staking-cli): add mainnet support and metadata validation (#3922)

* feat(staking-cli): add mainnet support and metadata validation

Mainnet support:
- Add config.mainnet.toml with mainnet contract addresses
- Add Network enum (Mainnet, Decaf, Local) for init command
- Update init command to require --network parameter
- Update README with mainnet contract addresses and Docker usage

Metadata validation:
- Add NodeMetadataContent schema types for metadata validation
- Add validate_metadata_uri function with 5s timeout
- Add --skip-metadata-validation flag to bypass validation
- Add --consensus-public-key parameter for update-metadata-uri
- Add parse_bls_pub_key helper function
- Include --skip-metadata-validation hint in error messages

Contract deployer:
- Add configurable deploy cooldown via --post-deployment-cooldown
- Refactor Contracts struct to use explicit fields instead of Deref

Tests:
- Add metadata validation tests for register-validator and update-metadata-uri
- Remove unnecessary spawn_blocking from metadata validation tests
- Add bls_public_key_str helper to TestSystemExt

Documentation:
- Major README update with improved formatting and examples
- Document metadata validation and schema requirements
- Add calldata export documentation

* fix: contracts API for dev node

* refactor(staking-cli): deduplicate generate_bls_pub_key test helper

Move generate_bls_pub_key to module level with #[cfg(test)] so both
test and validation_tests modules can share it.

* test(staking-cli): add test for missing signer error

Verify that running a command without providing any signer
(--mnemonic, --private-key, or --ledger) fails with an appropriate
error message.

* fix(staking-cli): config command shows helpful message when no file exists

Previously the config command would print "Config file at X" and show
default values even when no config file existed. Now it correctly
detects missing files and suggests running init.

* docs(staking-cli): document multi-network config file usage

Add section explaining how to use the -c flag to maintain separate
config files for different networks (mainnet, decaf). Also clarify
that config files are optional and what happens when none exists.

Author: sveitser

Cargo.toml

@@ -147,8 +147,8 @@ indexmap = { version = "2", features = ["serde"] }
 lazy_static = "1"
 libp2p-identity = { version = "0.2", features = ["ed25519", "serde"] }
 libp2p-swarm-derive = { version = "0.35" }
-moka = { version = "0.12.12", features = ["future"] }
 memoize = { version = "0.4", features = ["full"] }
+moka = { version = "0.12.12", features = ["future"] }
 multiaddr = { version = "0.18" }
 nohash-hasher = "0.2.0"
 num_cpus = "1"

contracts/rust/deployer/src/lib.rs

@@ -21,7 +21,7 @@ use alloy::{
 };
 use anyhow::{anyhow, Context, Result};
 use clap::{builder::OsStr, Parser, ValueEnum};
-use derive_more::{derive::Deref, Display};
+use derive_more::Display;
 use espresso_types::{v0_1::L1Client, v0_3::Fetcher};
 use hotshot_contract_adapter::sol_types::*;
 
@@ -274,8 +274,22 @@ impl From<Contract> for OsStr {
 }
 
 /// Cache of contracts predeployed or deployed during this current run.
-#[derive(Deref, Debug, Clone, Default)]
-pub struct Contracts(HashMap<Contract, Address>);
+#[derive(Debug, Clone)]
+pub struct Contracts {
+    addresses: HashMap<Contract, Address>,
+    // TODO: having the cooldown field here is a bit hacky but we postpone a better solution to
+    // avoid a large refactor.
+    deploy_cooldown: Duration,
+}
+
+impl Default for Contracts {
+    fn default() -> Self {
+        Self {
+            addresses: HashMap::new(),
+            deploy_cooldown: Duration::ZERO,
+        }
+    }
+}
 
 impl From<DeployedContracts> for Contracts {
     fn from(deployed: DeployedContracts) -> Self {
@@ -337,17 +351,43 @@ impl From<DeployedContracts> for Contracts {
         if let Some(addr) = deployed.reward_claim_proxy {
             m.insert(Contract::RewardClaimProxy, addr);
         }
-        Self(m)
+        Self {
+            addresses: m,
+            deploy_cooldown: Duration::ZERO,
+        }
     }
 }
 
 impl Contracts {
     pub fn new() -> Self {
-        Contracts(HashMap::new())
+        Self::default()
+    }
+
+    pub fn with_cooldown(cooldown: Duration) -> Self {
+        Self {
+            addresses: HashMap::new(),
+            deploy_cooldown: cooldown,
+        }
+    }
+
+    pub fn set_cooldown(&mut self, cooldown: Duration) {
+        self.deploy_cooldown = cooldown;
     }
 
     pub fn address(&self, contract: Contract) -> Option<Address> {
-        self.0.get(&contract).copied()
+        self.addresses.get(&contract).copied()
+    }
+
+    pub fn get(&self, contract: &Contract) -> Option<&Address> {
+        self.addresses.get(contract)
+    }
+
+    pub fn iter(&self) -> impl Iterator<Item = (&Contract, &Address)> {
+        self.addresses.iter()
+    }
+
+    pub fn remove(&mut self, contract: &Contract) -> Option<Address> {
+        self.addresses.remove(contract)
     }
 
     /// Deploy a contract (with logging and cached deployments)
@@ -358,7 +398,7 @@ impl Contracts {
     where
         P: Provider,
     {
-        if let Some(addr) = self.0.get(&name) {
+        if let Some(addr) = self.addresses.get(&name) {
             tracing::info!("skipping deployment of {name}, already deployed at {addr:#x}");
             return Ok(*addr);
         }
@@ -377,18 +417,18 @@ impl Contracts {
 
         tracing::info!("deployed {name} at {addr:#x}");
 
-        // Cooldown after deployment to avoid rate limiting on public RPC nodes
-        // This helps when deploying multiple contracts in sequence
-        tokio::time::sleep(Duration::from_millis(1000)).await;
-        tracing::info!("cooldown 1000ms after deployment");
+        if !self.deploy_cooldown.is_zero() {
+            tokio::time::sleep(self.deploy_cooldown).await;
+            tracing::info!("cooldown {:?} after deployment", self.deploy_cooldown);
+        }
 
-        self.0.insert(name, addr);
+        self.addresses.insert(name, addr);
         Ok(addr)
     }
 
     /// Write a .env file.
     pub fn write(&self, mut w: impl Write) -> Result<()> {
-        for (contract, address) in &self.0 {
+        for (contract, address) in &self.addresses {
             writeln!(w, "{contract}={address:#x}")?;
         }
         Ok(())
@@ -2316,7 +2356,7 @@ mod tests {
 
     impl Contracts {
         fn insert(&mut self, name: Contract, address: Address) -> Option<Address> {
-            self.0.insert(name, address)
+            self.addresses.insert(name, address)
         }
     }
 
@@ -4486,7 +4526,7 @@ mod tests {
         let cached_impl_addr = contracts.address(Contract::FeeContract);
 
         // For patch upgrades, we need to clear the cache to allow redeployment
-        contracts.0.remove(&Contract::FeeContract);
+        contracts.remove(&Contract::FeeContract);
 
         // Test the upgrade function directly
         let receipt = upgrade_fee_v1(&provider, &mut contracts).await?;
@@ -4566,7 +4606,7 @@ mod tests {
 
         // Second upgrade to V2 (re-applying same version)
         // For patch upgrades, we need to clear the cache to allow redeployment
-        contracts.0.remove(&Contract::LightClientV2);
+        contracts.remove(&Contract::LightClientV2);
 
         // Second upgrade to V2 (re-applying same version)
         upgrade_light_client_v2(

sequencer/src/bin/deploy.rs

@@ -405,6 +405,16 @@ struct Options {
     #[clap(flatten)]
     logging: logging::Config,
 
+    /// Cooldown after each contract deployment to avoid outdated state during post deployment
+    /// verification steps.
+    #[clap(
+        long,
+        env = "ESPRESSO_POST_DEPLOYMENT_COOLDOWN",
+        default_value = "1s",
+        value_parser = parse_duration,
+    )]
+    post_deployment_cooldown: Duration,
+
     /// Command to run
     ///
     /// For backwards compatibility, the default is to deploy contracts, if no
@@ -432,6 +442,8 @@ async fn main() -> anyhow::Result<()> {
     };
 
     let mut contracts = Contracts::from(opt.contracts);
+    contracts.set_cooldown(opt.post_deployment_cooldown);
+
     let provider = if opt.ledger {
         let signer = connect_ledger(opt.account_index as usize).await?;
         tracing::info!("Using ledger for signing, watch ledger device for prompts.");