diff --git a/arbitrum-docs/audit-reports.mdx b/arbitrum-docs/audit-reports.mdx index abbda61f1..0f95ea07f 100644 --- a/arbitrum-docs/audit-reports.mdx +++ b/arbitrum-docs/audit-reports.mdx @@ -18,3 +18,4 @@ | **Trail of Bits** | 08/29/2024 | USDC Custom Gateway & ArbOS Timestamp Upgrade Action contract | [view](hosted-audit-reports/2024_08_29_trail_of_bits_security_audit_usdc_custom_gateway_and_arbos_upgrade_at_timestamp_action.pdf) | | **Trail of Bits** | 08/29/2024 | Orbit & Governance Upgrade Actions Contracts v2.1 | [view](hosted-audit-reports/2024_08_29_trail_of_bits_security_audit_orbit_and_governance_upgrade_actions_v2.1.pdf) | | **Open Zeppelin** | 09/05/2024 | Stylus Rust SDK | [view](hosted-audit-reports/2024_09_05_open_zeppelin_security_audit_stylus_rust_sdk.pdf) | +| **Trail of Bits** | 09/25/2024 | Timeboost Auction Contracts | [view](hosted-audit-reports/2024_09_25_trail_of_bits_security_audit_timeboost_auction_contracts.pdf) | \ No newline at end of file diff --git a/arbitrum-docs/hosted-audit-reports/2024_09_25_trail_of_bits_security_audit_timeboost_auction_contracts.pdf b/arbitrum-docs/hosted-audit-reports/2024_09_25_trail_of_bits_security_audit_timeboost_auction_contracts.pdf new file mode 100644 index 000000000..6808e5657 Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2024_09_25_trail_of_bits_security_audit_timeboost_auction_contracts.pdf differ diff --git a/arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.md b/arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.md index 46ae0b006..b5968e604 100644 --- a/arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.md +++ b/arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.md @@ -13,24 +13,23 @@ _The following document explains the economics and denial-of-service protection ## Background -[Arbitrum One](https://arbitrum.io/) is currently one of the most widely used Ethereum scaling solutions, with [~$18bn USD in total-value-locked](https://l2beat.com/scaling/projects/arbitrum) at the time of writing. Not only do its scaling properties, such as its 250ms block times, make it popular, but so do its security properties and approach to decentralization. Currently, Arbitrum One is governed by the Arbitrum DAO, one of the most active and robust on-chain organizations. +[Arbitrum One](https://arbitrum.io/) is currently one of the most widely used Ethereum scaling solutions, with [~$14bn USD in total-value-locked](https://l2beat.com/scaling/projects/arbitrum) at the time of writing. Not only do its scaling properties, such as its 250ms block times, make it popular, but so do its security properties and approach to decentralization. Currently, Arbitrum One is governed by the Arbitrum DAO, one of the most active and robust on-chain organizations. -However, Arbitrum has not yet achieved its [full promise of decentralization](https://docs.arbitrum.foundation/state-of-progressive-decentralization). Currently, withdrawals from Arbitrum One back to Ethereum are verified by a permissioned list of validators. These validators can still challenge invalid withdrawals, but the system prevents anyone outside this list from holding them accountable. This permissioned list of validators limits Arbitrum One and Arbitrum Nova to being categorized as a `Stage 1 Rollup` on the [L2Beat website](https://l2beat.com/scaling/summary), meaning it still has training wheels preventing it from reaching its full potential. +However, Arbitrum technology has not yet achieved its [full promise of being fully decentralized](https://docs.arbitrum.foundation/state-of-progressive-decentralization). Currently, withdrawals from Arbitrum One back to Ethereum are verified by a permissioned list of validators. These validators can still challenge invalid withdrawals, but the system prevents anyone outside this list from holding them accountable. This permissioned list of validators limits Arbitrum One and Arbitrum Nova to being categorized as a `Stage 1 Rollup` on the [L2Beat website](https://l2beat.com/scaling/summary), meaning it still has training wheels preventing it from reaching its full potential. -The rollup technology powering Arbitrum One is called "optimistic" because claims about its state settled to and confirmed on Ethereum after a period of approximately seven days. During those 7 days, the claimed states can be disputed. -To make an analogy, a check can be cashed immediately but can be taken to court to dispute if there is a problem within a specific time frame. Because Arbitrum's state is deterministic, a validator that is running a node and following the chain will always know if a posted claim is invalid. A key decentralization property allows **anyone** who knows the correct claim to challenge invalid claims and **_win_** the challenge. This preserves the accurate history of Arbitrum settling to Ethereum and protects the integrity of users' funds and withdrawals using a "single honest party" property. As long as there is a single entity following the chain and willing to dispute a claim, Arbitrum's security guarantees are maintained. +The rollup technology powering Arbitrum One is called "optimistic" because claims about its state settled to and confirmed on Ethereum after a period of approximately seven days. During those 7 days, the claimed states can be disputed. To make an analogy, a check can be cashed immediately but can be taken to court to dispute if there is a problem within a specific time frame. Because Arbitrum's state is deterministic, a validator that is running a node and following the chain will always know if a posted claim is invalid. A key decentralization property allows **anyone** who knows the correct claim to challenge invalid claims and **_win_** the challenge. This preserves the accurate history of Arbitrum settling to Ethereum and protects the integrity of users' funds and withdrawals using a "single honest party" property. As long as there is a single entity following the chain and willing to dispute a claim, Arbitrum's security guarantees are maintained. Today, Arbitrum One's security properties are defined by the size of its permissioned set of validators. Validators could collude or finalize/confirm an incorrect state, and users have no recourse aside from the Arbitrum One security council stepping in. Elevating Arbitrum One's decentralization requires a different approach. -In the Fall of 2023, Offchain Labs announced [Arbitrum BoLD](https://medium.com/offchainlabs/bold-permissionless-validation-for-arbitrum-chains-9934eb5328cc), a new dispute resolution protocol built from the ground up that will bring Arbitrum chains to the next level of decentralization. BoLD, which is an acryonym for **Bo**unded **L**iquidity **D**elay, allows permissionless validation of Arbitrum chains. This means that the Arbitrum DAO can remove the list of permissioned validators to allow anyone to challenge claims made about Arbitrum states on Ethereum and win those claims if they are correct. +In the Fall of 2023, Offchain Labs announced [Arbitrum BoLD](https://medium.com/offchainlabs/bold-permissionless-validation-for-arbitrum-chains-9934eb5328cc), a new dispute resolution protocol built from the ground up that will bring Arbitrum chains to the next level of decentralization. BoLD, which is an acryonym for **Bo**unded **L**iquidity **D**elay, allows permissionless validation of Arbitrum chains. This means that chain owners can remove the list of permissioned validators for their chains to allow anyone to challenge invalid claims made about Arbitrum states on their parent chain and win. In this document, we'll explore the economics and trade-offs enabling permissionless validation. ## Settling Arbitrum states to Ethereum -We frequently state that "Arbitrum settles its state to Ethereum", and we'll elaborate on what that means. All Arbitrum One transactions can be recreated by reading data from Ethereum L1, as compressed batches of all L2 transactions are frequently posted to Ethereum. Once a batched transaction is included in a finalized block on Ethereum, its history will never be reverted on Arbitrum. Ethereum, however, does not know if a batch posted to it refers to a correct version of Arbitrum's history. To verify batch integrity, there is a separate process that confirms batch correctness on Ethereum: it is called the "assertion." +We frequently state that "Arbitrum chains settles their states to a parent chain", and we'll elaborate on what that means. All Arbitrum One transactions can be recreated by reading data from Ethereum L1, as compressed batches of all L2 transactions are frequently posted to Ethereum. Once a batched transaction is included in a finalized block on Ethereum, its history will never be reverted on Arbitrum One. Ethereum, however, does not know if a batch posted to it refers to a correct version of Arbitrum One's history. To verify batch integrity, there is a separate process that confirms batch correctness on Ethereum: it is called the "assertion." -Approximately every hour, entities known as validators check the correctness of batches by following the Arbitrum chain. Validators then post something called an "assertion", which attests to the validity of a batch, saying, "I have verified this batch". As Ethereum does not know what is correct on Arbitrum, it allows about seven days for anyone to dispute one of these assertions. Currently, there is a permissioned list of validators who can post assertions and challenge assertions. Arbitrum BoLD will enable the Arbitrum DAO to remove this permissioned list. Note that validators who opt to posting assertions are otherwise known as a "assertion proposers". +For Arbitrum One specifically, approximately every hour, entities known as validators check the correctness of batches by following the Arbitrum chain. Validators then post something called an "assertion", which attests to the validity of a batch, saying, "I have verified this batch". As Ethereum does not know what is correct on Arbitrum One, it allows about seven days for anyone to dispute one of these assertions. Currently, there is a permissioned list of validators who can post assertions and challenge assertion for all Arbitrum chains. Arbitrum BoLD will enable any chain owner, such as the ArbitrumDAO, to remove this permissioned list. Note that validators who opt to posting assertions are otherwise known as a "assertion proposers". ### Withdrawing assets back to Ethereum from Arbitrum @@ -46,7 +45,7 @@ The reason there is a dispute window for assertions about Arbitrum One on Ethere An actual dispute occurs if a party disagrees with an assertion on Ethereum and posts an assertion they know to be correct as a counter-claim. This creates a "fork" in the chain of assertions, requiring a resolution process. We'll get into the high-level details of how disputes are resolved later in this document. -Once an actual dispute is ongoing, it will also take time to resolve, as, once again, Ethereum has no knowledge of the correctness of Arbitrum states. Ethereum must then give sufficient time for parties to submit their proofs and declare a winner. The new Arbitrum BoLD protocol **guarantees that a dispute will be resolved within seven days** so long as an honest party is present to defend against invalid claims. +Once an actual dispute is ongoing, it will also take time to resolve, as, once again, Ethereum has no knowledge of the correctness of Arbitrum One states. Ethereum must then give sufficient time for parties to submit their proofs and declare a winner. The new Arbitrum BoLD protocol **guarantees that a dispute will be resolved within seven days** so long as an honest party is present to defend against invalid claims. As assertions have a dispute window of seven days, and disputes require an additional seven days to resolve, a dispute made at the last second would **delay assertion confirmation to a maximum of 14 days**, or two weeks. BoLD is the only dispute protocol we are aware of that guarantees this bound. @@ -55,17 +54,28 @@ As assertions have a dispute window of seven days, and disputes require an addit Delaying withdrawals incurs opportunity costs and impacts user experience for users who want to withdraw their assets. In the happy case of no disputes, withdrawals already have a baked-in, seven-day delay. A dispute adds seven days to that delay. The problem is that disputes delay _all_ pending withdrawals from Arbitrum One back to Ethereum, not just a single claim. As such, **disputing a claim must have a cost for the initiator** proportional to the opportunity cost they impose on Arbitrum users. #### Requiring a bond to become a validator +By default, all Arbitrum nodes act as validators, monitoring the chain to verify assertions posted to the parent chain and flagging any invalid assertions. On Arbitrum One, running a validator, known as a “watchtower” node, is permissionless and requires no additional cost other than the infrastructure for the node. -The entities responsible for posting assertions about Arbitrum state to Ethereum are a special type of validator, known as a proposer. If proposing assertions were free, anyone could create conflicting assertions to always delay withdrawals by fourteen days instead of seven. As such, Arbitrum requires validators, who wish to be proposers, to make a "security deposit," known as a **bond**, to be allowed to propose assertions. Validators can withdraw their bond as soon as their latest proposed assertion has been confirmed. Withdrawing their bond formally ends the proposer's responsibilities. +Another type of validator, called a "proposer," performs additional tasks on top of their regular duties as a regular validator. Proposers compute Arbitrum states and propose assertions to the parent chain. To prevent abuse and delays in withdrawals, proposers must make a security deposit or "bond" to gain the privilege of proposing assertions. This bond can be withdrawn once their latest assertion is confirmed, ending their responsibilities as a proposer. + +Arbitrum BoLD allows validators to become proposers and challengers without permission. Proposers must bond `ETH` to propose state assertions to the parent chain. Only one proposer is needed for chain progress, allowing most validators to simply verify assertions. In case of disputes over state assertions, BoLD enables anyone to put up a "challenge bond" of `ETH` to dispute invalid assertions, acting as a challenger in defense of an Arbitrum chain. #### Pricing bonds Ensuring assertions are frequently posted is a requirement for Arbitrum, but at the same time, it should not be a privilege that is easily obtained, which is why the pricing of this "security deposit" is based on opportunity cost. -To be highly conservative, in a bank-run scenario, the [Arbitrum One bridge](https://etherscan.io/address/0x8315177ab297ba92a06054ce80a67ed4dbd7ed3a) contains approximately $3.5B USD worth of assets at the time of writing on Sept 20th, 2024. Assuming funds could earn a 5% APY if invested, the opportunity cost of 1 extra week of delay is approximately USD 3,400,000. Given this scenario, we recommend a bond for assertion posters to be greater than $3,400,000 USD. +To be highly conservative, in a "bank run"-like scenario, the [Arbitrum One bridge](https://etherscan.io/address/0x8315177ab297ba92a06054ce80a67ed4dbd7ed3a) contains approximately $3.4B USD worth of assets at the time of writing on Oct 23rd, 2024. Assuming funds could earn a 5% APY if invested elsewhere, the opportunity cost of 1 extra week of delay is approximately $3.27M USD. Given this scenario, we recommend a bond for assertion posters to be greater than $3.7M USD. Honest proposers can always withdraw their bond once their assertions are confirmed. However, adversaries stand to lose the entirety of their bond if they propose invalid assertions. A large bond size drastically improves the economic security of the system based on these two axes by making the cost to propose high and by guaranteeing that malicious actors will lose their entire bond when they are proven wrong by the protocol. +Given that participation in BoLD is permissionless, we recommend that the size of bonds required to participate be high enough to disincentivize malicious actors from attacking Arbitrum One and to mitigate against spam (that would otherwise delay confirmations up to 1 challenge period). High bonding values do not harm decentralization because (1) trustless bonding (or staking) pools can be deployed permissionlessly to open challenges and post assertions, and (2) any number of honest parties of unknown identities can emerge to bond their funds to the correct assertion and participate in the defense of Arbitrum at any time within a challenge. As with the current dispute resolution protocol, there are no protocol level incentives for parties who opt in to participate in validating Arbitrum One with BoLD. + +While both of these bonds can be any ERC20 token and be set to any size, we recommend the use of the `WETH` ERC20 token & the following bond sizes for Arbitrum One: +* Assertion bonds: 3600 `ETH` - required from validators to bond their funds to an assertion in the eventual hopes of having that assertion be confirmed by the rollup protocol. This is a one-time bond required to be able to start posting assertions. This bond can be withdrawn once a validator’s assertion is confirmed and can alternatively be put together via a trustless bonding pool. +* Challenge-bonds, per level: 555/79 `ETH` - required from validators to open challenges against an assertion observed on the parent chain (Ethereum, in the case for Arbitrum One), for each level. Note that “level” corresponds to the level of granularity over which the interactive dissection game gets played, starting at the block level, moving on to a range of WASM execution steps, and then finally to the level of a single step of execution. + +These values were carefully calculated to optimize for the resource ratio (explained later) and gas costs in the event of an attack, as explained in [BoLD whitepaper](https://arxiv.org/abs/2404.10491). This effectively means that an entity that has already put up a bond to propose an assertion does not need to put up a separate assertion bond to challenge an invalid state assertion that they observe. To be explicitly clear, the validator would still require 555 `ETH` and 79 `ETH` for ongoing challenges. These additional challenge bond amounts are needed to participate in the interactive dispute game (back and forth) and narrows down the disagreement to a single step of execution that is then proven on Ethereum. The 555 `ETH` and 79 `ETH` challenge bonds can be put together via a trustless bonding pool, and do not all have to be put up by the validator that opened the challenge. These bonds can be refunded at the end of a challenge and can also alternatively be put together by the community using a trustless bonding pool. + #### Centralization concerns Requiring a high bond to post assertions about Arbitrum seems centralizing, as we are replacing an allowlist of validators with a system that requires substantial funds to participate. However, **BoLD ships with a trustless bonding pool** for assertion posting. That is, any group of honest parties can pool funds into a simple contract that will post an assertion to Ethereum without needing to trust each other. We believe that making it easy to pool the funds to become an assertion poster without needing trust to dispute invalid claims does not affect the safety or decentralization of BoLD. @@ -130,18 +140,41 @@ The resource ratio will drive the price of disputes claims, impacting both hones #### The sweet spot -So, now that we've established that a higher resource ratio is better but comes with some trade-offs, what is the sweet spot? +So, now that we've established that a higher resource ratio is better but comes with some trade-offs, what is the sweet spot? -We propose a resource of ratio of 6.46. While odd, this resource ratio was calculated taking the initial "bond" to become a proposer (mentioned earlier) and a worst case scenario of 500 gwei/gas on L1 for posting assertions and making sub-challenge moves (i.e. if an attack were to happen, the malicious actor could choose to perform their attack during a period of elevated gas prices). Again, we should emphasize that the ratio of malicious to honest cost should be high to sufficiently deter attacks. Under our current assumptions (500gwei/gas) and proposed parameters (bond sizes, etc) for every $6.46 spent by malicious parties attacking, only $1 is needed to defend it successfully in BoLD. Here's a [direct link to the calculations](https://www.desmos.com/calculator/usmdcuopme) where the X-axis is L1 gas costs in gwei and the Y-axis is the resource ratio. +We propose a resource of ratio of 6.46 for Arbitrum One. While odd, this resource ratio was calculated taking the initial "bond" to become a proposer (mentioned earlier) and a worst case scenario of 500 gwei/gas on L1 for posting assertions and making sub-challenge moves (i.e. if an attack were to happen, the malicious actor could choose to perform their attack during a period of elevated gas prices). Again, we should emphasize that the ratio of malicious to honest cost should be high to sufficiently deter attacks. Under our current assumptions (500gwei/gas) and proposed parameters (bond sizes, etc) for every $6.46 spent by malicious parties attacking, only $1 is needed to defend it successfully in BoLD. Here's a [direct link to the calculations](https://www.desmos.com/calculator/usmdcuopme) where the X-axis is L1 gas costs in gwei and the Y-axis is the resource ratio. -Honest parties will always be refunded entirely and potentially rewarded using the bonds confiscated from malicious actors if a challenge occurs. Meanwhile, malicious parties always stand to lose 100% of their bond when they lose the challenge. The Arbitrum DAO could consider the cost of incentivizing or lending the assets to a single honest proposer in the happy case as the **security budget of the chain**. +Unfortunately, there is no "one size fits all" framework for choosing the resource ratio for your chain. Therefore, we recommend teams learn and understand the benefits and trade-offs of operating BoLD in a permissionless format - including performing the same type of economic risk analyses we have performed for Arbitrum One. ## Thinking about incentives Although we have made claims with hard numbers about how to price disputes and withdrawal delays in Arbitrum BoLD, we also took a step back and considered the theoretical assumptions we were making. Arbitrum One is a complex protocol used by many groups of people with different incentives. The research team at Offchain Labs has spent considerable effort studying the game theory of validators in Optimistic Rollup. Honest parties represent everyone with funds onchain, and they have a significant amount to gain by winning the challenge - as they can prevent the loss of their assets rather than losing them. -A more complex model is proposed, which considers all parties staking and their associated costs created by [Akaki Mamageishvili](mailto:amamageishvili@offchainlabs.com) and Ed Felten in their paper ["Incentive Schemes for Rollup Validators"](https://arxiv.org/abs/2308.02880). The paper examines the incentives needed to get parties to check whether assertions are correct. It finds that there is no pure strategy, Nash equilibrium, and only a mixed equilibrium if there is no incentive for honest validators. However, the research showed a pure strategy equilibrium can be reached if honest parties are incentivized to **check** results. The problem of honest validators' "free riding" and not checking is well-documented as the [verifier's dilemma](https://www.smithandcrown.com/glossary/verifiers-dilemma). We believe future iterations of BOLD could include "attention challenges" that reward honest validators for also doing their job. +A more complex model is proposed, which considers all parties staking and their associated costs paper ["Incentive Schemes for Rollup Validators"](https://arxiv.org/abs/2308.02880). The paper examines the incentives needed to get parties to check whether assertions are correct. It finds that there is no pure strategy, Nash equilibrium, and only a mixed equilibrium if there is no incentive for honest validators. However, the research showed a pure strategy equilibrium can be reached if honest parties are incentivized to **check** results. The problem of honest validators' "free riding" and not checking is well-documented as the [verifier's dilemma](https://www.smithandcrown.com/glossary/verifiers-dilemma). We believe future iterations of BOLD could include "attention challenges" that reward honest validators for also doing their job. + +### Service fee for “Active” proposers + +For Arbitrum BoLD's initial launch, we believe that chain owners should pay a service fee to active, top-level proposers as a way of removing the disincentive for participation by honest parties who bond their own capital and propose assertions for Arbitrum One. The fee should be denominated in `ETH` and should correlate to the annualized income that Ethereum mainnet validators receive, over the same time period. At the time of writing, the estimated annual income for Ethereum mainnet validators is approximately 3% to 4% of their stake (based on [CoinDesk Indices Composite Ether Staking Rate (CESR) benchmark](https://www.coindesk.com/indices/ether/cesr) and [Rated.Network](https://explorer.rated.network/network?network=mainnet&timeWindow=7d&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)). + +This service fee can be paid out upon an active proposer’s top-level assertion being confirmed on Ethereum and will be calculated using the duration of time that the proposer was considered active by the protocol. The procedure that calculates this will be handled off-chain, using a procedure that will be published at a later date. BoLD makes it permissionless for any validator to become a proposer and also introduces a way to pay a service fee to honest parties for locking up capital to do so. Validators are not considered active proposers until they successfully propose an assertion with a bond. + +In order to become an active proposer for an Arbitrum chain, post-BoLD, a validator has to propose a state assertion to its parent chain. For Arbitrum One and Nova, the state assertion is posted onto L1 Ethereum. If they do not have an active bond on L1, they then need to attach a bond to their assertion in order to successfully post the assertion. Subsequent assertions posted by the same address will simply move the already-supplied bond to their latest proposed assertion. Meanwhile, if an entity, say Bob, has posted a successor assertion to one previously made by another entity, Alice, then Bob would be considered by the protocol to be the current active proposer. Alice would no longer be considered by the protocol as the active proposer and once Alice’s assertion is confirmed, then Alice gets her assertion bond refunded. There can only be 1 “active” proposer at any point in time. + +For Arbitrum One specifically, all eligible entities who wish to be paid this service fee from the Arbitrum Foundation must undergo the Arbitrum Foundation’s KYC process as no AIP "may be in violation of applicable laws, in particular sanctions-related regulations". This is also written in the [ArbitrumDAO's Constitution](https://docs.arbitrum.foundation/dao-constitution#section-2-dao-proposals-and-voting-procedures). + +### Rewards and Reimbursements for Defenders +The service fee described above is meant to incentivize or reimburse an honest, active proposer for locking up their capital to propose assertions and advance the chain. Similarly, in the event of an attack, a bounty is proposed to be paid out to honest defenders using confiscated funds from malicious actors (in the event of a challenge). + +For Arbitrum One specifically, 1% (called the “defender’s bounty”) of the confiscated funds from a malicious actor is to be rewarded to honest parties who deposit a challenge bond and post assertions as part of a sub-challenge, proportional to the amount that a defender has put up to defend a correct state assertion during the challenge. This bounty applies for all challenges (block challenges, sub challenges and one step challenges). Note that any gas costs spent by honest parties to defend Arbitrum One during a challenge is 100% refundable by the Arbitrum Foundation. In this model, honest defenders and proposers of Arbitrum One are incentivized to participate while malicious actors stand to lose everything they spent attacking Arbitrum One. We believe chain owners who are interested in adopting BoLD for their own chain should follow a similar approach, described above for Arbitrum One, to incentivize challenge participation (but not necessarily assertion proposing). + +In this design, defenders are only eligible for the defender's bounty if they deposit a challenge bond (for Arbitrum One, this is either 555 or 79 `ETH`, depending on the level), posted to an on-chain assertion as part of a sub-challenge (i.e., not the top-level assertion), and have had their on-chain sub-challenge assertion get confirmed by the protocol. For Arbitrum One, the calculation for the defender's bounty is conducted off-chain by the Arbitrum Foundation, and payment will be made via an ArbitrumDAO governance vote (since confiscated funds go to an ArbitrumDAO-controlled address). Honest parties are not automatically rewarded with all the funds seized from malicious actors to avoid creating a situation where honest parties wastefully compete to be the first ones to make each honest move in the interactive fraud-proof game. Additionally, BoLD resolves disputes by determining which top-level assertion is correct, without necessarily being able to classify every move as “honest” or “malicious” as part of the interactive fraud-proof game without off-chain knowledge. + +Once all of a validator’s proposed assertions are confirmed, a validator can withdraw their bond in full. Additionally, the protocol will automatically handle refunds of challenge bonds for honest parties and confiscation of bonds from malicious parties in the event of a challenge. In other words, bonds put up by honest parties will always be returned and bonds put up by malicious parties will always be confiscated. For Arbitrum One specifically, L1 gas costs for honest parties defending a challenge will be reimbursed by the Arbitrum Foundation using a procedure that will be published at a later date. The chain owner could therefore consider the cost of incentivizing or lending the assets to a single honest proposer in the happy case as the **security budget of the chain**. + +For Arbitrum One specifically, all eligible entities who wish to be paid the defender's bounty from the ArbitrumDAO must undergo the Arbitrum Foundation’s KYC process as no AIP "may be in violation of applicable laws, in particular sanctions-related regulations". This is also written in the [ArbitrumDAO's Constitution](https://docs.arbitrum.foundation/dao-constitution#section-2-dao-proposals-and-voting-procedures). ## Conclusion -This paper summarizes the rationale behind choosing bond sizes and the cost of spam prevention in Optimistic Rollup dispute protocols. We recommend that bond sizes be high enough to discourage challenges from being opened, as malicious parties will always stand to lose when playing the game. As Arbitrum BoLD does not tie disputes to specific addresses, honest parties can have trustless cooperation to resolve disputes if desired. We posit that making the cost of the malicious parties 10x that of the honest party leads to nice economic properties that help us reason about how to price bonds. Finally, we look at a high-level game theory discussion of Optimistic Rollups and argue that solving the verifier's dilemma by incentives to honest validators is an important addition to work towards. +This page summarizes the rationale behind choosing bond sizes and the cost of spam prevention in Optimistic Rollup dispute protocols. We recommend that bond sizes be high enough to discourage challenges from being opened, as malicious parties will always stand to lose when playing the game. As Arbitrum BoLD does not tie disputes to specific addresses, honest parties can have trustless cooperation to resolve disputes if desired. We posit that making the cost of the malicious parties 10x that of the honest party leads to nice economic properties that help us reason about how to price bonds. Finally, we look at a high-level game theory discussion of Optimistic Rollups and argue that solving the verifier's dilemma by incentives to honest validators is an important addition to work towards. + +The topic of further improvements and new economic and incentive models for BoLD are valuable and we believe it deserves the full focus and attention of the community in future proposals and discussions. Details around additional or new proposed economic or incentive models for BoLD will need continued research and development work, but the deployment of BoLD as-is represents a substantial improvement to the security of Arbitrum even without economic-related concerns resolved. diff --git a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md index 55c6d688f..140c1e6da 100644 --- a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md +++ b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md @@ -86,54 +86,6 @@ Let’s dive in to an overview of how BoLD actually works. That’s it! We’ve now walked through each of the steps that validators will take to dispute challenges with the BoLD protocol. One final note here is that each of the steps explained above can take place concurrently and this is one of the reasons why BoLD can guarantee that disputes are resolved within a fixed time frame. -## The Economics of Disputes in Arbitrum BoLD - -:::tip -This section on BoLD's economics only applies to Arbitrum One, following the [BoLD DAO vote](https://forum.arbitrum.foundation/t/aip-bold-permissionless-validation-for-arbitrum/23232). As always, Arbitrum Orbit chain owners have full discretion over whether they adopt BoLD and how to use BoLD for the benefit of their project & users. The structure for how BoLD is used for Arbitrum One (outlined below) can be used to inform decisions around how BoLD is used for your Orbit chain(s). -::: - -Given that participation in BoLD is permissionless, it is recommended that the size of the bonds required to participate be high enough to disincentivize malicious actors from attacking Arbitrum One and Nova and to mitigate against spam (that would otherwise delay confirmations). High bonding values do not harm decentralization because (1) trustless bonding pools can be deployed permissionlessly to let the community open challenges and post assertions, and (2) any number of honest parties of unknown identities can emerge to bond their funds to the correct assertion and participate in the defense of Arbitrum at any time within a challenge. As with the current dispute resolution protocol, there are no protocol level incentives for parties who opt in to participate in validating Arbitrum One and Nova with BoLD. The bonds can be any ERC20 token and be set to any size for Arbitrum One and Nova, as determined by the Arbitrum DAO. - -BoLD lets validators permissionlessly become proposers and challengers if they want to. The role of a proposer is required to help progress the chain which requires bonding ETH, proposing and then posting state assertions to the parent chain. This bond is known as an “assertion bond”. The chain only needs 1 proposer to make progress. Therefore, most parties can watch the chain and independently verify assertions without being a proposer. In the unhappy case where there is a dispute about a proposed state assertion, BoLD lets anyone permissionlessly put up a bond of ETH to open challenges in the defense of Arbitrum (in their capacity as a challenger to invalid state assertions). This bond is known as a “challenge bond”. - -While both of these bonds can be any ERC20 token and be set to any size, this proposal recommends the use of the WETH ERC20 token & the following bond sizes: - -- Assertion bonds: 3600 ETH - required from validators to bond their funds to an assertion in the eventual hopes of having that assertion be confirmed by the rollup protocol. This is a one-time bond required to be able to start posting assertions. This bond can be withdrawn once a validator’s assertion is confirmed and can alternatively be put together via a trustless bonding pool. -- Challenge-bonds, per level: 555/79 ETH (UPDATED) - required from validators to open challenges against an assertion observed on Ethereum, for each level. Note that “level” corresponds to the level of granularity at which the interactive dissection game gets played over, starting at the block level, moving on to a range of WASM execution steps, and then finally to the level of a single step of execution. These values were carefully calculated to optimize for the resource ratio and gas costs in the event of an attack, as explained in the [Economics of Disputes in Arbitrum BoLD](https://github.com/OffchainLabs/BoLD/blob/main/docs/research-specs/Economics.pdf) and the [BoLD whitepaper](https://arxiv.org/abs/2404.10491). This effectively means that an entity that has already put up a bond to propose an assertion does not need to put up a separate assertion bond to challenge an invalid state assertion that they observe. To be explicitly clear, a validator would still require 555 ETH and 79 ETH for on-going challenges. These additional challenge bond amounts are needed to participate in the interactive dispute game (back and forth) and narrows down the disagreement to a single step of execution that is then proven on Ethereum. The 555 ETH and 79 ETH challenge bonds can be put together via a trustless bonding pool, and does not all have to be put up by the validator that opened the challenge. These bonds can be refunded at the end of a challenge and can also alternatively be put together by the community using a trustless bonding pool. - -BoLD makes permissionless validation possible for Arbitrum rollup chains and marks a major step towards [full decentralization](https://docs.arbitrum.foundation/state-of-progressive-decentralization). This significant milestone also lays the groundwork for productive discussions about future economic incentives for those participating in the protocol since anyone can participate. - -### Reimbursements and penalties - -Once all of a validator’s proposed assertions are confirmed, a validator can withdraw their bond in full. Other costs spent by the honest parties to defend Arbitrum, such as the L1 gas costs and the challenge bonds, are fully refundable following confirmation of all sub-challenges. Challenge bonds will be automatically refundable in-protocol while L1 gas costs will be reimbursed by the Arbitrum Foundation using an off-chain procedure. All costs spent by malicious actors, including the assertion bond, are confiscated and sent to an Arbitrum DAO controlled address at the conclusion of a challenge. All eligible entities who wish to be paid a reward or be reimbursed by the Arbitrum DAO or the Arbitrum Foundation are expected to undergo the Arbitrum Foundation’s KYC process. - -#### Service fee for “Active” proposers - -A service fee is to be paid to active block-level proposers as a way of removing the disincentive for participation by honest parties who bond their own capital and propose assertions for Arbitrum One. The fee should be denominated in ETH and should correlate to the annualized income that Ethereum mainnet validators receive, over the same time period. At the time of writing, the estimated annual income for Ethereum mainnet validators is approximately 3% to 4% of their stake (based on [CoinDesk Indices Composite Ether Staking Rate (CESR) benchmark](https://www.coindesk.com/indices/ether/cesr) and [Rated.Network](https://explorer.rated.network/network?network=mainnet&timeWindow=all&rewardsMetric=average&geoDistType=all&hostDistType=all&soloProDist=stake)). This fee is not a “reward” for the same reasons why the protocol does not automatically reward honest parties with all the funds confiscated from a malicious actor. - -This service fee can be paid out upon an active proposer’s top-level assertion being confirmed on Ethereum and will be calculated using the duration of time that the proposer was considered active by the protocol. The procedure that calculates this will be handled off-chain by the Arbitrum Foundation. BoLD makes it permissionless for any validator to become a proposer and also introduces a way to pay a service fee to honest parties for locking up capital to do so. Validators are not considered active proposers until they successfully propose an assertion with a bond. - -In order to become an active proposer for Arbitrum One, post-BoLD, a validator has to propose an L2 state assertion to Ethereum. If they do not have an active bond on L1, they then need to attach a bond to their assertion in order to successfully post the assertion. Subsequent assertions posted by the same address will simply move the already-supplied bond to their latest proposed assertion. Meanwhile, if an entity, say Bob, has posted a successor assertion to one previously made by another entity, Alice, then Bob would be considered by the protocol to be the current active proposer. Alice would no longer be considered by the protocol as the active proposer and once Alice’s assertion is confirmed, then Alice gets her assertion bond refunded. There can only be 1 “active” proposer at any point in time. - -This service fee would not apply to entities that use the DAO’s funds to become a proposer, if the proposal passes. The DAO may choose, via governance, to fund other parties or change this reward or service fee model at any time. - -As mentioned above in Step 5, once all of a validator’s assertions are confirmed, a validator can withdraw their full assertion bond and have their challenge bonds refunded automatically. Funds from a malicious party will be confiscated and sent to the ArbitrumDAO treasury. - -#### Rewards and Reimbursements for Defenders - "Defender's Bounty" - -The service fee described above is meant to incentivize or reimburse an honest, active proposer for locking up their capital to propose assertions and advance the chain. Similarly, in the event of an attack, a reward is paid out to honest defenders using confiscated funds from malicious actors. This reward is defined as the "Defender's Bounty". - -Specifically, 1% (one percent) of the confiscated funds from a malicious actor is proposed to be rewarded to honest parties who deposit a challenge bond and post assertions as part of a sub-challenge, proportional to the amount that a defender has put up to defend a correct state assertion during the challenge. Note that any gas costs spent by honest parties to defend Arbitrum One during a challenge is 100% refundable by the Arbitrum Foundation. In this model, honest defenders and proposers of Arbitrum One stand are incentivized to participate while malicious actors stand to lose everything they spent attacking Arbitrum One. - -- How to reimburse the challenge bond and gas costs to honest parties, and -- What to do with the funds confiscated from a malicious actor (including, but not limited to, rewarding the honest parties with a portion of the confiscated funds, burning the confiscated funds in its entirety, or sending the confiscated funds to the DAO treasury). - -Note that honest parties are not automatically rewarded with the funds confiscated from malicious actors to avoid creating a situation where honest parties wastefully compete to be the first one to make each honest move in the interactive fraud proof game. Additionally, BoLD resolves disputes by determining which top-level assertion is correct, without necessarily being able to classify every move as “honest” or “malicious” as part of the interactive fraud proof game without off-chain knowledge. - -Defenders are only eligible for this reward if they deposit a challenge bond (555 or 79 ETH, depending on the level), posted an on-chain assertion as part of a sub-challenge (i.e. not the top-level assertion), and have had their on-chain sub-challenge assertion get confirmed by the protocol. The calculation for this reward is conducted off-chain by the Arbitrum Foundation and payment will be made via an Arbitrum DAO vote (since confiscated funds go to a Arbitrum DAO-controlled address). - -The topic of further improvements and new economic and incentive models for BoLD are valuable and we believe it deserves the full focus and attention of the community via a separate proposal/discussion - decoupled from this proposal to bring BoLD to mainnet. Details around additional or new proposed economic or incentive models for BoLD will need continued research and development work, but the deployment of BoLD as-is represents a substantial improvement to the security of Arbitrum even without economic-related concerns resolved. - ## What can I do with BoLD today? Today, BoLD is deployed on a public testnet using Ethereum Sepolia as a base layer for anyone to experiment with and test on. The intent behind this testnet is purely to demonstrate, first-hand, how disputes can effectively resolved by a single party in a fixed challenge period on Arbitrum chains. Feedback gained from developers, users, and researchers will help improve and strengthen BoLD’s design. 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..4e56022f1 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx @@ -0,0 +1,42 @@ +--- +title: 'The AEP fee router: introduction' +sidebar_label: 'AEP fee router: overview' +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 +--- + +## 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 deploy on *any chain*permissionlessly. 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. + +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) chains, 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**. + +## How can I set up an AEP fee router on my Orbit chain? + +You can learn how to set up your AEP fee router in [implementation guide](/launch-orbit-chain/how-tos/set-up-aep-fee-router.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..694c0cdf3 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/how-tos/calculate-aep-fees.mdx @@ -0,0 +1,111 @@ +--- +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 +--- + +This document will help you calculate your Orbit chain’s _Protocol Net Revenue_ and AEP license fees. + +Before we define “Protocol Net Revenue,” let's explain how fees work in 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 to submit their transactions. 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 to 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 chain owners can optionally deduct assertion costs. + +### Additional revenue sources + +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. +- Broadly, any revenue earned in connection with 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 is 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 cannot track the amount of gas validators spend, and it cannot determine the eligibility of a validator. + +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. + +### Eligible validators + +Only validators directly associated with the Orbit chain owner are eligible for assertion cost deductions. By directly associated, we mean a validator operated by the team directly or contracted 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 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: + +- [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 costs_ 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 + +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, your custom gas token contract might be deployed on L2. If this L2 is not Arbitrum One, then the L2 token can 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 still determining if your Orbit configuration applies to the listed or unlisted special cases, we recommend engaging with the Arbitrum Foundation. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx index 39b721452..89e0d3547 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx @@ -1,6 +1,6 @@ --- title: 'Enable fast withdrawals on your Orbit chain' -sidebar_label: 'Enable fast withdrawals.' +sidebar_label: 'Enable fast withdrawals' description: 'Learn to deploy Fast Withdrawals' author: coopermidroni, tucksondev sme: tucksondev 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..cae4444d4 --- /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 +--- + +## 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 + +_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 reward 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 can send 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 a Layer-3 network or higher) +- Deploying a `RewardDistributor` contract configured to forward 10% of fees to the `ChildToParentRouter` and 90% 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](/launch-orbit-chain/how-tos/calculate-aep-fees#assertion-costs) 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 deploy quickly and set up 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, and 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, which can neither be an Arbitrum chain nor 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](#canonical-contracts) section of this document. If the parent chain your chain settles to is not on 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 +``` diff --git a/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.md b/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.md index aea28f730..7bdac3a2f 100644 --- a/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.md +++ b/arbitrum-docs/run-arbitrum-node/data-availability-committees/02-deploy-das.md @@ -291,7 +291,7 @@ Once the DAS is running, we can test if everything is working correctly using th ### Test 1: RPC health check -The RPC interface enabled in the DAS has a health check for the underlying storage that can be invoked by using the RPC method  `das_healthCheck` that returns `200` if the DAS is active. +The RPC interface enabled in the DAS has a health check for the underlying storage that can be invoked by using the RPC method  `das_healthCheck` that returns a status `200` if the DAS is active. Example: @@ -380,7 +380,7 @@ The retention period defaults to 24 hours, but can be configured when calling `d ### Test 3: REST health check -The REST interface has a health check on the path `/health` which will return `200` if the underlying storage is working, otherwise `503`. +The REST interface has a health check on the path `/health` which will return a status `200` if the underlying storage is working, otherwise `503`. Example: diff --git a/arbitrum-docs/stylus/how-tos/debugging-stylus-tx.mdx b/arbitrum-docs/stylus/how-tos/debugging-stylus-tx.mdx index 8f25c9ce7..2d098fe1b 100644 --- a/arbitrum-docs/stylus/how-tos/debugging-stylus-tx.mdx +++ b/arbitrum-docs/stylus/how-tos/debugging-stylus-tx.mdx @@ -13,11 +13,11 @@ import MacosVerifyTxIssueBannerPartial from '../../partials/_macos-verify-tx-iss -Debugging smart contracts can be challenging, especially when dealing with complex transactions. The `cargo-stylus-replay` crate simplifies the debugging process by allowing developers to replay Stylus transactions. This tool leverages GDB to provide an interactive debugging experience, enabling developers to set breakpoints, inspect state changes, and trace the execution flow step-by-step. This capability is crucial for identifying and resolving issues, ensuring that smart contracts function correctly and efficiently. +Debugging smart contracts can be challenging, especially when dealing with complex transactions. The `cargo-stylus` crate simplifies the debugging process by allowing developers to replay Stylus transactions. This tool leverages GDB to provide an interactive debugging experience, enabling developers to set breakpoints, inspect state changes, and trace the execution flow step-by-step. This capability is crucial for identifying and resolving issues, ensuring that smart contracts function correctly and efficiently. ### Overview -Cargo Stylus is a tool designed to simplify the development and debugging process for smart contracts written in Rust for the Stylus execution environment. One of its powerful features is the `cargo-stylus-replay` crate, which provides essential functionalities for developers: +Cargo Stylus is a tool designed to simplify the development and debugging process for smart contracts written in Rust for the Stylus execution environment. One of its powerful features is the `cargo stylus` subcommand, which provides essential functionalities for developers: 1. **Trace transactions**: Perform trace calls against Stylus transactions using Ethereum nodes' `debug_traceTransaction` RPC. This feature enables developers to analyze the execution flow and state changes of their transactions in a detailed manner. 2. **Debugging with GDB**: Replay and debug the execution of a Stylus transaction using the GNU Debugger (GDB). This allows developers to set breakpoints, inspect variables, and step through the transaction execution line by line, providing an in-depth understanding of the transaction's behavior. @@ -29,19 +29,19 @@ Cargo Stylus is a tool designed to simplify the development and debugging proces #### Requirements - **Rust** (version 1.77 or higher) -- **Crates**: `cargo-stylus`, `cargo-stylus-replay`, `cargo-stylus-check` +- **Crate**: `cargo-stylus` - **GNU Debugger (GDB)** - **[Cast](https://book.getfoundry.sh/cast/)** (an Ethereum CLI tool) - **Local Arbitrum Sepolia node** with tracing endpoints enabled or a [local Stylus dev node](https://arbitrum-docs-ncyp5gty1-offchain-labs.vercel.app/run-arbitrum-node/run-local-dev-node) -`cargo-stylus-replay` allows users to debug the execution of a Stylus transaction using [GDB](https://sourceware.org/gdb/) against the Rust source code. +`cargo stylus replay` allows users to debug the execution of a Stylus transaction using [GDB](https://sourceware.org/gdb/) against the Rust source code. ### Installation and setup 1. **Install the required crates and GDB**: First, let's ensure that the following crates are installed: ```sh -cargo install cargo-stylus cargo-stylus-replay cargo-stylus-check +cargo install cargo-stylus ``` Install GDB if it's not already installed: @@ -118,7 +118,7 @@ GDB will load and set a breakpoint automatically at the `user_entrypoint` intern ```sh [Detaching after vfork from child process 370003] -Thread 1 "cargo-stylus-re" hit Breakpoint 1, stylus_hello_world::user_entrypoint (len=4) at src/lib.rs:38 +Thread 1 "cargo-stylus" hit Breakpoint 1, stylus_hello_world::user_entrypoint (len=4) at src/lib.rs:38 38 #[entrypoint] (gdb) ``` @@ -139,7 +139,7 @@ Then, type `c` to continue the execution and you will reach that line where `inc Once you reach the `increment` method, inspect the state: ```sh -Thread 1 "cargo-stylus-re" hit Breakpoint 2, stylus_hello_world::Counter::increment (self=0x7fffffff9ae8) at src/lib.rs:69 +Thread 1 "cargo-stylus" hit Breakpoint 2, stylus_hello_world::Counter::increment (self=0x7fffffff9ae8) at src/lib.rs:69 69 let number = self.number.get(); (gdb) p number ``` diff --git a/arbitrum-docs/stylus/how-tos/verifying-contracts.mdx b/arbitrum-docs/stylus/how-tos/verifying-contracts.mdx index dcb3498ff..910c3f40d 100644 --- a/arbitrum-docs/stylus/how-tos/verifying-contracts.mdx +++ b/arbitrum-docs/stylus/how-tos/verifying-contracts.mdx @@ -98,7 +98,6 @@ RUN rustup default $VERSION-x86_64-unknown-linux-gnu RUN rustup target add wasm32-unknown-unknown RUN rustup target add wasm32-wasi RUN rustup target add x86_64-unknown-linux-gnu -RUN cargo install cargo-stylus-check RUN cargo install cargo-stylus ``` diff --git a/arbitrum-docs/stylus/stylus-quickstart.md b/arbitrum-docs/stylus/stylus-quickstart.md index 49bb607e9..91d85aedd 100644 --- a/arbitrum-docs/stylus/stylus-quickstart.md +++ b/arbitrum-docs/stylus/stylus-quickstart.md @@ -82,10 +82,11 @@ In your terminal, run: cargo install --force cargo-stylus ``` -Add WASM ([WebAssembly](https://webassembly.org/)) as a build target for your Rust compiler with the following command: +Add WASM ([WebAssembly](https://webassembly.org/)) as a build target for the specific Rust toolchain you are using. The below example sets your default Rust toolchain to 1.80 as well as adding the WASM build target: ```shell -rustup target add wasm32-unknown-unknown +rustup default 1.80 +rustup target add wasm32-unknown-unknown --toolchain 1.80 ``` You can verify that cargo stylus is installed by running `cargo stylus --help` in your terminal, which will return a list of helpful commands, we will use some of them in this guide: diff --git a/website/sidebars.js b/website/sidebars.js index 27968e439..481280714 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -317,6 +317,28 @@ const sidebars = { id: 'launch-orbit-chain/how-tos/fast-withdrawals', label: `Enable fast withdrawals`, }, + { + type: 'category', + label: 'AEP fee router', + collapsed: true, + items: [ + { + type: 'doc', + id: 'launch-orbit-chain/aep-fee-router-introduction', + 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`, + }, + ], + }, ], }, {