From 513b2b85c9846a564c8ecb370bbdceecd63aae68 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 24 Sep 2024 18:44:46 -0700 Subject: [PATCH 01/29] feat: add early version of AEP's overview --- .../aep-fee-router-introduction.mdx | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) create mode 100644 arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx diff --git a/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx new file mode 100644 index 000000000..d67025703 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx @@ -0,0 +1,52 @@ +--- +title: 'The AEP fee router: introduction' +sidebar_label: 'AEP fee router' +description: 'Learn what is the AEP fee router.' +author: Midroni +sme: Midroni +user_story: As a current Orbit chain owner, I need to understand what the AEP fee router is. +content_type: get-started +--- + +import { MermaidWithHtml, Nodes, Node, Connection, NodeDescriptions, NodeDescription } from '/src/components/MermaidWithHtml/MermaidWithHtml'; + +## What is the Arbitrum Expansion Program? + +The [Arbitrum Expansion Program](https://forum.arbitrum.foundation/t/the-arbitrum-expansion-program-and-developer-guild/20722) (AEP) allows Orbit chains to permissionlessly deploy on *any chain*. As part of the [AEP license](https://docs.arbitrum.foundation/assets/files/Arbitrum%20Expansion%20Program%20Jan182024-4f08b0c2cb476a55dc153380fa3e64b0.pdf), Orbit chains deployed outside of Arbitrum One and Arbitrum Nova must pay 10% of their **Net Protocol Revenue** to the Arbitrum DAO. + + + + + firstInput + secondInput + someFunction(firstInput, secondInput) + L1 Ethereum + + + + + + +The Arbitrum Expansion Program and Developer Guild are initiatives launched in collaboration with Offchain Labs to promote the development of customized Arbitrum chains using the Orbit framework. The Expansion Program simplifies the process for teams to create Layer 2 (L2) and Layer 3 (L3) blockchains, offering self-service tools and customization options. +Projects benefit from features like: +- Dedicated block space +- Custom gas tokens +- Flexible governance. + +These chains can settle to any chain relying on the Ethereum security model. + +The Developer Guild incentivizes developers contributing to the Arbitrum codebase, with 2% of revenue from new chains going to a fund dedicated to this purpose. The Expansion Program is designed to align with Ethereum, encourage innovation, and enable projects to tailor the Arbitrum stack to their specific needs. The program also aims to streamline chain deployment, making it easier for developers to adopt Arbitrum's technology while contributing back to the community + +As an Orbit chain owner, you may have the following questions: + +## How do I send my AEP fees from my Orbit chain to the Arbitrum DAO? +Arbitrum provides Orbit chains with easily deployable smart contracts that can streamline the transfer of AEP Fees into the Arbitrum DAO treasury. These contracts are known as **AEP Fee Routers**. +## What is Net Protocol Revenue? +Net Protocol Revenue is equivalent to an Orbit chain’s profit (revenue minus costs). +## How can I ensure I’m complying with the AEP license? +The Arbitrum Foundation will track compliance based on fees received through the **AEP Fee Router**. + + + + + From 628e4b163defd1ed00cf86c6a9f47446ce27689b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 24 Sep 2024 18:45:52 -0700 Subject: [PATCH 02/29] feat: add article to sidebars --- website/sidebars.js | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/website/sidebars.js b/website/sidebars.js index 10ab488c8..a0727650b 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -307,6 +307,11 @@ const sidebars = { id: 'launch-orbit-chain/how-tos/usdc-standard-bridge', label: `Implement Circle bridged USDC`, }, + { + type: 'doc', + id: 'launch-orbit-chain/aep-fee-router-introduction', + label: `AEP fee router`, + }, ], }, { From 617a490679ba390277d7afacfbb5e925a6d3c27a Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 27 Sep 2024 12:16:02 -0700 Subject: [PATCH 03/29] fix: re-format + fontmatter --- .../aep-fee-router-introduction.mdx | 19 +++---------------- 1 file changed, 3 insertions(+), 16 deletions(-) diff --git a/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx index d67025703..80d16de67 100644 --- a/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx +++ b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx @@ -1,6 +1,6 @@ --- title: 'The AEP fee router: introduction' -sidebar_label: 'AEP fee router' +sidebar_label: 'AEP fee router: overview' description: 'Learn what is the AEP fee router.' author: Midroni sme: Midroni @@ -8,25 +8,11 @@ user_story: As a current Orbit chain owner, I need to understand what the AEP fe content_type: get-started --- -import { MermaidWithHtml, Nodes, Node, Connection, NodeDescriptions, NodeDescription } from '/src/components/MermaidWithHtml/MermaidWithHtml'; - ## What is the Arbitrum Expansion Program? The [Arbitrum Expansion Program](https://forum.arbitrum.foundation/t/the-arbitrum-expansion-program-and-developer-guild/20722) (AEP) allows Orbit chains to permissionlessly deploy on *any chain*. As part of the [AEP license](https://docs.arbitrum.foundation/assets/files/Arbitrum%20Expansion%20Program%20Jan182024-4f08b0c2cb476a55dc153380fa3e64b0.pdf), Orbit chains deployed outside of Arbitrum One and Arbitrum Nova must pay 10% of their **Net Protocol Revenue** to the Arbitrum DAO. - - - firstInput - secondInput - someFunction(firstInput, secondInput) - L1 Ethereum - - - - - - The Arbitrum Expansion Program and Developer Guild are initiatives launched in collaboration with Offchain Labs to promote the development of customized Arbitrum chains using the Orbit framework. The Expansion Program simplifies the process for teams to create Layer 2 (L2) and Layer 3 (L3) blockchains, offering self-service tools and customization options. Projects benefit from features like: - Dedicated block space @@ -46,7 +32,8 @@ Net Protocol Revenue is equivalent to an Orbit chain’s profit (revenue minus c ## How can I ensure I’m complying with the AEP license? The Arbitrum Foundation will track compliance based on fees received through the **AEP Fee Router**. - +## How can I setup and AEP fee router on my Orbit chain? +You can learn how to setup your AEP fee router in [implementation guide](launch-orbit-chain/how-tos/set-up-aep-fee-router). From 20ec2c42f2657392e03b8deed9d6a7705da837c6 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 27 Sep 2024 12:16:36 -0700 Subject: [PATCH 04/29] feat: add aep fee router set up article --- .../how-tos/set-up-aep-fee-router.mdx | 113 ++++++++++++++++++ 1 file changed, 113 insertions(+) create mode 100644 arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx new file mode 100644 index 000000000..85b9fdae9 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx @@ -0,0 +1,113 @@ +--- +title: 'How to set up an AEP fee router' +sidebar_label: 'Set up an AEP fee router' +description: 'Learn how to implement AEP fee router.' +author: Midroni +sme: Midroni +user_story: As a current Orbit chain owner, I need to learn how to set up an AEP fee router. +content_type: how-to +--- + + +# AEP fee router implementation + +## Quick start + +- You can adopt the AEP Fee Router by using the [AEP Router deployment scripts](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router) provided in the [Orbit SDK](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main) + +### Canonical Contracts + +| Network | Contract | Address | Configured For | +|---------------|----------------------|------------------------------------------------------------------------------------------------------------------------------------------------------------|----------------| +| Ethereum | `Parent2ChildRouter` | [https://etherscan.io/address/0x40Cd7D713D7ae463f95cE5d342Ea6E7F5cF7C999](https://etherscan.io/address/0x40Cd7D713D7ae463f95cE5d342Ea6E7F5cF7C999) | `ETH`, `ERC-20` | +| Arbitrum Nova | `Child2ParentRouter` | [https://nova.arbiscan.io/address/0x36D0170D92F66e8949eB276C3AC4FEA64f83704d](https://nova.arbiscan.io/address/0x36D0170D92F66e8949eB276C3AC4FEA64f83704d) | `ETH` | + +## The AEP fee router contract system + +### `RewardDistributor` + +The **AEP fee router** system relies on configuring an escrow contract as the intended rewards address for protocol fee components. This intermediary contract is known as the `RewardDistributor`. + +The `RewardDistributor` is configured to separate the AEP portion of the fees from fees intended for the chain owner. The `RewardDistributor` can be permissionlessly called to perform a withdrawal which simultaneously transfers 90% of accrued fees to the chain’s fee collector and 10% of accrued fees to a routing contract on the parent chain. From here, the chain owner has complete control over their earned fees, and the routing contracts can direct AEP fees to a collecting address for the Arbitrum DAO. + +### `ChildToParentRouter` + +AEP fees from the `RewardDistributor` must first be sent to Ethereum before they can be deposited to the DAO-controlled address on Arbitrum One. To facilitate this transfer to Ethereum, AEP fees are sent through a series of contracts known as `ChildToParentRouters`. + +The `ChildToParentRouter` is configured to withdraw a single token (immutable, and specified at deployment) from the child chain to a specific target address on the parent chain (either another ChildToParentRouter or the ParentToChildRouter on Ethereum) + +### `ParentToChildRouter` + +All AEP fees from the network of Orbit chains will arrive at the `ParentToChildRouter` on Ethereum. This contract is capable of sending ETH and arbitrary ERC-20 tokens to a DAO-controlled address on Arbitrum one + +## Deploying your AEP fee router contracts + +An Orbit chain is responsible for deploying all `ChildToParentRouters` necessary for their AEP funds to arrive at the `ParentToChildRouter` on Ethereum. This includes: + +- Deploying a `ChildToParentRouter` on their Orbit chain configured for their gas token and configured to send funds to either: + - The `ParentToChildRouter` on Ethereum (assuming the network is a Layer-2) + - Another `ChildToParentRouter` configured to the same gas token and configured to send funds to a successive parent chain (this is the case for an Layer-3 networks or higher) +- Deploying a `RewardDistributor` contract that is configured to forward 10% of fees to the `ChildToParentRouter` and 90% of fees to the chain owner’s preferred reward-receiving address. + +In the event that a `ChildToParentRouter` does not connect to the `ParentToChildRouter` on Ethereum, an Orbit chain must deploy successive `ChildToParentRouter` contracts until a connection to `ParentToChildRouter` is established. + +And optionally, an Orbit chain can decide to deduct assertion costs by following the instructions in the [Deducting Assertion Costs](https://www.notion.so/AEP-Fee-Router-DOCS-4fe72e869dbf47338a1b2d0c084cdfbd?pvs=21) section: + + + +## Deployment scripts + +The Orbit SDK provides a [configurable script](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router) that allows a chain operator to quickly deploy and setup the AEP fee router contracts. + + + +The script performs the following operations: + +1. Obtain the rollup and inbox contract of the chain. These are needed to execute the next steps. +2. Obtain the current fee collectors of the chain: Orbit base fee collector, Orbit surplus fee collector, Parent chain surplus fee collector. +3. Deploy the ChildToParentRouter contract, configured to send the amounts received to the appropriate Arbitrum DAO controlled address on the parent chain. +4. Deploy a RewardDistributor contract for each different fee collector account, configured to distribute 90% of the amounts received to the current fee collector, and 10% to the ChildToParentRouter contract deployed in the previous step. +5. Set each of the fee collectors to the RewardDistributor contracts + + + +To configure the script, you need to specify the following [environment variables](https://github.com/OffchainLabs/arbitrum-orbit-sdk/blob/main/examples/setup-aep-fee-router/.env.example): + +- `ROLLUP_ADDRESS`: address of the Rollup contract +- `CHAIN_OWNER_PRIVATE_KEY`: private key of the account with executor privileges in the `UpgradeExecutor` admin contract for the chain +- `ORBIT_CHAIN_ID`: `chainId` of the Orbit chain +- `ORBIT_CHAIN_RPC`: RPC of the Orbit chain +- `PARENT_CHAIN_ID`: `chainId` of the parent chain (should be a non-Arbitrum chain, including Ethereum) +- `PARENT_CHAIN_TARGET_ADDRESS`: address on the parent chain where 10% of the revenue will be sent to. You can find the potential target addresses in the [Canonical contracts](https://www.notion.so/AEP-Fee-Router-DOCS-4fe72e869dbf47338a1b2d0c084cdfbd?pvs=21) section of this document. If the parent chain your chain settles to is not in that list, contact the Arbitrum Foundation to obtain a specific target address for your chain. + +Finally, follow these steps to execute the script (from the `examples/setup-aep-fee-router` folder): + +1. Install dependencies + +```shell +yarn install +``` + +2. Create .env file and add the env vars + +```shell +cp .env.example .env +``` + +3. Run the script + +```shell +yarn dev +``` + From 3d5b306aa2780ee140d2360c78fad8f1170a1091 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 27 Sep 2024 12:16:54 -0700 Subject: [PATCH 05/29] feat: add aep fee/revenue calculation article --- .../how-tos/calculate-aep-fees.mdx | 96 +++++++++++++++++++ 1 file changed, 96 insertions(+) create mode 100644 arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx new file mode 100644 index 000000000..4f1afacdc --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx @@ -0,0 +1,96 @@ +--- +title: 'Calculating AEP license fees' +sidebar_label: 'Calculating AEP license fees' +description: 'Learn how to calculate your Orbit chains revenue and license fees.' +author: Midroni +sme: Midroni +user_story: As a current Orbit chain owner, I need to understand how my Orbit chain revenue and AEP license fees are calculated. +content_type: how-to +--- + +Before we define “Protocol Net Revenue” let's explain how fees work on a standard Orbit chain. From there we can connect how each fee equates to a revenue or a cost. + +### Sequencing revenue + +In a vanilla Orbit chain (a chain without customizations, transaction ordering policies, or other add-ons), users and dApps will pay a single gas fee for submitting their transaction. Under the hood, however, a user’s fee is allocated across four components used by the network in different ways. These four fee components are split as follows: + +- `l2BaseFee`: fees paid to execute a transaction on the Orbit chain. +- `l2SurplusFee`: surplus fees are charged in addition to the base fee when an Orbit chain is congested. +- `l1BaseFee`: fees paid to cover the cost of an Orbit chain posting its settlement transaction to the parent chain. +- `l1SurplusFee`: an additional surplus fee that can be configured to award extra fees to the batch poster. + +Based on the above, we interpret that an Orbit chain’s revenue sources include all fee components: `l2BaseFee`, `l2SurplusFee`, `l1BaseFee`, and `l1SurplusFee`. However one of these fee components is also a cost: `l1BaseFee`, as it is used to pay for parent chain settlement. + +### Assertion costs + +The above fee system applies to an Orbit chain’s Sequencer and Batch Poster, but there is another important actor that is considered essential to the chain. These are the [**validators](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#validators).** + +Validators are responsible for posting assertions on the parent chain, which are disputable claims about the new state of the rollup. Posting an assertion is what progressed chain state on the parent chain. Validators are also responsible for securing the chain by creating disputes on false assertions. + +As validators are necessary for chain security and chain progression, the gas costs paid by validators are a cost under the AEP license. + +The AEP license permits an Orbit chain deduct the gas costs of assertion posting and confirming **only for validators operated by the chain owner**. The AEP Fee Router does not deduct assertion costs from its fees. In a later section, we will explain how assertion costs can be optionally deducted by chain owners. + +### Additional revenue sources + +As the Orbit license allows for chain owners to customize their rollup, the AEP license accounts for revenue sources that could arise out of innovations. As such, it’s worth noting that the total calculation of revenue will also include: + +- Revenue from transaction ordering policies. +- Revenue earned through fees on top of the bridge. +- Broadly, any revenue earned in connection your use of Arbitrum Nitro. + +You can read the relevant legal terminology in Section 2 of the [AEP Terms](https://docs.arbitrum.foundation/assets/files/Arbitrum%20Expansion%20Program%20Jan182024-4f08b0c2cb476a55dc153380fa3e64b0.pdf). + +## Calculating AEP fees + +We are now in a place where we can precisely define AEP fees. An Orbit chain’s obligation for AEP license are 10% of a chain’s **Net Protocol Revenue**. Net Protocol Revenue is broadly the difference between (i) gross revenue and (ii) settlement costs. + +Based on our understanding above, we can calculate AEP fees as follows. + +```jsx +AEP_FEES = [(gross revenue) - (settlement costs)]*0.1 +AEP_FEES = [(sequencing revenue + additional revenue) - (settlement costs + assertion costs)]*0.1 +AEP_FEES = [(l2BaseFee + l2SurplusFee + l1BaseFee + l1SurplusFee) - (l1BaseFee + assertion costs)]*0.1 +``` + +## Opting in for assertion cost deduction + +The AEP Fee Router **does not deduct** **assertion costs** from the fees it routes. This is because the contract system is not able to track the amount of gas validators spend and it cannot determine the eligibility of a validator. + +As such, Orbit chains to optionally elect to deduct these costs from the fee stream, but this will require Orbit chains to self-report assertion costs and implement an intermediary multisig that sits before the AEP Fee Router system. + +Instructions for doing so can be found below. + +### Eligible validators + +Only validators that are directly associated with the Orbit chain owner are eligible for assertion cost deductions. By directly associated, we mean a validator that is operated by the team directly or contract by an external provider (e.g. a Rollup-as-a-Service team) to act as a validator on behalf of the team. In the event of a contracted validator, only one validator can be eligible. + +### Eligible costs + +The following costs can be deducted for an eligible validator: + +1. The cost of posting assertions +2. The cost of confirming assertions +3. The cost of participating in fraud proofs + +### Deducting assertion costs + +If a team elects to deduct their assertion posting costs from eligible validators, they must establish and obey the following process: + +- Communicate with the AFArbitrum Foundation that they intend to deduct on-chain assertion costs + - Align on a cadence of disbursal and accounting these costs with the AFArbitrum Foundation (e.g. quarterly, annually) + - At this cadence, Provide on-chain accounting to the Arbitrum Foundation to substantiate deducted costs from the AEP Fee Router stream. + +To implement the deduction, the team should do the following: + +- [Configure all Orbit chain fee components](https://docs.arbitrum.io/launch-orbit-chain/how-tos/manage-fee-collectors#how-to-configure-the-fee-collector-addresses) to send all fees to a secure multisig address. + - For ease of accounting it’s strongly recommended that this multisig handle no funds other than the rewards earned from the protocol. +- On the established regular cadence (e.g. quarterly) deduct *all eligible assertion gas cost* from the multisig’s balance by transferring it to your preferred fee-collecting address. The remainder of the amount must be forwarded to the `RewardDistributor` contract (configured as directed previously) +- Following this, the `RewardDistributor` will split the post-deduction funds between the **AEP Fee Router** contracts and the configured chain-owner controlled addresses. + +## Special cases and exceptions + +- L2-based Custom Gas Token = pay in ETH + - Requires a similar multisig set up as above +- Non-Ethereum L1 +- Identifying customizations and reporting additional revenue sources From fe70a5f0486d99537ac3e1f2326230c853bbdf9b Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Fri, 27 Sep 2024 12:17:30 -0700 Subject: [PATCH 06/29] feat: add all 3 aep fee router articles to sidebar --- website/sidebars.js | 12 +++++++++++- 1 file changed, 11 insertions(+), 1 deletion(-) diff --git a/website/sidebars.js b/website/sidebars.js index a0727650b..6f726267a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -310,7 +310,17 @@ const sidebars = { { type: 'doc', id: 'launch-orbit-chain/aep-fee-router-introduction', - label: `AEP fee router`, + label: `AEP fee router overview`, + }, + { + type: 'doc', + id: 'launch-orbit-chain/how-tos/set-up-aep-fee-router', + label: `Set up AEP fee router`, + }, + { + type: 'doc', + id: 'launch-orbit-chain/how-tos/calculate-aep-fees', + label: `Calculate AEP license fees`, }, ], }, From 392440875a02e48eaa4d33a58f57fcfbba2ac3e3 Mon Sep 17 00:00:00 2001 From: Cooper Midroni <34783043+Midroni@users.noreply.github.com> Date: Mon, 30 Sep 2024 12:14:23 -0400 Subject: [PATCH 07/29] Update calculate-aep-fees.mdx added better descriptions for edge cases --- .../launch-orbit-chain/how-tos/calculate-aep-fees.mdx | 9 +++++---- 1 file changed, 5 insertions(+), 4 deletions(-) diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx index 4f1afacdc..3fcaf8d0f 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx @@ -89,8 +89,9 @@ To implement the deduction, the team should do the following: - Following this, the `RewardDistributor` will split the post-deduction funds between the **AEP Fee Router** contracts and the configured chain-owner controlled addresses. ## Special cases and exceptions +Certain Orbit configurations and customizations require special handling of AEP fees. The following is a non-exhaustive list of applicable scenarios and how to ensure AEP compliance. If any of the following cases apply, the recommended approach for fee handling will require manual handling of a portion of or all AEP Fees. -- L2-based Custom Gas Token = pay in ETH - - Requires a similar multisig set up as above -- Non-Ethereum L1 -- Identifying customizations and reporting additional revenue sources +- L2-Based Custom Gas Tokens: If you are an L3 or higher chain with a custom gas token, it may be the case that your custom gas token contract is deployed on L2. If this L2 is not Arbitrum One, then it is possible for the L2 token to be transferred via the AEP Fee Router, as this would first require bridging down to Ethereum (impossible for L2-based tokens). In this instance, we recommend your chain pay fees in ETH by manually sending fees to an ETH-configured routing system. +- Non-Ethereum L1: If your Orbit chain is deployed on a non-Ethereum L1 (e.g. Solana, BNB Chain) your fees must be manually transferred to a DAO-controlled address. +- Novel Fee-Earning Customizations: As discussed above in Additional revenue sources, if you have customized your Orbit chain to earn revenue through any enshrined component, this revenue must be calculated as part of the AEP fees. In such cases, we recommend engaging with the AF to agree on a revenue model and reporting cadence, and then manually send additional fees into the routing system as required. +- Other: If you are uncertain if your Orbit configuration applies to the listed or unlisted special cases, we recommend engaging with the Arbitrum Foundation. From 573310fb1b1585d80431dc4f2e793febc2066928 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 1 Oct 2024 13:47:35 -0400 Subject: [PATCH 08/29] fix: format/syntax/grammar --- .../how-tos/calculate-aep-fees.mdx | 26 ++++++++++++------- 1 file changed, 16 insertions(+), 10 deletions(-) diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx index 3fcaf8d0f..3c2e4dc9e 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx @@ -8,11 +8,13 @@ user_story: As a current Orbit chain owner, I need to understand how my Orbit ch content_type: how-to --- +This document will run you through how to calculate your Orbit chain’s _Protocol Net Revenue_ and AEP license fees. + Before we define “Protocol Net Revenue” let's explain how fees work on a standard Orbit chain. From there we can connect how each fee equates to a revenue or a cost. ### Sequencing revenue -In a vanilla Orbit chain (a chain without customizations, transaction ordering policies, or other add-ons), users and dApps will pay a single gas fee for submitting their transaction. Under the hood, however, a user’s fee is allocated across four components used by the network in different ways. These four fee components are split as follows: +In a vanilla Orbit chain (a chain without customizations, transaction ordering policies, or other add-ons), users and dApps will pay a single gas fee to submit their transaction. Under the hood, however, a user’s fee is allocated across four components used by the network in different ways. These four fee components are split as follows: - `l2BaseFee`: fees paid to execute a transaction on the Orbit chain. - `l2SurplusFee`: surplus fees are charged in addition to the base fee when an Orbit chain is congested. @@ -25,7 +27,7 @@ Based on the above, we interpret that an Orbit chain’s revenue sources include The above fee system applies to an Orbit chain’s Sequencer and Batch Poster, but there is another important actor that is considered essential to the chain. These are the [**validators](https://docs.arbitrum.io/how-arbitrum-works/inside-arbitrum-nitro#validators).** -Validators are responsible for posting assertions on the parent chain, which are disputable claims about the new state of the rollup. Posting an assertion is what progressed chain state on the parent chain. Validators are also responsible for securing the chain by creating disputes on false assertions. +Validators are responsible for posting assertions on the parent chain, which are disputable claims about the new state of the Rollup. Posting an assertion is what progressed chain state on the parent chain. Validators are also responsible for securing the chain by creating disputes on false assertions. As validators are necessary for chain security and chain progression, the gas costs paid by validators are a cost under the AEP license. @@ -33,7 +35,7 @@ The AEP license permits an Orbit chain deduct the gas costs of assertion posting ### Additional revenue sources -As the Orbit license allows for chain owners to customize their rollup, the AEP license accounts for revenue sources that could arise out of innovations. As such, it’s worth noting that the total calculation of revenue will also include: +As the Orbit license allows chain owners to customize their Rollup, the AEP license accounts for revenue sources that could arise out of innovations. As such, it’s worth noting that the total calculation of revenue will also include: - Revenue from transaction ordering policies. - Revenue earned through fees on top of the bridge. @@ -57,7 +59,7 @@ AEP_FEES = [(l2BaseFee + l2SurplusFee + l1BaseFee + l1SurplusFee) - (l1BaseFee + The AEP Fee Router **does not deduct** **assertion costs** from the fees it routes. This is because the contract system is not able to track the amount of gas validators spend and it cannot determine the eligibility of a validator. -As such, Orbit chains to optionally elect to deduct these costs from the fee stream, but this will require Orbit chains to self-report assertion costs and implement an intermediary multisig that sits before the AEP Fee Router system. +As such, Orbit chains can choose to deduct these costs from their fee stream, but this will require Orbit chains to self-report assertion costs and implement an intermediary multisig that sits before the AEP Fee Router system. Instructions for doing so can be found below. @@ -77,8 +79,8 @@ The following costs can be deducted for an eligible validator: If a team elects to deduct their assertion posting costs from eligible validators, they must establish and obey the following process: -- Communicate with the AFArbitrum Foundation that they intend to deduct on-chain assertion costs - - Align on a cadence of disbursal and accounting these costs with the AFArbitrum Foundation (e.g. quarterly, annually) +- Communicate to the Arbitrum Foundation that they intend to deduct on-chain assertion costs + - Align on a cadence of disbursal and accounting these costs with the Arbitrum Foundation (e.g. quarterly, annually) - At this cadence, Provide on-chain accounting to the Arbitrum Foundation to substantiate deducted costs from the AEP Fee Router stream. To implement the deduction, the team should do the following: @@ -91,7 +93,11 @@ To implement the deduction, the team should do the following: ## Special cases and exceptions Certain Orbit configurations and customizations require special handling of AEP fees. The following is a non-exhaustive list of applicable scenarios and how to ensure AEP compliance. If any of the following cases apply, the recommended approach for fee handling will require manual handling of a portion of or all AEP Fees. -- L2-Based Custom Gas Tokens: If you are an L3 or higher chain with a custom gas token, it may be the case that your custom gas token contract is deployed on L2. If this L2 is not Arbitrum One, then it is possible for the L2 token to be transferred via the AEP Fee Router, as this would first require bridging down to Ethereum (impossible for L2-based tokens). In this instance, we recommend your chain pay fees in ETH by manually sending fees to an ETH-configured routing system. -- Non-Ethereum L1: If your Orbit chain is deployed on a non-Ethereum L1 (e.g. Solana, BNB Chain) your fees must be manually transferred to a DAO-controlled address. -- Novel Fee-Earning Customizations: As discussed above in Additional revenue sources, if you have customized your Orbit chain to earn revenue through any enshrined component, this revenue must be calculated as part of the AEP fees. In such cases, we recommend engaging with the AF to agree on a revenue model and reporting cadence, and then manually send additional fees into the routing system as required. -- Other: If you are uncertain if your Orbit configuration applies to the listed or unlisted special cases, we recommend engaging with the Arbitrum Foundation. +### L2-Based Custom Gas Tokens +If you are an L3 or higher chain with a custom gas token, your custom gas token contract might be deployed on L2. If this L2 is not Arbitrum One, then it is possible for the L2 token to be transferred via the AEP Fee Router, as this would first require bridging down to Ethereum (impossible for L2-based tokens). In this instance, we recommend your chain pay fees in ETH by manually sending fees to an ETH-configured routing system. +### Non-Ethereum L1 +If your Orbit chain is deployed on a non-Ethereum L1 (e.g. Solana, BNB Chain) your fees must be manually transferred to a DAO-controlled address. +### Novel Fee-Earning Customizations +As discussed above in Additional revenue sources, if you have customized your Orbit chain to earn revenue through any enshrined component, this revenue must be calculated as part of the AEP fees. In such cases, we recommend engaging with the AF to agree on a revenue model and reporting cadence, and then manually send additional fees into the routing system as required. +### Other cases +If you are uncertain if your Orbit configuration applies to the listed or unlisted special cases, we recommend engaging with the Arbitrum Foundation. From 650e8d20acfe53f2c1b7e076070c1bf3f0592beb Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ga=C3=ABl=20Blanchemain?= Date: Tue, 1 Oct 2024 13:48:00 -0400 Subject: [PATCH 09/29] fix: format/syntax/grammar --- .../how-tos/set-up-aep-fee-router.mdx | 37 +++++++++++-------- 1 file changed, 21 insertions(+), 16 deletions(-) diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx index 85b9fdae9..57a579aad 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/set-up-aep-fee-router.mdx @@ -8,7 +8,6 @@ user_story: As a current Orbit chain owner, I need to learn how to set up an AEP content_type: how-to --- - # AEP fee router implementation ## Quick start @@ -24,25 +23,31 @@ content_type: how-to ## The AEP fee router contract system -### `RewardDistributor` +_Link to the [Router contracts' source code](https://github.com/OffchainLabs/fund-distribution-contracts/tree/main/src/FeeRouter)._ + +### RewardDistributor The **AEP fee router** system relies on configuring an escrow contract as the intended rewards address for protocol fee components. This intermediary contract is known as the `RewardDistributor`. The `RewardDistributor` is configured to separate the AEP portion of the fees from fees intended for the chain owner. The `RewardDistributor` can be permissionlessly called to perform a withdrawal which simultaneously transfers 90% of accrued fees to the chain’s fee collector and 10% of accrued fees to a routing contract on the parent chain. From here, the chain owner has complete control over their earned fees, and the routing contracts can direct AEP fees to a collecting address for the Arbitrum DAO. -### `ChildToParentRouter` + +### ChildToParentRouter AEP fees from the `RewardDistributor` must first be sent to Ethereum before they can be deposited to the DAO-controlled address on Arbitrum One. To facilitate this transfer to Ethereum, AEP fees are sent through a series of contracts known as `ChildToParentRouters`. -The `ChildToParentRouter` is configured to withdraw a single token (immutable, and specified at deployment) from the child chain to a specific target address on the parent chain (either another ChildToParentRouter or the ParentToChildRouter on Ethereum) +The `ChildToParentRouter` is configured to withdraw a single token (immutable, and specified at deployment) from the child chain to a specific target address on the parent chain: either another `ChildToParentRouter` or the `ParentToChildRouter` on Ethereum. -### `ParentToChildRouter` +### ParentToChildRouter All AEP fees from the network of Orbit chains will arrive at the `ParentToChildRouter` on Ethereum. This contract is capable of sending ETH and arbitrary ERC-20 tokens to a DAO-controlled address on Arbitrum one + ## Deploying your AEP fee router contracts -An Orbit chain is responsible for deploying all `ChildToParentRouters` necessary for their AEP funds to arrive at the `ParentToChildRouter` on Ethereum. This includes: +An Orbit chain is responsible for deploying all `ChildToParentRouters` necessary for their AEP funds to arrive at the `ParentToChildRouter` on Ethereum. + +This includes: - Deploying a `ChildToParentRouter` on their Orbit chain configured for their gas token and configured to send funds to either: - The `ParentToChildRouter` on Ethereum (assuming the network is a Layer-2) @@ -50,14 +55,13 @@ An Orbit chain is responsible for deploying all `ChildToParentRouters` necessary - Deploying a `RewardDistributor` contract that is configured to forward 10% of fees to the `ChildToParentRouter` and 90% of fees to the chain owner’s preferred reward-receiving address. In the event that a `ChildToParentRouter` does not connect to the `ParentToChildRouter` on Ethereum, an Orbit chain must deploy successive `ChildToParentRouter` contracts until a connection to `ParentToChildRouter` is established. - -And optionally, an Orbit chain can decide to deduct assertion costs by following the instructions in the [Deducting Assertion Costs](https://www.notion.so/AEP-Fee-Router-DOCS-4fe72e869dbf47338a1b2d0c084cdfbd?pvs=21) section: + +And optionally, an Orbit chain can decide to deduct assertion costs by following the instructions in the [Deducting Assertion Costs](/launch-orbit-chain/how-tos/calculate-aep-fees#assertion-costs) section: ## Deployment scripts @@ -65,17 +69,17 @@ In the absence of these, please send ETH through the AEP Fee Router to fulfill y The Orbit SDK provides a [configurable script](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/setup-aep-fee-router) that allows a chain operator to quickly deploy and setup the AEP fee router contracts. The script performs the following operations: -1. Obtain the rollup and inbox contract of the chain. These are needed to execute the next steps. +1. Obtain the Rollup and inbox contract of the chain. These are needed to execute the next steps. 2. Obtain the current fee collectors of the chain: Orbit base fee collector, Orbit surplus fee collector, Parent chain surplus fee collector. -3. Deploy the ChildToParentRouter contract, configured to send the amounts received to the appropriate Arbitrum DAO controlled address on the parent chain. -4. Deploy a RewardDistributor contract for each different fee collector account, configured to distribute 90% of the amounts received to the current fee collector, and 10% to the ChildToParentRouter contract deployed in the previous step. -5. Set each of the fee collectors to the RewardDistributor contracts +3. Deploy the `ChildToParentRouter` contract, configured to send the amounts received to the appropriate Arbitrum DAO controlled address on the parent chain. +4. Deploy a `RewardDistributor` contract for each different fee collector account, configured to distribute 90% of the amounts received to the current fee collector, and 10% to the ChildToParentRouter contract deployed in the previous step. +5. Set each of the fee collectors to the `RewardDistributor` contracts