Skip to content

Commit

Permalink
update dev-node.md for multiple providers support (#1857)
Browse files Browse the repository at this point in the history 
* update dev-node.md for multiple providers support

* update json response

* line breaks

* lint
  • Loading branch information
@imabdulbasit
imabdulbasit authored Aug 13, 2024
1 parent 6914edd commit 702fa23
Show file tree
Hide file tree
Showing 2 changed files with 76 additions and 48 deletions.
66 changes: 48 additions & 18 deletions doc/espresso-dev-node.md
View file
Original file line number Diff line number Diff line change
@@ -1,7 +1,9 @@
# Espresso Dev Node

Espresso dev node is a node specifically designed for development and testing. It includes various nodes required to run
a complete Espresso network, such as `builder`, `sequencer`, etc. Developers can use it for development and testing.
a complete Espresso network, such as `builder`, `sequencer`, `state_prover` etc. Additionally, it supports deploying
light client contracts on alternative chains and running a separate prover for each which can be useful for testing
involving L3s. Developers can use dev node for development and testing.

## Download

Expand All @@ -13,16 +15,23 @@ docker run ghcr.io/espressosystems/espresso-sequencer/espresso-dev-node:main

## Parameters

| Name | Type | Environment Variable | Default Value | Description |
| ------------------------------- | --------------- | ------------------------------------ | ------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpc_url` | `Option<Url>` | `ESPRESSO_SEQUENCER_L1_PROVIDER` | Automatically launched Avil node if not provided. | The JSON-RPC endpoint of the L1. If not provided, an Avil node will be launched automatically. |
| `mnemonic` | `String` | `ESPRESSO_SEQUENCER_ETH_MNEMONIC` | `test test test test test test test test test test test junk` | Mnemonic for an L1 wallet. This wallet is used to deploy the contracts, so the account indicated by `ACCOUNT_INDEX` must be funded with ETH. |
| `account_index` | `u32` | `ESPRESSO_DEPLOYER_ACCOUNT_INDEX` | `0` | Account index of the L1 wallet generated from `MNEMONIC`. Used when deploying contracts. |
| `sequencer_api_port` | `u16` | `ESPRESSO_SEQUENCER_API_PORT` | Required | Port that the HTTP API will use. |
| `sequencer_api_max_connections` | `Option<usize>` | `ESPRESSO_SEQUENCER_MAX_CONNECTIONS` | None | Maximum concurrent connections allowed by the HTTP API server. |
| `builder_port` | `Option<u16>` | `ESPRESSO_BUILDER_PORT` | An unused port | Port for connecting to the builder. |
| `prover_port` | `Option<u16>` | `ESPRESSO_PROVER_PORT` | An unused port | Port for connecting to the prover. If this is not provided, an available port will be selected. |
| `dev_node_port` | `u16` | `ESPRESSO_DEV_NODE_PORT` | `20000` | Port for the dev node. This is used to provide tools and information to facilitate developers debugging. |
| Name | Type | Environment Variable | Default Value | Description |
| ------------------------------- | --------------- | -------------------------------------------- | ------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `rpc_url` | `Option<Url>` | `ESPRESSO_SEQUENCER_L1_PROVIDER` | Automatically launched Avil node if not provided. | The JSON-RPC endpoint of the L1. If not provided, an Avil node will be launched automatically. |
| `mnemonic` | `String` | `ESPRESSO_SEQUENCER_ETH_MNEMONIC` | `test test test test test test test test test test test junk` | Mnemonic for an L1 wallet. This wallet is used to deploy the contracts, so the account indicated by`ACCOUNT_INDEX` must be funded with ETH. |
| `account_index` | `u32` | `ESPRESSO_DEPLOYER_ACCOUNT_INDEX` | `0` | Account index of the L1 wallet generated from`MNEMONIC`. Used when deploying contracts. |
| `sequencer_api_port` | `u16` | `ESPRESSO_SEQUENCER_API_PORT` | Required | Port that the HTTP API will use. |
| `sequencer_api_max_connections` | `Option<usize>` | `ESPRESSO_SEQUENCER_MAX_CONNECTIONS` | None | Maximum concurrent connections allowed by the HTTP API server. |
| `builder_port` | `Option<u16>` | `ESPRESSO_BUILDER_PORT` | An unused port | Port for connecting to the builder. |
| `prover_port` | `Option<u16>` | `ESPRESSO_PROVER_PORT` | An unused port | Port for connecting to the prover. If this is not provided, an available port will be selected. |
| `dev_node_port` | `u16` | `ESPRESSO_DEV_NODE_PORT` | `20000` | Port for the dev node. This is used to provide tools and information to facilitate developers debugging. |
| `update_interval` | `Duration` | `ESPRESSO_STATE_PROVER_UPDATE_INTERVAL` | `20s` | The frequency of updating the light client state |
| `retry_interval` | `Duration` | `ESPRESSO_STATE_PROVER_RETRY_INTERVAL` | `2s` | Interval between retries if a state update fails. |
| `alt_chain_providers` | `Vec<Url>` | `ESPRESSO_DEPLOYER_ALT_CHAIN_PROVIDERS` | `None` | Optional list of URLs representing alternate chains where the dev node will deploy Light client contracts and submit Light contract state updates. Useful for test environments involving L3s. |
| `alt_mnemonics` | `Vec<String>` | `ESPRESSO_DEPLOYER_ALT_MNEMONICS` | `None` | Optional list of mnemonics for the alternate chains. If there are fewer mnemonics provided than chains, the base `MNEMONIC` will be used. |
| `alt_account_indices` | `Vec<u32>` | `ESPRESSO_SEQUENCER_DEPLOYER_ALT_INDICES` | `None` | Optional list of account indices to use when deploying the contracts. If there are fewer indices provided than chains, the base ACCOUNT_INDEX will be used. |
| `alt_prover_update_intervals` | `Vec<Duration>` | `ESPRESSO_STATE_PROVER_ALT_UPDATE_INTERVALS` | `None` | The frequency of updating the light client state for alternate chains. If there are fewer provided than chains, the base update_interval will be used. |
| `alt_prover_retry_intervals` | `Vec<Duration>` | `ESPRESSO_STATE_PROVER_ALT_RETRY_INTERVALS` | `None` | Interval between retries if a state update fails for alternate chains. If there are fewer intervals provided than chains, the base retry_interval will be used. |

## APIs

Expand All @@ -42,9 +51,23 @@ An example response is like this:
```json
{
"builder_url": "http://localhost:41003/",
"prover_port": 23156,
"l1_prover_port": 23156,
"l1_url": "http://localhost:8545/",
"light_client_address": "0xb075b82c7a23e0994df4793422a1f03dbcf9136f"
"l1_light_client_address": "0xb075b82c7a23e0994df4793422a1f03dbcf9136f",
"alt_chains": [
{
"chain_id": 9,
"provider_url": "http://localhost:8546/",
"light_client_address": "0xa1b2c3d4e5f678901234567890abcdef12345678",
"prover_port": 23157
},
{
"chain_id": 10,
"provider_url": "http://localhost:8547/",
"light_client_address": "0xabcdefabcdefabcdefabcdefabcdefabcdefabcdef",
"prover_port": 23158
}
]
}
```

Expand All @@ -53,8 +76,8 @@ An example response is like this:
This endpoint simulates the effect of a liveness failure of the hotshot consensus protocol in the Light Client smart
contract.

By calling this, the L1 height in the light contract will be frozen, and rollups will detect the HotShot failure. This
is intended for testing rollups' functionalities when HotShot is down.
By calling this, the height in the light contract will be frozen, and rollups will detect the HotShot failure. This is
intended for testing rollups' functionalities when HotShot is down.

An example of a `curl` command:

Expand All @@ -66,9 +89,10 @@ curl -X POST "http://localhost:20000/api/set-hotshot-down" \

Parameters

| Name | Type | Description |
| ------ | ------- | ---------------------------------------- |
| height | integer | The L1 height from which hotshot is down |
| Name | Type | Required | Description |
| -------- | ------- | -------- | ------------------------------------------------------------------------------------------------------------- |
| chain_id | integer | No | chain id for which the height needs to be frozen. If not provided, the base L1 light client contract is used. |
| height | integer | Yes | The height from which hotshot is down |

### POST /api/set-hotshot-up

Expand All @@ -84,3 +108,9 @@ An example of a `curl` command:
curl -X POST "http://localhost:20000/api/set-hotshot-up" \
-H "Content-Type: application/json"
```

Parameter

| Name | Type | Required | Description |
| -------- | ------- | -------- | --------------------------------------------------------------------------------------------------------------- |
| chain_id | integer | No | chain id for which the height needs to be unfrozen. If not provided, the base L1 light client contract will be used. |
58 changes: 28 additions & 30 deletions sequencer/src/bin/espresso-dev-node.rs
View file
Original file line number Diff line number Diff line change
Expand Up @@ -40,14 +40,14 @@ use vbs::version::StaticVersionType;

#[derive(Clone, Debug, Parser)]
struct Args {
/// A JSON-RPC endpoint for the L1 to deploy to. If this is not provided, an Avil node will be
/// launched automatically.
/// A JSON-RPC endpoint for the L1 to deploy to.
/// If this is not provided, an Avil node will be launched automatically.
#[clap(short, long, env = "ESPRESSO_SEQUENCER_L1_PROVIDER")]
rpc_url: Option<Url>,
/// Mnemonic for an L1 wallet.
///
/// This wallet is used to deploy the contracts, so the account indicated by ACCOUNT_INDEX must
/// be funded with with ETH.
/// This wallet is used to deploy the contracts,
/// so the account indicated by ACCOUNT_INDEX must be funded with with ETH.
#[clap(
long,
name = "MNEMONIC",
Expand All @@ -64,27 +64,33 @@ struct Args {
)]
account_index: u32,

/// Optional list of URLs representing alternate chains where the dev node will deploy LC contracts
/// and submit LC state updates.
/// The frequency of updating the light client state, expressed in update interval
#[clap( long, value_parser = parse_duration, default_value = "20s", env = "ESPRESSO_STATE_PROVER_UPDATE_INTERVAL")]
update_interval: Duration,

/// Interval between retries if a state update fails
#[clap(long , value_parser = parse_duration, default_value = "2s", env = "ESPRESSO_STATE_PROVER_RETRY_INTERVAL")]
retry_interval: Duration,

/// Optional list of URLs representing alternate chains
/// where the dev node will deploy LC contracts and submit LC state updates.
///
/// Useful for test environments involving L3s.
#[arg(long, env = "ESPRESSO_DEPLOYER_ALT_CHAIN_PROVIDERS", num_args = 1.., value_delimiter = ',')]
alt_chain_providers: Vec<Url>,

/// Optional list of mnemonics for the alternate chains. If there are fewer mnemonics provided than chains, the base MNEMONIC will be used.
/// Optional list of mnemonics for the alternate chains.
/// If there are fewer mnemonics provided than chains, the base MNEMONIC will be used.
#[arg(long, env = "ESPRESSO_DEPLOYER_ALT_MNEMONICS", num_args = 1.., value_delimiter = ',')]
alt_mnemonics: Vec<String>,

/// The frequency of updating the light client state, expressed in update interval
#[clap( long, value_parser = parse_duration, default_value = "20s", env = "ESPRESSO_STATE_PROVER_UPDATE_INTERVAL")]
update_interval: Duration,
/// Alternate account indices generated by the mnemonics to use when deploying the contracts.
/// If there are fewer indices provided than chains, the base ACCOUNT_INDEX will be used.
#[clap(long, env = "ESPRESSO_SEQUENCER_DEPLOYER_ALT_INDICES")]
alt_account_indices: Vec<u32>,

/// Interval between retries if a state update fails
#[clap(long , value_parser = parse_duration, default_value = "2s", env = "ESPRESSO_STATE_PROVER_RETRY_INTERVAL")]
retry_interval: Duration,
/// The frequency of updating the light client state for alt chains.
/// If there are fewer intervals provided than chains, the base update interval will be used.

#[clap(long, value_parser = parse_duration, env = "ESPRESSO_STATE_PROVER_ALT_UPDATE_INTERVALS", num_args = 1.., value_delimiter = ',')]
alt_prover_update_intervals: Vec<Duration>,

Expand All @@ -93,14 +99,6 @@ struct Args {
#[clap(long, value_parser = parse_duration, env = "ESPRESSO_STATE_PROVER_ALT_RETRY_INTERVALS", num_args = 1.., value_delimiter = ',')]
alt_prover_retry_intervals: Vec<Duration>,

/// Alternate account indices generated by the mnemonics to use when deploying the contracts. If there are fewer indices provided than chains, the base ACCOUNT_INDEX will be used.
#[clap(
long,
env = "ESPRESSO_SEQUENCER_DEPLOYER_ALT_INDICES",
default_value = "0"
)]
alt_account_indices: Vec<u32>,

/// Port that the HTTP API will use.
#[clap(long, env = "ESPRESSO_SEQUENCER_API_PORT")]
sequencer_api_port: u16,
Expand Down Expand Up @@ -130,14 +128,6 @@ struct Args {
logging: logging::Config,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct AltChainInfo {
pub chain_id: u64,
pub provider_url: Url,
pub light_client_address: Address,
pub prover_port: u16,
}

#[async_std::main]
async fn main() -> anyhow::Result<()> {
let cli_params = Args::parse();
Expand Down Expand Up @@ -484,6 +474,14 @@ struct DevInfo {
pub alt_chains: Vec<AltChainInfo>,
}

#[derive(Debug, Clone, Serialize, Deserialize)]
struct AltChainInfo {
pub chain_id: u64,
pub provider_url: Url,
pub light_client_address: Address,
pub prover_port: u16,
}

#[derive(Debug, Serialize, Deserialize)]
struct SetHotshotDownReqBody {
// return l1 light client address if not provided
Expand Down

0 comments on commit 702fa23

Please sign in to comment.