diff --git a/docs/launch-arbitrum-chain/02-configure-your-chain/common/gas/priority-fees.mdx b/docs/launch-arbitrum-chain/02-configure-your-chain/common/gas/priority-fees.mdx new file mode 100644 index 0000000000..34e50959eb --- /dev/null +++ b/docs/launch-arbitrum-chain/02-configure-your-chain/common/gas/priority-fees.mdx @@ -0,0 +1,61 @@ +--- +title: 'Priority fees collection' +sidebar_label: 'Priority fees' +description: "How to enable priority-fee (tip) collection on an Arbitrum chain in ArbOS 60 'Elara', and the additional requirements for tip-based transaction ordering." +content_type: concept +author: 'gaelblanchemain' +sme: 'vbridge-hash' +--- + +ArbOS 60 ("Elara") introduces the **capability** for chain owners to collect priority fees (tips) on their Arbitrum chain. The feature ships disabled, and a chain owner can enable it through a deliberate, two-step action. + + + +For Arbitrum One and Nova, enabling this feature requires an **additional Constitutional DAO vote** — it isn't activated as part of the ArbOS 60 upgrade itself. The upgrade only makes tip collection *possible* for chains that opt in. + + + +## How to enable tip collection + +The chain owner calls the [`ArbOwner` precompile](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) at `0x0000000000000000000000000000000000000070`: + +```solidity +// Enable tip collection +IArbOwner(address(0x70)).setCollectTips(true); + +// Disable it again +IArbOwner(address(0x70)).setCollectTips(false); + +// Read the current state +bool collecting = IArbOwner(address(0x70)).getCollectTips(); +``` + +`ArbOwner` is access-controlled — only the chain owner (typically the DAO or a designated operator address) can call these methods. The implementation is in [`precompiles/ArbOwner.go`](https://github.com/OffchainLabs/nitro/blob/6dce8d13902649a1acdfd3f2504129f1f5612358/precompiles/ArbOwner.go#L666). + +## How tips are collected + +Once enabled, any `priorityFee` (EIP-1559 `maxPriorityFeePerGas`) included in a transaction is collected the same way all other gas fees are, and routed into an onchain account. No separate infrastructure is needed. + +## Activation and receipt timing + +If tip-paying transactions land in the same block but **before** the transaction that enables fee collection, tips aren't collected from those earlier transactions — but their receipts will report tips as if they were. This is a known issue. + +To avoid it, the chain owner can either: + +- enable tip collection inside a delayed transaction, or +- ensure the enabling transaction is the first (or only) transaction in its block. + +## Tip-based transaction ordering + +Enabling collection alone does **not** change how transactions are ordered. For priority fees to actually influence sequencing, the chain needs **both**: + +1. **`setCollectTips(true)`** — activates fee collection via `ArbOwner`. +2. **Updated sequencer logic** — the sequencer must be configured to read the `PriorityFee` field when sorting transactions. + +Without step 2, the sequencer continues to use its existing ordering rules (such as [Timeboost](/how-arbitrum-works/timeboost/gentle-introduction.mdx)) regardless of the priority fee attached to a transaction. + +## References + +- [Constitutional AIP: ArbOS 60 Elara — Priority fees](https://forum.arbitrum.foundation/t/constitutional-aip-arbos-60-elara/30601) +- [`ArbOwner` precompile reference](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) +- [`setCollectTips` source](https://github.com/OffchainLabs/nitro/blob/6dce8d13902649a1acdfd3f2504129f1f5612358/precompiles/ArbOwner.go#L666) diff --git a/sidebars.js b/sidebars.js index bc4cc21172..e30fab6210 100644 --- a/sidebars.js +++ b/sidebars.js @@ -430,6 +430,11 @@ const sidebars = { id: 'launch-arbitrum-chain/configure-your-chain/common/gas/dynamic-pricing-for-arbitrum-chains', label: 'Dynamic Pricing for Arbitrum Chains', }, + { + type: 'doc', + id: 'launch-arbitrum-chain/configure-your-chain/common/gas/priority-fees', + label: 'Priority fees', + }, ], }, {