taskrunner

TaskRunner

Execute configurable task sequences with initialization and recurring execution phases.

⚠️ IMPORTANT: This scenario requires task configuration via --tasks or --tasks-file. It will not work without tasks defined.

Usage

spamoor taskrunner [flags]

Configuration

Base Settings (required)

• --privkey - Private key of the sending wallet
• --rpchost - RPC endpoint(s) to send transactions to

Task Configuration (required)

• --tasks - Inline task configuration (YAML/JSON string)
• --tasks-file - Path to task configuration file or URL (http/https)
• --await-txs - Send and await each transaction individually instead of batching

Volume Control (either -c or -t required)

• -c, --count - Total number of task execution cycles
• -t, --throughput - Task execution cycles per slot
• --max-pending - Maximum number of running execution cycles with pending transactions

Transaction Settings

• --basefee - Max fee per gas in gwei (default: 20) - inherited by all tasks
• --tipfee - Max tip per gas in gwei (default: 2) - inherited by all tasks
• --rebroadcast - Seconds to wait before rebroadcasting (default: 120)

Wallet Management

• --max-wallets - Maximum number of child wallets to use

Client Settings

• --client-group - Client group to use for sending transactions

Debug Options

• --timeout - Maximum scenario runtime (e.g. '1h', '30m', '5s')
• --log-txs - Log all submitted transactions

Examples

Deploy contract and call function repeatedly:

spamoor taskrunner -p "<PRIVKEY>" -h http://rpc-host:8545 -c 100 \
  --tasks '{
    "execution": [
      {
        "type": "deploy",
        "name": "test", 
        "data": {"contract_code": "0x6080..."}
      },
      {
        "type": "call",
        "data": {
          "target": "{contract:test}",
          "call_data": "0x6057361d{random:32}"
        }
      }
    ]
  }'

Load tasks from file:

spamoor taskrunner -p "<PRIVKEY>" -h http://rpc-host:8545 -t 5 \
  --tasks-file ./tasks.yaml

Load tasks from URL:

spamoor taskrunner -p "<PRIVKEY>" -h http://rpc-host:8545 -c 1000 \
  --tasks-file https://example.com/test-tasks.yaml

Advanced Usage

Transaction Execution Modes

Batch Mode (default): All tasks in an execution cycle are built first, then sent as a batch for maximum throughput. This creates temporary nonce gaps during building.

Await Mode (--await-txs): Each task is built, sent, and awaited individually before proceeding to the next task. This ensures:

• No nonce gaps during execution (critical for concurrent operations)
• Sequential execution within each cycle
• Each task waits for confirmation before the next task is built
• Easier debugging and transaction tracking
• Lower throughput but guaranteed ordering and no nonce conflicts

Example with sequential execution:

spamoor taskrunner -p "<PRIVKEY>" -h http://rpc-host:8545 -c 100 \
  --await-txs --tasks-file ./sequential-tasks.yaml

Task Configuration Format

Tasks are configured in YAML or JSON with two phases. All tasks automatically inherit the global transaction settings (--basefee, --tipfee) from the scenario options:

# Initialization tasks (run once)
init:
  - type: deploy
    name: factory
    data:
      contract_file: "./factory.bin"
      gas_limit: 3000000

# Execution tasks (run repeatedly)  
execution:
  - type: deploy
    name: token
    data:
      contract_file: "./erc20.bin"
      contract_args: "0x000000000000000000000000000000000000000000000000000000000000001e"
      
  - type: call
    data:
      target: "{contract:token}"
      call_abi_file: "./erc20-abi.json" 
      call_fn_name: "transfer"
      call_args: ["{randomaddr}", "{random:1000000}"]

Task Types

Deploy Task

Deploys a contract and optionally registers it in the contract registry.

- type: deploy
  name: token        # Optional: register contract as "token"
  data:
    contract_code: "0x608060405234801561001057600080fd5b50..."  # Inline bytecode
    # OR
    contract_file: "./contracts/erc20.bin"                       # File path or URL (http/https)
    
    contract_args: "0x000000000000000000000000000000000000000000000000000000000000001e"  # Constructor args
    gas_limit: 4000000    # Gas limit for deployment
    amount: 1000          # ETH to send in gwei (optional)

Call Task

Calls a function on a deployed contract.

- type: call
  name: transfer     # Optional task name
  data:
    target: "{contract:token}"        # Contract reference
    # OR
    target: "0x742d35Cc9B3Ed5F9..."  # Direct address
    
    # Method 1: Raw calldata
    call_data: "0xa9059cbb000000000000000000000000742d35cc9b3ed5f9..."
    
    # Method 2: ABI + function
    call_abi: '[{"inputs":[...],"name":"transfer",...}]'  # Inline ABI
    # OR
    call_abi_file: "./contracts/erc20-abi.json"           # ABI file or URL (http/https)
    call_fn_name: "transfer"                              # Function name
    call_args: ["{randomaddr}", "1000000"]                # Function arguments
    
    gas_limit: 100000
    amount: 0         # ETH to send in gwei (optional)

Placeholders

TaskRunner supports dynamic placeholders in arguments and bytecode:

Basic Placeholders

• {random} - Random uint256 value
• {random:N} - Random value between 0 and N
• {randomaddr} - Random Ethereum address
• {txid} - Current transaction ID
• {stepid} - Current step index within execution cycle

Contract Address Placeholders

• {contract:name} - Reference to deployed contract address
• {contract:name:nonce} - Child contract address calculation using CREATE opcode

The child address calculation uses Ethereum's standard CREATE address formula: childAddress = keccak256(rlp.encode(parentAddress, nonce))[12:]

Examples:

# Basic contract reference
call_args: ["{contract:token}", "{random:1000000}"]

# Child contract addresses
call_args: ["{contract:factory:1}", "{contract:factory:2}"]  # First and second child contracts

# In deploy bytecode (automatically strips 0x prefix)
contract_code: "608060405234801561001057600080fd5b50{contract:factory:1}..."

# In constructor arguments (automatically strips 0x prefix)  
contract_args: "000000000000000000000000{contract:parent:0}0000000000000000000000000000000000000000000000000000000000000001"

Address Formatting:

• Call tasks: Contract addresses include 0x prefix (standard format)
• Deploy tasks: Contract addresses in contract_code and contract_args automatically strip 0x prefix for bytecode compatibility

Contract Registry

The contract registry maintains deployed contract addresses across phases:

1. Init Phase: Contracts deployed here are available throughout execution
2. Execution Phase: Each cycle has its own registry that inherits from init
3. Contract References: Use {contract:name} to reference deployed contracts

Wallet Management

TaskRunner uses different wallet strategies for each phase:

1. Init Phase: Uses a well-known wallet (taskrunner-init) for all initialization tasks

   • Ensures init contracts have predictable addresses
   • Avoids conflicts with numbered wallets used in execution
   • Sequential execution with consistent wallet state

2. Execution Phase: Uses numbered wallets distributed across cycles

   • Each execution cycle can use different wallets for parallel processing
   • Follows standard spamoor wallet selection patterns
   • Enables high throughput execution

Registry Inheritance:

Init Registry (Global)
├── Contract "factory" → 0x123...
└── Contract "helper" → 0x456...

Execution Registry (Per Cycle)  
├── Inherits: factory, helper
├── Contract "token" → 0x789...    # Deployed this cycle
└── Contract "nft" → 0xabc...      # Deployed this cycle

Advanced Examples

Multi-Contract Deployment

init:
  - type: deploy
    name: factory
    data:
      contract_file: "./factory.bin"
      gas_limit: 3000000

execution:
  - type: call
    data:
      target: "{contract:factory}"
      call_abi_file: "./factory-abi.json"
      call_fn_name: "createToken"
      call_args: ["{random}", "{randomaddr}"]
      
  - type: call  
    data:
      target: "{contract:factory}"
      call_fn_name: "mint"
      call_args: ["{randomaddr}", "{random:1000000}"]

Complex ERC20 Testing

init:
  - type: deploy
    name: token
    data:
      contract_file: "./erc20.bin"
      contract_args: "0x0000000000000000000000000000000000000000000000056bc75e2d630eb20000"

execution:
  - type: call
    data:
      target: "{contract:token}"
      call_abi_file: "./erc20-abi.json"
      call_fn_name: "transfer" 
      call_args: ["{randomaddr}", "{random:1000000}"]
      
  - type: call
    data:
      target: "{contract:token}"
      call_abi_file: "./erc20-abi.json"
      call_fn_name: "approve"
      call_args: ["{randomaddr}", "{random:2000000}"]

Factory Pattern with Child Contracts

init:
  - type: deploy
    name: factory
    data:
      contract_file: "./factory.bin"

execution:
  # Deploy child contracts through factory
  - type: call
    data:
      target: "{contract:factory}"
      call_abi_file: "./factory-abi.json"
      call_fn_name: "createChild"
      call_args: ["{random}", "{randomaddr}"]
      
  # Interact with the first child contract deployed by factory
  - type: call
    data:
      target: "{contract:factory:1}"  # First child (nonce 1)
      call_abi_file: "./child-abi.json"
      call_fn_name: "initialize"
      call_args: ["{contract:factory}", "{random:1000}"]
      
  # Deploy another child and interact with the second one
  - type: call
    data:
      target: "{contract:factory}"
      call_fn_name: "createChild" 
      call_args: ["{random}", "{randomaddr}"]
      
  - type: call
    data:
      target: "{contract:factory:2}"  # Second child (nonce 2)
      call_fn_name: "setParent"
      call_args: ["{contract:factory}"]

Proxy Pattern with Predictable Addresses

init:
  - type: deploy
    name: implementation
    data:
      contract_file: "./implementation.bin"
      
  - type: deploy
    name: proxy_factory
    data:
      contract_file: "./proxy_factory.bin"
      # Embed implementation address in proxy bytecode
      contract_args: "000000000000000000000000{contract:implementation}"

execution:
  # Create proxy pointing to implementation
  - type: call
    data:
      target: "{contract:proxy_factory}"
      call_fn_name: "createProxy"
      call_args: ["{randomaddr}"]  # owner
      
  # Call implementation through first proxy
  - type: call
    data:
      target: "{contract:proxy_factory:1}"  # First proxy created
      call_abi_file: "./implementation-abi.json"
      call_fn_name: "setValue"
      call_args: ["{random:1000000}"]

When to Use TaskRunner

Use TaskRunner when:

• Testing complex multi-step contract interaction patterns
• Need to maintain state between transaction cycles
• Require flexible, configurable transaction sequences
• Other scenarios are too rigid or specific

Don't use TaskRunner for:

• Simple EOA transfers (use eoatx)
• Basic contract deployments (use deploytx)
• Standard token transfers (use erctx)
• Single-function contract calls (use calltx)

Error Handling

• Configuration Errors: Invalid YAML/JSON or missing required fields cause immediate failure
• Task Validation: Each task is validated before execution starts
• Transaction Failures: Failed transactions are logged but don't stop the scenario
• Contract References: Unknown contract references cause immediate task failure

Performance Tips

1. Minimize Init Tasks: Init phase runs sequentially using a single well-known wallet - keep it minimal
2. Use Multiple Wallets: Distribute execution load across --max-wallets for better throughput
3. Choose Execution Mode:
   • Use batch mode (default) for maximum throughput
   • Use await mode (--await-txs) when tasks must execute sequentially or for debugging
4. Wallet Strategy: Init phase isolation prevents wallet conflicts during high-throughput execution
5. Optimize Gas Limits: Set appropriate gas limits to avoid failures

Troubleshooting

"no tasks configuration provided"

• Cause: Neither --tasks nor --tasks-file was specified
• Fix: Provide task configuration via one of these flags

"contract 'name' not found in registry"

• Cause: Referencing a contract that wasn't deployed or named incorrectly
• Fix: Ensure contract is deployed in init phase or earlier in execution phase

"failed to parse tasks as YAML or JSON"

• Cause: Malformed configuration syntax
• Fix: Validate YAML/JSON syntax using online validators

High transaction failure rates

• Cause: Insufficient gas limits or network congestion
• Fix: Increase gas limits or reduce throughput