P5 Priority fees page (TW-740)

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 ArbOS61 'Elara', and the additional requirements for tip-based transaction ordering."
+content_type: concept
+author: 'gaelblanchemain'
+sme: 'vbridge-hash'
+---
+
+ArbOS61 ("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.
+
+<VanillaAdmonition type="caution" title="Activation requires a separate Constitutional vote">
+
+For Arbitrum One and Nova, enabling this feature requires an **additional Constitutional DAO vote** — it isn't activated as part of the ArbOS61 upgrade itself. The upgrade only makes tip collection *possible* for chains that opt in.
+
+</VanillaAdmonition>
+
+## 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: ArbOS61 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)

sidebars.js

@@ -301,6 +301,41 @@ const sidebars = {
                   label: `DAC defaults`,
                 },
                 {
+                  type: 'category',
+                  label: 'Gas',
+                  collapsed: true,
+                  items: [
+                    {
+                      type: 'doc',
+                      id: 'launch-arbitrum-chain/configure-your-chain/common/gas/use-a-custom-gas-token-anytrust',
+                      label: `AnyTrust custom gas token`,
+                    },
+                    {
+                      type: 'doc',
+                      id: 'launch-arbitrum-chain/configure-your-chain/common/gas/use-a-custom-gas-token-rollup',
+                      label: `Rollup custom gas token`,
+                    },
+                    {
+                      type: 'doc',
+                      id: 'launch-arbitrum-chain/configure-your-chain/common/gas/configure-native-mint-burn-gas-token',
+                      label: 'Native mint/burn gas token',
+                    },
+                    {
+                      type: 'doc',
+                      id: 'launch-arbitrum-chain/configure-your-chain/common/gas/gas-optimization-tools',
+                      label: `Gas optimization tools`,
+                    },
+                    {
+                      type: 'doc',
+                      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',
+                    },
+                  ],
                   type: 'doc',
                   id: 'launch-arbitrum-chain/chain-config/data-availability/configure-dac',
                   label: `DAC how-to`,