From 921bc6b681cf67aeeec4cdfdacdee8fdf077af8f Mon Sep 17 00:00:00 2001 From: dylan Date: Tue, 3 Jun 2025 20:26:26 -0600 Subject: [PATCH 1/7] update readme --- README.md | 45 +++++++++++++++++++++++++++++++++------------ 1 file changed, 33 insertions(+), 12 deletions(-) diff --git a/README.md b/README.md index 031035ae..a6f330fa 100644 --- a/README.md +++ b/README.md @@ -8,29 +8,32 @@ This crate contains an example block builder in the Signet ecosystem. ### Requirements -- Rust 1.81.0 -- Cargo [Lambda](https://www.cargo-lambda.info/) -- AWS CLI and credentials +- Rust 1.85 +- AWS CLI +- A private key or AWS KMS key for signing transactions ### Environment The following environment variables are exposed to configure the Builder: ```bash -# Builder Configs -HOST_CHAIN_ID="17000" # Holesky Testnet -RU_CHAIN_ID="17001" -HOST_RPC_URL="http://host.url.here" -# trailing slash is required -TX_BROADCAST_URLS="http://tx.broadcast.url.here/,https://additional.url.here/" -ZENITH_ADDRESS="ZENITH_ADDRESS_HERE" -QUINCEY_URL="http://signer.url.here" +# Builder Configs for Pecorino Test Net +HOST_CHAIN_ID="3151908" +RU_CHAIN_ID="14174" +HOST_RPC_URL="https://host-rpc.pecorino.signet.sh" +TX_BROADCAST_URLS="" # trailing slash is required - set to none for test net configuration +ZENITH_ADDRESS="0xbe45611502116387211D28cE493D6Fb3d192bc4E" +QUINCEY_URL="http://sequencer.pecorino.signet.sh/signBlock" BUILDER_PORT="8080" -BUILDER_KEY="YOUR_BUILDER_KEY_HERE" INCOMING_TRANSACTIONS_BUFFER="10" BLOCK_CONFIRMATION_BUFFER="10" BUILDER_REWARDS_ADDRESS="BUILDER_REWARDS_ADDRESS_HERE" ROLLUP_BLOCK_GAS_LIMIT="30000000" +CONCURRENCY_LIMIT=10 # Concurrency parameter for simulation +# Pecorino Slot Timing Configuration +SLOT_OFFSET="4" +SLOT_DURATION="12" +START_TIMESTAMP="1740681556" # Transaction Pool Configs TX_POOL_URL="http://pool.url.here/" # trailing slash is required TX_POOL_POLL_INTERVAL="5" # seconds @@ -53,3 +56,21 @@ Sign request example payload: "contents": "0x0707070707070707070707070707070707070707070707070707070707070707" } ``` + +## Transaction Sender + +The builder includes a `transaction-sender` for sending miniscule transactions for the purpose of testing the rollup block construction process. The `transaction-sender` is located in `bin/submit-transaction.rs`. + +It requires a key to sign the transactions and a funded wallet. + +### Environment Variables + +The `transaction-sender` also has a set of configurable environment variables listed below. + +``` +RPC_URL="" # The URL of the RPC endpoint of the node you're sending the transaction to. +RECIPIENT_ADDRESS="" # The address the submitter addresses the transaction to. +SLEEP_TIME="" # The time to wait before sending another transaction, in seconds. +SIGNER_CHAIN_ID="" +SIGNER_KEY="" # +``` \ No newline at end of file From be98d1889aab5a805df42be82e26caf8b4c1af13 Mon Sep 17 00:00:00 2001 From: dylan Date: Wed, 4 Jun 2025 11:38:23 -0600 Subject: [PATCH 2/7] more cleanup and readme updates - removes some unused env vars --- README.md | 62 +++++++++++++++++++++++++---------------------- src/config.rs | 48 +++++++++++++++++++++--------------- src/test_utils.rs | 2 -- 3 files changed, 61 insertions(+), 51 deletions(-) diff --git a/README.md b/README.md index a6f330fa..0a2c4c54 100644 --- a/README.md +++ b/README.md @@ -20,43 +20,35 @@ The following environment variables are exposed to configure the Builder: # Builder Configs for Pecorino Test Net HOST_CHAIN_ID="3151908" RU_CHAIN_ID="14174" + +# Transaction Pool Configs +TX_POOL_URL="http://pool.url.here/" # trailing slash is required + +# RPC Endpoints HOST_RPC_URL="https://host-rpc.pecorino.signet.sh" +RU_RPC_URL="https://rpc.pecorino.signet.sh" +TX_POOL_URL="" TX_BROADCAST_URLS="" # trailing slash is required - set to none for test net configuration + +# Contract configurations ZENITH_ADDRESS="0xbe45611502116387211D28cE493D6Fb3d192bc4E" +BUILDER_HELPER_ADDRESS="0xb393416A722Fd48C3b0a9ab5fC2512Ef0c55e4CA" + +# Misc. QUINCEY_URL="http://sequencer.pecorino.signet.sh/signBlock" BUILDER_PORT="8080" -INCOMING_TRANSACTIONS_BUFFER="10" -BLOCK_CONFIRMATION_BUFFER="10" +SEQUENCER_KEY="" +BUILDER_KEY="" BUILDER_REWARDS_ADDRESS="BUILDER_REWARDS_ADDRESS_HERE" -ROLLUP_BLOCK_GAS_LIMIT="30000000" -CONCURRENCY_LIMIT=10 # Concurrency parameter for simulation -# Pecorino Slot Timing Configuration +ROLLUP_BLOCK_GAS_LIMIT="" +CONCURRENCY_LIMIT="" + +# Pecorino Slot Timing Configurations SLOT_OFFSET="4" SLOT_DURATION="12" START_TIMESTAMP="1740681556" -# Transaction Pool Configs -TX_POOL_URL="http://pool.url.here/" # trailing slash is required -TX_POOL_POLL_INTERVAL="5" # seconds -TX_POOL_CACHE_DURATION="600" # seconds ``` -## API - -### SignRequest - -Sign request example payload: - -```json -{ - "hostBlockNumber": "0x0", - "hostChainId": "0x1", - "ruChainId": "0x2", - "gasLimit": "0x5", - "ruRewardAddress": "0x0606060606060606060606060606060606060606", - "contents": "0x0707070707070707070707070707070707070707070707070707070707070707" -} -``` - ## Transaction Sender The builder includes a `transaction-sender` for sending miniscule transactions for the purpose of testing the rollup block construction process. The `transaction-sender` is located in `bin/submit-transaction.rs`. @@ -67,10 +59,22 @@ It requires a key to sign the transactions and a funded wallet. The `transaction-sender` also has a set of configurable environment variables listed below. -``` +```sh RPC_URL="" # The URL of the RPC endpoint of the node you're sending the transaction to. RECIPIENT_ADDRESS="" # The address the submitter addresses the transaction to. SLEEP_TIME="" # The time to wait before sending another transaction, in seconds. SIGNER_CHAIN_ID="" -SIGNER_KEY="" # -``` \ No newline at end of file +SIGNER_KEY="" +``` + +## Testing + +### F + +In order to test the `builder`, one must build and deploy an image in the target network with a provisioned key. + +1. Build a docker image with your changes +2. Push the image to the image repository +3. Update the image in the deployment +4. Assert and confirm expected behavior + diff --git a/src/config.rs b/src/config.rs index 49bed7b6..624c67a3 100644 --- a/src/config.rs +++ b/src/config.rs @@ -55,20 +55,33 @@ pub type HostProvider = FillProvider< /// chain. #[derive(Debug, Clone, FromEnv)] pub struct BuilderConfig { - /// The chain ID of the host chain + /// The chain ID of the host chain. #[from_env(var = "HOST_CHAIN_ID", desc = "The chain ID of the host chain")] pub host_chain_id: u64, - /// The chain ID of the rollup chain + + /// The chain ID of the rollup chain. #[from_env(var = "RU_CHAIN_ID", desc = "The chain ID of the rollup chain")] pub ru_chain_id: u64, + /// URL for Host RPC node. #[from_env(var = "HOST_RPC_URL", desc = "URL for Host RPC node", infallible)] pub host_rpc_url: Cow<'static, str>, + /// URL for the Rollup RPC node. #[from_env(var = "ROLLUP_RPC_URL", desc = "URL for Rollup RPC node", infallible)] pub ru_rpc_url: Cow<'static, str>, - /// Additional RPC URLs to which to broadcast transactions. - /// NOTE: should not include the host_rpc_url value + + /// URL of the tx pool to poll for incoming transactions. + #[from_env( + var = "TX_POOL_URL", + desc = "URL of the tx pool to poll for incoming transactions", + infallible + )] + pub tx_pool_url: Cow<'static, str>, + + /// Additional RPC URLs to which the builder should broadcast transactions. + /// * Should not include the `HOST_RPC_URL` value, as that is already sent to by default. + /// * Setting this can incur `already known` errors. #[from_env( var = "TX_BROADCAST_URLS", desc = "Additional RPC URLs to which the builder broadcasts transactions", @@ -76,26 +89,31 @@ pub struct BuilderConfig { optional )] pub tx_broadcast_urls: Vec>, - /// address of the Zenith contract on Host. + + /// Address of the Zenith contract on Host. #[from_env(var = "ZENITH_ADDRESS", desc = "address of the Zenith contract on Host")] pub zenith_address: Address, - /// address of the Builder Helper contract on Host. + + /// Address of the Builder Helper contract on Host. #[from_env( var = "BUILDER_HELPER_ADDRESS", desc = "address of the Builder Helper contract on Host" )] pub builder_helper_address: Address, + /// URL for remote Quincey Sequencer server to sign blocks. - /// Disregarded if a sequencer_signer is configured. + /// NB: Disregarded if a sequencer_signer is configured. #[from_env( var = "QUINCEY_URL", desc = "URL for remote Quincey Sequencer server to sign blocks", infallible )] pub quincey_url: Cow<'static, str>, + /// Port for the Builder server. #[from_env(var = "BUILDER_PORT", desc = "Port for the Builder server")] pub builder_port: u16, + /// Key to access Sequencer Wallet - AWS Key ID _OR_ local private key. /// Set IFF using local Sequencer signing instead of remote Quincey signing. #[from_env( @@ -105,6 +123,7 @@ pub struct BuilderConfig { optional )] pub sequencer_key: Option, + /// Key to access Builder transaction submission wallet - AWS Key ID _OR_ local private key. #[from_env( var = "BUILDER_KEY", @@ -112,6 +131,7 @@ pub struct BuilderConfig { infallible )] pub builder_key: String, + /// Buffer in seconds in which the `submitBlock` transaction must confirm on the Host chain. #[from_env( var = "BLOCK_CONFIRMATION_BUFFER", @@ -125,23 +145,11 @@ pub struct BuilderConfig { desc = "Address on Rollup to which Builder will receive user transaction fees" )] pub builder_rewards_address: Address, + /// Gas limit for RU block. /// NOTE: a "smart" builder would determine this programmatically by simulating the block. #[from_env(var = "ROLLUP_BLOCK_GAS_LIMIT", desc = "Gas limit for RU block")] pub rollup_block_gas_limit: u64, - /// URL of the tx pool to poll for incoming transactions. - #[from_env( - var = "TX_POOL_URL", - desc = "URL of the tx pool to poll for incoming transactions", - infallible - )] - pub tx_pool_url: Cow<'static, str>, - /// Duration in seconds transactions can live in the tx-pool cache. - #[from_env( - var = "TX_POOL_CACHE_DURATION", - desc = "Duration in seconds transactions can live in the tx-pool cache" - )] - pub tx_pool_cache_duration: u64, /// Oauth2 configuration for the builder to connect to init4 services. pub oauth: OAuthConfig, diff --git a/src/test_utils.rs b/src/test_utils.rs index e7d81cd4..085a98ce 100644 --- a/src/test_utils.rs +++ b/src/test_utils.rs @@ -29,11 +29,9 @@ pub fn setup_test_config() -> Result { builder_port: 8080, sequencer_key: None, builder_key: "0000000000000000000000000000000000000000000000000000000000000000".into(), - block_confirmation_buffer: 1, builder_rewards_address: Address::default(), rollup_block_gas_limit: 3_000_000_000, tx_pool_url: "http://localhost:9000/".into(), - tx_pool_cache_duration: 5, oauth: OAuthConfig { oauth_client_id: "some_client_id".into(), oauth_client_secret: "some_client_secret".into(), From 53239ac7061620680c90381f289c3b33cece2f88 Mon Sep 17 00:00:00 2001 From: dylan Date: Wed, 11 Jun 2025 17:48:25 -0600 Subject: [PATCH 3/7] add mermaid diagram and readme polish --- README.md | 170 +++++++++++++++++++++++++++++++++--------------------- 1 file changed, 104 insertions(+), 66 deletions(-) diff --git a/README.md b/README.md index 0a2c4c54..81a008a0 100644 --- a/README.md +++ b/README.md @@ -1,80 +1,118 @@ -# builder - -Our sample signet builder implementation. - -## Development - -This crate contains an example block builder in the Signet ecosystem. +# The Signet Block Builder + +The Builder is responsible for transactions through the Signet rollup, from ingestion and simulation to block construction and submission to Ethereum L1. + +--- + +## 🚀 System Design + +The Builder orchestrates a series of asynchronous actors that work together to: + +1. **Env** - watches the latest host and rollup blocks to monitor gas rates and block updates. +2. **Cache** - polls bundle and transaction caches and adds them to the cache. +3. **Simulator** - simulates transactions against rollup state and block environment to build them into a cohesive block. +5. **Submit** - builds a blob transaction of the built block and sends it to Ethereum L1. +6. **Metrics** - records block and tx data. + +```mermaid +flowchart TD + %% ────────────── INITIALIZATION ────────────── + A0(["Start main"]) --> A1[Init tracing & logging] + A1 --> A2_BuilderConfig[Load BuilderConfig from env] + + %% ────────────── CORE TASK SPAWNS ────────────── + subgraph Tasks_Spawned["Spawned Actors"] + EnvTaskActor["Env Task"] ==block_env==> CacheSystem + CacheSystem["Cache System"] + MetricsTaskActor["Metrics Task"] + SubmitTaskActor["Submit Task"] + SimulatorTaskActor["Simulator Task"] + end + + %% ────────────── CONNECTIONS & DATA FLOW ────────────── + A2_BuilderConfig --> A4_Providers["Connect Providers"] + + A4_Providers -.host_provider.-> MetricsTaskActor + A4_Providers -.host_provider.->SubmitTaskActor + A4_Providers -.ru_provider.-> SimulatorTaskActor + + EnvTaskActor ==block_env==> SimulatorTaskActor + CacheSystem ==sim_cache ==> SimulatorTaskActor + SubmitTaskActor ==tx receipt==> MetricsTaskActor + SimulatorTaskActor ==built block==> SubmitTaskActor + + SubmitTaskActor ==>|"signet block (blob tx)"| C1["Ethereum L1"] +``` -### Requirements +--- -- Rust 1.85 -- AWS CLI -- A private key or AWS KMS key for signing transactions +## ⚙️ Configuration -### Environment - -The following environment variables are exposed to configure the Builder: - -```bash -# Builder Configs for Pecorino Test Net -HOST_CHAIN_ID="3151908" -RU_CHAIN_ID="14174" - -# Transaction Pool Configs -TX_POOL_URL="http://pool.url.here/" # trailing slash is required - -# RPC Endpoints -HOST_RPC_URL="https://host-rpc.pecorino.signet.sh" -RU_RPC_URL="https://rpc.pecorino.signet.sh" -TX_POOL_URL="" -TX_BROADCAST_URLS="" # trailing slash is required - set to none for test net configuration - -# Contract configurations -ZENITH_ADDRESS="0xbe45611502116387211D28cE493D6Fb3d192bc4E" -BUILDER_HELPER_ADDRESS="0xb393416A722Fd48C3b0a9ab5fC2512Ef0c55e4CA" - -# Misc. -QUINCEY_URL="http://sequencer.pecorino.signet.sh/signBlock" -BUILDER_PORT="8080" -SEQUENCER_KEY="" -BUILDER_KEY="" -BUILDER_REWARDS_ADDRESS="BUILDER_REWARDS_ADDRESS_HERE" -ROLLUP_BLOCK_GAS_LIMIT="" -CONCURRENCY_LIMIT="" - -# Pecorino Slot Timing Configurations -SLOT_OFFSET="4" -SLOT_DURATION="12" -START_TIMESTAMP="1740681556" -``` +The Builder is configured via environment variables. The following values are supported for configuration. -## Transaction Sender +| Key | Required | Description | +| ------------------------- | -------- | ------------------------------------------------------------------- | +| `HOST_CHAIN_ID` | Yes | Host-chain ID (e.g. `3151908`) | +| `RU_CHAIN_ID` | Yes | Rollup-chain ID (e.g. `14174`) | +| `TX_POOL_URL` | Yes | Transaction pool URL (must end with `/`) | +| `HOST_RPC_URL` | Yes | RPC endpoint for the host chain | +| `RU_RPC_URL` | Yes | RPC endpoint for the rollup chain | +| `TX_BROADCAST_URLS` | No | Additional endpoints for blob txs (comma-separated, slash required) | +| `ZENITH_ADDRESS` | Yes | Zenith contract address | +| `BUILDER_HELPER_ADDRESS` | Yes | Builder helper contract address | +| `QUINCEY_URL` | Yes | Remote sequencer signing endpoint | +| `BUILDER_PORT` | Yes | HTTP port for the Builder (default: `8080`) | +| `SEQUENCER_KEY` | Yes | AWS KMS key ID _or_ local private key for sequencer signing | +| `BUILDER_KEY` | Yes | AWS KMS key ID _or_ local private key for builder signing | +| `BUILDER_REWARDS_ADDRESS` | Yes | Address receiving builder rewards | +| `ROLLUP_BLOCK_GAS_LIMIT` | No | Override for block gas limit | +| `CONCURRENCY_LIMIT` | Yes | Max concurrent tasks the simulator uses | +| `SLOT_OFFSET` | Yes | Slot timing offset in seconds | +| `SLOT_DURATION` | Yes | Slot duration in seconds | +| `START_TIMESTAMP` | Yes | UNIX timestamp for slot 0 | -The builder includes a `transaction-sender` for sending miniscule transactions for the purpose of testing the rollup block construction process. The `transaction-sender` is located in `bin/submit-transaction.rs`. +--- -It requires a key to sign the transactions and a funded wallet. +## 📤 Transaction Sender -### Environment Variables +A binary (`bin/submit-transaction.rs`) for continously sending very small transactions for testing block construction. -The `transaction-sender` also has a set of configurable environment variables listed below. +The following values are available for configuring the transaction sender: -```sh -RPC_URL="" # The URL of the RPC endpoint of the node you're sending the transaction to. -RECIPIENT_ADDRESS="" # The address the submitter addresses the transaction to. -SLEEP_TIME="" # The time to wait before sending another transaction, in seconds. -SIGNER_CHAIN_ID="" -SIGNER_KEY="" -``` +| Key | Required | Description | +| ------------------- | -------- | ------------------------------------------------ | +| `RPC_URL` | Yes | RPC endpoint used for sending the transaction | +| `RECIPIENT_ADDRESS` | Yes | Address to which the transaction is sent | +| `SLEEP_TIME` | No | Optional delay (in seconds) between transactions | +| `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing | +| `SIGNER_KEY` | Yes | Signing key used to sign the transaction | -## Testing +--- -### F +## 🛠️ Development -In order to test the `builder`, one must build and deploy an image in the target network with a provisioned key. +### Requirements -1. Build a docker image with your changes -2. Push the image to the image repository -3. Update the image in the deployment -4. Assert and confirm expected behavior +- **Rust** ≥ 1.85 +- **AWS CLI** +- A private key or AWS KMS key for signing transactions +--- + +## ✅ Testing + +1. Build the Docker image: + ```bash + docker build -t builder:latest . + ``` +2. Push to your container registry: + ```bash + docker push /builder:latest + ``` +3. Update your deployment manifests with the new image. +4. Verify expected behavior in your target network. + - This should typically include sending a test transaction and verifying it is simulated and built into a block. + +## 🪪 License + +This project is licensed under the [MIT License](https://opensource.org/licenses/MIT). From 5e181805af8d9d5b6a55fbf6e5c2438048a175f2 Mon Sep 17 00:00:00 2001 From: dylan Date: Thu, 12 Jun 2025 12:42:13 -0600 Subject: [PATCH 4/7] wip: update readme --- README.md | 86 ++++++++++++++++++++++++++++++++++++++--------- src/test_utils.rs | 1 + 2 files changed, 72 insertions(+), 15 deletions(-) diff --git a/README.md b/README.md index 81a008a0..d93d2f80 100644 --- a/README.md +++ b/README.md @@ -1,20 +1,23 @@ # The Signet Block Builder -The Builder is responsible for transactions through the Signet rollup, from ingestion and simulation to block construction and submission to Ethereum L1. +The Builder simulates bundles and transactions against the latest chain state to create valid Signet rollup blocks and submits them to the configured host chain as an [EIP-4844 transaction](https://github.com/ethereum/EIPs/blob/master/EIPS/eip-4844.md). + +Bundles are treated as Flashbots-style bundles, meaning that the Builder should respect transaction ordering, bundle atomicity, and the specified revertability. --- ## 🚀 System Design -The Builder orchestrates a series of asynchronous actors that work together to: +The Builder orchestrates a series of asynchronous actors that work together to build blocks for every assigned slot. 1. **Env** - watches the latest host and rollup blocks to monitor gas rates and block updates. 2. **Cache** - polls bundle and transaction caches and adds them to the cache. -3. **Simulator** - simulates transactions against rollup state and block environment to build them into a cohesive block. -5. **Submit** - builds a blob transaction of the built block and sends it to Ethereum L1. -6. **Metrics** - records block and tx data. +3. **Simulator** - simulates transactions and bundles against rollup state and block environment to build them into a cohesive block. +5. **Submit** - creates a blob transaction from the built block and sends it to Ethereum L1. +6. **Metrics** - records block and tx data over time. ```mermaid +%%{ init : { "theme" : "dark" } }%% flowchart TD %% ────────────── INITIALIZATION ────────────── A0(["Start main"]) --> A1[Init tracing & logging] @@ -22,28 +25,47 @@ flowchart TD %% ────────────── CORE TASK SPAWNS ────────────── subgraph Tasks_Spawned["Spawned Actors"] - EnvTaskActor["Env Task"] ==block_env==> CacheSystem - CacheSystem["Cache System"] - MetricsTaskActor["Metrics Task"] - SubmitTaskActor["Submit Task"] - SimulatorTaskActor["Simulator Task"] + EnvTaskActor["🔢 Env Task"] ==block_env==> CacheSystem + CacheSystem["🪏 Cache System"] + MetricsTaskActor["📏 Metrics Task"] + SubmitTaskActor["📡 Submit Task "] + SimulatorTaskActor["💾 Simulator Task"] + Quincey["🖊️ Quincey"] + + SubmitTaskActor -.block hash.-> Quincey + Quincey -.block signature.-> SubmitTaskActor end %% ────────────── CONNECTIONS & DATA FLOW ────────────── - A2_BuilderConfig --> A4_Providers["Connect Providers"] + A2_BuilderConfig -.host_provider.-> MetricsTaskActor + A2_BuilderConfig -.host_provider.->SubmitTaskActor + A2_BuilderConfig -.ru_provider.-> SimulatorTaskActor + A2_BuilderConfig -.host_provider.-> EnvTaskActor + A2_BuilderConfig -.ru_provider.-> EnvTaskActor - A4_Providers -.host_provider.-> MetricsTaskActor - A4_Providers -.host_provider.->SubmitTaskActor - A4_Providers -.ru_provider.-> SimulatorTaskActor + A3["📥 Transactions & + 📦 Bundles"] --> CacheSystem EnvTaskActor ==block_env==> SimulatorTaskActor CacheSystem ==sim_cache ==> SimulatorTaskActor SubmitTaskActor ==tx receipt==> MetricsTaskActor SimulatorTaskActor ==built block==> SubmitTaskActor - SubmitTaskActor ==>|"signet block (blob tx)"| C1["Ethereum L1"] + SubmitTaskActor ==>|"signet block (blob tx)"| C1["⛓️ Ethereum L1"] ``` +The block building loop waits until a new block has been received, and then kicks off the next attempt. + +When the Builder receives a new block, it takes a reference to the transaction cache, calculates a simulation deadline for the current slot with a buffer of 1.5 seconds, and begins constructing a block for the current slot. + +Transactions enter through the cache, and then they're sent to the simulator, where they're run against the latest chain state and block environment. If they're successfully applied, they're added to the block. If a transaction fails to be applied, it is simply ignored. + +When the deadline is reached, the simulator is stopped, and all open simulation threads and cancelled. The block is then bundled with the block environment and the previous host header that it was simulated against, and passes all three along to the submit task. + +If no transactions in the cache are valid and the resulting block is empty, the submit task will ignore it. + +Finally, if it's non-empty, the submit task attempts to get a signature for the block, and if it fails due to a 403 error, it will skip the current slot and begin waiting for the next block. + --- ## ⚙️ Configuration @@ -73,6 +95,36 @@ The Builder is configured via environment variables. The following values are su --- +## 💾 EVM Behavior + +### 🗿 Inherited Header Values + +`PREVRANDAO` is set to a random byte string for each block. + +```rust +// `src/tasks/env.rs` +prevrandao: Some(B256::random()), +``` + +`TIMESTAMP` - Block timestamps are set to the same value as the current Ethereum block. + +Blob gas values `excess_blob_gas` and `blob_gasprice` are also set to 0 for all Signet blocks. + +### 🔢 Disabled Opcodes + +`BLOBHASH` - EIP-4844 is not supported on Signet. +`BLOBBASEFEE` - EIP4844 is not supported. + +## ⛽ Transaction Submission + +When a completed, non-empty Signet block is received by the Submit task, it prepares the block data into a blob transaction and submits it to the network. + +If it fails, it will retry up to 3 times with a 12.5% bump on each retry. + +The previous header's basefee is tracked through the build loop and used for gas estimation purposes in the Submit Task. + +--- + ## 📤 Transaction Sender A binary (`bin/submit-transaction.rs`) for continously sending very small transactions for testing block construction. @@ -87,6 +139,10 @@ The following values are available for configuring the transaction sender: | `SIGNER_CHAIN_ID` | Yes | Chain ID used for signing | | `SIGNER_KEY` | Yes | Signing key used to sign the transaction | +The transaction submitter is located at `bin/submit_transaction.rs`. + +Run the transaction submitter with `cargo run --bin transaction-submitter` + --- ## 🛠️ Development diff --git a/src/test_utils.rs b/src/test_utils.rs index 085a98ce..0f7d5e9f 100644 --- a/src/test_utils.rs +++ b/src/test_utils.rs @@ -45,6 +45,7 @@ pub fn setup_test_config() -> Result { 1740681556, // pecorino start timestamp as sane default 0, 1, ), + block_confirmation_buffer: todo!(), }; Ok(config) } From e5877978d5fbb64c51d864c740ae300220d7df81 Mon Sep 17 00:00:00 2001 From: dylan Date: Thu, 12 Jun 2025 16:13:12 -0600 Subject: [PATCH 5/7] removes unused block confirmation buffer --- src/config.rs | 7 ------- src/test_utils.rs | 1 - 2 files changed, 8 deletions(-) diff --git a/src/config.rs b/src/config.rs index 624c67a3..13cb90c6 100644 --- a/src/config.rs +++ b/src/config.rs @@ -132,13 +132,6 @@ pub struct BuilderConfig { )] pub builder_key: String, - /// Buffer in seconds in which the `submitBlock` transaction must confirm on the Host chain. - #[from_env( - var = "BLOCK_CONFIRMATION_BUFFER", - desc = "Buffer in seconds in which the `submitBlock` transaction must confirm on the Host chain" - )] - pub block_confirmation_buffer: u64, - /// Address on Rollup to which Builder will receive user transaction fees. #[from_env( var = "BUILDER_REWARDS_ADDRESS", diff --git a/src/test_utils.rs b/src/test_utils.rs index 0f7d5e9f..085a98ce 100644 --- a/src/test_utils.rs +++ b/src/test_utils.rs @@ -45,7 +45,6 @@ pub fn setup_test_config() -> Result { 1740681556, // pecorino start timestamp as sane default 0, 1, ), - block_confirmation_buffer: todo!(), }; Ok(config) } From dee7abbc932cc6bce74cdd3e8fcb00c4ad385022 Mon Sep 17 00:00:00 2001 From: dylan Date: Fri, 13 Jun 2025 18:15:15 -0600 Subject: [PATCH 6/7] removes host_provider from env task --- README.md | 1 - 1 file changed, 1 deletion(-) diff --git a/README.md b/README.md index d93d2f80..4f892007 100644 --- a/README.md +++ b/README.md @@ -40,7 +40,6 @@ flowchart TD A2_BuilderConfig -.host_provider.-> MetricsTaskActor A2_BuilderConfig -.host_provider.->SubmitTaskActor A2_BuilderConfig -.ru_provider.-> SimulatorTaskActor - A2_BuilderConfig -.host_provider.-> EnvTaskActor A2_BuilderConfig -.ru_provider.-> EnvTaskActor A3["📥 Transactions & From 3fd866ada2d323666e5db3ad1173e259f73dd065 Mon Sep 17 00:00:00 2001 From: dylan Date: Fri, 13 Jun 2025 18:41:18 -0600 Subject: [PATCH 7/7] fmt --- src/config.rs | 18 +++++++++--------- 1 file changed, 9 insertions(+), 9 deletions(-) diff --git a/src/config.rs b/src/config.rs index 13cb90c6..6be92308 100644 --- a/src/config.rs +++ b/src/config.rs @@ -58,19 +58,19 @@ pub struct BuilderConfig { /// The chain ID of the host chain. #[from_env(var = "HOST_CHAIN_ID", desc = "The chain ID of the host chain")] pub host_chain_id: u64, - + /// The chain ID of the rollup chain. #[from_env(var = "RU_CHAIN_ID", desc = "The chain ID of the rollup chain")] pub ru_chain_id: u64, - + /// URL for Host RPC node. #[from_env(var = "HOST_RPC_URL", desc = "URL for Host RPC node", infallible)] pub host_rpc_url: Cow<'static, str>, - + /// URL for the Rollup RPC node. #[from_env(var = "ROLLUP_RPC_URL", desc = "URL for Rollup RPC node", infallible)] pub ru_rpc_url: Cow<'static, str>, - + /// URL of the tx pool to poll for incoming transactions. #[from_env( var = "TX_POOL_URL", @@ -89,18 +89,18 @@ pub struct BuilderConfig { optional )] pub tx_broadcast_urls: Vec>, - + /// Address of the Zenith contract on Host. #[from_env(var = "ZENITH_ADDRESS", desc = "address of the Zenith contract on Host")] pub zenith_address: Address, - + /// Address of the Builder Helper contract on Host. #[from_env( var = "BUILDER_HELPER_ADDRESS", desc = "address of the Builder Helper contract on Host" )] pub builder_helper_address: Address, - + /// URL for remote Quincey Sequencer server to sign blocks. /// NB: Disregarded if a sequencer_signer is configured. #[from_env( @@ -113,7 +113,7 @@ pub struct BuilderConfig { /// Port for the Builder server. #[from_env(var = "BUILDER_PORT", desc = "Port for the Builder server")] pub builder_port: u16, - + /// Key to access Sequencer Wallet - AWS Key ID _OR_ local private key. /// Set IFF using local Sequencer signing instead of remote Quincey signing. #[from_env( @@ -138,7 +138,7 @@ pub struct BuilderConfig { desc = "Address on Rollup to which Builder will receive user transaction fees" )] pub builder_rewards_address: Address, - + /// Gas limit for RU block. /// NOTE: a "smart" builder would determine this programmatically by simulating the block. #[from_env(var = "ROLLUP_BLOCK_GAS_LIMIT", desc = "Gas limit for RU block")]