Stylus execution path

This section details how Stylus integrates into the State Transition Function (STF), covering execution flow, messaging handling, caching, and interactions with ArbOS and Geth.

1. Execution flow of a Stylus transaction

When a transaction interacts with a Stylus contract, its execution follows a distinct path compared to EVM transactions:

• Transaction submission and routing

  • The transaction is included in a child chain block by the Sequencer.

  • Geth processes the transaction and determines its target contract.

  • If the target is a Stylus contract, ArbOS routes execution to the WASM runtime instead of the EVM.

• Stylus execution within ArbOS

  • ArbOS retrieves the Stylus program from its cache (stylus/src/cache.rs) or loads it from storage if not cached.

  • The WebAssembly System Interface (Go-WASI) initializes a secure execution environment.

  • The WASM module executes within ArbOS, processing instructions efficiently and calling host I/O functions.

• Host I/O operations for blockchain state access

  • Stylus contracts do not use EVM opcodes. Instead, they interact with the blockchain through host I/O calls handled by ArbOS.

  • These include storage access (TLOAD TSTORE), arithmetic operations (MULMOD, ADDMOD), and context retrieval (GETCALLER, GETCALLVALUE).

  • ArbOS ensures these operations are efficient and compatible with Ethereum's state model.

• State commitment and finalization

  • Once execution is complete, ArbOS finalizes storage changes and updates logs and receipts.

  • Geth processes the final transaction result and commits it to the state tree.

This process bypasses the EVM interpreter entirely, allowing Stylus contracts to execute significantly faster than their Solidity counterparts.

2. Stylus caching and gas pricing

Stylus gas pricing model

Unlike standard EVM gas pricing, Stylus pricing follows a multi-dimensional cost model, incorporating:

• Ink cost (memory and execution cost)

  • Measure in Ink units (Stylus's equivalent of computational gas).

  • Ink pricing varies based on execution complexity, memory usage, and computation steps.

  • Complex WASM operations consume more Ink, directly impacting execution costs.

• Opcode pricing

  • WASM instructions are assigned individual execution costs similar to EVM opcodes.

  • Heavy computation opcodes are priced higher.

  • Cheap opcodes (e.g., simple arithmetic, bitwise operations) have minimal costs.

• Host I/O pricing

  • Stylus introduces fine-grained pricing for different I/O calls:

    • Storage read/writes: Priced based on access pattern and data size.

    • Precompile calls: Stylus-specific precompiles have fixed execution costs.

    • External calls to EVM contracts: Encapsulated within ArbOS transaction handling, with additional gas considerations.

Stylus caching

Stylus contracts leverage an advanced caching system to minimize execution overhead within ArbOS:

• LRU (Least Recently Used) caching: Keeps the most recently accessed Stylus contracts in memory for fast execution.

• Persistent long-term caching: Caching for selected contracts may occur across blocks based on an economic auction model.

• Init costs and execution pricing: Instead of a flat gas cost, Stylus contracts have dynamic execution costs based on WASM complexity. ArbOS maintains pricing parameters (initCost, cachedCost) that adjust based on future optimizations in WASM execution.

3. Interaction with ArbOS and Geth

Execution Stage	Handled By
Transaction submission	Geth (identifies target contract)
Stylus execution	ArbOS (switches to WASM runtime)
Host I/O calls	ArbOS (handles storage, call data, context retrieval)
State commitment	Geth and ArbOS (finalizes updates, commits to state)

4. Go-WASI and co-threads in Stylus execution

ArbOS executes Stylus contracts using Go-WASI, a WASM-compatible runtime with custom optimizations for Arbitrum. Key features include:

• Memory management: WASM modules execute in a sandboxed environment with strict memory allocation policies.

• Co-threads for efficient execution: Instead of traditional synchronous execution, Stylus employs co-threading, enabling lightweight task switching and parallelism where possible.

• Deterministic execution: Ensures that Stylus contracts remain fully deterministic and compatible with Ethereum's consensus model.

These optimizations make Stylus an extremely efficient execution environment, capable of outperforming the EVM while maintaining security and compatibility with Ethereum's state model.