From daa8fb779bb218200a51319e2c4f5d8a67a05e27 Mon Sep 17 00:00:00 2001 From: Jacob Elias <19310318+jelias2@users.noreply.github.com> Date: Fri, 5 Jun 2026 17:52:36 -0400 Subject: [PATCH 1/5] Add scenario access list support with placeholder resolution (#588) * feat: add scenario access_list with placeholder resolution Supersedes #581. Adds an `access_list` field to FunctionCallDefinition that accepts {placeholder} strings in `address` and `storageKeys`, resolved during the loose-to-strict conversion via the existing templater + DB map. Coexists with max_priority_fee_per_gas (#580) and alloy 2.0 (#561). * support scenario [env] placeholders in access list fields * chore: clippy --------- Co-authored-by: zeroXbrock <2791467+zeroXbrock@users.noreply.github.com> --- crates/cli/src/server/static/openrpc.json | 10 ++- crates/core/src/generator/function_def.rs | 71 ++++++++++++++++++ crates/core/src/generator/templater.rs | 91 ++++++++++++++++++++++- crates/core/src/generator/trait.rs | 50 +++++++++++-- crates/testfile/src/lib.rs | 69 +++++++++++++++++ docs/creating_scenarios.md | 24 ++++++ scenarios/simpleAccessList.toml | 18 +++++ 7 files changed, 320 insertions(+), 13 deletions(-) create mode 100644 scenarios/simpleAccessList.toml diff --git a/crates/cli/src/server/static/openrpc.json b/crates/cli/src/server/static/openrpc.json index d01d1e38..d0d5d67b 100644 --- a/crates/cli/src/server/static/openrpc.json +++ b/crates/cli/src/server/static/openrpc.json @@ -15,7 +15,7 @@ "BlobsCliArgs": {"file":"crates/cli/src/default_scenarios/blobs.rs","line":10}, "BuilderParams": {"file":"crates/cli/src/server/rpc_server/types.rs","line":227}, "BuiltinScenarioCli": {"file":"crates/cli/src/default_scenarios/builtin.rs","line":33}, - "BundleCallDefinition": {"file":"crates/core/src/generator/function_def.rs","line":61}, + "BundleCallDefinition": {"file":"crates/core/src/generator/function_def.rs","line":79}, "BundleTypeCli": {"file":"crates/cli/src/commands/common.rs","line":438}, "CompiledContract": {"file":"crates/core/src/generator/create_def.rs","line":8}, "ContenderSessionInfo": {"file":"crates/cli/src/server/sessions.rs","line":128}, @@ -27,9 +27,10 @@ "EthereumOpcode": {"file":"crates/cli/src/default_scenarios/eth_functions/opcodes.rs","line":10}, "EthereumPrecompile": {"file":"crates/cli/src/default_scenarios/eth_functions/precompiles.rs","line":11}, "FillBlockCliArgs": {"file":"crates/cli/src/default_scenarios/fill_block.rs","line":17}, - "FunctionCallDefinition": {"file":"crates/core/src/generator/function_def.rs","line":12}, + "FunctionCallDefinition": {"file":"crates/core/src/generator/function_def.rs","line":25}, "FundAccountsParams": {"file":"crates/cli/src/server/rpc_server/types.rs","line":273}, - "FuzzParam": {"file":"crates/core/src/generator/function_def.rs","line":176}, + "FuzzParam": {"file":"crates/core/src/generator/function_def.rs","line":200}, + "LooseAccessListItem": {"file":"crates/core/src/generator/function_def.rs","line":15}, "RevertCliArgs": {"file":"crates/cli/src/default_scenarios/revert.rs","line":8}, "ServerStatus": {"file":"crates/cli/src/server/rpc_server/types.rs","line":33}, "SessionOptions": {"file":"crates/cli/src/server/rpc_server/types.rs","line":234}, @@ -188,9 +189,10 @@ "EthereumOpcode": {"type":"string","enum":["Stop","Add","Mul","Sub","Div","Sdiv","Mod","Smod","Addmod","Mulmod","Exp","Signextend","Lt","Gt","Slt","Sgt","Eq","Iszero","And","Or","Xor","Not","Byte","Shl","Shr","Sar","Sha3","Keccak256","Address","Balance","Origin","Caller","Callvalue","Calldataload","Calldatasize","Calldatacopy","Codesize","Codecopy","Gasprice","Extcodesize","Extcodecopy","Returndatasize","Returndatacopy","Extcodehash","Blockhash","Coinbase","Timestamp","Number","Prevrandao","Gaslimit","Chainid","Selfbalance","Basefee","Pop","Mload","Mstore","Mstore8","Sload","Sstore","Msize","Gas","Log0","Log1","Log2","Log3","Log4","Create","Call","Callcode","Return","Delegatecall","Create2","Staticcall","Revert","Invalid","Selfdestruct"]}, "EthereumPrecompile": {"type":"string","enum":["HashSha256","HashRipemd160","Identity","ModExp","EcAdd","EcMul","EcPairing","Blake2f"]}, "FillBlockCliArgs": {"description":"Taken from the CLI, this is used to fill a block with transactions.","type":"object","properties":{"max_gas_per_block":{"type":"integer"}}}, - "FunctionCallDefinition": {"description":"User-facing definition of a function call to be executed.","type":"object","properties":{"to":{"description":"Address of the contract to call.","type":"string"},"from":{"description":"Address of the tx sender.","type":"string"},"from_pool":{"description":"Get a `from` address from the pool of signers specified here.","type":"string"},"signature":{"description":"Name of the function to call.","type":"string"},"args":{"description":"Parameters to pass to the function.","type":"array","items":{"type":"string"}},"value":{"description":"Value in wei to send with the tx.","type":"string"},"fuzz":{"description":"Parameters to fuzz during the test.","type":"array","items":{"$ref":"#/components/schemas/FuzzParam"}},"kind":{"description":"Optional type of the spam transaction for categorization.","type":"string"},"gas_limit":{"description":"Optional gas limit, which will skip gas estimation. This allows reverting txs to be sent.","type":"integer"},"blob_data":{"description":"Optional blob data; tx type must be set to EIP4844 by spammer","type":"string"},"authorization_address":{"description":"Optional setCode data; tx type must be set to EIP7702 by spammer","type":"string"},"for_all_accounts":{"description":"If true and `from_pool` is set, run this setup transaction for all accounts in the pool. Defaults to false (only runs for the first account).","type":"boolean"},"max_priority_fee_per_gas":{"description":"Optional EIP-1559 priority fee for this tx. Accepts raw wei (`\"10000000000\"`), hex (`\"0x2540be400\"`), or a unit string (`\"10 gwei\"`, `\"0.001 eth\"`). May also be a `{placeholder}` that resolves to one of those forms. If unset, the spammer falls back to its default (`gas_price / 10`). This field is also fuzzable via `FuzzParam::max_priority_fee_per_gas = true`.","type":"string"}},"required":["to","for_all_accounts"]}, + "FunctionCallDefinition": {"description":"User-facing definition of a function call to be executed.","type":"object","properties":{"to":{"description":"Address of the contract to call.","type":"string"},"from":{"description":"Address of the tx sender.","type":"string"},"from_pool":{"description":"Get a `from` address from the pool of signers specified here.","type":"string"},"signature":{"description":"Name of the function to call.","type":"string"},"args":{"description":"Parameters to pass to the function.","type":"array","items":{"type":"string"}},"value":{"description":"Value in wei to send with the tx.","type":"string"},"fuzz":{"description":"Parameters to fuzz during the test.","type":"array","items":{"$ref":"#/components/schemas/FuzzParam"}},"kind":{"description":"Optional type of the spam transaction for categorization.","type":"string"},"gas_limit":{"description":"Optional gas limit, which will skip gas estimation. This allows reverting txs to be sent.","type":"integer"},"blob_data":{"description":"Optional blob data; tx type must be set to EIP4844 by spammer","type":"string"},"authorization_address":{"description":"Optional setCode data; tx type must be set to EIP7702 by spammer","type":"string"},"access_list":{"description":"Optional EIP-2930 access list entries to include in the transaction. Address and storage keys may contain `{placeholder}` references that are resolved when the loose definition is converted to its strict form.","type":"array","items":{"$ref":"#/components/schemas/LooseAccessListItem"}},"for_all_accounts":{"description":"If true and `from_pool` is set, run this setup transaction for all accounts in the pool. Defaults to false (only runs for the first account).","type":"boolean"},"max_priority_fee_per_gas":{"description":"Optional EIP-1559 priority fee for this tx. Accepts raw wei (`\"10000000000\"`), hex (`\"0x2540be400\"`), or a unit string (`\"10 gwei\"`, `\"0.001 eth\"`). May also be a `{placeholder}` that resolves to one of those forms. If unset, the spammer falls back to its default (`gas_price / 10`). This field is also fuzzable via `FuzzParam::max_priority_fee_per_gas = true`.","type":"string"}},"required":["to","for_all_accounts"]}, "FundAccountsParams": {"type":"object","properties":{"sessionId":{"type":"integer"},"agentClass":{"$ref":"#/components/schemas/AgentClass"},"amount":{"type":"string"}},"required":["sessionId","amount"]}, "FuzzParam": {"type":"object","properties":{"param":{"description":"Name of the parameter to fuzz.","type":"string"},"value":{"description":"Fuzz the `value` field of the tx (ETH sent with the tx).","type":"boolean"},"max_priority_fee_per_gas":{"description":"Fuzz the `max_priority_fee_per_gas` field of the tx (EIP-1559 priority fee, in wei).","type":"boolean"},"min":{"description":"Minimum value fuzzer will use. Accepts raw wei (`\"100\"`), hex (`\"0x2540be400\"`), or unit strings (`\"10 gwei\"`, `\"0.001 eth\"`).","type":"string"},"max":{"description":"Maximum value fuzzer will use. Accepts raw wei (`\"100\"`), hex (`\"0x2540be400\"`), or unit strings (`\"10 gwei\"`, `\"0.001 eth\"`).","type":"string"}}}, + "LooseAccessListItem": {"description":"User-facing access list entry. Address and storage keys are kept as strings so they can contain `{placeholder}` references that are resolved when the loose definition is converted to its strict form.","type":"object","properties":{"address":{"description":"Address of the contract. May be a `{placeholder}`.","type":"string"},"storageKeys":{"description":"Storage keys to prewarm. Each may be a `{placeholder}`.","type":"array","items":{"type":"string"}}},"required":["address","storageKeys"]}, "RevertCliArgs": {"type":"object","properties":{"gas_use":{"description":"Amount of gas to use before reverting.","type":"integer"}},"required":["gas_use"]}, "ServerStatus": {"description":"Data returned from the `status` endpoint, containing general info about the server.","type":"object","properties":{"numSessions":{"type":"integer"}},"required":["numSessions"]}, "SessionOptions": {"type":"object","properties":{"auth":{"$ref":"#/components/schemas/AuthParams"},"builder":{"$ref":"#/components/schemas/BuilderParams"},"minBalance":{"type":"string"},"timeoutSecs":{"type":"object","properties":{"secs":{"type":"integer"},"nanos":{"type":"integer"}}},"txType":{"$ref":"#/components/schemas/TxTypeCli"},"privateKeys":{"type":"array","items":{"type":"string"}},"agents":{"$ref":"#/components/schemas/AgentParams"},"env":{"type":"object","additionalProperties":{"type":"string"}}}}, diff --git a/crates/core/src/generator/function_def.rs b/crates/core/src/generator/function_def.rs index 8b566108..8a5f5890 100644 --- a/crates/core/src/generator/function_def.rs +++ b/crates/core/src/generator/function_def.rs @@ -4,9 +4,22 @@ use alloy::{ eips::eip7702::SignedAuthorization, hex::{FromHex, ToHexExt}, primitives::{Address, Bytes, U256}, + rpc::types::AccessListItem, }; use serde::{Deserialize, Serialize}; +/// User-facing access list entry. Address and storage keys are kept as strings +/// so they can contain `{placeholder}` references that are resolved when the +/// loose definition is converted to its strict form. +#[derive(Clone, Deserialize, Debug, Serialize)] +pub struct LooseAccessListItem { + /// Address of the contract. May be a `{placeholder}`. + pub address: String, + /// Storage keys to prewarm. Each may be a `{placeholder}`. + #[serde(rename = "storageKeys")] + pub storage_keys: Vec, +} + /// User-facing definition of a function call to be executed. #[derive(Clone, Deserialize, Debug, Serialize)] pub struct FunctionCallDefinition { @@ -42,6 +55,11 @@ pub struct FunctionCallDefinition { /// Optional setCode data; tx type must be set to EIP7702 by spammer #[serde(skip_serializing_if = "Option::is_none")] pub authorization_address: Option, + /// Optional EIP-2930 access list entries to include in the transaction. + /// Address and storage keys may contain `{placeholder}` references that are + /// resolved when the loose definition is converted to its strict form. + #[serde(skip_serializing_if = "Option::is_none")] + pub access_list: Option>, /// If true and `from_pool` is set, run this setup transaction for all accounts in the pool. /// Defaults to false (only runs for the first account). #[serde(default, skip_serializing_if = "std::ops::Not::not")] @@ -77,6 +95,7 @@ impl FunctionCallDefinition { gas_limit: None, blob_data: None, authorization_address: None, + access_list: None, for_all_accounts: false, max_priority_fee_per_gas: None, } @@ -127,6 +146,10 @@ impl FunctionCallDefinition { self.authorization_address = Some(auth_addr.as_ref().to_owned()); self } + pub fn with_access_list(mut self, access_list: Vec) -> Self { + self.access_list = Some(access_list); + self + } pub fn with_for_all_accounts(mut self, for_all_accounts: bool) -> Self { self.for_all_accounts = for_all_accounts; self @@ -170,6 +193,7 @@ pub struct FunctionCallDefinitionStrict { pub max_priority_fee_per_gas: Option, // may be a placeholder, so we can't use u128 pub sidecar: Option, pub authorization: Option>, + pub access_list: Option>, } #[derive(Clone, Deserialize, Debug, Serialize)] @@ -337,4 +361,51 @@ mod tests { assert!(fuzz[0].param.is_some()); assert_eq!(fuzz[0].max_priority_fee_per_gas, Some(true)); } + + #[test] + fn access_list_parses_from_toml() { + let toml = r#" + to = "0x1234567890123456789012345678901234567890" + from_pool = "test_pool" + signature = "test()" + + [[access_list]] + address = "0x4200000000000000000000000000000000000022" + storageKeys = [ + "0x0100000000000000000000000000000000000000000000000000000000000000", + "0x0300000000000000000000000000000000000000000000000000000000000000", + ] + "#; + let def: FunctionCallDefinition = toml::from_str(toml).unwrap(); + let access_list = def.access_list.unwrap(); + + assert_eq!(access_list.len(), 1); + assert_eq!( + access_list[0].address.to_string(), + "0x4200000000000000000000000000000000000022" + ); + assert_eq!(access_list[0].storage_keys.len(), 2); + } + + #[test] + fn access_list_parses_placeholders_from_toml() { + let toml = r#" + to = "0x1234567890123456789012345678901234567890" + from_pool = "test_pool" + signature = "test()" + + [[access_list]] + address = "{SpamMe5}" + storageKeys = ["{testkey1}", "{testkey2}"] + "#; + let def: FunctionCallDefinition = toml::from_str(toml).unwrap(); + let access_list = def.access_list.unwrap(); + + assert_eq!(access_list.len(), 1); + assert_eq!(access_list[0].address, "{SpamMe5}"); + assert_eq!( + access_list[0].storage_keys, + vec!["{testkey1}".to_string(), "{testkey2}".to_string()] + ); + } } diff --git a/crates/core/src/generator/templater.rs b/crates/core/src/generator/templater.rs index 85be155b..0f43914d 100644 --- a/crates/core/src/generator/templater.rs +++ b/crates/core/src/generator/templater.rs @@ -10,7 +10,7 @@ use crate::{ use alloy::{ hex::{FromHex, ToHexExt}, primitives::{Address, Bytes, FixedBytes, TxKind, U256}, - rpc::types::TransactionRequest, + rpc::types::{AccessList, TransactionRequest}, }; use std::collections::HashMap; use thiserror::Error; @@ -108,7 +108,7 @@ where /// Finds {placeholders} in `fncall` and looks them up in `db`, /// then inserts the values it finds into `placeholder_map`. - /// NOTE: only finds placeholders in `args`, `authorization_addr`, and `to` fields. + /// NOTE: scans `args`, `from`, `to`, `authorization_address`, and `access_list` fields. fn find_fncall_placeholders( &self, fncall: &FunctionCallDefinition, @@ -158,6 +158,28 @@ where scenario_label, )?; } + if let Some(access_list) = &fncall.access_list { + for item in access_list.iter() { + self.find_placeholder_values( + &item.address, + placeholder_map, + db, + rpc_url, + genesis_hash, + scenario_label, + )?; + for key in &item.storage_keys { + self.find_placeholder_values( + key, + placeholder_map, + db, + rpc_url, + genesis_hash, + scenario_label, + )?; + } + } + } Ok(()) } @@ -251,6 +273,7 @@ where }) }) .transpose()?; + let access_list = funcdef.access_list.to_owned().map(AccessList::from); Ok(TransactionRequest { to: Some(TxKind::Call(to)), @@ -261,6 +284,7 @@ where max_priority_fee_per_gas, sidecar: funcdef.sidecar.as_ref().map(|sc| sc.to_owned().into()), authorization_list: funcdef.authorization.to_owned(), + access_list, ..Default::default() }) } @@ -316,7 +340,10 @@ where #[cfg(test)] mod tests { use super::*; - use crate::generator::function_def::FunctionCallDefinitionStrict; + use crate::generator::{function_def::FunctionCallDefinitionStrict, util::complete_tx_request}; + use alloy::consensus::TxType; + use alloy::primitives::B256; + use alloy::rpc::types::AccessListItem; /// Minimal `Templater` mirroring the production `{key}` syntax, /// used so the priority-fee parsing path can be exercised in isolation. @@ -374,6 +401,7 @@ mod tests { max_priority_fee_per_gas: priority_fee.map(|s| s.to_owned()), sidecar: None, authorization: None, + access_list: None, } } @@ -428,4 +456,61 @@ mod tests { ); } } + + #[test] + fn template_function_call_threads_access_list_into_request() { + let templater = CurlyBraceTemplater; + let access_list_address = "0x4200000000000000000000000000000000000022"; + let storage_key = "0x0100000000000000000000000000000000000000000000000000000000000000"; + let second_storage_key = + "0x0300000000000000000000000000000000000000000000000000000000000000"; + let placeholder_map = HashMap::new(); + let funcdef = FunctionCallDefinitionStrict { + to: access_list_address.to_string(), + from: Address::ZERO, + signature: "validate()".to_string(), + args: vec![], + value: None, + fuzz: vec![], + kind: None, + gas_limit: Some(200_000), + max_priority_fee_per_gas: None, + sidecar: None, + authorization: None, + access_list: Some(vec![AccessListItem { + address: access_list_address.parse::
().unwrap(), + storage_keys: vec![ + storage_key.parse::().unwrap(), + second_storage_key.parse::().unwrap(), + ], + }]), + }; + + let mut tx = templater + .template_function_call(&funcdef, &placeholder_map) + .unwrap(); + let access_list = tx.access_list.as_ref().unwrap(); + + assert_eq!(access_list.len(), 1); + assert_eq!( + access_list[0].address, + access_list_address.parse::
().unwrap() + ); + assert_eq!(access_list[0].storage_keys.len(), 2); + assert_eq!( + access_list[0].storage_keys[0], + storage_key.parse::().unwrap() + ); + assert_eq!( + access_list[0].storage_keys[1], + second_storage_key.parse::().unwrap() + ); + + complete_tx_request(&mut tx, TxType::Eip1559, 10, 1, 200_000, 1, 0); + + assert_eq!(tx.access_list.unwrap().len(), 1); + assert_eq!(tx.max_fee_per_gas, Some(10)); + assert_eq!(tx.max_priority_fee_per_gas, Some(1)); + assert_eq!(tx.chain_id, Some(1)); + } } diff --git a/crates/core/src/generator/trait.rs b/crates/core/src/generator/trait.rs index 683b872b..68b53adc 100644 --- a/crates/core/src/generator/trait.rs +++ b/crates/core/src/generator/trait.rs @@ -17,9 +17,9 @@ use crate::{ use alloy::{ eips::eip7702::SignedAuthorization, hex::ToHexExt, - primitives::{keccak256, Address, FixedBytes, U256}, + primitives::{keccak256, Address, FixedBytes, B256, U256}, providers::Provider, - rpc::types::Authorization, + rpc::types::{AccessListItem, Authorization}, signers::{local::PrivateKeySigner, SignerSync}, }; use async_trait::async_trait; @@ -211,6 +211,10 @@ where idx: usize, ) -> Result { let agents = self.get_agent_store(); + let conf = self.get_plan_conf(); + let env = conf.get_env().unwrap_or_default(); + let mut placeholder_map = HashMap::::new(); + placeholder_map.extend(env); let from_address: Address = if let Some(from_pool) = &funcdef.from_pool { let agent = agents @@ -254,7 +258,6 @@ where let to_address = special_replace(&funcdef.to); let signed_auth = if let Some(auth_address) = &funcdef.authorization_address { - let mut placeholder_map = HashMap::::new(); let templater = self.get_templater(); templater.find_fncall_placeholders( funcdef, @@ -316,6 +319,42 @@ where None }; + // Resolve {placeholders} in the optional access list, then parse each + // entry into alloy's strict `AccessListItem` type. + let access_list = if let Some(loose_list) = &funcdef.access_list { + let templater = self.get_templater(); + templater.find_fncall_placeholders( + funcdef, + self.get_db(), + &mut placeholder_map, + &self.get_rpc_url(), + self.get_genesis_hash(), + self.get_scenario_label(), + )?; + let mut items = Vec::with_capacity(loose_list.len()); + for item in loose_list.iter() { + let resolved_addr = templater.replace_placeholders(&item.address, &placeholder_map); + let address = resolved_addr + .parse::
() + .map_err(|_| GeneratorError::address_not_found(&item.address))?; + let mut storage_keys = Vec::with_capacity(item.storage_keys.len()); + for key in &item.storage_keys { + let resolved_key = templater.replace_placeholders(key, &placeholder_map); + let parsed = resolved_key + .parse::() + .map_err(|_| GeneratorError::address_not_found(key))?; + storage_keys.push(parsed); + } + items.push(AccessListItem { + address, + storage_keys, + }); + } + Some(items) + } else { + None + }; + Ok(FunctionCallDefinitionStrict { to: to_address, from: from_address, @@ -328,6 +367,7 @@ where max_priority_fee_per_gas: funcdef.max_priority_fee_per_gas.to_owned(), sidecar: funcdef.sidecar_data()?, authorization: signed_auth.map(|a| vec![a]), + access_list, }) } @@ -345,9 +385,7 @@ where let templater = self.get_templater(); let mut placeholder_map = HashMap::::new(); - for (key, value) in env.iter() { - placeholder_map.insert(key.to_owned(), value.to_owned()); - } + placeholder_map.extend(env); let mut txs: Vec = vec![]; diff --git a/crates/testfile/src/lib.rs b/crates/testfile/src/lib.rs index b39dbb20..854d7adb 100644 --- a/crates/testfile/src/lib.rs +++ b/crates/testfile/src/lib.rs @@ -215,6 +215,75 @@ pub mod tests { } } + #[test] + fn parses_spam_tx_access_list_toml() { + let test_file = TestConfig::from_str( + r#" + [[spam]] + [spam.tx] + to = "0x4200000000000000000000000000000000000022" + from_pool = "spammers" + signature = "validate()" + gas_limit = 200000 + + [[spam.tx.access_list]] + address = "0x4200000000000000000000000000000000000022" + storageKeys = [ + "0x0100000000000000000000000000000000000000000000000000000000000000", + "0x0300000000000000000000000000000000000000000000000000000000000000", + ] + "#, + ) + .unwrap(); + let spam = test_file.spam.unwrap(); + + match &spam[0] { + SpamRequest::Tx(fncall) => { + let access_list = fncall.access_list.as_ref().unwrap(); + assert_eq!(access_list.len(), 1); + assert_eq!( + access_list[0].address, + "0x4200000000000000000000000000000000000022" + ); + assert_eq!(access_list[0].storage_keys.len(), 2); + } + SpamRequest::Bundle(_) => panic!("expected SpamRequest::Tx"), + } + } + + #[test] + fn parses_spam_tx_access_list_with_placeholders_toml() { + let test_file = TestConfig::from_str( + r#" + [[spam]] + [spam.tx] + to = "0x4200000000000000000000000000000000000022" + from_pool = "spammers" + signature = "validate()" + gas_limit = 200000 + + [[spam.tx.access_list]] + address = "{SpamMe5}" + storageKeys = ["{testkey1}", "{testkey2}"] + "#, + ) + .unwrap(); + let spam = test_file.spam.unwrap(); + + match &spam[0] { + SpamRequest::Tx(fncall) => { + let access_list = fncall.access_list.as_ref().unwrap(); + assert_eq!(access_list.len(), 1); + assert_eq!(access_list[0].address, "{SpamMe5}"); + assert_eq!( + access_list[0].storage_keys, + vec!["{testkey1}".to_string(), "{testkey2}".to_string()] + ); + } + SpamRequest::Bundle(_) => panic!("expected SpamRequest::Tx"), + } + } + fn repo_root_path() -> std::path::PathBuf { let mut dir = std::path::PathBuf::from(env!("CARGO_MANIFEST_DIR")); dir.pop(); // crates diff --git a/docs/creating_scenarios.md b/docs/creating_scenarios.md index 010d61f4..97a8528b 100644 --- a/docs/creating_scenarios.md +++ b/docs/creating_scenarios.md @@ -207,6 +207,30 @@ args = ["1350000"] gas_limit = 1350000 ``` +### access lists + +Spam transactions can include EIP-2930 access-list entries. This is useful for workloads that already know which account and storage keys need to be warm, while still sending EIP-1559 transactions by default. + +```toml +[[spam]] + +[spam.tx] +to = "0x1111111111111111111111111111111111111111" +from_pool = "bluepool" +signature = "touch(bytes32 lookupKey)" +args = [ + "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa", +] +gas_limit = 200000 + +[[spam.tx.access_list]] +address = "0x1111111111111111111111111111111111111111" +storageKeys = [ + "0x0100000000000000000000000000000000000000000000000000000000000000", + "0x0300000000000000000000000000000000000000000000000000000000000000", +] +``` + ### sending bundles The `[spam.tx]` directive sends a mempool transaction using `eth_sendRawTransaction`, but Contender also supports bundles. diff --git a/scenarios/simpleAccessList.toml b/scenarios/simpleAccessList.toml new file mode 100644 index 00000000..b087f10c --- /dev/null +++ b/scenarios/simpleAccessList.toml @@ -0,0 +1,18 @@ +[env] +testkey1 = "0x0000000000000000000000000000000000000000000000000000000000000001" +testkey2 = "0x0000000000000000000000000000000000000000000000000000000000000002" + +[[create]] +name = "SpamMe5" +# source: https://github.com/zeroXbrock/high-volume-contract/blob/main/src/SpamMe.sol +bytecode = "0x608060405234801561000f575f5ffd5b5060405180602001604052805f8152505f908161002c91906102c9565b5060405160200161003c906103ec565b604051602081830303815290604052805190602001205f1c6001819055506040516020016100699061044a565b604051602081830303815290604052600290816100869190610468565b50610537565b5f81519050919050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b7f4e487b71000000000000000000000000000000000000000000000000000000005f52602260045260245ffd5b5f600282049050600182168061010757607f821691505b60208210810361011a576101196100c3565b5b50919050565b5f819050815f5260205f209050919050565b5f6020601f8301049050919050565b5f82821b905092915050565b5f6008830261017c7fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff82610141565b6101868683610141565b95508019841693508086168417925050509392505050565b5f819050919050565b5f819050919050565b5f6101ca6101c56101c08461019e565b6101a7565b61019e565b9050919050565b5f819050919050565b6101e3836101b0565b6101f76101ef826101d1565b84845461014d565b825550505050565b5f5f905090565b61020e6101ff565b6102198184846101da565b505050565b5b8181101561023c576102315f82610206565b60018101905061021f565b5050565b601f8211156102815761025281610120565b61025b84610132565b8101602085101561026a578190505b61027e61027685610132565b83018261021e565b50505b505050565b5f82821c905092915050565b5f6102a15f1984600802610286565b1980831691505092915050565b5f6102b98383610292565b9150826002028217905092915050565b6102d28261008c565b67ffffffffffffffff8111156102eb576102ea610096565b5b6102f582546100f0565b610300828285610240565b5f60209050601f831160018114610331575f841561031f578287015190505b61032985826102ae565b865550610390565b601f19841661033f86610120565b5f5b8281101561036657848901518255600182019150602085019450602081019050610341565b86831015610383578489015161037f601f891682610292565b8355505b6001600288020188555050505b505050505050565b5f81905092915050565b7f666f757274792d74776f000000000000000000000000000000000000000000005f82015250565b5f6103d6600a83610398565b91506103e1826103a2565b600a82019050919050565b5f6103f6826103ca565b9150819050919050565b7f48656c6c6f2c20576f726c6421000000000000000000000000000000000000005f82015250565b5f610434600d83610398565b915061043f82610400565b600d82019050919050565b5f61045482610428565b9150819050919050565b5f81519050919050565b6104718261045e565b67ffffffffffffffff81111561048a57610489610096565b5b61049482546100f0565b61049f828285610240565b5f60209050601f8311600181146104d0575f84156104be578287015190505b6104c885826102ae565b86555061052f565b601f1984166104de86610120565b5f5b82811015610505578489015182556001820191506020850194506020810190506104e0565b86831015610522578489015161051e601f891682610292565b8355505b6001600288020188555050505b505050505050565b612ddf806105445f395ff3fe60806040526004361061007a575f3560e01c8063a329e8de1161004d578063a329e8de1461010c578063c5eeaf1714610134578063e30709d01461013e578063fb0e722b146101545761007a565b806369f86ec81461007e5780637ad42e50146100945780638199ba20146100bc5780639402c004146100e4575b5f5ffd5b348015610089575f5ffd5b5061009261017e565b005b34801561009f575f5ffd5b506100ba60048036038101906100b59190611baa565b610189565b005b3480156100c7575f5ffd5b506100e260048036038101906100dd9190611baa565b610878565b005b3480156100ef575f5ffd5b5061010a60048036038101906101059190611ca2565b610e00565b005b348015610117575f5ffd5b50610132600480360381019061012d9190611ce9565b610e33565b005b61013c610ec0565b005b348015610149575f5ffd5b50610152610f06565b005b34801561015f575f5ffd5b50610168610f7a565b6040516101759190611d74565b60405180910390f35b5b60325a1161017f57565b6101d16040518060400160405280600b81526020017f686173685f7368613235360000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610202575f5f90505b818110156101fc576101ee60015461105d565b5080806001019150506101db565b50610874565b61024a6040518060400160405280600e81526020017f686173685f726970656d643136300000000000000000000000000000000000008152508361100590919063ffffffff16565b1561027b575f5f90505b8181101561027557610267600154611144565b508080600101915050610254565b50610873565b6102c36040518060400160405280600881526020017f6964656e746974790000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b1561037a575f5f90505b8181101561037457610366600280546102e590611dc1565b80601f016020809104026020016040519081016040528092919081815260200182805461031190611dc1565b801561035c5780601f106103335761010080835404028352916020019161035c565b820191905f5260205f20905b81548152906001019060200180831161033f57829003601f168201915b505050505061122f565b5080806001019150506102cd565b50610872565b6103c26040518060400160405280600681526020017f6d6f6465787000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b156103f6575f5f90505b818110156103f0576103e2600a6004600e611304565b5080806001019150506103cc565b50610871565b61043e6040518060400160405280600581526020017f65634164640000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610473575f5f90505b8181101561046d5761045e600160025f5f6113f9565b50508080600101915050610448565b50610870565b6104bb6040518060400160405280600581526020017f65634d756c0000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b156104f0575f5f90505b818110156104ea576104db6001600260016114f6565b505080806001019150506104c5565b5061086f565b6105386040518060400160405280600981526020017f656350616972696e6700000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610582575f5f90505b8181101561057c5761056e604051806101a001604052806101808152602001612c2a61018091396115f0565b508080600101915050610542565b5061086e565b6105ca6040518060400160405280600781526020017f626c616b653266000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b156105f7576105f160405180610100016040528060d58152602001612b5560d591396116c8565b5061086d565b61063f6040518060400160405280600b81526020017f626c616b6532665f616c740000000000000000000000000000000000000000008152508361100590919063ffffffff16565b1561086c575f600c90506106516119c4565b7f48c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa55f1b815f6002811061068757610686611df1565b5b6020020181815250507fd182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b5f1b816001600281106106c7576106c6611df1565b5b6020020181815250506106d86119e6565b7f61626300000000000000000000000000000000000000000000000000000000005f1b815f6004811061070e5761070d611df1565b5b6020020181815250505f5f1b8160016004811061072e5761072d611df1565b5b6020020181815250505f5f1b8160026004811061074e5761074d611df1565b5b6020020181815250505f5f1b8160036004811061076e5761076d611df1565b5b60200201818152505061077f611a08565b67030000000000000060c01b815f6002811061079e5761079d611df1565b5b602002019077ffffffffffffffffffffffffffffffffffffffffffffffff1916908177ffffffffffffffffffffffffffffffffffffffffffffffff1916815250505f60c01b816001600281106107f7576107f6611df1565b5b602002019077ffffffffffffffffffffffffffffffffffffffffffffffff1916908177ffffffffffffffffffffffffffffffffffffffffffffffff1916815250505f600190505f5f90505b868110156108655761085786868686866117c2565b508080600101915050610842565b5050505050505b5b5b5b5b5b5b5b5b5050565b6108c06040518060400160405280600681526020017f7373746f726500000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b156108ed575f5f90505b818110156108e7576108da6118e8565b80806001019150506108ca565b50610dfc565b6109356040518060400160405280600581526020017f736c6f61640000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610962575f5f90505b8181101561095c5761094f6118ed565b808060010191505061093f565b50610dfb565b6109aa6040518060400160405280600681526020017f6d73746f726500000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b156109d7575f5f90505b818110156109d1576109c46118ef565b80806001019150506109b4565b50610dfa565b610a1f6040518060400160405280600581526020017f6d6c6f61640000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610a4c575f5f90505b81811015610a4657610a396118f4565b8080600101915050610a29565b50610df9565b610a946040518060400160405280600381526020017f61646400000000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610ac1575f5f90505b81811015610abb57610aae6118f9565b8080600101915050610a9e565b50610df8565b610b096040518060400160405280600381526020017f73756200000000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610b36575f5f90505b81811015610b3057610b236118fb565b8080600101915050610b13565b50610df7565b610b7e6040518060400160405280600381526020017f6d756c00000000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610bab575f5f90505b81811015610ba557610b986118fd565b8080600101915050610b88565b50610df6565b610bf36040518060400160405280600381526020017f64697600000000000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610c20575f5f90505b81811015610c1a57610c0d6118ff565b8080600101915050610bfd565b50610df5565b610c686040518060400160405280600981526020017f65637265636f76657200000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610c96575f5f90505b81811015610c9057610c82611901565b508080600101915050610c72565b50610df4565b610cde6040518060400160405280600981526020017f6b656363616b32353600000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610d0b575f5f90505b81811015610d0557610cf86119b4565b8080600101915050610ce8565b50610df3565b610d536040518060400160405280600781526020017f62616c616e6365000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610d80575f5f90505b81811015610d7a57610d6d6119bb565b8080600101915050610d5d565b50610df2565b610dc86040518060400160405280600681526020017f63616c6c657200000000000000000000000000000000000000000000000000008152508361100590919063ffffffff16565b15610df1575f5f90505b81811015610def57610de26119c2565b8080600101915050610dd2565b505b5b5b5b5b5b5b5b5b5b5b5b5050565b5f81604051602001610e13929190611eea565b6040516020818303038152906040525f9081610e2f919061209b565b5050565b5f8111610e75576040517f08c379a0000000000000000000000000000000000000000000000000000000008152600401610e6c906121c4565b60405180910390fd5b5f6095610a2883610e86919061220f565b610e90919061226f565b90505f8103610e9e57600190505b5f5f90505b81811015610ebb575f5f558080600101915050610ea3565b505050565b4173ffffffffffffffffffffffffffffffffffffffff166108fc3490811502906040515f60405180830381858888f19350505050158015610f03573d5f5f3e3d5ffd5b50565b5f600242610f14919061229f565b14610f54576040517f08c379a0000000000000000000000000000000000000000000000000000000008152600401610f4b9061233f565b60405180910390fd5b5f5f90505b6064811015610f7757610f6a6118f4565b8080600101915050610f59565b50565b5f8054610f8690611dc1565b80601f0160208091040260200160405190810160405280929190818152602001828054610fb290611dc1565b8015610ffd5780601f10610fd457610100808354040283529160200191610ffd565b820191905f5260205f20905b815481529060010190602001808311610fe057829003601f168201915b505050505081565b5f8160405160200161101791906123a1565b604051602081830303815290604052805190602001208360405160200161103e91906123a1565b6040516020818303038152906040528051906020012014905092915050565b5f5f5f600273ffffffffffffffffffffffffffffffffffffffff168460405160200161108991906123c6565b6040516020818303038152906040526040516110a591906123df565b5f60405180830381855afa9150503d805f81146110dd576040519150601f19603f3d011682016040523d82523d5f602084013e6110e2565b606091505b509150915081611127576040517f08c379a000000000000000000000000000000000000000000000000000000000815260040161111e9061243f565b60405180910390fd5b8080602001905181019061113b9190612490565b92505050919050565b5f5f5f600373ffffffffffffffffffffffffffffffffffffffff168460405160200161117091906123c6565b60405160208183030381529060405260405161118c91906123df565b5f60405180830381855afa9150503d805f81146111c4576040519150601f19603f3d011682016040523d82523d5f602084013e6111c9565b606091505b50915091508161120e576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016112059061243f565b60405180910390fd5b6060818060200190518101906112249190612490565b901b92505050919050565b60605f5f600473ffffffffffffffffffffffffffffffffffffffff168460405160200161125c9190611d74565b60405160208183030381529060405260405161127891906123df565b5f60405180830381855afa9150503d805f81146112b0576040519150601f19603f3d011682016040523d82523d5f602084013e6112b5565b606091505b5091509150816112fa576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016112f19061243f565b60405180910390fd5b8092505050919050565b5f5f5f600573ffffffffffffffffffffffffffffffffffffffff16602080602089898960405160200161133c96959493929190612500565b60405160208183030381529060405260405161135891906123df565b5f60405180830381855afa9150503d805f8114611390576040519150601f19603f3d011682016040523d82523d5f602084013e611395565b606091505b5091509150816113da576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016113d19061243f565b60405180910390fd5b808060200190518101906113ee9190612573565b925050509392505050565b5f5f5f8686868660405160200161141394939291906125be565b60405160208183030381529060405290505f5f600673ffffffffffffffffffffffffffffffffffffffff168360405161144c91906123df565b5f60405180830381855afa9150503d805f8114611484576040519150601f19603f3d011682016040523d82523d5f602084013e611489565b606091505b5091509150816114ce576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016114c590612655565b60405180910390fd5b808060200190518101906114e29190612673565b809550819650505050505094509492505050565b5f5f5f85858560405160200161150e939291906126b1565b60405160208183030381529060405290505f5f600773ffffffffffffffffffffffffffffffffffffffff168360405161154791906123df565b5f60405180830381855afa9150503d805f811461157f576040519150601f19603f3d011682016040523d82523d5f602084013e611584565b606091505b5091509150816115c9576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016115c09061275d565b60405180910390fd5b808060200190518101906115dd9190612673565b8095508196505050505050935093915050565b5f5f5f600873ffffffffffffffffffffffffffffffffffffffff168460405161161991906123df565b5f60405180830381855afa9150503d805f8114611651576040519150601f19603f3d011682016040523d82523d5f602084013e611656565b606091505b50915091508161169b576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016116929061243f565b60405180910390fd5b602081511480156116bf57505f818060200190518101906116bc9190612573565b14155b92505050919050565b606060d582511461170e576040517f08c379a0000000000000000000000000000000000000000000000000000000008152600401611705906127eb565b60405180910390fd5b5f5f600973ffffffffffffffffffffffffffffffffffffffff168460405161173691906123df565b5f60405180830381855afa9150503d805f811461176e576040519150601f19603f3d011682016040523d82523d5f602084013e611773565b606091505b5091509150816117b8576040517f08c379a00000000000000000000000000000000000000000000000000000000081526004016117af90612853565b60405180910390fd5b8092505050919050565b6117ca6119c4565b6117d26119c4565b5f87875f600281106117e7576117e6611df1565b5b602002015188600160028110611800576117ff611df1565b5b6020020151885f6004811061181857611817611df1565b5b60200201518960016004811061183157611830611df1565b5b60200201518a60026004811061184a57611849611df1565b5b60200201518b60036004811061186357611862611df1565b5b60200201518b5f6002811061187b5761187a611df1565b5b60200201518c60016002811061189457611893611df1565b5b60200201518c6040516020016118b39a9998979695949392919061296f565b604051602081830303815290604052905060408260d56020840160095f19fa6118da575f5ffd5b819250505095945050505050565b5f5f55565b565b5f5f52565b5f5150565b565b565b565b565b5f60017f84b9e10435e0bc5ea883d65dcc978b7d415228d21e4617775048722ef01a97e7601c7f7f05b09e99332068f90b5aa7233b53b9191ced11229aafe97f1a8d6e52af5dc57f049979df9965db093de9cac6c4224bd5bce586510fae94edcc513f12328b06856040515f81526020016040526040516119859493929190612b11565b6020604051602081039080840390855afa1580156119a5573d5f5f3e3d5ffd5b50505060206040510351905090565b60205f2050565b5f33905050565b565b6040518060400160405280600290602082028036833780820191505090505090565b6040518060800160405280600490602082028036833780820191505090505090565b6040518060400160405280600290602082028036833780820191505090505090565b5f604051905090565b5f5ffd5b5f5ffd5b5f5ffd5b5f5ffd5b5f601f19601f8301169050919050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52604160045260245ffd5b611a8982611a43565b810181811067ffffffffffffffff82111715611aa857611aa7611a53565b5b80604052505050565b5f611aba611a2a565b9050611ac68282611a80565b919050565b5f67ffffffffffffffff821115611ae557611ae4611a53565b5b611aee82611a43565b9050602081019050919050565b828183375f83830152505050565b5f611b1b611b1684611acb565b611ab1565b905082815260208101848484011115611b3757611b36611a3f565b5b611b42848285611afb565b509392505050565b5f82601f830112611b5e57611b5d611a3b565b5b8135611b6e848260208601611b09565b91505092915050565b5f819050919050565b611b8981611b77565b8114611b93575f5ffd5b50565b5f81359050611ba481611b80565b92915050565b5f5f60408385031215611bc057611bbf611a33565b5b5f83013567ffffffffffffffff811115611bdd57611bdc611a37565b5b611be985828601611b4a565b9250506020611bfa85828601611b96565b9150509250929050565b5f67ffffffffffffffff821115611c1e57611c1d611a53565b5b611c2782611a43565b9050602081019050919050565b5f611c46611c4184611c04565b611ab1565b905082815260208101848484011115611c6257611c61611a3f565b5b611c6d848285611afb565b509392505050565b5f82601f830112611c8957611c88611a3b565b5b8135611c99848260208601611c34565b91505092915050565b5f60208284031215611cb757611cb6611a33565b5b5f82013567ffffffffffffffff811115611cd457611cd3611a37565b5b611ce084828501611c75565b91505092915050565b5f60208284031215611cfe57611cfd611a33565b5b5f611d0b84828501611b96565b91505092915050565b5f81519050919050565b5f82825260208201905092915050565b8281835e5f83830152505050565b5f611d4682611d14565b611d508185611d1e565b9350611d60818560208601611d2e565b611d6981611a43565b840191505092915050565b5f6020820190508181035f830152611d8c8184611d3c565b905092915050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52602260045260245ffd5b5f6002820490506001821680611dd857607f821691505b602082108103611deb57611dea611d94565b5b50919050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52603260045260245ffd5b5f81905092915050565b5f819050815f5260205f209050919050565b5f8154611e4681611dc1565b611e508186611e1e565b9450600182165f8114611e6a5760018114611e7f57611eb1565b60ff1983168652811515820286019350611eb1565b611e8885611e28565b5f5b83811015611ea957815481890152600182019150602081019050611e8a565b838801955050505b50505092915050565b5f611ec482611d14565b611ece8185611e1e565b9350611ede818560208601611d2e565b80840191505092915050565b5f611ef58285611e3a565b9150611f018284611eba565b91508190509392505050565b5f6020601f8301049050919050565b5f82821b905092915050565b5f60088302611f577fffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff82611f1c565b611f618683611f1c565b95508019841693508086168417925050509392505050565b5f819050919050565b5f611f9c611f97611f9284611b77565b611f79565b611b77565b9050919050565b5f819050919050565b611fb583611f82565b611fc9611fc182611fa3565b848454611f28565b825550505050565b5f5f905090565b611fe0611fd1565b611feb818484611fac565b505050565b5b8181101561200e576120035f82611fd8565b600181019050611ff1565b5050565b601f8211156120535761202481611e28565b61202d84611f0d565b8101602085101561203c578190505b61205061204885611f0d565b830182611ff0565b50505b505050565b5f82821c905092915050565b5f6120735f1984600802612058565b1980831691505092915050565b5f61208b8383612064565b9150826002028217905092915050565b6120a482611d14565b67ffffffffffffffff8111156120bd576120bc611a53565b5b6120c78254611dc1565b6120d2828285612012565b5f60209050601f831160018114612103575f84156120f1578287015190505b6120fb8582612080565b865550612162565b601f19841661211186611e28565b5f5b8281101561213857848901518255600182019150602085019450602081019050612113565b868310156121555784890151612151601f891682612064565b8355505b6001600288020188555050505b505050505050565b5f82825260208201905092915050565b7f476173206d7573742062652067726561746572207468616e20300000000000005f82015250565b5f6121ae601a8361216a565b91506121b98261217a565b602082019050919050565b5f6020820190508181035f8301526121db816121a2565b9050919050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52601160045260245ffd5b5f61221982611b77565b915061222483611b77565b925082820390508181111561223c5761223b6121e2565b5b92915050565b7f4e487b71000000000000000000000000000000000000000000000000000000005f52601260045260245ffd5b5f61227982611b77565b915061228483611b77565b92508261229457612293612242565b5b828204905092915050565b5f6122a982611b77565b91506122b483611b77565b9250826122c4576122c3612242565b5b828206905092915050565b7f626c6f636b20776173206f64642c20616e64204920646f6e2774206c696b65205f8201527f7468617400000000000000000000000000000000000000000000000000000000602082015250565b5f61232960248361216a565b9150612334826122cf565b604082019050919050565b5f6020820190508181035f8301526123568161231d565b9050919050565b5f81519050919050565b5f81905092915050565b5f61237b8261235d565b6123858185612367565b9350612395818560208601611d2e565b80840191505092915050565b5f6123ac8284612371565b915081905092915050565b6123c081611b77565b82525050565b5f6020820190506123d95f8301846123b7565b92915050565b5f6123ea8284611eba565b915081905092915050565b7f6661696c656400000000000000000000000000000000000000000000000000005f82015250565b5f61242960068361216a565b9150612434826123f5565b602082019050919050565b5f6020820190508181035f8301526124568161241d565b9050919050565b5f819050919050565b61246f8161245d565b8114612479575f5ffd5b50565b5f8151905061248a81612466565b92915050565b5f602082840312156124a5576124a4611a33565b5b5f6124b28482850161247c565b91505092915050565b5f819050919050565b5f60ff82169050919050565b5f6124ea6124e56124e0846124bb565b611f79565b6124c4565b9050919050565b6124fa816124d0565b82525050565b5f60c0820190506125135f8301896124f1565b61252060208301886124f1565b61252d60408301876124f1565b61253a60608301866123b7565b61254760808301856123b7565b61255460a08301846123b7565b979650505050505050565b5f8151905061256d81611b80565b92915050565b5f6020828403121561258857612587611a33565b5b5f6125958482850161255f565b91505092915050565b5f819050919050565b6125b86125b382611b77565b61259e565b82525050565b5f6125c982876125a7565b6020820191506125d982866125a7565b6020820191506125e982856125a7565b6020820191506125f982846125a7565b60208201915081905095945050505050565b7f456c6c6970746963206375727665206164646974696f6e206661696c656400005f82015250565b5f61263f601e8361216a565b915061264a8261260b565b602082019050919050565b5f6020820190508181035f83015261266c81612633565b9050919050565b5f5f6040838503121561268957612688611a33565b5b5f6126968582860161255f565b92505060206126a78582860161255f565b9150509250929050565b5f6126bc82866125a7565b6020820191506126cc82856125a7565b6020820191506126dc82846125a7565b602082019150819050949350505050565b7f456c6c6970746963206375727665206d756c7469706c69636174696f6e2066615f8201527f696c656400000000000000000000000000000000000000000000000000000000602082015250565b5f61274760248361216a565b9150612752826126ed565b604082019050919050565b5f6020820190508181035f8301526127748161273b565b9050919050565b7f696e707574206c656e677468206d7573742062652065786163746c79203231335f8201527f2062797465730000000000000000000000000000000000000000000000000000602082015250565b5f6127d560268361216a565b91506127e08261277b565b604082019050919050565b5f6020820190508181035f830152612802816127c9565b9050919050565b7f426c616b65326620707265636f6d70696c65206661696c6564000000000000005f82015250565b5f61283d60198361216a565b915061284882612809565b602082019050919050565b5f6020820190508181035f83015261286a81612831565b9050919050565b5f63ffffffff82169050919050565b5f8160e01b9050919050565b5f61289682612880565b9050919050565b6128ae6128a982612871565b61288c565b82525050565b5f819050919050565b6128ce6128c98261245d565b6128b4565b82525050565b5f7fffffffffffffffff00000000000000000000000000000000000000000000000082169050919050565b5f819050919050565b612919612914826128d4565b6128ff565b82525050565b5f8115159050919050565b5f8160f81b9050919050565b5f6129408261292a565b9050919050565b5f61295182612936565b9050919050565b6129696129648261291f565b612947565b82525050565b5f61297a828d61289d565b60048201915061298a828c6128bd565b60208201915061299a828b6128bd565b6020820191506129aa828a6128bd565b6020820191506129ba82896128bd565b6020820191506129ca82886128bd565b6020820191506129da82876128bd565b6020820191506129ea8286612908565b6008820191506129fa8285612908565b600882019150612a0a8284612958565b6001820191508190509b9a5050505050505050505050565b5f819050919050565b5f815f1b9050919050565b5f612a50612a4b612a4684612a22565b612a2b565b61245d565b9050919050565b612a6081612a36565b82525050565b5f819050919050565b5f612a89612a84612a7f84612a66565b611f79565b6124c4565b9050919050565b612a9981612a6f565b82525050565b5f819050919050565b5f612ac2612abd612ab884612a9f565b612a2b565b61245d565b9050919050565b612ad281612aa8565b82525050565b5f819050919050565b5f612afb612af6612af184612ad8565b612a2b565b61245d565b9050919050565b612b0b81612ae1565b82525050565b5f608082019050612b245f830187612a57565b612b316020830186612a90565b612b3e6040830185612ac9565b612b4b6060830184612b02565b9594505050505056fe0000000148c9bdf267e6096a3ba7ca8485ae67bb2bf894fe72f36e3cf1361d5f3af54fa5d182e6ad7f520e511f6c3e2b8c68059b6bbd41fbabd9831f79217e1319cde05b616263000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000003000000000000000000000000000000011b6e4577cc71df5e856ed88d2d14a464343f140b07693e3b08308570b28fd55b24198aa6ee0f5bfec020ad2ff15729434439e4af7554fa0f7395ee20cb926346246b8e8c771c3db7226a8066537632923d7d5a542f8e0d600e7f0195240f1ec513cbe706f9ba436dd4a781fab85fa2e9d82854446cf91182dcfa66eb68c4b7e72533a60b837f9cf4838c4c38f4f9c8988fee10c9895753e7925a86330e925db702f47f10f7da957cfcc613361ab6aaeb67f14d22c06eec14e47e36988c4ee06705a596bd22bbb13dc898acfdd420c88893dd09f7fd4875e8b3fb65b54ad9643f2847ab3c7d853e89cfdf520de28e1092c1955b7e17d9cba5808f047a3d6898fd2f64f057deda8bbb646d5b9864d9789a696abf2a42218f7af28baae517f5e45723bd3952d332068086b2079260b285896cb84c73ece3647094fac90d8b1374c21eebb3f8ea3c3d9147fa09e4506bcff1c222a02ea8b4904fc6df3bca1cc0505e133d9a4794eb099e9bdf82a6fecdb2e2e29b0867bf0fe557475dc758d796714ea26469706673582212204fd746b5bf517cb8d8c8cc3229b6edfe0d245a9e97fbace28fb75b3d9c68de8c64736f6c634300081b0033" + +[[spam]] +[spam.tx] +to = "{SpamMe5}" +signature = "callPrecompile(string memory method, uint256 iterations)" +args = ["sstore", "5"] + +[[spam.tx.access_list]] +address = "{SpamMe5}" +storageKeys = ["{testkey1}", "{testkey2}"] From c91598ad3ba96e3c777bbeaf509591e948af99b5 Mon Sep 17 00:00:00 2001 From: Jacob Elias <19310318+jelias2@users.noreply.github.com> Date: Fri, 5 Jun 2026 19:13:20 -0400 Subject: [PATCH 2/5] spam-stream subcommand for streaming tx specs (relayer use case) (#589) MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * feat: add spam-stream subcommand for streaming tx specs (draft) Reads newline-delimited JSON FunctionCallDefinitions from stdin or a file and spams them via the existing TestScenario pipeline. Reuses agent pools, rate limiting, nonce management, and receipt tracking. See docs/stream-mode.md for the design note and scope. * feat(spam-stream): versioned stdout envelope + drop decoy TestConfig - Address review feedback on PR #589: - #2/#3: emit structured, versioned/tagged JSON envelope on stdout (one tx_result event per spec) so the schema can evolve; default for spam-stream mode (logs stay on stderr). - #5: replace the decoy zero-address TestConfig with a direct AgentStore pool, injecting signers into the scenario and syncing nonces from the RPC. * fix(spam-stream): record run, cache gas price, surface backpressure/summary Address review gaps on the prototype: - record a real run via insert_run so dumped receipts aren't orphaned under run_id 0 (run_txs has a foreign key into runs) - cache the gas price, refreshing every 6s instead of once per tx - emit `backpressure` and a terminal `summary` event; track sent vs failed - reject blob (4844) / setCode (7702) specs up front - unify the stdin/file reader and drop dead run_id plumbing * fix(spam-stream): enable nonce sync so sends don't fail with NonceMissing TestScenario::sync_nonces() is gated on should_sync_nonces (= the sync_nonces_after_batch param). spam-stream set it false, making its two explicit sync_nonces() calls silent no-ops, so pool accounts' nonces were never loaded and prepare_tx_request failed every send with NonceMissing (surfaced as 'core error'). Stream mode sends one tx at a time and never hits the post-batch sync path, so enabling this only makes the initial pool-nonce sync run. * fix(spam-stream): reclaim nonce on failed send to avoid nonce gaps prepare_tx_request advances an account's local nonce before the send. When the send is rejected (e.g. an interop access-list filter rejecting a not-yet-valid or forged executing message), the tx never enters the mempool but the local nonce stays advanced, leaving a gap that stalls every later tx from that account behind it. Roll the nonce back by one on a failed send. The stream sends serially, so no concurrent send touched the account in between. * docs(spam-stream): clarify --tps long_help (review #589) --tps paces how fast specs are pulled off the input stream; each spec is sent exactly once, so a one-line input sends a single tx regardless of the value. Add long_help explaining this, plus tests asserting the help text is present and the clap arg config is valid (debug_assert). * feat(spam-stream): accept unit strings for --min-balance (review #589) --min-balance now parses unit-value strings ("10 eth", "0.5 ether", "100 gwei") via util::parse_value, matching the other CLI balance/value flags; a plain number is still wei. Default expressed as "0.01 ether" (unchanged 1e16 wei). Tests cover unit parsing, the wei fallback, and the default round-trip through the value_parser. * fix(spam-stream): persist seed so --skip-funding works across runs (review #589) When --seed was unset, spam-stream generated a fresh random RandSeed each invocation, so the executor pool's addresses differed every run. Funding the pool with --min-balance in one run then re-running with --skip-funding hit "insufficient funds" because the second run derived a different (unfunded) pool. Fall back to the persisted seedfile (data_dir/seed) when --seed is unset, matching spam/setup/campaign. Threads data_dir into spam_stream(). Pool addresses are now stable across invocations for a given data-dir. Test: build_pool_agent_store is deterministic per seed (same seed -> same addresses, different seed -> different). Manually verified against anvil: run 1 funds the pool + writes the seedfile; run 2 with --skip-funding and no funder key sends successfully (previously failed with insufficient funds). * style(spam-stream): cargo fmt test module (CI fmt fix) --------- Co-authored-by: brock 🤖⚡ <2791467+zeroXbrock@users.noreply.github.com> --- .../cli/src/commands/contender_subcommand.rs | 11 + crates/cli/src/commands/error.rs | 3 + crates/cli/src/commands/mod.rs | 1 + crates/cli/src/commands/spam_stream.rs | 823 ++++++++++++++++++ crates/cli/src/main.rs | 4 + docs/stream-mode.md | 213 +++++ 6 files changed, 1055 insertions(+) create mode 100644 crates/cli/src/commands/spam_stream.rs create mode 100644 docs/stream-mode.md diff --git a/crates/cli/src/commands/contender_subcommand.rs b/crates/cli/src/commands/contender_subcommand.rs index 92f7e25d..ec886b46 100644 --- a/crates/cli/src/commands/contender_subcommand.rs +++ b/crates/cli/src/commands/contender_subcommand.rs @@ -9,6 +9,7 @@ use crate::default_scenarios::BuiltinScenarioCli; use super::admin::AdminCommand; use super::spam::SpamCliArgs; +use super::spam_stream::SpamStreamCliArgs; use super::ReportFormat; #[derive(Debug, Subcommand)] @@ -34,6 +35,16 @@ pub enum ContenderSubcommand { builtin_scenario_config: Option, }, + #[command( + name = "spam-stream", + long_about = "Read newline-delimited JSON tx specs from stdin or a file and spam them. \ + Each line is a FunctionCallDefinition (same fields as scenario TOML `[[spam.tx]]`)." + )] + SpamStream { + #[command(flatten)] + args: Box, + }, + #[command( name = "setup", long_about = "Deploy contracts and execute one-time setup txs." diff --git a/crates/cli/src/commands/error.rs b/crates/cli/src/commands/error.rs index 9ab196f0..766febf6 100644 --- a/crates/cli/src/commands/error.rs +++ b/crates/cli/src/commands/error.rs @@ -78,6 +78,9 @@ pub enum ArgsError { #[error("failed to parse url")] UrlParse(#[from] url::ParseError), + + #[error("{0}")] + Custom(String), } #[derive(Debug, Error)] diff --git a/crates/cli/src/commands/mod.rs b/crates/cli/src/commands/mod.rs index 6b834134..d3e6c834 100644 --- a/crates/cli/src/commands/mod.rs +++ b/crates/cli/src/commands/mod.rs @@ -8,6 +8,7 @@ pub mod replay; pub mod rpc; mod setup; mod spam; +pub mod spam_stream; use clap::{Parser, ValueEnum}; use contender_core::db::DbOps; diff --git a/crates/cli/src/commands/spam_stream.rs b/crates/cli/src/commands/spam_stream.rs new file mode 100644 index 00000000..b1bf958e --- /dev/null +++ b/crates/cli/src/commands/spam_stream.rs @@ -0,0 +1,823 @@ +//! `spam-stream` subcommand: read newline-delimited JSON tx specs from stdin +//! or a file, and spam them through the contender pipeline. +//! +//! This is the entry point for the "stream mode" prototype. See +//! `docs/stream-mode.md` for the design note. + +use crate::{ + commands::{ + common::{HELP_HEADING_COMMON, HELP_HEADING_PAYLOAD, HELP_HEADING_RUNTIME}, + error::ArgsError, + Result, + }, + error::CliError, + util::{fund_accounts, load_seedfile}, + LATENCY_HIST as HIST, PROM, +}; +use alloy::{ + consensus::TxType, + network::{AnyTxEnvelope, Ethereum, NetworkTransactionBuilder}, + primitives::{utils::format_ether, U256}, + providers::Provider, + transports::http::reqwest::Url, +}; +use clap::Args; +use contender_core::{ + agent_controller::{AgentClass, AgentStore}, + db::{DbOps, SpamDuration, SpamRunRequest}, + generator::{ + agent_pools::AgentSpec, seeder::rand_seed::SeedGenerator, templater::Templater, + util::parse_value, FunctionCallDefinition, Generator, PlanConfig, RandSeed, + }, + spammer::tx_actor::{ActorContext, CacheTx}, + test_scenario::{TestScenario, TestScenarioParams}, + BundleType, +}; +use contender_sqlite::SqliteDb; +use contender_testfile::TestConfig; +use serde::Serialize; +use std::{ + collections::HashMap, + path::{Path, PathBuf}, + sync::Arc, + time::{Duration, Instant, SystemTime, UNIX_EPOCH}, +}; +use tokio::{ + io::{AsyncBufRead, AsyncBufReadExt, BufReader}, + sync::mpsc, +}; +use tokio_util::sync::CancellationToken; +use tracing::{debug, info, warn}; + +/// Default agent-pool name when the user does not specify one. +const DEFAULT_POOL: &str = "executors"; +/// Channel buffer between the reader task and the spam loop. +const STREAM_BUFFER: usize = 256; +/// Schema version of the structured stdout output. Bump when the envelope +/// shape changes in a backward-incompatible way. +const OUTPUT_VERSION: u32 = 1; +/// How often to refresh the cached gas price during the stream loop. Avoids an +/// RPC round-trip on every single tx. +const GAS_REFRESH_INTERVAL: Duration = Duration::from_secs(6); + +/// Versioned, tagged envelope written to stdout (one JSON line per event) so +/// downstream consumers can evolve with the schema. The `version` field pins +/// the schema and the `type` tag (via `payload`) discriminates event kinds. +#[derive(Debug, Serialize)] +struct StreamEvent { + version: u32, + #[serde(flatten)] + payload: StreamPayload, +} + +#[derive(Debug, Serialize)] +#[serde(tag = "type", rename_all = "snake_case")] +enum StreamPayload { + /// Emitted once per input spec after the send attempt. + TxResult { + /// Zero-based index of the spec in the stream. + idx: usize, + /// Transaction hash (present even when the send RPC call failed). + tx_hash: String, + /// Unix-epoch milliseconds when the send was attempted. + start_timestamp_ms: u128, + /// Optional `kind` carried over from the input spec. + #[serde(skip_serializing_if = "Option::is_none")] + kind: Option, + /// Send-time error from the RPC, if any. + #[serde(skip_serializing_if = "Option::is_none")] + error: Option, + }, + /// Buffer saturated; the reader is blocking. Signals the producer to slow down. + Backpressure { queued: usize, capacity: usize }, + /// Emitted once when the stream finishes (EOF or cancellation). + Summary { sent: usize, failed: usize }, +} + +impl StreamEvent { + fn emit(payload: StreamPayload) { + let event = StreamEvent { + version: OUTPUT_VERSION, + payload, + }; + // Serialization of these fixed-shape payloads cannot fail. + if let Ok(line) = serde_json::to_string(&event) { + println!("{line}"); + } + } +} + +#[derive(Clone, Debug, Args)] +pub struct SpamStreamCliArgs { + /// RPC URL to send transactions to. + #[arg( + env = "RPC_URL", + short = 'r', + long, + default_value = "http://localhost:8545", + help_heading = HELP_HEADING_COMMON, + )] + pub rpc_url: Url, + + /// Funder private key. Used to fund the pool of executor accounts before spam begins. + #[arg( + env = "CONTENDER_PRIVATE_KEY", + short = 'p', + long = "priv-key", + help_heading = HELP_HEADING_COMMON, + )] + pub private_key: Option, + + /// Source of the JSON-lines stream: either `stdin` or a file path. + #[arg( + long = "from", + default_value = "stdin", + help_heading = HELP_HEADING_COMMON, + )] + pub from: String, + + /// Pool name used to source signers for each tx. Stream specs that omit + /// `from`/`from_pool` will default to this pool. + #[arg( + long = "from-pool", + default_value = DEFAULT_POOL, + help_heading = HELP_HEADING_PAYLOAD, + )] + pub from_pool: String, + + /// Number of accounts to generate in the pool. + #[arg( + long = "pool-size", + default_value_t = 10, + help_heading = HELP_HEADING_PAYLOAD, + )] + pub pool_size: usize, + + /// Target transactions per second. `0` means "send as fast as the stream + /// can be parsed". + #[arg( + long, + long_help = "Target transactions per second. This paces how fast specs are pulled \ + off the input stream, NOT how many txs are duplicated: each input spec is sent \ + exactly once. With `0` (the default) specs are sent as fast as they arrive. If \ + the stream supplies fewer specs per second than `--tps`, the rate is bounded by \ + the stream, so a one-line input sends a single tx regardless of the value.", + default_value_t = 0, + help_heading = HELP_HEADING_RUNTIME, + )] + pub tps: u64, + + /// Minimum balance to keep in each pool account. + #[arg( + long, + long_help = "The minimum balance to keep in each pool account, with units \ + (e.g. \"10 eth\", \"0.5 ether\", \"100 gwei\"). A plain number is parsed as wei.", + default_value = "0.01 ether", + value_parser = parse_value, + help_heading = HELP_HEADING_RUNTIME, + )] + pub min_balance: U256, + + /// Seed for deterministic pool-signer generation. + #[arg( + env = "CONTENDER_SEED", + long, + help_heading = HELP_HEADING_RUNTIME, + )] + pub seed: Option, + + /// Skip funding the executor accounts. Useful when the pool was funded + /// out-of-band or every spec carries a `from` address with an existing balance. + #[arg(long, default_value_t = false, help_heading = HELP_HEADING_RUNTIME)] + pub skip_funding: bool, +} + +/// Asynchronously reads JSON lines from `from` (stdin or file path), parses each +/// into a `FunctionCallDefinition`, and forwards it to `tx`. The task exits when +/// EOF is reached or the receiver drops. +pub fn spawn_stream_reader( + from: &str, + tx: mpsc::Sender, +) -> Result> { + // Validate file existence eagerly so a bad path is a clean CLI error rather + // than a silent warning from inside the spawned task. + if from != "stdin" && !PathBuf::from(from).exists() { + return Err(CliError::Args(ArgsError::Custom(format!( + "stream source file not found: {from}" + )))); + } + + let from = from.to_owned(); + Ok(tokio::spawn(async move { + let reader: Box = if from == "stdin" { + Box::new(BufReader::new(tokio::io::stdin())) + } else { + match tokio::fs::File::open(&from).await { + Ok(f) => Box::new(BufReader::new(f)), + Err(e) => { + warn!("failed to open stream source {from}: {e}"); + return; + } + } + }; + forward_lines(reader, tx).await; + })) +} + +async fn forward_lines(reader: R, tx: mpsc::Sender) +where + R: tokio::io::AsyncBufRead + Unpin, +{ + let mut lines = reader.lines(); + let mut line_no: u64 = 0; + // Emit the backpressure event once per saturation episode, not per blocked send. + let mut backpressured = false; + loop { + match lines.next_line().await { + Ok(Some(line)) => { + line_no += 1; + let trimmed = line.trim(); + if trimmed.is_empty() || trimmed.starts_with('#') { + continue; + } + match serde_json::from_str::(trimmed) { + Ok(spec) => match tx.try_send(spec) { + Ok(()) => backpressured = false, + Err(mpsc::error::TrySendError::Full(spec)) => { + if !backpressured { + backpressured = true; + let capacity = tx.max_capacity(); + StreamEvent::emit(StreamPayload::Backpressure { + queued: capacity.saturating_sub(tx.capacity()), + capacity, + }); + } + // Block until a slot frees, applying real backpressure. + if tx.send(spec).await.is_err() { + return; // receiver dropped + } + } + Err(mpsc::error::TrySendError::Closed(_)) => return, + }, + Err(e) => warn!("stream: skipping malformed line {line_no}: {e}"), + } + } + Ok(None) => return, // EOF + Err(e) => { + warn!("stream: read error: {e}"); + return; + } + } + } +} + +/// Build an `AgentStore` holding a single spam pool named `from_pool` with +/// `pool_size` signers, derived from `seed`. Stream mode provisions the pool +/// directly instead of round-tripping through a scenario `TestConfig`, since +/// it never executes any pre-defined spam steps. +fn build_pool_agent_store(from_pool: &str, pool_size: usize, seed: &RandSeed) -> AgentStore { + let mut store = AgentStore::new(); + if pool_size > 0 { + store.add_new_agent(from_pool, pool_size, seed, AgentClass::Spammer); + } + store +} + +/// Drive the stream loop: pull specs, build/sign/send txs, cache in the +/// tx_actor for receipt tracking. Returns when the stream channel closes. +async fn drive_stream( + scenario: &mut TestScenario, + mut rx: mpsc::Receiver, + fallback_pool: String, + tps: u64, + cancel: CancellationToken, +) -> Result<(usize, usize)> +where + S: SeedGenerator + Send + Sync + Clone, + P: PlanConfig + Templater + Send + Sync + Clone, +{ + // Rate limiter: only ticks when tps > 0. + let mut ticker = if tps > 0 { + let period = Duration::from_secs_f64(1.0 / tps as f64); + let mut int = tokio::time::interval(period); + int.set_missed_tick_behavior(tokio::time::MissedTickBehavior::Delay); + Some(int) + } else { + None + }; + + // Cache the gas price instead of fetching it per tx; refreshed below. + let mut gas_price = scenario.rpc_client.get_gas_price().await?; + let mut last_gas_refresh = Instant::now(); + + let mut sent: usize = 0; + let mut failed: usize = 0; + let mut idx: usize = 0; + let placeholder_map = HashMap::::new(); + + loop { + tokio::select! { + _ = cancel.cancelled() => { + info!("stream cancelled; flushing."); + break; + } + spec = rx.recv() => { + let Some(mut spec) = spec else { + debug!("stream EOF received"); + break; + }; + + // Apply default pool if the spec doesn't pick one. + if spec.from.is_none() && spec.from_pool.is_none() { + spec.from_pool = Some(fallback_pool.clone()); + } + + // Rate limit (only when --tps > 0). + if let Some(int) = ticker.as_mut() { + int.tick().await; + } + + if last_gas_refresh.elapsed() >= GAS_REFRESH_INTERVAL { + if let Ok(gp) = scenario.rpc_client.get_gas_price().await { + gas_price = gp; + } + last_gas_refresh = Instant::now(); + } + + match send_one(scenario, &spec, idx, &placeholder_map, gas_price).await { + Ok(true) => sent += 1, + Ok(false) => failed += 1, + Err(e) => { + failed += 1; + warn!("stream: failed to send tx (idx {idx}): {e}"); + } + } + idx += 1; + } + } + } + + Ok((sent, failed)) +} + +/// Build a single transaction from a stream spec, sign it, send it, and cache +/// it in the tx_actor for receipt tracking. +async fn send_one( + scenario: &mut TestScenario, + spec: &FunctionCallDefinition, + idx: usize, + placeholder_map: &HashMap, + gas_price: u128, +) -> Result +where + S: SeedGenerator + Send + Sync + Clone, + P: PlanConfig + Templater + Send + Sync + Clone, +{ + // Stream mode only builds EIP-1559 txs (no blob gas price, no auth list), so + // reject blob (4844) / setCode (7702) specs up front instead of silently + // producing an invalid tx. + if spec.blob_data.is_some() || spec.authorization_address.is_some() { + warn!("stream tx[{idx}]: blob/7702 specs are unsupported in stream mode; skipping"); + return Ok(false); + } + + // 1. Resolve `from`/`from_pool` and access list against the scenario's + // agent store + templater. This produces a strict FunctionCallDefinition. + let strict = scenario + .make_strict_call(spec, idx) + .map_err(contender_core::Error::Generator)?; + + // 2. Render the strict definition into a TransactionRequest (encodes + // calldata, threads access_list, sets value/gas_limit). + let tx_req = scenario + .get_templater() + .template_function_call(&strict, placeholder_map) + .map_err(contender_core::Error::Templater)?; + + // 3. Assign nonce/gas-limit + sign using the cached gas price. + let (prepared, wallet) = scenario.prepare_tx_request(&tx_req, gas_price, 0).await?; + // Build & sign via the alloy Ethereum network. The op-alloy-network re-export + // can create trait-resolution ambiguity, so we fully-qualify the trait + // method and convert the error string-ly instead of relying on From. + let envelope = + >::build( + prepared, &wallet, + ) + .await + .map_err(|e| CliError::Args(ArgsError::Custom(format!("build envelope: {e}"))))?; + let tx_hash = envelope.tx_hash().to_owned(); + + // 4. Send via the same txs_client the regular spammer uses. + let any_envelope = AnyTxEnvelope::Ethereum(envelope); + let start_ms = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis(); + let res = scenario.txs_client.send_tx_envelope(any_envelope).await; + let error = match res { + Ok(_) => { + info!("stream tx[{idx}]: {tx_hash} sent"); + None + } + Err(e) => { + let msg = e + .as_error_resp() + .map(|err| err.message.to_string()) + .unwrap_or_else(|| format!("{e}")); + warn!("stream tx[{idx}]: {tx_hash} failed: {msg}"); + Some(msg) + } + }; + + let submitted = error.is_none(); + if !submitted { + // prepare_tx_request already advanced this account's local nonce, but + // the tx never entered the mempool (e.g. rejected by an interop access + // -list filter). Reclaim the nonce so the next send from this account + // doesn't leave a gap that stalls every later tx behind it. The stream + // sends serially, so nothing else has touched this account meanwhile. + if let Some(n) = scenario.nonces.get_mut(&strict.from) { + *n = n.saturating_sub(1); + } + } + + // 5. Emit a structured result line to stdout (mirrors the input stream so + // reactive callers can correlate sends with their specs). + StreamEvent::emit(StreamPayload::TxResult { + idx, + tx_hash: tx_hash.to_string(), + start_timestamp_ms: start_ms, + kind: spec.kind.clone(), + error: error.clone(), + }); + + // 6. Cache in the tx_actor so its flush loop polls for the receipt. + scenario + .tx_actor() + .cache_run_tx(CacheTx { + tx_hash, + start_timestamp_ms: start_ms, + end_timestamp_ms: None, + kind: spec.kind.clone(), + error, + }) + .await?; + + Ok(submitted) +} + +/// Top-level entry point invoked from `main.rs`. +pub async fn spam_stream(db: &SqliteDb, args: SpamStreamCliArgs, data_dir: &Path) -> Result<()> { + // Fall back to the persisted seedfile (not a fresh random seed) when --seed + // is unset, matching `spam`/`setup`/`campaign`. This keeps the executor + // pool's addresses stable across invocations, so a pool funded in one run + // is still funded for a later `--skip-funding` run. + let seed = RandSeed::seed_from_str(&match &args.seed { + Some(s) => s.clone(), + None => load_seedfile(data_dir)?, + }); + + // Provision the executor pool directly. Stream mode never runs pre-defined + // create/setup/spam steps, so the scenario starts from an empty config and + // we inject the pool's signers below. + let config = TestConfig::new(); + let pool_store = build_pool_agent_store(&args.from_pool, args.pool_size, &seed); + let agent_spec = AgentSpec::default() + .create_accounts(0) + .setup_accounts(0) + .spam_accounts(args.pool_size); + + let funder = if let Some(key) = &args.private_key { + let s = key.trim().trim_start_matches("0x"); + Some( + alloy::signers::local::PrivateKeySigner::from_slice( + &alloy::hex::decode(s) + .map_err(|e| CliError::Args(ArgsError::Custom(format!("bad priv-key: {e}"))))?, + ) + .map_err(|e| CliError::Args(ArgsError::Custom(format!("bad priv-key: {e}"))))?, + ) + } else { + None + }; + // TestScenario needs at least one user signer for signer_map. Use a + // throwaway signer if none was provided (we only sign with pool accounts). + let user_signers = if let Some(s) = &funder { + vec![s.clone()] + } else { + vec![alloy::signers::local::PrivateKeySigner::random()] + }; + + let cancel = CancellationToken::new(); + let params = TestScenarioParams { + rpc_url: args.rpc_url.clone(), + builder_rpc_url: None, + txs_rpc_url: None, + signers: user_signers, + agent_spec, + tx_type: TxType::Eip1559, + bundle_type: BundleType::default(), + pending_tx_timeout: Duration::from_secs(60), + extra_msg_handles: None, + // Must be true: gates TestScenario::sync_nonces(). With it false the + // explicit sync_nonces() calls below are silent no-ops, leaving the + // pool accounts' nonces unset, so prepare_tx_request fails every send + // with NonceMissing ("core error"). Stream mode sends one tx at a time + // and never hits the post-batch sync path, so enabling this only makes + // the initial pool-nonce sync actually run. + sync_nonces_after_batch: true, + rpc_batch_size: 0, + gas_price: None, + scenario_label: Some(format!("stream-{}", args.from_pool)), + send_raw_tx_sync: false, + flashblocks_ws_url: None, + }; + + let mut scenario: TestScenario = TestScenario::new( + config, + Arc::new(db.clone()), + seed, + params, + None, + (&PROM, &HIST).into(), + &cancel, + ) + .await?; + + // Register the pool's signers with the scenario so it can sign with them + // and track their nonces, then sync nonces from the RPC. + for (_name, store) in pool_store.all_agents() { + for signer in &store.signers { + scenario.signer_map.insert(signer.address(), signer.clone()); + } + } + scenario.agent_store = pool_store; + scenario.sync_nonces().await?; + + // Fund the pool from the funder key if provided. + if !args.skip_funding { + if let Some(funder) = &funder { + let addrs = scenario.agent_store.all_signer_addresses(); + if !addrs.is_empty() { + info!( + "funding {} pool account(s) to {} ETH min from {}", + addrs.len(), + format_ether(args.min_balance), + funder.address() + ); + fund_accounts( + &addrs, + funder, + &scenario.rpc_client, + args.min_balance, + TxType::Legacy, + &Default::default(), + ) + .await?; + // Re-sync nonces for the freshly-funded accounts so the first + // sent tx uses the correct nonce. + scenario.sync_nonces().await?; + } + } else { + warn!("no funder key supplied; pool accounts must already be funded"); + } + } + + // Register a run row so receipts dump under a real run_id; run_txs has a FK + // into runs, so a bogus id (e.g. 0) would orphan them. + let timestamp = SystemTime::now() + .duration_since(UNIX_EPOCH) + .unwrap_or_default() + .as_millis() as usize; + let run = SpamRunRequest { + timestamp, + tx_count: 0, // unbounded stream; the real count lands as txs flush + scenario_name: format!("stream-{}", args.from_pool), + campaign_id: None, + campaign_name: None, + stage_name: None, + rpc_url: args.rpc_url.to_string(), + txs_per_duration: args.tps, + duration: SpamDuration::Seconds(0), + pending_timeout: Duration::from_secs(60), + }; + let run_id = db + .insert_run(&run) + .map_err(|e| contender_core::Error::Db(e.into()))?; + info!(run_id, "created stream run"); + + // Set up tx_actor context so cached txs flush to the DB. + let start_block = scenario.rpc_client.get_block_number().await?; + let actor_ctx = + ActorContext::new(start_block, run_id).with_pending_tx_timeout(Duration::from_secs(60)); + scenario.tx_actor().init_ctx(actor_ctx).await?; + + // Spawn the reader and run the drive loop. + let (tx, rx) = mpsc::channel::(STREAM_BUFFER); + let _reader = spawn_stream_reader(&args.from, tx)?; + + // CTRL-C cancels the loop; drive_stream observes the token and returns its counts. + let ctrlc_cancel = cancel.clone(); + tokio::spawn(async move { + let _ = tokio::signal::ctrl_c().await; + ctrlc_cancel.cancel(); + }); + + let (sent, failed) = drive_stream( + &mut scenario, + rx, + args.from_pool.clone(), + args.tps, + cancel.clone(), + ) + .await?; + StreamEvent::emit(StreamPayload::Summary { sent, failed }); + + info!("stream complete: {sent} sent, {failed} failed; draining pending receipts..."); + + tokio::select! { + _ = scenario.dump_tx_cache(run_id) => {} + _ = tokio::signal::ctrl_c() => { + info!("CTRL-C during drain; exiting"); + } + } + scenario.shutdown().await; + + Ok(()) +} + +#[cfg(test)] +mod tests { + use super::*; + use clap::{Command, FromArgMatches}; + + /// `SpamStreamCliArgs` derives `Args` (not `Parser`), so build a throwaway + /// `Command` from it to introspect the argument configuration in tests. + fn args_command() -> Command { + SpamStreamCliArgs::augment_args(Command::new("spam-stream")) + } + + #[test] + fn args_config_is_valid() { + // Catches clap misconfiguration (conflicting attrs, bad value_parser, etc.). + args_command().debug_assert(); + } + + #[test] + fn tps_flag_has_long_help() { + // The review asked for long_help clarifying that --tps paces the stream + // rather than duplicating txs. Assert it's wired up and mentions the + // single-spec behavior so the explanation can't silently regress. + let cmd = args_command(); + let tps = cmd + .get_arguments() + .find(|a| a.get_id() == "tps") + .expect("tps arg exists"); + let long_help = tps.get_long_help().expect("tps has long_help").to_string(); + assert!(long_help.contains("once"), "long_help: {long_help}"); + assert!(long_help.contains("stream"), "long_help: {long_help}"); + } + + /// Parse CLI args from a token list, the way clap would at runtime, so we + /// can assert how value strings are coerced into `SpamStreamCliArgs`. + fn parse_args(tokens: &[&str]) -> SpamStreamCliArgs { + let matches = args_command() + .get_matches_from(std::iter::once("spam-stream").chain(tokens.iter().copied())); + SpamStreamCliArgs::from_arg_matches(&matches).expect("from_arg_matches") + } + + #[test] + fn min_balance_accepts_unit_strings() { + // The review asked --min-balance to accept unit-value strings via parse_value. + // 10 eth == 10e18 wei. + let eth = parse_args(&["--min-balance", "10 eth"]); + assert_eq!(eth.min_balance, U256::from(10_000_000_000_000_000_000u128)); + // A plain number is still wei (parse_value's fallback). + let wei = parse_args(&["--min-balance", "12345"]); + assert_eq!(wei.min_balance, U256::from(12345u64)); + } + + #[test] + fn min_balance_default_is_point_zero_one_ether() { + // Default must round-trip through value_parser to 0.01 ETH = 1e16 wei. + let args = parse_args(&[]); + assert_eq!(args.min_balance, U256::from(10_000_000_000_000_000u128)); + } + + #[test] + fn pool_addresses_are_deterministic_for_a_seed() { + // The --skip-funding bug was that a fresh random seed each run produced + // different pool addresses, so a pool funded in run 1 looked unfunded in + // run 2. Pin the invariant the fix relies on: a given seed always yields + // the same pool addresses, and different seeds yield different ones. + let seed_a = RandSeed::seed_from_str("0xabc"); + let s1 = build_pool_agent_store("executors", 5, &seed_a); + let s2 = build_pool_agent_store("executors", 5, &seed_a); + assert_eq!(s1.all_signer_addresses(), s2.all_signer_addresses()); + assert_eq!(s1.all_signer_addresses().len(), 5); + + let seed_b = RandSeed::seed_from_str("0xdef"); + let s3 = build_pool_agent_store("executors", 5, &seed_b); + assert_ne!(s1.all_signer_addresses(), s3.all_signer_addresses()); + } + + #[test] + fn tx_result_envelope_is_versioned_and_tagged() { + let event = StreamEvent { + version: OUTPUT_VERSION, + payload: StreamPayload::TxResult { + idx: 3, + tx_hash: "0xabc".to_string(), + start_timestamp_ms: 1_733_155_200_000, + kind: Some("validate".to_string()), + error: None, + }, + }; + let json: serde_json::Value = + serde_json::from_str(&serde_json::to_string(&event).unwrap()).unwrap(); + assert_eq!(json["version"], 1); + assert_eq!(json["type"], "tx_result"); + assert_eq!(json["idx"], 3); + assert_eq!(json["tx_hash"], "0xabc"); + assert_eq!(json["kind"], "validate"); + // `error` is omitted when None. + assert!(json.get("error").is_none()); + } + + #[test] + fn summary_and_backpressure_envelopes_are_tagged() { + let summary = serde_json::to_value(StreamEvent { + version: OUTPUT_VERSION, + payload: StreamPayload::Summary { sent: 9, failed: 1 }, + }) + .unwrap(); + assert_eq!(summary["version"], 1); + assert_eq!(summary["type"], "summary"); + assert_eq!(summary["sent"], 9); + assert_eq!(summary["failed"], 1); + + let backpressure = serde_json::to_value(StreamEvent { + version: OUTPUT_VERSION, + payload: StreamPayload::Backpressure { + queued: 256, + capacity: 256, + }, + }) + .unwrap(); + assert_eq!(backpressure["type"], "backpressure"); + assert_eq!(backpressure["queued"], 256); + assert_eq!(backpressure["capacity"], 256); + } + + #[test] + fn parses_minimal_spec() { + let line = + r#"{"to":"0xdeAD000000000000000000000000000000000000","value":"1","gas_limit":21000}"#; + let spec: FunctionCallDefinition = serde_json::from_str(line).unwrap(); + assert_eq!(spec.to, "0xdeAD000000000000000000000000000000000000"); + assert_eq!(spec.value.as_deref(), Some("1")); + assert_eq!(spec.gas_limit, Some(21000)); + assert!(spec.from.is_none() && spec.from_pool.is_none()); + } + + #[test] + fn parses_spec_with_signature_and_args() { + let line = r#"{ + "to": "0x4200000000000000000000000000000000000022", + "signature": "validateMessage(bytes32)", + "args": ["0x0102030405060708091011121314151617181920212223242526272829303132"], + "gas_limit": 200000 + }"#; + let spec: FunctionCallDefinition = serde_json::from_str(line).unwrap(); + assert_eq!(spec.signature.as_deref(), Some("validateMessage(bytes32)")); + assert_eq!(spec.args.as_ref().unwrap().len(), 1); + assert_eq!(spec.gas_limit, Some(200000)); + } + + #[tokio::test] + async fn forward_lines_skips_blank_and_comments_and_emits_specs() { + let (tx, mut rx) = mpsc::channel::(8); + let input = b"\n# this is a comment\n{\"to\":\"0xdeAD000000000000000000000000000000000000\",\"value\":\"1\"}\n\n{\"to\":\"0xdeAD000000000000000000000000000000000001\",\"value\":\"2\"}\n"; + let reader = BufReader::new(&input[..]); + forward_lines(reader, tx).await; + let mut received = vec![]; + while let Ok(spec) = rx.try_recv() { + received.push(spec); + } + assert_eq!(received.len(), 2); + assert_eq!(received[0].value.as_deref(), Some("1")); + assert_eq!(received[1].value.as_deref(), Some("2")); + } + + #[tokio::test] + async fn forward_lines_skips_malformed_lines() { + let (tx, mut rx) = mpsc::channel::(8); + let input = b"not json at all\n{\"to\":\"0xdeAD000000000000000000000000000000000000\"}\n"; + let reader = BufReader::new(&input[..]); + forward_lines(reader, tx).await; + let mut received = vec![]; + while let Ok(spec) = rx.try_recv() { + received.push(spec); + } + assert_eq!(received.len(), 1); + } +} diff --git a/crates/cli/src/main.rs b/crates/cli/src/main.rs index 4e0af9a5..74faf0ec 100644 --- a/crates/cli/src/main.rs +++ b/crates/cli/src/main.rs @@ -140,6 +140,10 @@ async fn run() -> Result<(), contender_cli::Error> { commands::spam(&db, &spam_args, SpamCampaignContext::default()).await?; } + ContenderSubcommand::SpamStream { args } => { + contender_cli::commands::spam_stream::spam_stream(&db, *args, &data_dir).await?; + } + ContenderSubcommand::Server => { contender_cli::server::run() .await diff --git a/docs/stream-mode.md b/docs/stream-mode.md new file mode 100644 index 00000000..27a1dc55 --- /dev/null +++ b/docs/stream-mode.md @@ -0,0 +1,213 @@ +# Stream Mode (`spam-stream`) + +> **Status:** prototype / draft. This document accompanies the +> initial implementation of `spam-stream`. Expect the CLI surface and the +> stream format to evolve based on review feedback. + +## Motivation + +Contender is a TPS spammer driven by static scenario TOML files. It cycles +through `[[spam]]` entries, fuzzes args, and sends at a configured rate. + +Some use cases need to feed *dynamically discovered* tx specs into the spam +loop. For example, an interop relayer reads message-emitted events on chain A +and needs to execute the corresponding `validateMessage(...)` call on chain B +— with the right access list, calldata, and target. Today these workflows +end up reimplementing rate limiting, signer pools, nonce management, and +receipt tracking outside contender. + +Stream mode lets contender act as the "sender" half of those workflows: any +upstream process can pipe JSON tx specs into contender and reuse the existing +agent pools, rate limiter, `tx_actor` receipt tracking, gas-price caching, +and Prometheus latency metrics. + +## CLI + +```bash +contender spam-stream \ + -r https://chain-b \ + -p $FUNDING_KEY \ + --from \ + --from-pool executors --pool-size 10 \ + --tps 5 +``` + +Key flags: + +| Flag | Default | Meaning | +|------|---------|---------| +| `-r, --rpc-url` | `http://localhost:8545` | Target RPC. | +| `-p, --priv-key` | none | Funder key (funds the pool before spam starts). | +| `--from` | `stdin` | `stdin` or a file path. | +| `--from-pool` | `executors` | Pool name. Specs that omit `from`/`from_pool` use this pool. | +| `--pool-size` | `10` | Accounts generated in the pool. | +| `--tps` | `0` | `0` = consume as fast as channel emits. | +| `--min-balance` | `0.01 ETH` (wei) | Min pool-account balance during funding. | +| `--skip-funding` | `false` | Skip pre-spam funding. | +| `--seed` | random | Deterministic pool generation. | + +## Stream format + +Newline-delimited JSON, one [`FunctionCallDefinition`](../crates/core/src/generator/function_def.rs) +per line. Same field names as scenario TOML. + +Minimal: + +```json +{"to":"0xdeAD000000000000000000000000000000000000","value":"1 wei","gas_limit":21000} +``` + +Full (interop-style): + +```json +{ + "to": "0x4200000000000000000000000000000000000022", + "signature": "validateMessage(bytes32)", + "args": ["0x0102030405060708091011121314151617181920212223242526272829303132"], + "access_list": [ + { + "address": "0x4200000000000000000000000000000000000022", + "storageKeys": ["0x0100000000000000000000000000000000000000000000000000000000000000"] + } + ], + "gas_limit": 200000 +} +``` + +Empty lines and lines beginning with `#` are ignored. Malformed JSON lines +log a warning and the loop continues. + +## Architecture + +Stream mode does **not** introduce a new spammer trait or a new tx pipeline. +It reuses the existing `TestScenario` machinery and wires a JSON-line reader +to it through an mpsc channel. + +``` +stdin/file -> reader task -> mpsc + | + v + drive_stream loop + | + v + for each spec: + scenario.make_strict_call (Generator trait, resolves from_pool + access_list) + scenario.config.template_function_call (Templater, builds TransactionRequest) + scenario.prepare_tx_request (assigns nonce, gas limit, signs key from pool) + scenario.txs_client.send_tx_envelope + scenario.tx_actor().cache_run_tx (queues for receipt polling) +``` + +Code map: + +- [`crates/cli/src/commands/spam_stream.rs`](../crates/cli/src/commands/spam_stream.rs) + is the new subcommand. All logic lives there. +- The scenario starts from an empty `TestConfig`; the executor pool is + provisioned directly via `AgentStore::add_new_agent` and its signers are + registered with the scenario, then nonces are synced from the RPC. +- The reader task is a small wrapper around `tokio::io::BufReader::lines()` + that forwards parsed specs over an mpsc channel and exits on EOF. +- The drive loop honors `--tps` via `tokio::time::interval`. + +## Structured output + +`spam-stream` writes a structured, newline-delimited JSON event stream to +**stdout** (human-readable logs go to stderr via `tracing`). Each event is a +versioned, tagged envelope so the schema can evolve without breaking +consumers: + +```json +{"version":1,"type":"tx_result","idx":0,"tx_hash":"0x...","start_timestamp_ms":1733155200000,"kind":"validate","error":null} +``` + +- `version` pins the schema (bump on breaking changes). +- `type` discriminates the event kind: `tx_result`, `backpressure`, or `summary`. +- One `tx_result` is emitted per input spec after the send attempt; `error` is + present only when the send RPC call failed. +- A `backpressure` event is emitted when the input buffer saturates and the + reader blocks, so the producer can slow down: + `{"version":1,"type":"backpressure","queued":256,"capacity":256}` +- A single `summary` event closes the stream (on EOF or CTRL-C): + `{"version":1,"type":"summary","sent":42,"failed":3}` + +## Reuse vs. new code + +| Existing piece | Reused as-is | +|----------------|--------------| +| `TestScenario` constructor (signer map, nonce sync, txs_client) | yes | +| `Generator::make_strict_call` (resolves `from_pool`, access list, EIP-7702) | yes | +| `Templater::template_function_call` (calldata encoding, access list threading) | yes | +| `TestScenario::prepare_tx_request` (nonce, gas limit, complete_tx_request) | yes | +| Pool generation via `AgentPools::build_agent_store` | yes | +| `TxActorHandle::cache_run_tx` + flush loop (DB writes, receipt polling) | yes | +| `fund_accounts` helper | yes | +| Prometheus latency histograms via Tower middleware | yes (inherited from `TestScenario`) | +| The `Spammer` trait + `TimedSpammer`/`BlockwiseSpammer` | **not** reused | + +The reason we skip `TimedSpammer` is that its `on_spam` loop drives ticks +from a pre-loaded `Vec>` returned by +`get_spam_tx_chunks`. Stream mode wants a stream-shaped tick: pull one spec, +send one tx. Bolting the channel into `TimedSpammer` would require a generic +`SpamSource` abstraction across the existing spammers. Out of scope for the +prototype; a candidate for a follow-up if the prototype lands. + +## Scope of the prototype + +In scope: + +- `--from stdin|FILE`, `--from-pool`, `--pool-size`, `--tps`, `--priv-key`, `--rpc-url`, `--seed`, `--min-balance`, `--skip-funding`. +- Same `FunctionCallDefinition` schema as scenario TOML (incl. `access_list`, + `gas_limit`, `signature`, `args`, `value`, `from`, `from_pool`, `kind`). +- Pool funding from `--priv-key` before spam begins. +- Receipt tracking + DB persistence via the existing tx_actor flush loop, + recorded under a real `run_id` so dumped receipts are queryable. +- Graceful CTRL-C and stream EOF handling (drain pending receipts before exit). + +Out of scope (future work): + +- Bundle support (`[[spam.bundle]]` analogue in the stream). +- Blob transactions (EIP-4844) and authorization transactions (EIP-7702) — + specs carrying `blob_data` or `authorization_address` are rejected up front + rather than silently producing an invalid tx. +- Fuzzing in stream mode — fuzz happens upstream of the stream. +- Gas-bump / nonce-shift retry logic from the regular spammer's + `handle_tx_outcome`. The stream loop currently logs send errors and moves + on; the upstream is expected to resubmit if it cares. +- `--rpc-batch-size`, `--send-raw-tx-sync` integration. +- A generic `SpamSource` trait so `TimedSpammer` can consume a stream too. + +## Validation + +Unit tests live alongside the implementation: + +``` +cargo test -p contender_cli spam_stream +``` + +Smoke test: + +```bash +echo '{"to":"0xdeAD000000000000000000000000000000000000","value":"1","gas_limit":21000}' | \ + contender spam-stream -r $RPC -p $FUNDING_KEY --from stdin --tps 1 +``` + +The tx should land on the target chain; the funder needs at least enough ETH +to fund the executor pool. + +## Open questions + +1. Should stream mode get its own `Spammer` impl in `contender_core` so + campaigns can reuse it? Today the prototype lives entirely in `cli/`. + *(Deferred to a follow-up: refactoring the `Spammer` trait is out of scope + for the prototype.)* +2. ~~Is the JSON spec the right shape, or should we standardize on a tagged + envelope so we can evolve it later?~~ **Resolved:** the stdout output is now + a versioned, tagged envelope (`{"version":1,"type":"tx_result",...}`). See + "Structured output" above. +3. ~~How should errors propagate back to the upstream producer?~~ **Resolved:** + `spam-stream` emits a structured `tx_result` event per spec on stdout + (including send errors), plus `backpressure` and a terminal `summary` event, + in addition to the DB + logs. +4. Should `--tps 0` (drain-as-fast) bound concurrency by pool size, or is + "one in flight at a time" acceptable for the relayer case? *(Deferred: + parallel sends judged not worth the effort for the prototype.)* From e0a355f6f20bf2df0b4de32c53ceba8331489041 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?brock=20=F0=9F=A4=96=E2=9A=A1?= <2791467+zeroXbrock@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:17:46 -0700 Subject: [PATCH 3/5] release/v0.10.2 (#591) * chore: update changelogs * chore: bump versions --- Cargo.lock | 10 +++++----- crates/cli/CHANGELOG.md | 6 ++++++ crates/cli/Cargo.toml | 2 +- crates/cli/src/server/static/openrpc.json | 2 +- crates/core/CHANGELOG.md | 4 +++- crates/core/Cargo.toml | 2 +- crates/report/Cargo.toml | 2 +- crates/sqlite_db/Cargo.toml | 2 +- crates/testfile/Cargo.toml | 2 +- 9 files changed, 20 insertions(+), 12 deletions(-) diff --git a/Cargo.lock b/Cargo.lock index b24d8095..e5b22d9d 100644 --- a/Cargo.lock +++ b/Cargo.lock @@ -2104,7 +2104,7 @@ dependencies = [ [[package]] name = "contender_cli" -version = "0.10.1" +version = "0.10.2" dependencies = [ "alloy", "async-trait", @@ -2148,7 +2148,7 @@ dependencies = [ [[package]] name = "contender_core" -version = "0.11.0" +version = "0.11.1" dependencies = [ "alloy", "ark-bn254", @@ -2199,7 +2199,7 @@ dependencies = [ [[package]] name = "contender_report" -version = "0.10.1" +version = "0.10.2" dependencies = [ "alloy", "chrono", @@ -2218,7 +2218,7 @@ dependencies = [ [[package]] name = "contender_sqlite" -version = "0.10.1" +version = "0.10.2" dependencies = [ "alloy", "contender_core", @@ -2232,7 +2232,7 @@ dependencies = [ [[package]] name = "contender_testfile" -version = "0.10.1" +version = "0.10.2" dependencies = [ "alloy", "contender_core", diff --git a/crates/cli/CHANGELOG.md b/crates/cli/CHANGELOG.md index 1c1d9fe1..06c0be34 100644 --- a/crates/cli/CHANGELOG.md +++ b/crates/cli/CHANGELOG.md @@ -5,6 +5,12 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). +## [0.10.2](https://github.com/flashbots/contender/releases/tag/v0.10.2) - 2026-06-11 + +- Add scenario access list support with placeholder resolution ([#588](https://github.com/flashbots/contender/pull/588)) +- spam-stream subcommand for streaming tx specs (relayer use case) ([#589](https://github.com/flashbots/contender/pull/589)) +- upgrade contender_core to [v0.11.1](../core/CHANGELOG.md) + ## [0.10.1](https://github.com/flashbots/contender/releases/tag/v0.10.1) - 2026-05-06 - update alloy dependencies ([#561](https://github.com/flashbots/contender/pull/561)) diff --git a/crates/cli/Cargo.toml b/crates/cli/Cargo.toml index 52905de6..b32cb884 100644 --- a/crates/cli/Cargo.toml +++ b/crates/cli/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "contender_cli" description = "Contender CLI" -version = "0.10.1" +version = "0.10.2" edition.workspace = true rust-version.workspace = true authors.workspace = true diff --git a/crates/cli/src/server/static/openrpc.json b/crates/cli/src/server/static/openrpc.json index d0d5d67b..415053dd 100644 --- a/crates/cli/src/server/static/openrpc.json +++ b/crates/cli/src/server/static/openrpc.json @@ -3,7 +3,7 @@ "info": { "title": "Contender RPC Server", "description": "JSON-RPC API to remotely run contender sessions.", - "version": "0.10.1" + "version": "0.10.2" }, "x-source": { "repository": "https://github.com/flashbots/contender", diff --git a/crates/core/CHANGELOG.md b/crates/core/CHANGELOG.md index e945bbaa..089e7972 100644 --- a/crates/core/CHANGELOG.md +++ b/crates/core/CHANGELOG.md @@ -5,7 +5,9 @@ All notable changes to this project will be documented in this file. The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.0.0/), and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). -## [Unreleased] +## [0.11.1](https://github.com/flashbots/contender/releases/tag/contender_core-v0.11.1) - 2026-06-11 + +*from [#580](https://github.com/flashbots/contender/pull/580):* - added `FunctionCallDefinition::max_priority_fee_per_gas` for setting a static (or `{placeholder}`-driven) per-tx EIP-1559 priority fee - added `FuzzParam::max_priority_fee_per_gas` (a bool flag mirroring `FuzzParam::value`) so the priority fee can be fuzzed per-tx alongside function args and `value` diff --git a/crates/core/Cargo.toml b/crates/core/Cargo.toml index 8d021f18..0e4271b0 100644 --- a/crates/core/Cargo.toml +++ b/crates/core/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "contender_core" description = "Contender core library" -version = "0.11.0" +version = "0.11.1" edition.workspace = true rust-version.workspace = true authors.workspace = true diff --git a/crates/report/Cargo.toml b/crates/report/Cargo.toml index 32f7842c..41553e6b 100644 --- a/crates/report/Cargo.toml +++ b/crates/report/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "contender_report" description = "Generate reports to analyze chain performance and orderflow from contender spam runs." -version = "0.10.1" +version = "0.10.2" edition.workspace = true rust-version.workspace = true authors.workspace = true diff --git a/crates/sqlite_db/Cargo.toml b/crates/sqlite_db/Cargo.toml index 3fc731bc..e9388f08 100644 --- a/crates/sqlite_db/Cargo.toml +++ b/crates/sqlite_db/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "contender_sqlite" description = "SQLite database for contender" -version = "0.10.1" +version = "0.10.2" authors.workspace = true edition.workspace = true homepage.workspace = true diff --git a/crates/testfile/Cargo.toml b/crates/testfile/Cargo.toml index fb8a50a3..f688eda8 100644 --- a/crates/testfile/Cargo.toml +++ b/crates/testfile/Cargo.toml @@ -1,7 +1,7 @@ [package] name = "contender_testfile" description = "Definitions for contender scenarios to be encoded as TOML files." -version = "0.10.1" +version = "0.10.2" edition.workspace = true rust-version.workspace = true authors.workspace = true From b528a4644f6268dcd81f7b929442345e31e713be Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?brock=20=F0=9F=A4=96=E2=9A=A1?= <2791467+zeroXbrock@users.noreply.github.com> Date: Thu, 11 Jun 2026 13:31:51 -0700 Subject: [PATCH 4/5] fix check-version CI script (#592) --- .github/workflows/release.yml | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml index f49b4082..55dc5ec2 100644 --- a/.github/workflows/release.yml +++ b/.github/workflows/release.yml @@ -62,7 +62,10 @@ jobs: run: | tag="${{ needs.extract-version.outputs.VERSION }}" tag=${tag#v} - cargo_ver=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[0].version') + # WARNING: VERY SHITTY VERSION EXTRACTION, PLEASE FIX + # packages[1] is contender_cli, which is the primary user-facing crate. + # For this check, we focus on this crate only. Probably needs to be more robust, though. + cargo_ver=$(cargo metadata --no-deps --format-version 1 | jq -r '.packages[1].version') [[ "$tag" == "$cargo_ver"* ]] || { echo "Tag $tag doesn’t match the Cargo version $cargo_ver"; exit 1; } build: From c470154b2100419f9f7605c778f17fc99a672063 Mon Sep 17 00:00:00 2001 From: op-will <232669456+op-will@users.noreply.github.com> Date: Fri, 12 Jun 2026 09:01:05 -0400 Subject: [PATCH 5/5] fix(core): cap estimate_gas ceiling at EIP-7825 per-tx gas limit On a chain that enforces EIP-7825 (Osaka), eth_estimateGas binary-searches using the block gas limit as its upper bound. When that limit exceeds the 2^24 per-tx cap, the first simulated execution is itself invalid and the node returns "intrinsic gas too high" instead of an estimate, so the call fails before any tx is sent. This aborts contract deployment during setup. Clamp the gas ceiling on the estimate request to 2^24 at the three estimate_gas sites (contract deploy, setup tx, spam tx). The returned estimate is the true gas the tx needs, so this never inflates the final gas limit. --- crates/core/src/test_scenario.rs | 30 ++++++++++++++++++++++++++++-- 1 file changed, 28 insertions(+), 2 deletions(-) diff --git a/crates/core/src/test_scenario.rs b/crates/core/src/test_scenario.rs index 690e5b43..fc90af71 100644 --- a/crates/core/src/test_scenario.rs +++ b/crates/core/src/test_scenario.rs @@ -64,6 +64,27 @@ use tracing::{debug, info, trace, warn}; pub use alloy::transports::http::reqwest::Url; +/// Per-transaction gas limit cap introduced by EIP-7825 (activated in the Osaka +/// hard fork): 2^24 gas. A transaction whose gas limit exceeds this is invalid. +const EIP_7825_MAX_TX_GAS_LIMIT: u64 = 1 << 24; + +/// Bounds a transaction request's `gas` field below the EIP-7825 per-tx gas cap +/// before it is handed to `eth_estimateGas`. +/// +/// On a chain that enforces EIP-7825, `eth_estimateGas` binary-searches for the +/// gas limit using the block gas limit as its upper bound. When that block limit +/// exceeds `EIP_7825_MAX_TX_GAS_LIMIT`, the first simulated execution is itself +/// invalid and the node returns "intrinsic gas too high" instead of an estimate — +/// so the call fails before any transaction is ever sent. Clamping the request's +/// gas ceiling to the cap keeps the search within the valid range; the returned +/// estimate is the true (smaller) gas the tx needs, so this never inflates the +/// final gas limit. +fn cap_gas_for_estimate(tx: &mut TransactionRequest) { + if tx.gas.is_none_or(|gas| gas > EIP_7825_MAX_TX_GAS_LIMIT) { + tx.gas = Some(EIP_7825_MAX_TX_GAS_LIMIT); + } +} + /// Fetch a u128 value via an async RPC call, caching on success and falling back /// to the cached value on transient failure. async fn fetch_with_cache( @@ -769,8 +790,10 @@ where } = extra_tx_params; // estimate gas limit + let mut estimate_req = tx_req.tx.to_owned(); + cap_gas_for_estimate(&mut estimate_req); let gas_limit = provider - .estimate_gas(WithOtherFields::new(tx_req.tx.to_owned())) + .estimate_gas(WithOtherFields::new(estimate_req)) .await?; debug!("estimated gas limit: {gas_limit}"); @@ -897,7 +920,9 @@ where let gas_limit = if let Some(gas) = tx_req.tx.gas { gas } else { - let res = provider.estimate_gas(tx_req.tx.to_owned().into()).await; + let mut estimate_req = tx_req.tx.to_owned(); + cap_gas_for_estimate(&mut estimate_req); + let res = provider.estimate_gas(estimate_req.into()).await; if let Ok(res) = res { res } else { @@ -1963,6 +1988,7 @@ where } } } + cap_gas_for_estimate(&mut tx_req); self.rpc_client .estimate_gas(WithOtherFields::new(tx_req.to_owned())) .await?