diff --git a/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx b/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx index b059e511a1..1651de892c 100644 --- a/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx +++ b/docs/how-arbitrum-works/01-inside-arbitrum-nitro.mdx @@ -29,7 +29,7 @@ Transactions first enter the Inbox, serving as the primary gateway into the ecos The deterministic model ensures that identical inputs will always produce the same outputs, among honest nodes, forming the bedrock of Arbitrum’s security. It supports efficient fraud proofs and dispute resolution, enabling verification of execution correctness without re-running entire transactions, thereby minimizing computational overhead. -For foundational concepts about the STF, see the [State Transition Function gentle introduction](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx). +For foundational concepts about the STF, see the [State Transition Function deep dive](/how-arbitrum-works/deep-dives/stf.mdx). ## Step 1: Submitting a transaction @@ -63,7 +63,7 @@ For a deeper look at how the Sequencer orders, batches, and posts transactions, With ordering and batching complete, execution shifts to the State Transition Function (STF), the core of Arbitrum's processing engine. -For foundational concepts about how the STF works, see the [State Transition Function gentle introduction](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx). +For foundational concepts about how the STF works, see the [State Transition Function deep dive](/how-arbitrum-works/deep-dives/stf.mdx). Arbitrum ensures full Ethereum Virtual Machine (EVM) compatibility via a three-layer architecture. At the base, the Geth core handles EVM execution, aligning behaviors with Ethereum and drawing on its extensively tested code for security. @@ -174,7 +174,7 @@ In this overview, you've learned about the complete transaction journey through - [Transaction Lifecycle](/how-arbitrum-works/deep-dives/transaction-lifecycle.mdx): Detailed transaction lifecycle from submission to finality - [Sequencer](/how-arbitrum-works/deep-dives/sequencer.mdx): How the Sequencer orders, batches, and posts transactions - [Gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx): Gas pricing, fee calculations, and adaptive pricing algorithm -- [State Transition Function: Gentle Introduction](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx): Foundational concepts of the STF +- [State Transition Function](/how-arbitrum-works/deep-dives/stf.mdx): Foundational concepts of the STF - [Geth](/how-arbitrum-works/reference/geth.mdx): Geth core and EVM compatibility - [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx): Arbitrum Operating System features and capabilities - [State Transition Function inputs](/how-arbitrum-works/reference/stf-inputs.mdx): Message types and STF processing mechanics diff --git a/docs/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx b/docs/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx deleted file mode 100644 index eb6ef74199..0000000000 --- a/docs/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx +++ /dev/null @@ -1,38 +0,0 @@ ---- -title: 'A gentle introduction' -description: 'Learn the fundamentals of Nitro, Arbitrum stack.' -author: petevielhaber -sme: Mehdi -user_story: As a current or prospective Arbitrum user, I need learn more about Nitros design. -content_type: gentle-introduction ---- - -The State Transition Function (STF) determines how blockchain systems change state during transaction processing. The STF takes the current blockchain state (account balances, smart contract data, and ledger information) and an input (a transaction or a block) to compute the new state deterministically. This deterministic property ensures all network nodes reach the same result, maintaining consensus. - -With Arbitrum, the STF plays an even more pivotal role. Arbitrum executes transactions offchain in batches, periodically submitting summaries to the parent chain. This approach leverages offchain computation to achieve higher throughput and lower gas costs while maintaining Ethereum’s security. - -To safeguard against incorrect or malicious offchain execution, Arbitrum employs a challenge mechanism called fraud proofs. If a dispute arises, the STF can be recomputed step-by-step onchain, enabling the network to verify the validity of offchain computations and ensure that errors or fraudulent behavior are detected and corrected. For how disputes are resolved in practice, see [Assertions](/how-arbitrum-works/deep-dives/assertions.mdx) and the [BoLD gentle introduction](/how-arbitrum-works/bold/gentle-introduction.mdx). - -The [Arbitrum Nitro](/how-arbitrum-works/01-inside-arbitrum-nitro.mdx) stack's STF mirrors Ethereum's STF with key modifications for Arbitrum chain requirements. The function processes ordered transactions and outputs the updated state from the transaction batch. - -[Stylus](/stylus/gentle-introduction.mdx) expands Arbitrum’s execution model beyond the Ethereum Virtual Machine (EVM) by adding WebAssembly (WASM)—based execution, allowing high-performance contracts in Rust, C, and C++ to run alongside traditional EVM contracts (Solidity). This integration of Stylus introduces several modifications to the STF, including: - -## Stylus-specific transaction processing - -A modified version of Geth that recognizes and processes Stylus transactions, ensuring proper inclusion in state transitions. - -## Execution in a WASM runtime - -Stylus transactions execute in [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx)'s WASM runtime instead of the EVM, enabling faster execution and more efficient computation. - -## Stylus gas accounting and pricing - -Unlike standard EVM transactions, Stylus transactions introduce new gas pricing models that account for factors such as opcode pricing, host I/O operations, and Ink usage costs. - -## Interoperability with the EVM - -Stylus contracts can interact with Solidity contracts, enabling hybrid applications that leverage EVM and WASM execution environments. - -These Stylus-related changes aim to maintain compatibility with Ethereum’s execution model while introducing a more efficient, flexible, and scalable alternative for smart contract development. - -The following sections cover [STF inputs](/how-arbitrum-works/reference/stf-inputs.mdx), node processing, and implementation rules, highlighting [differences between Ethereum and Arbitrum](/arbitrum-essentials/arbitrum-vs-ethereum/comparison-overview.mdx), and Stylus execution environments. [Stylus-specific execution tasks handled within ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) will be covered separately, focusing on host I/O operations, caching, and WASM memory management. diff --git a/docs/how-arbitrum-works/deep-dives/arbos.mdx b/docs/how-arbitrum-works/deep-dives/arbos.mdx index 4075a74d87..bc01eab4ce 100644 --- a/docs/how-arbitrum-works/deep-dives/arbos.mdx +++ b/docs/how-arbitrum-works/deep-dives/arbos.mdx @@ -7,7 +7,7 @@ user_story: As a current or prospective Arbitrum user, I need to learn more abou content_type: concept --- -ArbOS is the child-EVM virtual machine monitor (VMM—aka hypervisor) for the Arbitrum chain, providing the execution environment for the chain. It acts as a trusted “system glue” component within the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx). +ArbOS is the child-EVM virtual machine monitor (VMM) for Arbitrum Nitro. It's a trusted system component that lives inside the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/stf.mdx) and provides the execution environment for the chain. Unlike a conventional operating system, ArbOS is not a process running beside the chain—it's ordinary Go code compiled into the STF, so every node (and fraud prover) can replay it deterministically. ArbOS is responsible for: diff --git a/docs/how-arbitrum-works/deep-dives/assertions.mdx b/docs/how-arbitrum-works/deep-dives/assertions.mdx index 2a35aede1b..1e748f065b 100644 --- a/docs/how-arbitrum-works/deep-dives/assertions.mdx +++ b/docs/how-arbitrum-works/deep-dives/assertions.mdx @@ -40,7 +40,7 @@ For more details on how the Rollup chain works under chain state using the chain's [STF](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx), whereas proposers can also assert and challenge the chain state on the parent chain. +Validators validate transactions by computing the next chain state using the chain's [STF](/how-arbitrum-works/deep-dives/stf.mdx), whereas proposers can also assert and challenge the chain state on the parent chain. ::: diff --git a/docs/how-arbitrum-works/deep-dives/batchposter.mdx b/docs/how-arbitrum-works/deep-dives/batchposter.mdx new file mode 100644 index 0000000000..b966e65f72 --- /dev/null +++ b/docs/how-arbitrum-works/deep-dives/batchposter.mdx @@ -0,0 +1,51 @@ +--- +title: The batch poster +description: 'Learn the fundamentals of the Arbitrum batch poster.' +author: pete-vielhaber +sme: Mehdi +user_story: As a current or prospective Arbitrum user, I need to learn more about the batch poster. +content_type: reference +--- + +Batch posting is a fundamental process for the Sequencer's operation in Arbitrum. It involves collecting multiple child chain transactions, organizing them into batches, compressing the data to reduce size, and sending these batches to the Sequencer Inbox contract on the parent chain. This mechanism securely records transactions on the parent chain while optimizing for costs and performance. + +## How it works + + + +#### 1. Messages arrive (upstream handoff) + +A transaction’s journey into the batch poster begins after it’s already been [sequenced](/how-arbitrum-works/deep-dives/sequencer.mdx). The poster pulls ordered child chain messages from the `TransactionStreamer`—that’s a handoff into the batch poster; sequencing, [execution](/how-arbitrum-works/deep-dives/stf.mdx), and [soft finality](/how-arbitrum-works/reference/finality-and-reorgs.mdx#the-three-confirmation-levels) all happened before this point and live outside of the batch poster. + +#### 2. The poster decides where it stands + +The main loop (`MaybePostSequencerBatch`) first does a safety check (refuse to post if a prior batch reverted), then asks “what batch number and the parent chain nonce am I on?” and establishes the parent chain time/block window the batch will use. That window comes from reading the parent chain SequencerInbox contract’s `MaxTimeVariation`—a read-only handoff out to the parent chain. + +#### 3. Messages become a compressed batch + +The poster receives messages in order, turning each into typed segments (the transaction itself, plus small bookkeeping notes for delayed-message markers and time/block advances) and streaming them through Brotli. It watches size and segment-count caps, and adapts compression effort to how far behind it is—more compression when calm, less when backlogged. When it decides the batch is ready (full enough, old enough, or a delayed message is about to expire), it seals and recompresses it. This is the core work done inside the batch poster. + +#### 4. The data is routed to storage (DA handoff) + +The sealed bytes are handed to a data availability (DA) provider—an offchain AnyTrust/DAS committee or a custom backend—via the small Writer.Store interface, with a fallback to putting data directly on Ethereum (calldata or blobs). What comes back is either a certificate (offchain) or the raw data (EthDA). The committee aggregation, BLS signing, and blob KZG cryptography all happen behind that interface—handoffs that the batch poster isn’t involved in. + +#### 5. The batch is wrapped for the parent chain and self-checked + +The poster builds calldata for the right `SequencerInbox` method (calldata vs. blobs, with or without a delay proof) and—as a correctness gate—replays the whole batch through the `InboxMultiplexer` (the same read/decode machinery used to consume batches) to confirm it decodes back to the exact original messages before anything is sent. + +#### 6. The transaction is shipped to the parent chain (`DataPoster` handoff) + +The batch poster hands the calldata, blobs, and gas estimate to the `DataPoster`—the “shipping department.” From here, nonce selection, fee bidding, signing, queue persistence, and replace-by-fee-if-stuck are the `DataPoster`’s job, deliberately kept separate so the batch poster never has to deal with Ethereum gas mechanics. The `DataPoster` ultimately submits the transaction to the parent chain `SequencerInbox` contract. + +#### 7. Finality and feedback + +Once the parent chain transaction confirms, the transactions cross from the Sequencer’s soft finality into [hard finality](/how-arbitrum-works/reference/finality-and-reorgs.mdx) anchored on the parent chain. The poster updates its backlog estimate (feeding back into compression effort and fee urgency), and a background revert watcher monitors the parent chain—if a posted batch ever fails onchain, it halts all posting for operator intervention. + +## Related resources + +- [The Sequencer and censorship resistance](/how-arbitrum-works/deep-dives/sequencer.mdx#posting-to-the-parent-chain): batching, compression, and the Sequencer Inbox methods. +- [Sequencer transaction flow](/how-arbitrum-works/deep-dives/sequencer-transaction-flow.mdx): what happens before the handoff, from the queue to block creation. +- [Gas and fees](/how-arbitrum-works/deep-dives/gas-and-fees.mdx#parent-chain-gas-pricing): how the parent chain pricer reimburses batch posting costs. +- [Finality and reorgs](/how-arbitrum-works/reference/finality-and-reorgs.mdx): what parent chain finality guarantees, and the failure modes around posting. +- [AnyTrust protocol](/how-arbitrum-works/deep-dives/anytrust-protocol.mdx): what the DAC does with the data behind the DA handoff. +- [Run a batch poster](/launch-arbitrum-chain/run-a-node/batch-poster.mdx) and [Batch poster troubleshooting](/launch-arbitrum-chain/operate/batch-poster-troubleshooting.mdx): the operator view. diff --git a/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx b/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx index 6633c9541b..c447a6a6d2 100644 --- a/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx +++ b/docs/how-arbitrum-works/deep-dives/gas-and-fees.mdx @@ -16,7 +16,7 @@ There are two parties a user pays when submitting a transaction: The parent chain component is the product of the transaction's estimated contribution to its batch's size—computed using [Brotli](/how-arbitrum-works/deep-dives/sequencer.mdx#posting-to-the-parent-chain) on the transaction alone—and the child chain's view of the parent chain data price. This value dynamically adjusts over time to ensure the batch poster is ultimately fairly compensated. -The child chain component consists of the traditional fees Geth would pay to bonders in a vanilla parent chain, such as the computation and storage charges that apply to the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx). [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) charges additional fees for executing its child-chain-specific [precompiles](/arbitrum-essentials/precompiles/overview.mdx), whose fees are dynamically priced based on the resources used during execution. +The child chain component consists of the traditional fees Geth would pay to bonders in a vanilla parent chain, such as the computation and storage charges that apply to the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/stf.mdx). [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) charges additional fees for executing its child-chain-specific [precompiles](/arbitrum-essentials/precompiles/overview.mdx), whose fees are dynamically priced based on the resources used during execution. The following sections detail how parent and child chain fees are calculated. For a practical guide on estimating gas for your transactions, see [How to estimate gas in Arbitrum](/arbitrum-essentials/how-to-estimate-gas.mdx). diff --git a/docs/how-arbitrum-works/deep-dives/sequencer.mdx b/docs/how-arbitrum-works/deep-dives/sequencer.mdx index 75bdbd9579..fab57e9847 100644 --- a/docs/how-arbitrum-works/deep-dives/sequencer.mdx +++ b/docs/how-arbitrum-works/deep-dives/sequencer.mdx @@ -27,7 +27,7 @@ Once the Sequencer has a finalized ordering, it calls the ExecutionEngine, which -Everything from this point of execution—iterating the ordered transactions, applying pre- and post-execution filters, running each transaction against chain state, metering child- and parent-chain gas, and computing the resulting state—is the job of the [State Transition Function](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx) and [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx). The Sequencer supplies the ordered input and receives a produced block in return; it does not decide execution outcomes. +Everything from this point of execution—iterating the ordered transactions, applying pre- and post-execution filters, running each transaction against chain state, metering child- and parent-chain gas, and computing the resulting state—is the job of the [State Transition Function](/how-arbitrum-works/deep-dives/stf.mdx) and [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx). The Sequencer supplies the ordered input and receives a produced block in return; it does not decide execution outcomes. diff --git a/docs/how-arbitrum-works/deep-dives/stf.mdx b/docs/how-arbitrum-works/deep-dives/stf.mdx new file mode 100644 index 0000000000..4a52f347b4 --- /dev/null +++ b/docs/how-arbitrum-works/deep-dives/stf.mdx @@ -0,0 +1,56 @@ +--- +title: 'State Transition Function' +description: 'Learn the fundamentals of the State Transition Function within Arbitrum Nitro.' +author: petevielhaber +sme: Mehdi +user_story: As a current or prospective Arbitrum user, I need to learn more about Nitro's design. +content_type: reference +--- + +An Arbitrum node is a deterministic machine: feed it the same ordered inputs, and it will always produce the same outputs. The job of everything before the State Transition Function (STF) is to agree on exactly which inputs those are and in what order they should be. + +## How it works + +#### 1. Two doors, one source of truth + +Inputs reach a node through two doors. The fast door is the [Sequencer feed](/how-arbitrum-works/deep-dives/sequencer.mdx)—a real-time broadcast of newly ordered messages, so nodes feel the chain advance within milliseconds. The slow, trustworthy door is Ethereum itself: the Sequencer periodically posts compressed batches to the parent-chain inbox, emitting a `SequencerBatchDelivered` event. When the two disagree, the feed yields—the parent chain is the canonical record (Ethereum for Arbitrum), and a node will reorg its optimistic feed-derived state to match what was actually settled on Ethereum. + +#### 2. The envelope (`L1IncomingMessage`) + +Whatever the door, every input lands as one `L1IncomingMessage`: a header plus an opaque L2msg payload. The header is the input surface the STF reads: message type, sender, `BlockNumber` and `Timestamp`, the ordering/identity handle, and `L1BaseFee` (the parent-chain gas price used). Determinism comes from this: the STF never asks the outside world for the time or the gas price; it only reads what is in the header. + +#### 3. One byte decides the path + +The header’s `Kind` routes the message. A handful of kinds are system messages that the protocol mints: `Initialize` (kind 11) is the genesis message that sets the chain ID and base fee, `EthDeposit` (kind 12) bridges the native token, `SubmitRetryable` (kind 9) carries the retryable-ticket mechanism behind robust parent-to-child chain messaging, and `BatchPostingReport` (kind 13) lets the STF charge the batch poster for the parent-chain data it consumes. The workhorse, though, is `L2Message` (kind 3)—the envelope for ordinary user activity. For every kind, its value, and the name the bridge contracts use for it, see the [message type reference](/how-arbitrum-works/reference/stf-inputs.mdx#message-types). + +#### 4. The envelope inside the envelope + +Open an `L2Message`, and you’ll find a second type byte—the `L2MessageKind`. The type byte can be a single signed transaction (`SignedTx`), an unsigned EOA or contract call (`UnsignedUserTx`, `ContractTx`), or—most importantly—a Batch, which is simply a list of more L2 messages. This nesting is why the type space looks deceptively flat in summaries but is really two layers: an outer parent-chain framing and an inner transaction framing. + +#### 5. From batch to messages + +A batch posted to L1 isn’t a list of transactions; it can be either a Brotli-compressed blob or some calldata. The inbox multiplexer inspects the leading header byte, decompresses, and pops out individual `L1IncomingMessage`s one at a time—the same shape the feed delivers. By the time anything reaches the STF, both doors have converged on the identical stream of envelopes. + +#### 6. The unwrap + +Finally, `ParseL2Transactions` turns each envelope into the EVM transactions Geth will run: deposits become `ArbitrumDepositTx`, retryables become their submission transaction, batches recurse, and bookkeeping kinds like `RollupEvent` are acknowledged and skipped. What flows out is an ordered list of transactions. That ordered list is derived deterministically from headers that no node can fabricate; it is the true input to Arbitrum’s State Transition Function. + +## Stylus-specific transaction processing + +A modified version of Geth that recognizes and processes Stylus transactions, ensuring proper inclusion in state transitions. + +## Execution in a WASM runtime + +Stylus transactions execute in [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx)'s WASM runtime instead of the EVM, enabling faster execution and more efficient computation. + +## Stylus gas accounting and pricing + +Unlike standard EVM transactions, Stylus transactions introduce new gas pricing models that account for factors such as opcode pricing, host I/O operations, and Ink usage costs. + +## Interoperability with the EVM + +Stylus contracts can interact with Solidity contracts, enabling hybrid applications that leverage EVM and WASM execution environments. + +These Stylus-related changes aim to maintain compatibility with Ethereum’s execution model while introducing a more efficient, flexible, and scalable alternative for smart contract development. + +The following sections cover [STF inputs](/how-arbitrum-works/reference/stf-inputs.mdx), node processing, and implementation rules, highlighting [differences between Ethereum and Arbitrum](/arbitrum-essentials/arbitrum-vs-ethereum/comparison-overview.mdx), and Stylus execution environments. [Stylus-specific execution tasks handled within ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) will be covered separately, focusing on host I/O operations, caching, and WASM memory management. diff --git a/docs/how-arbitrum-works/reference/arbos-reference.mdx b/docs/how-arbitrum-works/reference/arbos-reference.mdx index 08eea4eeda..d080986d56 100644 --- a/docs/how-arbitrum-works/reference/arbos-reference.mdx +++ b/docs/how-arbitrum-works/reference/arbos-reference.mdx @@ -57,7 +57,7 @@ ArbOS's per-block gas limit is distinct from Geth's block limit, which ArbOS [se ## Stylus-specific differences -This section details how [Stylus](/stylus/gentle-introduction.mdx) integrates into the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx), covering execution flow, message handling, caching, and interactions with [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) and [Geth](/how-arbitrum-works/reference/geth.mdx). +This section details how [Stylus](/stylus/gentle-introduction.mdx) integrates into the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/stf.mdx), covering execution flow, message handling, caching, and interactions with [ArbOS](/how-arbitrum-works/deep-dives/arbos.mdx) and [Geth](/how-arbitrum-works/reference/geth.mdx). ### Execution flow of a Stylus transaction diff --git a/docs/how-arbitrum-works/reference/stf-inputs.mdx b/docs/how-arbitrum-works/reference/stf-inputs.mdx index d6751d8281..d01e375ef5 100644 --- a/docs/how-arbitrum-works/reference/stf-inputs.mdx +++ b/docs/how-arbitrum-works/reference/stf-inputs.mdx @@ -14,7 +14,7 @@ content_type: reference The two channels suit different applications because they carry different trust assumptions. The feed gives you sub-second soft confirmations that depend on the Sequencer behaving honestly. The `SequencerBatchDelivered` event gives you hard finality once the parent chain finalizes the batch. See [Finality and reorgs](/how-arbitrum-works/reference/finality-and-reorgs.mdx#the-three-confirmation-levels). -These transactions serve as inputs for the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/01-stf-gentle-intro.mdx). +These transactions serve as inputs for the [State Transition Function (STF)](/how-arbitrum-works/deep-dives/stf.mdx). ## Message types diff --git a/docs/launch-arbitrum-chain/overview/introduction.mdx b/docs/launch-arbitrum-chain/overview/introduction.mdx index 21565a8592..a97e20426e 100644 --- a/docs/launch-arbitrum-chain/overview/introduction.mdx +++ b/docs/launch-arbitrum-chain/overview/introduction.mdx @@ -24,11 +24,11 @@ Critically, your chain isn't siloed: it plugs directly into Ethereum's deep liqu Set confirmation speed and settlement behavior for products where timing and certainty matter—payments, trading, treasury, and internal asset movement. -| Feature | Your benefit | User benefit | Guide | -| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Tune block time | You own the speed-versus-cost tradeoff. Faster blocks let you position the chain as a premium, low-latency venue (trading, gaming, payments) without waiting on a third party to change infrastructure. | Near-instant confirmations make the app feel like a familiar web experience rather than a slow onchain one, reducing the “did my transaction go through?” hesitation. | - [Configure chain finality](/launch-arbitrum-chain/chain-config/sequencer/chain-finality.mdx)
- [Sequencer timing adjustments](launch-arbitrum-chain/chain-config/sequencer/sequencer-timing-adjustments.mdx) | -| Configure deposit finality (delayed inbox) | You match certainty guarantees to your actual risk profile to avoid paying for stronger finality than your product needs. Adjust the time before the chain processes a deposit. | Predictable, well-defined settlement means users know exactly when funds and actions are final—important for anyone moving real value. | [Configure chain finality](/launch-arbitrum-chain/chain-config/sequencer/chain-finality.mdx) | -| Enable fast withdrawals to reduce withdrawal finality time | Fewer support tickets and complaints about locked-up capital, and a more competitive bridging story when users compare your chain to alternatives. | Users get their funds in minutes instead of waiting the full challenge window, dramatically lowering the friction of exiting the chain. | [Fast withdrawals](/launch-arbitrum-chain/chain-config/validation/fast-withdrawals.mdx) | +| Feature | Your benefit | User benefit | Guide | +| -------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Tune block time | You own the speed-versus-cost tradeoff. Faster blocks let you position the chain as a premium, low-latency venue (trading, gaming, payments) without waiting on a third party to change infrastructure. | Near-instant confirmations make the app feel like a familiar web experience rather than a slow onchain one, reducing the “did my transaction go through?” hesitation. | - [Configure chain finality](/launch-arbitrum-chain/chain-config/sequencer/chain-finality.mdx)
- [Sequencer timing adjustments](/launch-arbitrum-chain/chain-config/sequencer/sequencer-timing-adjustments.mdx) | +| Configure deposit finality (delayed inbox) | You match certainty guarantees to your actual risk profile to avoid paying for stronger finality than your product needs. Adjust the time before the chain processes a deposit. | Predictable, well-defined settlement means users know exactly when funds and actions are final—important for anyone moving real value. | [Configure chain finality](/launch-arbitrum-chain/chain-config/sequencer/chain-finality.mdx) | +| Enable fast withdrawals to reduce withdrawal finality time | Fewer support tickets and complaints about locked-up capital, and a more competitive bridging story when users compare your chain to alternatives. | Users get their funds in minutes instead of waiting the full challenge window, dramatically lowering the friction of exiting the chain. | [Fast withdrawals](/launch-arbitrum-chain/chain-config/validation/fast-withdrawals.mdx) | The 100ms figure is an optional lower bound on block time, not the default. Most chains run at the @@l2BlockTimeMs=250@@ms default; 100ms is available when you opt into it. By default, fast withdrawals is not enabled—the default withdrawal time is @@arbOneDisputeWindowDays=6.4@@ days. diff --git a/docs/notices/arbos51-upgrade-notice.mdx b/docs/notices/arbos51-upgrade-notice.mdx index e1ed905894..7f96374164 100644 --- a/docs/notices/arbos51-upgrade-notice.mdx +++ b/docs/notices/arbos51-upgrade-notice.mdx @@ -5,7 +5,7 @@ user_story: As an Arbitrum node operator, I want to keep my nodes in sync with A content_type: notice --- -[ArbOS 51 "Dia"](docs/run-arbitrum-node/arbos-releases/arbos51.mdx) will be activated on the Arbitrum Sepolia, Arbitrum One, and Arbitrum Nova chains. +[ArbOS 51 "Dia"](/run-arbitrum-node/arbos-releases/arbos51.mdx) will be activated on the Arbitrum Sepolia, Arbitrum One, and Arbitrum Nova chains. ## Actions required for node operators @@ -29,6 +29,6 @@ The following dates are relevant for Arbitrum chain operators. ## Context -[ArbOS 51 "Dia"](docs/run-arbitrum-node/arbos-releases/arbos51.mdx) builds upon [ArbOS 40 "Callisto"](docs/run-arbitrum-node/arbos-releases/arbos40.mdx) with support for the relevant EVM changes that are a part of Ethereum's [Fusaka upgrade](https://ethereum.org/en/roadmap/fusaka/), as well as additional improvements to the gas pricing algorithm, a change to the min L2 base fee, `MaxTxGasLimit` allowing full block utilization, changes to instrument Nitro’s State Transition Function (STF) to price gas based on specific resource usage, native token mint/burn capabilities, and a few bug fixes. +[ArbOS 51 "Dia"](/run-arbitrum-node/arbos-releases/arbos51.mdx) builds upon [ArbOS 40 "Callisto"](/run-arbitrum-node/arbos-releases/arbos40.mdx) with support for the relevant EVM changes that are a part of Ethereum's [Fusaka upgrade](https://ethereum.org/en/roadmap/fusaka/), as well as additional improvements to the gas pricing algorithm, a change to the min L2 base fee, `MaxTxGasLimit` allowing full block utilization, changes to instrument Nitro’s State Transition Function (STF) to price gas based on specific resource usage, native token mint/burn capabilities, and a few bug fixes. Upstream governance items ([ArbOS 50](https://snapshot.box/#/s:arbitrumfoundation.eth/proposal/0x33754da4006d0ef38666ec5d5e85fd0966a891a594ab9dc21f23beedea2d330b) + [Gas Target & Pricing Framework](https://snapshot.box/#/s:arbitrumfoundation.eth/proposal/0x4a96a91d162975de0d402b83ca8b8a24e808ca357150120fc0d44ae0bf1cc4a5)) were bundled into a single [ArbOS 51 onchain vote](https://www.tally.xyz/gov/arbitrum/proposal/53154361738756237993090798888616593723057470462495169047773178676976253908001?govId=eip155:42161:0xf07DeD9dC292157749B6Fd268E37DF6EA38395B9). Both components have passed Snapshot temperature checks, and the bundled Tally vote was passed **December 18, 2025**. diff --git a/docs/notices/arbos61-upgrade-notice.mdx b/docs/notices/arbos61-upgrade-notice.mdx index 0c90eee17a..365cf7c6b9 100644 --- a/docs/notices/arbos61-upgrade-notice.mdx +++ b/docs/notices/arbos61-upgrade-notice.mdx @@ -39,11 +39,11 @@ The following dates are relevant for Arbitrum chain operators. ## Context -ArbOS 61 "Elara" builds upon [ArbOS 51 "Dia"](docs/run-arbitrum-node/arbos-releases/arbos51.mdx). It makes two changes to Arbitrum One and Nova: it raises the Stylus contract code size limit to 96 KB, and it adds a `BaseFeeManager` contract that manages the minimum L2 base fee. +ArbOS 61 "Elara" builds upon [ArbOS 51 "Dia"](/run-arbitrum-node/arbos-releases/arbos51.mdx). It makes two changes to Arbitrum One and Nova: it raises the Stylus contract code size limit to 96 KB, and it adds a `BaseFeeManager` contract that manages the minimum L2 base fee. ArbOS 61 also ships two features that stay disabled on Arbitrum One and Nova, for the convenience of other Arbitrum chains: an Alternative Data Availability (AltDA) Layer API, and optional compliance transaction filtering. A chain owner must enable each one explicitly. -To learn how to build a custom DA provider against the new API, refer to [How to integrate with the DA API](docs/launch-arbitrum-chain/extend-the-protocol/da-api-guide.mdx). To learn how transaction filtering works, refer to [Compliance filtering](docs/launch-arbitrum-chain/chain-config/sequencer/compliance-filtering.mdx). +To learn how to build a custom DA provider against the new API, refer to [How to integrate with the DA API](/launch-arbitrum-chain/extend-the-protocol/da-api-guide.mdx). To learn how transaction filtering works, refer to [Compliance filtering](/launch-arbitrum-chain/chain-config/sequencer/compliance-filtering.mdx). ArbOS 61 corrects two interacting bugs in the gas refund logic that were found while testing ArbOS 60 on Arbitrum Sepolia. The fixes change the State Transition Function (STF), so they required a new ArbOS version. ArbOS 60 never activated on Arbitrum One or Nova, so neither chain was affected. diff --git a/docs/notices/fusaka-upgrade-notice.mdx b/docs/notices/fusaka-upgrade-notice.mdx index 59dc8e0cb4..b05a398b95 100644 --- a/docs/notices/fusaka-upgrade-notice.mdx +++ b/docs/notices/fusaka-upgrade-notice.mdx @@ -7,7 +7,7 @@ content_type: notice :::danger 🛑 IMPORTANT 🛑 -Arbitrum chain operators must ensure that their nodes are properly configured before or shortly after the parent chain upgrades to Fusaka or the child chain upgrades to [ArbOS 51](docs/run-arbitrum-node/arbos-releases/arbos51.mdx). +Arbitrum chain operators must ensure that their nodes are properly configured before or shortly after the parent chain upgrades to Fusaka or the child chain upgrades to [ArbOS 51](/run-arbitrum-node/arbos-releases/arbos51.mdx). ::: @@ -21,13 +21,13 @@ The Fusaka upgrade introduces several breaking changes. Review [EIP-7607](https: The following dates are relevant for Arbitrum chain operators. -| Date | Network upgrade | Affected audience | -| ----------------------------- | ------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------- | -| `Nov 20th 2025, 17:00:00 UTC` | Arbitrum Sepolia upgrade to ArbOS 50 | Node operators for Arbitrum Sepolia | -| `Dec 1st 2025, 17:00:00 UTC` | Arbitrum Sepolia upgrade to [ArbOS 51](docs/run-arbitrum-node/arbos-releases/arbos51.mdx) | Node operators for Arbitrum Sepolia | -| `Jan 8th, 2026, 17:00:00 UTC` | Arbitrum One/Nova upgrade to [ArbOS 51](docs/run-arbitrum-node/arbos-releases/arbos51.mdx) | Node operators for Arbitrum One/Nova | -| `Oct 14th 2025, 07:36:00 UTC` | Ethereum Sepolia Fusaka hard fork | Node operators for Arbitrum chains settling on Ethereum Sepolia (Arbitrum L2s, Arbitrum Sepolia) | -| `Dec 3rd 2025, 21:49:11 UTC` | Ethereum Mainnet Fusaka hard fork | Node operators for Arbitrum chains settling on Ethereum Mainnet (Arbitrum L2s, Arbitrum One/Nova) | +| Date | Network upgrade | Affected audience | +| ----------------------------- | -------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- | +| `Nov 20th 2025, 17:00:00 UTC` | Arbitrum Sepolia upgrade to ArbOS 50 | Node operators for Arbitrum Sepolia | +| `Dec 1st 2025, 17:00:00 UTC` | Arbitrum Sepolia upgrade to [ArbOS 51](/run-arbitrum-node/arbos-releases/arbos51.mdx) | Node operators for Arbitrum Sepolia | +| `Jan 8th, 2026, 17:00:00 UTC` | Arbitrum One/Nova upgrade to [ArbOS 51](/run-arbitrum-node/arbos-releases/arbos51.mdx) | Node operators for Arbitrum One/Nova | +| `Oct 14th 2025, 07:36:00 UTC` | Ethereum Sepolia Fusaka hard fork | Node operators for Arbitrum chains settling on Ethereum Sepolia (Arbitrum L2s, Arbitrum Sepolia) | +| `Dec 3rd 2025, 21:49:11 UTC` | Ethereum Mainnet Fusaka hard fork | Node operators for Arbitrum chains settling on Ethereum Mainnet (Arbitrum L2s, Arbitrum One/Nova) | ## For node operators diff --git a/docs/partials/_glossary-partial.mdx b/docs/partials/_glossary-partial.mdx index af95700a93..5ffb764a88 100644 --- a/docs/partials/_glossary-partial.mdx +++ b/docs/partials/_glossary-partial.mdx @@ -316,7 +316,7 @@ The means by which an [Active Validator](/intro/glossary#active-validator) prove ### Gas Price Floor {#gas-price-floor} -Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the [chain info page](for-devs/dev-tools-and-resources/chain-info.mdx#chain-parameters). +Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the [chain info page](/for-devs/dev-tools-and-resources/chain-info.mdx#chain-parameters). ### Gas target {#gas-target} diff --git a/docs/partials/glossary/_gas-price-floor.mdx b/docs/partials/glossary/_gas-price-floor.mdx index a5cb821f26..a3e11ee3ef 100644 --- a/docs/partials/glossary/_gas-price-floor.mdx +++ b/docs/partials/glossary/_gas-price-floor.mdx @@ -4,4 +4,4 @@ key: gas-price-floor titleforSort: Gas Price Floor --- -Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the [chain info page](for-devs/dev-tools-and-resources/chain-info.mdx#chain-parameters). +Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the [chain info page](/for-devs/dev-tools-and-resources/chain-info.mdx#chain-parameters). diff --git a/redirects.config.js b/redirects.config.js index 9edd3b99fc..d5cbba7eaf 100644 --- a/redirects.config.js +++ b/redirects.config.js @@ -16,6 +16,11 @@ export const redirects = [ from: '/stylus/how-tos/adding-support-for-new-languages', to: '/stylus/how-tos/deploying-non-rust-wasm-contracts', }, + // Manual redirect — STF gentle introduction replaced by the STF deep dive + { + from: '/how-arbitrum-works/deep-dives/stf-gentle-intro', + to: '/how-arbitrum-works/deep-dives/stf', + }, // AUTO-GENERATED REDIRECTS START { from: '/build-decentralized-apps/how-to-estimate-gas', diff --git a/sidebars.js b/sidebars.js index 99db506205..acf3f176f4 100644 --- a/sidebars.js +++ b/sidebars.js @@ -1015,8 +1015,8 @@ const sidebars = { }, { type: 'doc', - label: 'STF inputs', - id: 'how-arbitrum-works/reference/stf-inputs', + label: 'STF', + id: 'how-arbitrum-works/deep-dives/stf', }, ], }, @@ -1039,6 +1039,11 @@ const sidebars = { label: 'Finality and reorgs', id: 'how-arbitrum-works/reference/finality-and-reorgs', }, + { + type: 'doc', + label: 'STF inputs', + id: 'how-arbitrum-works/reference/stf-inputs', + }, ], }, { diff --git a/static/glossary.json b/static/glossary.json index 072f2e7849..63bab4fb3a 100644 --- a/static/glossary.json +++ b/static/glossary.json @@ -293,7 +293,7 @@ }, "gas-price-floor": { "title": "Gas Price Floor", - "text": "

Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the chain info page.

\n" + "text": "

Protocol-enforced minimum gas price on an Arbitrum chain. These values can be found on the chain info page.

\n" }, "gas-target": { "title": "Gas target", diff --git a/vercel.json b/vercel.json index b64e0d8c3d..b2443e331c 100644 --- a/vercel.json +++ b/vercel.json @@ -21,6 +21,11 @@ "destination": "/stylus/how-tos/deploying-non-rust-wasm-contracts", "permanent": false }, + { + "source": "/how-arbitrum-works/deep-dives/stf-gentle-intro", + "destination": "/how-arbitrum-works/deep-dives/stf", + "permanent": false + }, { "source": "/build-decentralized-apps/how-to-estimate-gas", "destination": "/arbitrum-essentials/how-to-estimate-gas", @@ -1209,7 +1214,7 @@ }, { "source": "/(how-arbitrum-works/geth-at-the-core/?)", - "destination": "/how-arbitrum-works/deep-dives/stf-gentle-intro", + "destination": "/how-arbitrum-works/deep-dives/stf", "permanent": false }, { @@ -1279,7 +1284,7 @@ }, { "source": "/(how-arbitrum-works/state-transition-function/stf-gentle-intro/?)", - "destination": "/how-arbitrum-works/deep-dives/stf-gentle-intro", + "destination": "/how-arbitrum-works/deep-dives/stf", "permanent": false }, {