diff --git a/.github/dependabot.yml b/.github/dependabot.yml new file mode 100644 index 000000000..272712417 --- /dev/null +++ b/.github/dependabot.yml @@ -0,0 +1,11 @@ +# To get started with Dependabot version updates, you'll need to specify which +# package ecosystems to update and where the package manifests are located. +# Please see the documentation for all configuration options: +# https://docs.github.com/code-security/dependabot/dependabot-version-updates/configuration-options-for-the-dependabot.yml-file + +version: 2 +updates: + - package-ecosystem: "gitsubmodule" # See documentation for possible values + directory: "/" # Location of package manifests + schedule: + interval: "daily" diff --git a/.github/workflows/check-undocumented-issues.yml b/.github/workflows/check-undocumented-issues.yml new file mode 100644 index 000000000..ece52e116 --- /dev/null +++ b/.github/workflows/check-undocumented-issues.yml @@ -0,0 +1,57 @@ +name: Check Undocumented Issues + +on: + issues: + types: [opened] + +jobs: + check-issue-content: + runs-on: ubuntu-latest + permissions: + issues: write + + steps: + - name: Check issue content + uses: actions/github-script@v7 + with: + script: | + const issue = context.payload.issue; + + // Get the issue body and title + const body = issue.body || ''; + const title = issue.title || ''; + + // Check if this is a docs update request + const isDocsRequest = title.startsWith('Docs update request:'); + + if (!isDocsRequest) { + return; + } + + // Split body into lines and remove empty ones + const bodyLines = body.split('\n').filter(line => line.trim()); + + // Check if only contains the template content + const hasOnlyTemplate = + bodyLines.length <= 3 && // Updated to match 3 lines + bodyLines[0]?.startsWith('Source:') && + bodyLines[1]?.startsWith('Request: (how can we help?)') && + bodyLines[2]?.includes('Psst, this issue will be closed'); // Added check for the warning message + + if (hasOnlyTemplate) { + // Close the issue with a comment + await github.rest.issues.createComment({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issue.number, + body: 'This issue is being closed automatically as it appears to be an empty documentation update request. Please provide specific details about what needs to be updated or improved in the documentation. You can create a new issue with more details if needed.\n\nSome helpful details to include:\n- What specific part of the documentation needs updating?\n- What is unclear or missing?\n- What would make the documentation more helpful?\n\nThank you for helping us improve our documentation!' + }); + + await github.rest.issues.update({ + owner: context.repo.owner, + repo: context.repo.repo, + issue_number: issue.number, + state: 'closed', + state_reason: 'not_planned' + }); + } diff --git a/.gitignore b/.gitignore index d5c300a76..83be1e7d7 100644 --- a/.gitignore +++ b/.gitignore @@ -2,3 +2,4 @@ arbitrum-docs/sdk arbitrum-docs/stylus-by-example .vercel +.DS_Store diff --git a/arbitrum-docs/arbitrum-bridge/01-quickstart.mdx b/arbitrum-docs/arbitrum-bridge/01-quickstart.mdx index e27ea8c24..f978ef4c9 100644 --- a/arbitrum-docs/arbitrum-bridge/01-quickstart.mdx +++ b/arbitrum-docs/arbitrum-bridge/01-quickstart.mdx @@ -74,7 +74,7 @@ Also make sure your wallet is set to the destination chain so you can see your f :::info There's at least a 7 day withdrawal period for Arbitrum One and Nova networks Once you withdraw your funds from Arbitrum One or Nova through the Arbitrum bridge, you will have to wait for at least 7 days to receive them on Ethereum mainnet. -For more details, see [Arbitrum Bridge: Troubleshooting](/arbitrum-bridge/03-troubleshooting.mdx#how-long-does-it-take-before-i-receive-my-funds-when-i-initiate-withdrawal-from-arbitrum-chains-one-and-nova). +For more details, see [Arbitrum Bridge: Troubleshooting](https://docs.arbitrum.io/arbitrum-bridge/troubleshooting#how-long-does-it-take-before-i-receive-my-funds-when-i-initiate-a-withdrawal-from-arbitrum-chains-one-and-nova). ::: diff --git a/arbitrum-docs/arbitrum-bridge/02-usdc-arbitrum-one.mdx b/arbitrum-docs/arbitrum-bridge/02-usdc-arbitrum-one.mdx index b943f5fe4..30de9d499 100644 --- a/arbitrum-docs/arbitrum-bridge/02-usdc-arbitrum-one.mdx +++ b/arbitrum-docs/arbitrum-bridge/02-usdc-arbitrum-one.mdx @@ -9,7 +9,7 @@ sidebar_position: 4 Arbitrum One supports two different types of USDC: -1. **Arbitrum-native USDC (USDC)**: USDC tokens native to the Arbitrum One chain. +1. **USDC (USDC)**: USDC tokens native to the Arbitrum One chain. 2. **Bridged USDC (USDC.e)**: Ethereum-native USDC tokens that have been bridged to Arbitrum One. ### Differences between USDC and USDC.e @@ -17,12 +17,12 @@ Arbitrum One supports two different types of USDC: - + - + @@ -54,4 +54,6 @@ The Arbitrum Bridge will continue to facilitate transfers of all USDC tokens. Wh ### Historical context -Arbitrum One has supported Bridged USDC since conception, which previously had over a billion Bridged USDC in circulation. On June 8th 2023, Circle added support for the Cross-Chain Transfer Protocol and launched Arbitrum-native USDC, which enabled direct minting and burning of Arbitrum-Native USDC on Arbitrum One. Due to this, the Bridged USDC token symbol was renamed from USDC to USDC.e to accommodate Arbitrum-native USDC. The expectation is that over time the conversion of Bridged USDC to Arbitrum-native USDC will continue. +The Arbitrum Bridge will continue to facilitate transfers of all USDC tokens. When depositing USDC from Ethereum, the option exists to receive USDC using Circle’s Cross-Chain Transfer Protocol or receive Bridged USDC using Arbitrum’s lock-and-mint bridge. +Historical context +In 2023, Circle launched USDC natively on Arbitrum One and added support for Cross-Chain Transfer Protocol, which enabled direct minting and burning of USDC between Ethereum and Arbitrum One. Due to this, the token symbol for Bridged USDC was renamed to USDC.e to accommodate an ecosystem-wide liquidity migration to native USDC. The expectation is that over time the liquidity migration of USDC.e to USDC will continue. diff --git a/arbitrum-docs/audit-reports.mdx b/arbitrum-docs/audit-reports.mdx index 47b01bc7a..5d6e3bbb0 100644 --- a/arbitrum-docs/audit-reports.mdx +++ b/arbitrum-docs/audit-reports.mdx @@ -1,22 +1,26 @@ # Security Audit Reports -| Auditor | Audit date | Audited code | View report | -| ----------------------- | ---------- | ---------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -| **Trail of Bits** | 10/30/2024 | BoLD contracts in Nitro due to changes to support EIP7702 & Fast Withdrawals | [view](hosted-audit-reports/2024_10_30_trail_of_bits_security_audit_Nitro_Contracts_with_BoLD.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) | -| **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** | 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) | -| **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/01/2024 | Custom fee token | [view](hosted-audit-reports/2024_08_01_trail_of_bits_security_audit_custom_fee_token.pdf) | -| **Trail of Bits** | 07/26/2024 | ArbOS 31 Bianca: Nitro Upgrade | [view](hosted-audit-reports/2024_07_26_trail_of_bits_security_audit_arbos_31.pdf) | -| **Trail of Bits** | 07/26/2024 | ArbOS 30 Atlas: Nitro Upgrade | [view](hosted-audit-reports/2024_07_26_trail_of_bits_security_audit_arbos30_nitro_upgrade.pdf) | -| **Code4rena** | 06/17/2024 | Arbitrum BoLD: Public Audit Competition Report | [view](hosted-audit-reports/2024_06_17_code4arena_security_audit_arbos30_nitro_upgrade.pdf) | -| **Trail of Bits** | 06/10/2024 | Arbitrum Stylus | [view](hosted-audit-reports/2024_06_10_trail_of_bits_security_audit_stylus.pdf) | -| **Trail of Bits** | 05/02/2024 | Arbitrum BoLD & Delay Buffer | [view](hosted-audit-reports/2024_05_02_trail_of_bits_security_audit_bold_delay_buffer.pdf) | -| **Chainsecurity** | 03/20/2024 | Nova Fee Router Updates (ArbOS 31) | [view](hosted-audit-reports/2024_08_20_chainsecurity_security_audit_nova_fee_router_update_arbos_31.pdf) | -| **Trail of Bits** | 03/18/2024 | l1-l3-teleporter | [view](hosted-audit-reports/2024_03_18_trail_of_bits_security_audit_l1_l3_teleporter.pdf) | -| **Trail of Bits** | 01/06/2023 | Governance & Token Bridge | [view](hosted-audit-reports/2023_06_23_trail_of_bits_security_audit_governance_report_governance_token_bridge.pdf) | -| **Trail of Bits** | 10/10/2022 | Nitro Node & Core Contracts, 2 of 2 | [view](hosted-audit-reports/2022_10_22_trail_of_bits_security_audit_nitro_2_of_2.pdf) | -| **ConsenSys Diligence** | 06/24/2022 | Nitro Node & Core Contracts | [view](hosted-audit-reports/2024_06_24_consensys_diligence_security_audit_nitro_contracts.pdf) | -| **Trail of Bits** | 03/14/2022 | Nitro Node & Core Contracts, 1 of 2 | [view](hosted-audit-reports/2022_03_14_trail_of_bits_security_audit_nitro_1_of_2.pdf) | -| **ConsenSys Diligence** | 11/05/2021 | Core Contracts, Token Bridge | [view](hosted-audit-reports/2021_11_05_consensys_diligence_security_audit_core_contracts_token_bridge.pdf) | +| Auditor | Audit date (MM/DD/YYY) | Audited code | View report | +| ----------------------- | ---------------------- | ----------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | +| **Trail of Bits** | 10/30/2024 | Changes to BoLD Solidity contracts to support EIP7702 & Fast Withdrawals | [view](hosted-audit-reports/2024_10_30_trail_of_bits_security_audit_Nitro_Contracts_with_BoLD.pdf) | +| **Trail of Bits** | 10/23/2024 | ArbOS 32 Bianca: Emergency Stylus Fixes | [view](hosted-audit-reports/2024_10_23_trail_of_bits_security_audit_arbos32_emergency_fixes.pdf) | +| **Trail of Bits** | 10/07/2024 | Optimizations to BoLD history commitments | [view](hosted-audit-reports/2024_10_07_trail_of_bits_security_audit_bold_optimized_history_commitments.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) | +| **Open Zeppelin** | 09/05/2024 | Initial Stylus Rust SDK audit | [view](hosted-audit-reports/2024_09_05_open_zeppelin_security_audit_stylus_rust_sdk.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) | +| **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/05/2024 | BoLD contract fixes from the May 2024 audit & DAC reward updates | [view](hosted-audit-reports/2024_08_05_trail_of_bits_security_audit_bold_and_dac_rewards_updates.pdf) | +| **Trail of Bits** | 08/01/2024 | Custom fee token | [view](hosted-audit-reports/2024_08_01_trail_of_bits_security_audit_custom_fee_token.pdf) | +| **Trail of Bits** | 07/26/2024 | ArbOS 31 Bianca: Nitro Upgrade | [view](hosted-audit-reports/2024_07_26_trail_of_bits_security_audit_arbos_31.pdf) | +| **Trail of Bits** | 07/26/2024 | ArbOS 30 Atlas: Nitro Upgrade | [view](hosted-audit-reports/2024_07_26_trail_of_bits_security_audit_arbos30_nitro_upgrade.pdf) | +| **Code4rena** | 06/17/2024 | Arbitrum BoLD: Public Audit Competition Report | [view](hosted-audit-reports/2024_06_17_code4arena_security_audit_arbos30_nitro_upgrade.pdf) | +| **Trail of Bits** | 06/10/2024 | Arbitrum Stylus | [view](hosted-audit-reports/2024_06_10_trail_of_bits_security_audit_stylus.pdf) | +| **Trail of Bits** | 05/02/2024 | BoLD contract fixes from the Aug 2023 audit & Delay Buffer changes to the sequencer inbox | [view](hosted-audit-reports/2024_05_02_trail_of_bits_security_audit_bold_delay_buffer.pdf) | +| **Chainsecurity** | 03/20/2024 | Nova Fee Router Updates (ArbOS 31) | [view](hosted-audit-reports/2024_08_20_chainsecurity_security_audit_nova_fee_router_update_arbos_31.pdf) | +| **Trail of Bits** | 03/18/2024 | l1-l3-teleporter | [view](hosted-audit-reports/2024_03_18_trail_of_bits_security_audit_l1_l3_teleporter.pdf) | +| **Trail of Bits** | 08/02/2023 | Arbitrum BoLD - initial audit (then called challenge protocol v2) | [view](hosted-audit-reports/2023_08_02_trail_of_bits_security_audit_challenge_protocol_v2.pdf) | +| **Trail of Bits** | 01/06/2023 | Governance & Token Bridge | [view](hosted-audit-reports/2023_06_23_trail_of_bits_security_audit_governance_report_governance_token_bridge.pdf) | +| **Trail of Bits** | 10/10/2022 | Nitro Node & Core Contracts, 2 of 2 | [view](hosted-audit-reports/2022_10_22_trail_of_bits_security_audit_nitro_2_of_2.pdf) | +| **ConsenSys Diligence** | 06/24/2022 | Nitro Node & Core Contracts | [view](hosted-audit-reports/2024_06_24_consensys_diligence_security_audit_nitro_contracts.pdf) | +| **Trail of Bits** | 03/14/2022 | Nitro Node & Core Contracts, 1 of 2 | [view](hosted-audit-reports/2022_03_14_trail_of_bits_security_audit_nitro_1_of_2.pdf) | +| **ConsenSys Diligence** | 11/05/2021 | Core Contracts, Token Bridge | [view](hosted-audit-reports/2021_11_05_consensys_diligence_security_audit_core_contracts_token_bridge.pdf) | diff --git a/arbitrum-docs/bold/concepts/bold-technical-deep-dive.mdx b/arbitrum-docs/bold/concepts/bold-technical-deep-dive.mdx index 7b656d60f..a27a7684c 100644 --- a/arbitrum-docs/bold/concepts/bold-technical-deep-dive.mdx +++ b/arbitrum-docs/bold/concepts/bold-technical-deep-dive.mdx @@ -198,17 +198,17 @@ To create a challenge, there must be a fork in the Arbitrum assertion chain smar Challenge bonds are named as such because they are bonds required for opening challenges. The mechanism of how challenge bond economics are decided is contained in the -[Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.md), which also explains +[Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.mdx), which also explains the cost profile and spam prevention in BoLD. In short, the actual cost of a bond encompasses many costs associated with participating in the dispute game. More information on the bond sizes and how they were -calculated can be found in the [Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.md) +calculated can be found in the [Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.mdx) document mentioned above. Each subchallenge that is created requires depositing a challenge bond. For Arbitrum One, the first unrivaled edge’s bond is kept in the challenge manager contract on Ethereum, while any subsequent rival bonds are kept in an excess bond receiver address. Once a challenge is complete, all bonds for an honest party are automatically refunded in-protocol while all confiscated bonds are sent to the ArbitrumDAO treasury. It is important to not offer the majority of the bonds confiscated from dishonest parties to honest parties to avoid perverse incentives, such as grieving attacks in self-challenges or to discourage needless competition between honest parties. ### Reimbursements of bonds -The reimbursement of assertion bonds and challenge bonds for honest parties will be handled “in-band” by the protocol. Please see [Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.md) for more information about this topic. +The reimbursement of assertion bonds and challenge bonds for honest parties will be handled “in-band” by the protocol. Please see [Economics of Disputes](../../how-arbitrum-works/bold/bold-economics-of-disputes.mdx) for more information about this topic. ### Upgrade mechanism diff --git a/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx b/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx index 9b1a57167..239b48450 100644 --- a/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx +++ b/arbitrum-docs/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx @@ -8,7 +8,7 @@ content_type: quickstart :::info Want to use Rust instead? -Head over to [the Stylus quickstart](/stylus/stylus-quickstart) if you'd like to use Rust instead of Solidity. +Head over to [the Stylus quickstart](/stylus/quickstart) if you'd like to use Rust instead of Solidity. ::: @@ -456,7 +456,7 @@ Select `Arbitrum Sepolia` from Metamask's dropdown, paste your contract address Now that we've verified that our smart contract works on Arbitrum's Sepolia testnet, we're ready to deploy it to Arbitrum One Mainnet. This is the same process as deploying to Arbitrum's Sepolia testnet, except that we'll need to pay a transaction fee in real $ETH instead of $ASPL. -Expect to see inconsistent $ETH gas fees in this step - the [Gas and fees section](/how-arbitrum-works/gas-fees.md) contains more information about how gas fees are determined for Arbitrum transactions. +Expect to see inconsistent $ETH gas fees in this step - the [Gas and fees section](/how-arbitrum-works/gas-fees.mdx) contains more information about how gas fees are determined for Arbitrum transactions. @@ -513,7 +513,7 @@ If you have any questions or feedback, reach out to us on [Discord](https://disc - Visit [How to estimate gas](/build-decentralized-apps/02-how-to-estimate-gas.mdx) to learn how to estimate the gas cost of your smart contract transactions. -- Visit [RPC endpoints and providers](/build-decentralized-apps/reference/01-node-providers.mdx#rpc-endpoints) for a list of public chains that you can deploy your smart contracts to. +- Visit [RPC endpoints and providers](/build-decentralized-apps/reference/01-node-providers.mdx) for a list of public chains that you can deploy your smart contracts to. [^1]: The vending machine example was inspired by [Ethereum.org's "Introduction to Smart Contracts"](https://ethereum.org/en/developers/docs/smart-contracts/), which was inspired by [Nick Szabo's "From vending machines to smart contracts"](http://unenumerated.blogspot.com/2006/12/from-vending-machines-to-smart.html). [^2]: Although application front-ends are usually hosted by centralized services, smart contracts allow the underlying logic and data to be partially or fully decentralized. These smart contracts are hosted and executed by Ethereum's public, decentralized network of nodes. Arbitrum has its own network of nodes that use advanced cryptography techniques to "batch process" Ethereum transactions and then submit them to Ethereum L1, which significantly reduces the cost of using Ethereum. All without requiring developers to compromise on security or decentralization. diff --git a/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx b/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx index c496c2c3f..1e449f6e5 100644 --- a/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx +++ b/arbitrum-docs/build-decentralized-apps/02-how-to-estimate-gas.mdx @@ -11,7 +11,7 @@ Head over to [the Stylus gas docs](/stylus/reference/opcode-hostio-pricing) for ::: -This how-to is intended for users and developers interested in understanding how gas operates in Arbitrum, how it's calculated, and how to estimate it before submitting transactions. More detailed information about these calculations can be found in this [Medium article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the [Gas and Fees](/how-arbitrum-works/gas-fees.md) page. +This how-to is intended for users and developers interested in understanding how gas operates in Arbitrum, how it's calculated, and how to estimate it before submitting transactions. More detailed information about these calculations can be found in this [Medium article](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) and the [Gas and Fees](/how-arbitrum-works/gas-fees.mdx) page. ## Skip the formula, focus on practical know-how @@ -21,7 +21,7 @@ Multiplying the value obtained from `eth_estimateGas` by the L2 gas price will g Alternatively, to obtain the gas limit for your transaction, you can call `NodeInterface.gasEstimateComponents()` and then use the first result, which is `gasEstimate`. Next, to find the total cost, you need to multiply this amount by the L2 gas price, which is available in the third result, `baseFee`. -Note that when working with L1 to L2 messages (also known as [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.md)), you can use the function [L1ToL2MessageGasEstimator.estimateAll()](https://github.com/OffchainLabs/arbitrum-sdk/blob/main/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) of the Arbitrum SDK or [NodeInterface.estimateRetryableTicket()](https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction. +Note that when working with L1 to L2 messages (also known as [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.mdx)), you can use the function [L1ToL2MessageGasEstimator.estimateAll()](https://github.com/OffchainLabs/arbitrum-sdk/blob/main/src/lib/message/L1ToL2MessageGasEstimator.ts#L215) of the Arbitrum SDK or [NodeInterface.estimateRetryableTicket()](https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/nodeInterface/NodeInterface.go#L120) to get all the gas information needed to send a successful transaction. ## Breaking down the formula @@ -35,7 +35,7 @@ As explained in the Medium article, the transaction fees to pay at any given mom Transaction fees (TXFEES) = L2 Gas Price (P) * Gas Limit (G) ``` -This Gas Limit includes the gas of the L2 computation and an additional buffer to cover the L1 gas to be paid by the Sequencer when [posting the batch including this transaction on L1](/how-arbitrum-works/inside-arbitrum-nitro.md#how-the-sequencer-publishes-the-sequence). +This Gas Limit includes the gas of the L2 computation and an additional buffer to cover the L1 gas to be paid by the Sequencer when [posting the batch including this transaction on L1](/how-arbitrum-works/inside-arbitrum-nitro.mdx#how-the-sequencer-publishes-the-sequence). ``` Gas Limit (G) = Gas used on L2 (L2G) + Extra Buffer for L1 cost (B) @@ -46,7 +46,7 @@ This buffer takes into account the cost of posting the transaction, batched and - L1S, which estimates the amount of data the transaction will take up in the batch by compressing the transaction with Brotli. - L1P, which is the L2's estimated view of the current L1's price of data (per byte), which the L2 dynamically adjusts over time. -More information is available [in this page](/how-arbitrum-works/l1-gas-pricing.md). +More information is available [in this page](/how-arbitrum-works/l1-gas-pricing.mdx). ``` L1 Estimated Cost (L1C) = L1 price per byte of data (L1P) * Size of data to be posted in bytes (L1S) @@ -75,7 +75,7 @@ We'll use one resource available in Arbitrum: the [NodeInterface](/build-decentr - L1P (L1 estimated price per byte of data) ⇒ Estimated cost of posting 1 byte of data on L1: - Call `NodeInterface.GasEstimateComponents()`, get the fourth element `l1BaseFeeEstimate` and multiply it by 16. - L1S (Size of data to be posted on L1, in bytes) ⇒ This will depend on the data of the transaction. Keep in mind that Arbitrum adds a fixed amount to this number to make up for the static part of the transaction, which is also posted on L1 (140 bytes). We can do a small calculation to obtain this value: call `NodeInterface.GasEstimateComponents()` take the second element, `gasEstimateForL1` (this is equivalent to `B` in our formula), multiply it by P and divide it by L1P. - - For Arbitrum Nova (AnyTrust), the size of the data is also a fixed value, as only the Data Availability Certificate is posted on L1, [as explained here](/how-arbitrum-works/inside-anytrust.md#data-availability-certificates). + - For Arbitrum Nova (AnyTrust), the size of the data is also a fixed value, as only the Data Availability Certificate is posted on L1, [as explained here](/how-arbitrum-works/inside-anytrust.mdx#data-availability-certificates). (Note: for L1P and L1S, you can also call `NodeInterface.gasEstimateL1Component()` to get `l1BaseFeeEstimate` and `gasEstimateForL1`) diff --git a/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx b/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx index c2ac5e4cf..cc2925b0f 100644 --- a/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx +++ b/arbitrum-docs/build-decentralized-apps/03-public-chains.mdx @@ -13,11 +13,11 @@ Arbitrum chains are Layer 2 solutions built on top of the Ethereum blockchain, d ### Arbitrum One -**Arbitrum One** is a Layer 2 (L2) optimistic rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's Layer 1 (L1) chain. It lets you build high-performance Ethereum dApps with low transaction costs and Ethereum-grade security guarantees, introducing no additional trust assumptions. This is made possible by the [Nitro](/how-arbitrum-works/inside-arbitrum-nitro.md) technology stack, a "Geth-at-the-core" architecture that gives Arbitrum One (and Nova) advanced calldata compression, separate contexts for common execution and fault proving, Ethereum L1 gas compatibility, and more. +**Arbitrum One** is a Layer 2 (L2) optimistic rollup chain that implements the Arbitrum Rollup protocol and settles to Ethereum's Layer 1 (L1) chain. It lets you build high-performance Ethereum dApps with low transaction costs and Ethereum-grade security guarantees, introducing no additional trust assumptions. This is made possible by the [Nitro](/how-arbitrum-works/inside-arbitrum-nitro.mdx) technology stack, a "Geth-at-the-core" architecture that gives Arbitrum One (and Nova) advanced calldata compression, separate contexts for common execution and fault proving, Ethereum L1 gas compatibility, and more. ### Arbitrum Nova -**Arbitrum Nova** is a high-performance alternative to Arbitrum One's chain. While Arbitrum One implements the purely trustless Rollup protocol, Arbitrum Nova implements the mostly trustless [AnyTrust](/how-arbitrum-works/inside-anytrust.md) protocol. They key difference between Rollup and AnyTrust is that the AnyTrust protocol introduces an additional trust assumption in the form of a data availability committee (DAC). This committee (detailed below) is responsible for expediting the process of storing, batching, and posting L2 transaction data to Ethereum's L1. This lets you use Arbitrum in scenarios that demand performance and affordability, while Arbitrum One is optimal for scenarios that demand Ethereum's pure trustlessness. +**Arbitrum Nova** is a high-performance alternative to Arbitrum One's chain. While Arbitrum One implements the purely trustless Rollup protocol, Arbitrum Nova implements the mostly trustless [AnyTrust](/how-arbitrum-works/inside-anytrust.mdx) protocol. They key difference between Rollup and AnyTrust is that the AnyTrust protocol introduces an additional trust assumption in the form of a data availability committee (DAC). This committee (detailed below) is responsible for expediting the process of storing, batching, and posting L2 transaction data to Ethereum's L1. This lets you use Arbitrum in scenarios that demand performance and affordability, while Arbitrum One is optimal for scenarios that demand Ethereum's pure trustlessness. ## What Arbitrum testnet chains are available? @@ -57,11 +57,11 @@ Finally, Arbitrum Sepolia is a testnet chain. It's designed for testing purposes ### Nitro -Nitro is the technology that powers Arbitrum One, Arbitrum Nova (with AnyTrust configuration),and Arbitrum Sepolia. It's designed to offer high throughput and low cost, making it ideal for scaling Ethereum applications. Nitro is a major upgrade to the “Classic” stack, offering several improvements including advanced calldata compression, separate contexts for common execution and fault proving, Ethereum L1 gas compatibility, and more. You can find more information about Nitro in [Inside Arbitrum Nitro](/how-arbitrum-works/inside-arbitrum-nitro.md). +Nitro is the technology that powers Arbitrum One, Arbitrum Nova (with AnyTrust configuration),and Arbitrum Sepolia. It's designed to offer high throughput and low cost, making it ideal for scaling Ethereum applications. Nitro is a major upgrade to the “Classic” stack, offering several improvements including advanced calldata compression, separate contexts for common execution and fault proving, Ethereum L1 gas compatibility, and more. You can find more information about Nitro in [Inside Arbitrum Nitro](/how-arbitrum-works/inside-arbitrum-nitro.mdx). ### AnyTrust (variant of Nitro) -AnyTrust is a variant of the Nitro technology stack that lowers costs by accepting a mild trust assumption. The AnyTrust protocol relies on an external Data Availability Committee (DAC) to store data and provide it on demand. The DAC has N members, of which AnyTrust assumes at least two are honest. Keeping the data off-chain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.md). +AnyTrust is a variant of the Nitro technology stack that lowers costs by accepting a mild trust assumption. The AnyTrust protocol relies on an external Data Availability Committee (DAC) to store data and provide it on demand. The DAC has N members, of which AnyTrust assumes at least two are honest. Keeping the data off-chain in the happy/common case means the system can charge the user significantly lower fees. You can find more information about AnyTrust in [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.mdx). ### Classic (deprecated) diff --git a/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx b/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx index fc47d1af5..03e3b72a5 100644 --- a/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx +++ b/arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx @@ -11,7 +11,7 @@ The Arbitrum protocol and related tooling makes it easy for developers to build Arbitrary L1 to L2 contract calls can be created via the `Inbox`'s `createRetryableTicket` method; upon publishing the L1 transaction, the L2 side will typically get included within minutes. Happily / commonly, the L2 execution will automatically succeed, but if reverts, and it can be rexecuted via a call to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile. -For details and protocol specification, see [L1 to L2 Messages](/how-arbitrum-works/arbos/l1-l2-messaging.md). +For details and protocol specification, see [L1 to L2 Messages](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). For an example of retryable tickets in action, see the [Greeter](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/greeter) tutorial, which uses the [Arbitrum SDK](../sdk/1-introduction.mdx). @@ -19,6 +19,6 @@ For an example of retryable tickets in action, see the [Greeter](https://github. Similarly, L2 contracts can send Arbitrary messages for execution on L1. These are initiated via calls to the [ArbSys](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile contract's `sendTxToL1` method. Upon confirmation (about 1 week later), they can executed by retrieving the relevant data via a call to `NodeInterface` contract's `constructOutboxProof` method, and then executing them via the `Outbox`'s `executeTransaction` method. -For details and protocol specification, see [L2 to L1 Messages](/how-arbitrum-works/arbos/l2-l1-messaging.md). +For details and protocol specification, see [L2 to L1 Messages](/how-arbitrum-works/arbos/l2-l1-messaging.mdx). For a demo, see the [Outbox Tutorial](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/outbox-execute). diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx index 09b112dfd..1b1389eb6 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx @@ -26,13 +26,13 @@ You can deploy Solidity contracts onto Arbitrum just like you do Ethereum. There ## Fees -The fees an Arbitrum transaction pays for execution essentially work identically to gas fees on Ethereum. Arbitrum transactions must also, however, pay a fee component to cover the cost of posting their calldata to the parent chain (for example, calldata on Arbitrum One, an L2, is posted to Ethereum, an L1). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/gas-fees.md) and [L1 pricing](/how-arbitrum-works/l1-gas-pricing.md). +The fees an Arbitrum transaction pays for execution essentially work identically to gas fees on Ethereum. Arbitrum transactions must also, however, pay a fee component to cover the cost of posting their calldata to the parent chain (for example, calldata on Arbitrum One, an L2, is posted to Ethereum, an L1). Find more information about the two components of gas fees in [Gas and fees](/how-arbitrum-works/gas-fees.mdx) and [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx). ## Cross-chain messaging -Arbitrum chains support arbitrary message passing from a parent chain (for example, a Layer 1 (L1) like Ethereum) to a child chain (for example, a Layer 2 (L2) like Arbitrum One or Arbitrum Nova). These are commonly known as "L1 to L2 messages". Developers using this functionality should familiarize themselves with how they work. Find more information about it in [L1 to L2 messaging](/how-arbitrum-works/arbos/l1-l2-messaging.md). +Arbitrum chains support arbitrary message passing from a parent chain (for example, a Layer 1 (L1) like Ethereum) to a child chain (for example, a Layer 2 (L2) like Arbitrum One or Arbitrum Nova). These are commonly known as "L1 to L2 messages". Developers using this functionality should familiarize themselves with how they work. Find more information about it in [L1 to L2 messaging](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). -Similarly, Arbitrum chains can also send messages to the parent chain. Find more information about them in [L2 to L1 messaging and the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.md). +Similarly, Arbitrum chains can also send messages to the parent chain. Find more information about them in [L2 to L1 messaging and the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx). ## Precompiles diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx index b9bc36f6a..00b92cc6d 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx @@ -13,7 +13,7 @@ With the release of Arbitrum Orbit, Arbitrum chains can now be L2s that settle t ::: -As in Ethereum, Arbitrum clients submit transactions, and the system executes those transactions at some later time. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the sequencer](/how-arbitrum-works/sequencer.md#happycommon-case-sequencer-is-live-and-well-behaved) or via the chain's [delayed inbox](/how-arbitrum-works/sequencer.md#unhappyuncommon-case-sequencer-isnt-doing-its-job). +As in Ethereum, Arbitrum clients submit transactions, and the system executes those transactions at some later time. In Arbitrum, clients submit transactions by posting messages to the Ethereum chain, either [through the sequencer](/how-arbitrum-works/sequencer.mdx#happycommon-case-sequencer-is-live-and-well-behaved) or via the chain's [delayed inbox](/how-arbitrum-works/sequencer.mdx#unhappyuncommon-case-sequencer-isnt-doing-its-job). Once in the chain's core inbox contract, transactions are processed in order. Generally, some time will elapse between when a message is put into the inbox (and timestamped) and when the contract processes the message and carries out the transaction requested by the message. diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx index 45ce7b82e..b24a68c8c 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/03-rpc-methods.mdx @@ -21,18 +21,18 @@ When calling [`eth_getTransactionByHash`](https://ethereum.org/en/developers/doc ### Transaction types -In addition to the [three transaction types](https://ethereum.org/en/developers/docs/transactions/#types-of-transactions) currently supported on Ethereum, Arbitrum adds additional types listed below and [documented in full detail here](/how-arbitrum-works/arbos/geth.md#transaction-types). +In addition to the [three transaction types](https://ethereum.org/en/developers/docs/transactions/#types-of-transactions) currently supported on Ethereum, Arbitrum adds additional types listed below and [documented in full detail here](/how-arbitrum-works/arbos/geth.mdx#transaction-types). On RPC calls that return transactions, the `type` field will reflect the custom codes where applicable. -| Transaction type code | Transaction type name | Description | -| --------------------- | ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `100` | `ArbitrumDepositTxType` | Used to deposit ETH from L1 to L2 via the Arbitrum bridge | -| `101` | `ArbitrumUnsignedTxType` | Used to call an L2 contract from L1, originated by a user through the Arbitrum bridge | -| `102` | `ArbitrumContractTxType` | Used to call an L2 contract from L1, originated by a contract through the Arbitrum bridge | -| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.md) on L2 that failed to execute automatically (usually due to low gas) | -| `105` | `ArbitrumSubmitRetryableTxType` | Used to [submit a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.md#submission) via the Arbitrum bridge on L1 | -| `106` | `ArbitrumInternalTxType` | Internal transactions created by the ArbOS itself for certain state updates, like the L1 base fee and the block number | +| Transaction type code | Transaction type name | Description | +| --------------------- | ------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| `100` | `ArbitrumDepositTxType` | Used to deposit ETH from L1 to L2 via the Arbitrum bridge | +| `101` | `ArbitrumUnsignedTxType` | Used to call an L2 contract from L1, originated by a user through the Arbitrum bridge | +| `102` | `ArbitrumContractTxType` | Used to call an L2 contract from L1, originated by a contract through the Arbitrum bridge | +| `104` | `ArbitrumRetryTxType` | Used to [manually redeem a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) on L2 that failed to execute automatically (usually due to low gas) | +| `105` | `ArbitrumSubmitRetryableTxType` | Used to [submit a retryable ticket](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#submission) via the Arbitrum bridge on L1 | +| `106` | `ArbitrumInternalTxType` | Internal transactions created by the ArbOS itself for certain state updates, like the L1 base fee and the block number | ### Additional fields @@ -46,9 +46,9 @@ On RPC calls that return transactions, the following fields are added to the ret On RPC calls that return transactions, the following fields will have a different content than what's received on Ethereum. -| Field name | Description | -| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| `from` | On L1 to L2 transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/arbos/l1-l2-messaging.md#address-aliasing) of the L1's `msg.sender` | +| Field name | Description | +| ---------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ | +| `from` | On L1 to L2 transactions, this field will contain the [_aliased_ version](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#address-aliasing) of the L1's `msg.sender` | ## Transaction receipts @@ -61,7 +61,7 @@ On RPC calls that return transaction receipts, the following fields are added to | Field name | Description | | --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `l1BlockNumber` | The L1 block number that would be used for `block.number` calls. More information in [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx) | -| `gasUsedForL1` | Amount of gas spent on L1 calldata in units of L2 gas. More information in [Gas and fees](/how-arbitrum-works/gas-fees.md) | +| `gasUsedForL1` | Amount of gas spent on L1 calldata in units of L2 gas. More information in [Gas and fees](/how-arbitrum-works/gas-fees.mdx) | ## Blocks @@ -134,14 +134,14 @@ Note that if the sync process encounters an error while trying to collect the da ### `debug_traceTransaction` -The Nitro node provides a native tracer for debugging Stylus contracts called `stylusTracer`, which returns a JSON array with objects containing the metadata for each executed HostIO. -HostIOs are calls the WasmVM makes to read and write data in the EVM. -With the result of this tracer and the code for the Stylus contract, you have all the data to understand what happened in a Stylus transaction. +- [ ] The Nitro node provides a native tracer for debugging Stylus contracts called `stylusTracer`, which returns a JSON array with objects containing the metadata for each executed HostIO. + HostIOs are calls the WasmVM makes to read and write data in the EVM. + With the result of this tracer and the code for the Stylus contract, you have all the data to understand what happened in a Stylus transaction. :::info The `cargo-stylus` command-line tool uses the `stylusTracer` to replay transactions locally inside a debugger. -More information can be found on [How to debug Stylus transactions using Cargo Stylus Replay](/stylus/how-tos/debugging-stylus-tx). +More information can be found on [How to debug Stylus transactions using Cargo Stylus Replay](/stylus/how-tos/debugging-tx). ::: diff --git a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx index 3f0533117..8730e9eba 100644 --- a/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx +++ b/arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/04-solidity-support.mdx @@ -22,5 +22,5 @@ Although Arbitrum supports Solidity code, there are differences in the effects o | `block.difficulty` | Returns the constant 1. | | `block.prevrandao` | Returns the constant 1. | | `block.number` | Returns an "estimate" of the L1 block number at which the sequencer received the transaction. For more information, see [Block numbers and time](/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx). | -| `msg.sender` | Works the same way it does on Ethereum for regular L2 to L2 transactions. For transactions submitted via the delayed inbox, it will return the L2 address alias of the L1 contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/arbos/l1-l2-messaging.md#address-aliasing). | +| `msg.sender` | Works the same way it does on Ethereum for regular L2 to L2 transactions. For transactions submitted via the delayed inbox, it will return the L2 address alias of the L1 contract that triggered the message. For more information, see [address aliasing](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#address-aliasing). | | OPCODE `PUSH0` | This OPCODE was added as part of ArbOS 11 and is now supported. | diff --git a/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx b/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx index 7749b3326..37edc16a3 100644 --- a/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx +++ b/arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx @@ -179,7 +179,7 @@ import ArbOwnerPublicRef from '../../for-devs/dev-tools-and-resources/partials/p ### ArbRetryableTx -ArbRetryableTx ([Interface][arbretryabletx_link_interface] | [Implementation][arbretryabletx_link_implementation]) provides methods for managing retryables. The model has been adjusted for Nitro, most notably in terms of how retry transactions are scheduled. For more information on retryables, please see [the retryable documentation](/how-arbitrum-works/arbos/introduction.md#Retryables). +ArbRetryableTx ([Interface][arbretryabletx_link_interface] | [Implementation][arbretryabletx_link_implementation]) provides methods for managing retryables. The model has been adjusted for Nitro, most notably in terms of how retry transactions are scheduled. For more information on retryables, please see [the retryable documentation](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets). Precompile address: `0x000000000000000000000000000000000000006E` diff --git a/arbitrum-docs/build-decentralized-apps/reference/06-monitoring-tools-block-explorers.mdx b/arbitrum-docs/build-decentralized-apps/reference/06-monitoring-tools-block-explorers.mdx index e9cbe1d4c..965f2af47 100644 --- a/arbitrum-docs/build-decentralized-apps/reference/06-monitoring-tools-block-explorers.mdx +++ b/arbitrum-docs/build-decentralized-apps/reference/06-monitoring-tools-block-explorers.mdx @@ -11,11 +11,11 @@ import KnowMoreToolsBox from '../../for-devs/partials/_know-more-tools-box-parti Here, we offer a compilation of tools and blockchain explorers that enable you to examine and oversee transactions, smart contracts, and overall blockchain activity related to decentralized applications (dApps) on different Arbitrum chains. -| Tool | Use-cases | Relevant links | -| ---------- | ---------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -| Arbiscan | Track/trace transactions and examine addresses on Arbitrum networks | | -| Blockscout | Track/trace transactions and examine addresses on Arbitrum networks | | -| Chainbase | Index, transform, and use on-chain data at scale | [Chainbase](https://chainbase.com/) | -| DexGuru | Track/trace transactions and examine addresses on Arbitrum networks | | -| Dune | Visualize and analyze Arbitrum network data | | -| OKLINK | Track/trace transactions and examine addresses on Arbitrum One network | | +| Tool | Use-cases | Relevant links | +| ---------- | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | +| Arbiscan | Track/trace transactions and examine addresses on Arbitrum networks | | +| Blockscout | Track/trace transactions and examine addresses on Arbitrum networks | | +| Chainbase | Index, transform, and use on-chain data at scale | [Chainbase](https://chainbase.com/) | +| DexGuru | Track/trace transactions and examine addresses on Arbitrum networks | | +| Dune | Visualize and analyze Arbitrum network data | | +| OKLINK | Track/trace transactions and examine addresses on Arbitrum One network | | diff --git a/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx b/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx index 1e094cb41..abe6452a1 100644 --- a/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx +++ b/arbitrum-docs/build-decentralized-apps/reference/08-mainnet-risks.mdx @@ -6,7 +6,7 @@ author: dzgoldman # Arbitrum: Understanding the risks -Arbitrum One — the first permissionless Ethereum layer 2 rollup with full Ethereum smart contract functionality — is [live on mainnet](https://offchain.medium.com/mainnet-for-everyone-27ce0f67c85e) — as is [Nova](https://medium.com/offchainlabs/its-time-for-a-new-dawn-nova-is-open-to-the-public-a081df1e4ad2), our first [AnyTrust chain](/how-arbitrum-works/inside-anytrust.md); We're sure you're (almost) as excited as we are! +Arbitrum One — the first permissionless Ethereum layer 2 rollup with full Ethereum smart contract functionality — is [live on mainnet](https://offchain.medium.com/mainnet-for-everyone-27ce0f67c85e) — as is [Nova](https://medium.com/offchainlabs/its-time-for-a-new-dawn-nova-is-open-to-the-public-a081df1e4ad2), our first [AnyTrust chain](/how-arbitrum-works/inside-anytrust.mdx); We're sure you're (almost) as excited as we are! Here are some risks you should know about before using the system: ### State Of progressive decentralization @@ -16,7 +16,7 @@ The Arbitrum DAO system is the owner of both the Arbitrum One and Arbitrum AnyTr ### General words of caution: Software bugs Offchain Labs’ [implementation](https://github.com/OffchainLabs/nitro) of the Arbitrum protocol has been carefully constructed, is perpetually being audited by several independent firms, and is continuously reviewed and tested following best engineering practices. -That said, there remains a non-zero chance that our codebase contains some undiscovered vulnerabilities that put user funds at risk. Users should carefully factor this risk into their decision to use Arbitrum One and/or Arbitrum Nova, and in deciding how much of their value to entrust into the system. Note that Offchain Labs also sponsors a [multi-million dollar bug bounty program](https://immunefi.com/bounty/arbitrum/) to incentivize any party who funds such a critical bug to disclose it responsibly. +That said, there remains a non-zero chance that our codebase contains some undiscovered vulnerabilities that put user funds at risk. Users should carefully factor this risk into their decision to use Arbitrum One and/or Arbitrum Nova, and in deciding how much of their value to entrust into the system. Note that Offchain Labs also sponsors a [multi-million dollar bug bounty program](https://immunefi.com/bounty/arbitrum/) to incentivize any party who finds such a critical bug to disclose it responsibly. ### General words of caution: Scams diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.md b/arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.mdx similarity index 82% rename from arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.md rename to arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.mdx index 034c72fae..46f4fe575 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.md +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/01-overview.mdx @@ -13,6 +13,6 @@ This section offers a series of conceptual documents explaining how asset bridgi This section is divided in 3 parts: -- [ETH bridging](/build-decentralized-apps/token-bridging/02-token-bridge-ether.md): explains how Arbitrum handles bridging ETH, the native token of Ethereum and the Arbitrum chains, between L1 and L2. -- [ERC-20 token bridging](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md): explains the architecture of the token bridge for this type of asset, describing the different options available to make a token bridgeable. +- [ETH bridging](/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx): explains how Arbitrum handles bridging ETH, the native token of Ethereum and the Arbitrum chains, between L1 and L2. +- [ERC-20 token bridging](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx): explains the architecture of the token bridge for this type of asset, describing the different options available to make a token bridgeable. - [Bridge tokens programmatically](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx): goes over the process of making an ERC-20 token bridgeable using the different types of gateway available in the token bridge. diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.md b/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx similarity index 94% rename from arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.md rename to arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx index 69863b353..a17c9c0d5 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.md +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.mdx @@ -36,7 +36,7 @@ ArbSys(100).withdrawEth{ value: 2300000 }(destAddress) Upon withdrawing, the Ether balance is burnt on the Arbitrum side, and will later be made available on the Ethereum side. -`ArbSys.withdrawEth` is actually a convenience function which is equivalent to calling `ArbSys.sendTxToL1` with empty calldataForL1. Like any other `sendTxToL1` call, it will require an additional call to `Outbox.executeTransaction` on L1 after the dispute period elapses for the user to finalize claiming their funds on L1 (see ["L2 to L1 Messages"](/how-arbitrum-works/arbos/l2-l1-messaging.md)). Once the withdrawal is executed from the Outbox, the user's Ether balance will be credited on L1. +`ArbSys.withdrawEth` is actually a convenience function which is equivalent to calling `ArbSys.sendTxToL1` with empty calldataForL1. Like any other `sendTxToL1` call, it will require an additional call to `Outbox.executeTransaction` on L1 after the dispute period elapses for the user to finalize claiming their funds on L1 (see ["L2 to L1 Messages"](/how-arbitrum-works/arbos/l2-l1-messaging.mdx)). Once the withdrawal is executed from the Outbox, the user's Ether balance will be credited on L1. The following diagram depicts the process that funds follow during a withdraw operation. diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md b/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx similarity index 99% rename from arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md rename to arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx index 60a51e557..4cd915dc0 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx @@ -44,11 +44,11 @@ Our architecture consists of three types of contracts: ![img](./assets/gatewayUML.svg) -All Ethereum to Arbitrum token transfers are initiated via the router contract on L1, the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on L1, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping L1 token addresses to L1Gateway contracts, thus acting as an L1/L2 address oracle, and ensuring that each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on L2, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.md)). +All Ethereum to Arbitrum token transfers are initiated via the router contract on L1, the `L1GatewayRouter` contract. `L1GatewayRouter` forwards the token's deposit call to the appropriate gateway contract on L1, the `L1ArbitrumGateway` contract. `L1GatewayRouter` is responsible for mapping L1 token addresses to L1Gateway contracts, thus acting as an L1/L2 address oracle, and ensuring that each token corresponds to only one gateway. The `L1ArbitrumGateway` then communicates to its counterpart gateway contract on L2, the `L2ArbitrumGateway` contract (typically/expectedly via [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.mdx)). ![img](./assets/bridge_deposits.png) -Similarly, Arbitrum to Ethereum transfers are initiated via the router contract on L2, the `L2GatewayRouter` contract, which calls the token's gateway contract on L2, the `L2ArbitrumGateway` contract, which in turn communicates to its corresponding gateway contract on L1, the `L1ArbitrumGateway` contract (typically/expectedly via [sending L2-to-L1 messages to the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.md)). +Similarly, Arbitrum to Ethereum transfers are initiated via the router contract on L2, the `L2GatewayRouter` contract, which calls the token's gateway contract on L2, the `L2ArbitrumGateway` contract, which in turn communicates to its corresponding gateway contract on L1, the `L1ArbitrumGateway` contract (typically/expectedly via [sending L2-to-L1 messages to the outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx)). ![img](./assets/bridge_withdrawals.png) @@ -106,7 +106,7 @@ Your token on L1 should conform to the [ICustomToken](https://github.com/Offchai Your token should conform to the minimum [IArbToken](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/IArbToken.sol) interface; i.e., it should have `bridgeMint` and `bridgeBurn` methods only callable by the L2CustomGateway contract, and the address of its corresponding Ethereum token accessible via `l1Address`. For an example implementation, see [L2GatewayToken](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/libraries/L2GatewayToken.sol). -import TokenCompatibilityPartial from './partials/_token-compatibility.md'; +import TokenCompatibilityPartial from './partials/_token-compatibility.mdx'; diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx index f79990f76..84fc66acb 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx @@ -11,9 +11,9 @@ This section offers a series of how-tos showcasing the different methods availab You have three options to consider when deciding on how to bridge your token: -1. [Standard gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx): opt for this method if you want to have an standard ERC-20 token automatically deployed on Arbitrum, which will act as the L2 counterpart to your L1 token. For additional information, please refer to [this section on the standard ERC-20 gateway in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#default-standard-bridging). -2. [Generic-custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx): choose this method if you require custom functionality for your ERC20 token on Arbitrum. You will deploy your counterpart token on Arbitrum equipped with the unique features you wish to implement. For additional information, please refer to [this section on the Arbitrum generic custom gateway in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#the-arbitrum-generic-custom-gateway). -3. [Custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx): this method is intended for edge cases where a custom ERC20 token is insufficient and you need an additional layer of flexibility with the gateway (for example, your token has the capacity to increase its supply on L2, and you want those L2-minted tokens to be withdrawable back to L1 and recognized by the L1 contract). For additional information, please refer to [this section on other types of gateways in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#other-flavors-of-gateways). +1. [Standard gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx): opt for this method if you want to have an standard ERC-20 token automatically deployed on Arbitrum, which will act as the L2 counterpart to your L1 token. For additional information, please refer to [this section on the standard ERC-20 gateway in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging). +2. [Generic-custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx): choose this method if you require custom functionality for your ERC20 token on Arbitrum. You will deploy your counterpart token on Arbitrum equipped with the unique features you wish to implement. For additional information, please refer to [this section on the Arbitrum generic custom gateway in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway). +3. [Custom gateway](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx): this method is intended for edge cases where a custom ERC20 token is insufficient and you need an additional layer of flexibility with the gateway (for example, your token has the capacity to increase its supply on L2, and you want those L2-minted tokens to be withdrawable back to L1 and recognized by the L1 contract). For additional information, please refer to [this section on other types of gateways in the conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#other-flavors-of-gateways). ## What if I just want to bridge a token programmatically? diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx index 2c5d3e104..f54a4a12e 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/02-how-to-bridge-tokens-standard.mdx @@ -5,9 +5,9 @@ user_story: As a developer, I want to understand how to bridge tokens between Et content_type: how-to --- -In this how-to you’ll learn how to bridge your own token between Ethereum (Layer 1 or L1) and Arbitrum (Layer 2 or L2), using [Arbitrum’s standard ERC20 gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#default-standard-bridging). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx). +In this how-to you’ll learn how to bridge your own token between Ethereum (Layer 1 or L1) and Arbitrum (Layer 2 or L2), using [Arbitrum’s standard ERC20 gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx). -Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.md), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. +Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.mdx), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. We will go through all steps involved in the process. However, if you want to jump straight to the code, we have created [this script in our tutorials repository](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/token-deposit) that encapsulates the entire process. @@ -74,7 +74,7 @@ main() ## Step 2: Identify the bridge contracts to call (concepts summary) -As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#default-standard-bridging), when using Arbitrum’s standard ERC20 gateway, you don’t need to do any pre-configuration process. Your token will be “bridgeable” out of the box. +As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging), when using Arbitrum’s standard ERC20 gateway, you don’t need to do any pre-configuration process. Your token will be “bridgeable” out of the box. As explained in the conceptual page, there are 2 contracts that we need to be aware of when bridging tokens: @@ -83,7 +83,7 @@ As explained in the conceptual page, there are 2 contracts that we need to be aw For simplicity, in this how-to we’ll focus on the first case: bridging from Ethereum (L1) to Arbitrum (L2). -We’ll explain below what specific contracts and methods need to be called to bridge your token, but you can abstract this whole process of finding the right addresses by using Arbitrum’s SDK. You can use the [deposit](../../../sdk/reference/assetBridger/erc20Bridger.md#deposit) function of the [Erc20Bridger](../../../sdk/reference/assetBridger/erc20Bridger.md) class to bridge your tokens, which will use the appropriate router contract based on the network you’re connected to, and will relay the request to the appropriate gateway contract. You can also use the function [getParentGatewayAddress](../../../sdk/reference/assetBridger/erc20Bridger.md#getParentGatewayAddress) to get the address of the gateway contract that’s going to be used. But don’t worry about any of this yet, we’ll use those functions in the next steps. +We’ll explain below what specific contracts and methods need to be called to bridge your token, but you can abstract this whole process of finding the right addresses by using Arbitrum’s SDK. You can use the [deposit](../../../sdk/reference/assetBridger/erc20Bridger.md#deposit) function of the [Erc20Bridger](../../../sdk/reference/assetBridger/erc20Bridger.md) class to bridge your tokens, which will use the appropriate router contract based on the network you’re connected to, and will relay the request to the appropriate gateway contract. You can also use the function [getParentGatewayAddress](https://docs.arbitrum.io/sdk/reference/assetBridger/erc20Bridger#getparentgatewayaddress) to get the address of the gateway contract that’s going to be used. But don’t worry about any of this yet, we’ll use those functions in the next steps. Now, here’s an explanation of the contracts and methods that need to be called to manually bridge your token: @@ -172,7 +172,7 @@ As mentioned before, you can also call the method `outboundTransferCustomRefund` ## Step 5: Wait for execution on L2 -After calling the deposit method (or the `outboundTransferCustomRefund`, if you’re choosing the manual way), you’ll have to wait a bit until the message is executed on L2. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page, to know more about [L1-to-L2 messages, also known as retryables](/how-arbitrum-works/arbos/l1-l2-messaging.md). +After calling the deposit method (or the `outboundTransferCustomRefund`, if you’re choosing the manual way), you’ll have to wait a bit until the message is executed on L2. We will verify the status of the underlying retryable ticket created to bridge the tokens. Check this page, to know more about [L1-to-L2 messages, also known as retryables](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). You can programmatically wait for the execution of the transaction on L2 using Arbitrum’s SDK. You should first wait for the execution of the submission transaction (the one sent to the router contract) and then the execution of the L2 transaction. @@ -197,7 +197,7 @@ If you’re going the manual way, you can verify if the message has been execute Finally, let’s find the token contract that has been created on L2. -Using Arbitrum’s SDK, you can call method [getChildErc20Address](../../../sdk/reference/assetBridger/erc20Bridger.md#getChildErc20Address) of the [Erc20Bridger](../../../sdk/reference/assetBridger/erc20Bridger.md) class, which will return the address of the token contract in L2 that corresponds to the L1 token contract sent as parameter. +Using Arbitrum’s SDK, you can call method [getChildErc20Address](https://docs.arbitrum.io/sdk/reference/assetBridger/erc20Bridger#getchildgatewayaddress) of the [Erc20Bridger](../../../sdk/reference/assetBridger/erc20Bridger.md) class, which will return the address of the token contract in L2 that corresponds to the L1 token contract sent as parameter. ```tsx /** @@ -210,7 +210,7 @@ const l2Token = erc20Bridger.getChildTokenContract(l2Provider, l2TokenAddress); To do this operation manually, you can call method `calculateL2TokenAddress` of the router contract. -If you visit that address in [Arbiscan](https://arbiscan.io/), you’ll notice that it is a copy of the contract [StandardArbERC20](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/StandardArbERC20.sol). This is the standard contract that is automatically created the first time a token that doesn’t exist in Arbitrum is bridged. [The token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#default-standard-bridging) has more information about this contract. +If you visit that address in [Arbiscan](https://arbiscan.io/), you’ll notice that it is a copy of the contract [StandardArbERC20](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/StandardArbERC20.sol). This is the standard contract that is automatically created the first time a token that doesn’t exist in Arbitrum is bridged. [The token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#default-standard-bridging) has more information about this contract. ## Conclusion @@ -218,6 +218,6 @@ After finishing this process, you’ll now have a counterpart token contract aut ## Resources -1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.md) +1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) 2. [Arbitrum SDK](https://github.com/OffchainLabs/arbitrum-sdk) 3. [Token bridge contract addresses](/build-decentralized-apps/reference/02-contract-addresses.mdx) diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx index 9edf01d7d..88a79ed10 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/03-how-to-bridge-tokens-generic-custom.mdx @@ -5,15 +5,15 @@ user_story: As a developer, I want to understand how to bridge tokens between Et content_type: how-to --- -In this how-to you’ll learn how to bridge your own token between Ethereum (Layer 1 or L1) and Arbitrum (Layer 2 or L2), using [Arbitrum’s generic-custom gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#the-arbitrum-generic-custom-gateway). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx). +In this how-to you’ll learn how to bridge your own token between Ethereum (Layer 1 or L1) and Arbitrum (Layer 2 or L2), using [Arbitrum’s generic-custom gateway](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway). For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx). -Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.md), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. +Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.mdx), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. We will go through all steps involved in the process. However, if you want to jump straight to the code, we have created [this script in our tutorials repository](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/custom-token-bridging) that encapsulates the entire process. ## Step 0: Review the prerequisites -As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#the-arbitrum-generic-custom-gateway), there are a few prerequisites to keep in mind while using this method to make a token bridgeable. +As stated in the [token bridge conceptual page](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#the-arbitrum-generic-custom-gateway), there are a few prerequisites to keep in mind while using this method to make a token bridgeable. First of all, the **L1 counterpart of the token**, must conform to the [ICustomToken](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/ICustomToken.sol) interface. This means that: @@ -32,7 +32,7 @@ Also, the **L2 counterpart of the token**, must conform to the [IArbToken](https - It must have`bridgeMint` and `bridgeBurn` methods only callable by the L2CustomGateway contract - It must have an `l1Address` view method that returns the address of the token in L1 -import TokenCompatibilityPartial from '../partials/_token-compatibility.md'; +import TokenCompatibilityPartial from '../partials/_token-compatibility.mdx'; @@ -375,7 +375,7 @@ Yes, if your token has a standard ERC20 counterpart on L2, you can go through th ## Resources -1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.md) +1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) 2. [Arbitrum SDK](https://github.com/OffchainLabs/arbitrum-sdk) 3. [Token bridge contract addresses](/build-decentralized-apps/reference/02-contract-addresses.mdx) ) diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx index 2450ef467..5c45239ff 100644 --- a/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx +++ b/arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx @@ -13,7 +13,7 @@ Before starting to implement and deploy a custom gateway, it is strongly encoura In this how-to you’ll learn how to bridge your own token between Ethereum (Layer 1 or L1) and Arbitrum (Layer 2 or L2), using a custom gateway. For alternative ways of bridging tokens, don’t forget to check out this [overview](/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/01-get-started.mdx). -Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.md), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. +Familiarity with [Arbitrum’s token bridge system](/build-decentralized-apps/token-bridging/01-overview.mdx), smart contracts, and blockchain development is expected. If you’re new to blockchain development, consider reviewing our [Quickstart: Build a dApp with Arbitrum (Solidity, Hardhat)](/build-decentralized-apps/01-quickstart-solidity-hardhat.mdx) before proceeding. We will use [Arbitrum’s SDK](https://github.com/OffchainLabs/arbitrum-sdk) throughout this how-to, although no prior knowledge is required. We will go through all steps involved in the process. However, if you want to jump straight to the code, we have created [this script in our tutorials repository](https://github.com/OffchainLabs/arbitrum-tutorials/tree/master/packages/custom-gateway-bridging) that encapsulates the entire process. @@ -839,6 +839,6 @@ The full code of this how-to and a more extensive deployment and testing script ## Resources -1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.md) +1. [Concept page: Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) 2. [Arbitrum SDK](https://github.com/OffchainLabs/arbitrum-sdk) 3. [Token bridge contract addresses](/build-decentralized-apps/reference/02-contract-addresses.mdx) diff --git a/arbitrum-docs/build-decentralized-apps/token-bridging/partials/_token-compatibility.md b/arbitrum-docs/build-decentralized-apps/token-bridging/partials/_token-compatibility.mdx similarity index 100% rename from arbitrum-docs/build-decentralized-apps/token-bridging/partials/_token-compatibility.md rename to arbitrum-docs/build-decentralized-apps/token-bridging/partials/_token-compatibility.mdx diff --git a/arbitrum-docs/for-devs/contribute.mdx b/arbitrum-docs/for-devs/contribute.mdx index 7795a031b..8e13ea78b 100644 --- a/arbitrum-docs/for-devs/contribute.mdx +++ b/arbitrum-docs/for-devs/contribute.mdx @@ -1,6 +1,6 @@ --- title: 'Contribute docs' -description: "Learn how to contribute to Arbitrum's documentation" +description: "Learn how to contribute to Arbitrum's open-source documentation. Enhance developer resources and play a key role in scaling Ethereum's leading Layer 2 ecosystem." author: symbolpunk --- diff --git a/arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide/usdc.mdx b/arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide.mdx similarity index 97% rename from arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide/usdc.mdx rename to arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide.mdx index 3382ac295..964dcf5b3 100644 --- a/arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide/usdc.mdx +++ b/arbitrum-docs/for-devs/third-party-docs/Circle/usdc-quickstart-guide.mdx @@ -1,4 +1,9 @@ -## QuickStart +--- +title: 'USDC quick start guide' +description: 'Learn how to integrate USDC into your application using the Arbitrum network.' +author: circle-cooper +sme: circle-cooper +--- USDC provides the ability to transfer dollars over the Arbitrum network using a smart contract. The smart contract enables users to send, receive, and store dollars on-chain with a wallet. diff --git a/arbitrum-docs/for-devs/third-party-docs/contribute.mdx b/arbitrum-docs/for-devs/third-party-docs/contribute.mdx index 756ec1a77..1996c8c78 100644 --- a/arbitrum-docs/for-devs/third-party-docs/contribute.mdx +++ b/arbitrum-docs/for-devs/third-party-docs/contribute.mdx @@ -1,6 +1,6 @@ --- title: 'Contribute third-party docs' -description: "Learn how to contribute to Arbitrum's documentation" +description: "Discover how to contribute third-party resources to Arbitrum's documentation. Share your expertise and help expand the largest Ethereum Layer 2 developer ecosystem." sidebar_position: 0 --- diff --git a/arbitrum-docs/hosted-audit-reports/2023_08_02_trail_of_bits_security_audit_challenge_protocol_v2.pdf b/arbitrum-docs/hosted-audit-reports/2023_08_02_trail_of_bits_security_audit_challenge_protocol_v2.pdf new file mode 100644 index 000000000..30a4f6157 Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2023_08_02_trail_of_bits_security_audit_challenge_protocol_v2.pdf differ diff --git a/arbitrum-docs/hosted-audit-reports/2024_08_05_trail_of_bits_security_audit_bold_and_dac_rewards_updates.pdf b/arbitrum-docs/hosted-audit-reports/2024_08_05_trail_of_bits_security_audit_bold_and_dac_rewards_updates.pdf new file mode 100644 index 000000000..229adf860 Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2024_08_05_trail_of_bits_security_audit_bold_and_dac_rewards_updates.pdf differ diff --git a/arbitrum-docs/hosted-audit-reports/2024_10_07_trail_of_bits_security_audit_bold_optimized_history_commitments.pdf b/arbitrum-docs/hosted-audit-reports/2024_10_07_trail_of_bits_security_audit_bold_optimized_history_commitments.pdf new file mode 100644 index 000000000..f7253df16 Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2024_10_07_trail_of_bits_security_audit_bold_optimized_history_commitments.pdf differ diff --git a/arbitrum-docs/hosted-audit-reports/2024_10_23_trail_of_bits_security_audit_arbos32_emergency_fixes.pdf b/arbitrum-docs/hosted-audit-reports/2024_10_23_trail_of_bits_security_audit_arbos32_emergency_fixes.pdf new file mode 100644 index 000000000..358b77c5b Binary files /dev/null and b/arbitrum-docs/hosted-audit-reports/2024_10_23_trail_of_bits_security_audit_arbos32_emergency_fixes.pdf differ diff --git a/arbitrum-docs/how-arbitrum-works/arbos/geth.md b/arbitrum-docs/how-arbitrum-works/arbos/geth.mdx similarity index 97% rename from arbitrum-docs/how-arbitrum-works/arbos/geth.md rename to arbitrum-docs/how-arbitrum-works/arbos/geth.mdx index a1ca1aebf..6057b6073 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/geth.md +++ b/arbitrum-docs/how-arbitrum-works/arbos/geth.mdx @@ -21,7 +21,7 @@ Please note any links on this page may be referencing old releases of Nitro or o Arbitrum uses various hooks to modify Geth's behavior when processing transactions. Each provides an opportunity for ArbOS to update its state and make decisions about the transaction during its lifetime. Transactions are applied using Geth's [`ApplyTransaction`][applytransaction_link] function. -Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additional info on where the various Arbitrum-specific hooks are inserted. Click on any to go to their section. By default, these hooks do nothing so as to leave Geth's default behavior unchanged, but for chains configured with [`EnableArbOS`](#EnableArbOS) set to true, [`ReadyEVMForL2`](#ReadyEVMForL2) installs the alternative L2 hooks. +Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additional info on where the various Arbitrum-specific hooks are inserted. Click on any to go to their section. By default, these hooks do nothing so as to leave Geth's default behavior unchanged, but for chains configured with [`EnableArbOS`](#enablearbos) set to true, [`ReadyEVMForL2`](#ReadyEVMForL2) installs the alternative L2 hooks. - `core.ApplyTransaction` ⮕ `core.applyTransaction` ⮕ `core.ApplyMessage` - `core.NewStateTransition` @@ -34,7 +34,7 @@ Below is [`ApplyTransaction`][applytransaction_link]'s callgraph, with additiona - `evm.Call` - `core.vm.EVMInterpreter.Run` - [`PushCaller`](#PushCaller) - - [`PopCaller`](#PopCaller) + - `PopCaller` - `core.StateTransition.refundGas` - [`ForceRefundGas`](#ForceRefundGas) - [`NonrefundableGas`](#NonrefundableGas) @@ -176,11 +176,11 @@ Represents a user deposit from L1 to L2. This increases the user's balance by th ### [`ArbitrumSubmitRetryableTx`][arbitrumsubmitretryabletx_link]{#ArbitrumSubmitRetryableTx} -Represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#ArbitrumRetryTx) if provided enough gas. Please see the [retryables documentation](/how-arbitrum-works/arbos/introduction.md#Retryables) for more info. +Represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#ArbitrumRetryTx) if provided enough gas. Please see the [retryables documentation](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) for more info. ### [`ArbitrumRetryTx`][arbitrumretrytx_link]{#ArbitrumRetryTx} -These are scheduled by calls to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Please see the [retryables documentation](/how-arbitrum-works/arbos/introduction.md#Retryables) for more info. +These are scheduled by calls to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.mdx#arbretryabletx) precompile and via retryable auto-redemption. Please see the [retryables documentation](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) for more info. ### [`ArbitrumInternalTx`][arbitruminternaltx_link]{#ArbitrumInternalTx} @@ -228,7 +228,7 @@ Nitro's Geth may be configured with the following [l2-specific chain parameters] ### `EnableArbos` -Introduces [ArbOS](/how-arbitrum-works/arbos/introduction.md), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. +Introduces [ArbOS](/how-arbitrum-works/arbos/introduction.mdx), converting what would otherwise be a vanilla L1 chain into an L2 Arbitrum rollup. ### `AllowDebugPrecompiles` @@ -256,7 +256,7 @@ To aid with [outbox proof construction][proof_link], the root hash and leaf coun ### Retryable Support -Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/arbos/introduction.md#retryables). Some modifications were required in Geth to support them. +Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/arbos/introduction.mdx#retryables). Some modifications were required in Geth to support them. - Added ScheduledTxes field to ExecutionResult. This lists transactions scheduled during the execution. To enable using this field, we also pass the ExecutionResult to callers of ApplyTransaction. - Added gasEstimation param to DoCall. When enabled, DoCall will also also executing any retryable activated by the original call. This allows estimating gas to enable retryables. diff --git a/arbitrum-docs/how-arbitrum-works/arbos/introduction.md b/arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx similarity index 97% rename from arbitrum-docs/how-arbitrum-works/arbos/introduction.md rename to arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx index 0a0ece5cd..729f4b72a 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/introduction.md +++ b/arbitrum-docs/how-arbitrum-works/arbos/introduction.mdx @@ -34,7 +34,7 @@ An [`L1IncomingMessage`][l1incomingmessage_link] represents an incoming sequence ## Retryables -A Retryable is a special message type for creating atomic L1 to L2 messages; for details, see [L1 To L2 Messaging](/how-arbitrum-works/arbos/l1-l2-messaging.md). +A Retryable is a special message type for creating atomic L1 to L2 messages; for details, see [L1 To L2 Messaging](/how-arbitrum-works/arbos/l1-l2-messaging.mdx). ## ArbOS State @@ -81,7 +81,7 @@ Based on this information, ArbOS maintains an L1 data fee, also tracked as part The L2 pricing state tracks L2 resource usage to determine a reasonable L2 gas price. This process considers a variety of factors, including user demand, the state of Geth, and the computational speed limit. The primary mechanism for doing so consists of a pair of pools, one larger than the other, that drain as L2-specific resources are consumed and filled as time passes. L1-specific resources like L1 `calldata` are not tracked by the pools, as they have little bearing on the actual work done by the network actors that the speed limit is meant to keep stable and synced. -While much of this state is accessible through the [`ArbGasInfo`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) and [`ArbOwner`](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) precompiles, most changes are automatic and happen during [block production][block_production_link] and [the transaction hooks](geth#Hooks). Each of an incoming message's transactions removes from the pool the L2 component of the gas it uses, and afterward the message's timestamp [informs the pricing mechanism][notify_pricer_link] of the time that's passed as ArbOS [finalizes the block][finalizeblock_link]. +While much of this state is accessible through the [`ArbGasInfo`](/build-decentralized-apps/precompiles/02-reference.mdx#arbgasinfo) and [`ArbOwner`](/build-decentralized-apps/precompiles/02-reference.mdx#arbowner) precompiles, most changes are automatic and happen during [block production][block_production_link] and [the transaction hooks](/how-arbitrum-works/arbos/geth.mdx#hooks). Each of an incoming message's transactions removes from the pool the L2 component of the gas it uses, and afterward the message's timestamp [informs the pricing mechanism][notify_pricer_link] of the time that's passed as ArbOS [finalizes the block][finalizeblock_link]. ArbOS's larger gas pool [determines][maintain_limit_link] the per-block gas limit, setting a dynamic [upper limit][per_block_limit_link] on the amount of compute gas an L2 block may have. This limit is always enforced, though for the [first transaction][first_transaction_link] it's done in the [GasChargingHook](geth#GasChargingHook) to avoid sharp decreases in the L1 gas price from over-inflating the compute component purchased to above the gas limit. This improves UX by allowing the first transaction to succeed rather than requiring a resubmission. Because the first transaction lowers the amount of space left in the block, subsequent transactions do not employ this strategy and may fail from such compute-component inflation. This is acceptable because such transactions are only present in cases where the system is under heavy load and the result is that the user's transaction is dropped without charges since the state transition fails early. Those trusting the sequencer can rely on the transaction being automatically resubmitted in such a scenario. diff --git a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.md b/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx similarity index 98% rename from arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.md rename to arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx index 965821c01..c7cf4e50c 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.md +++ b/arbitrum-docs/how-arbitrum-works/arbos/l1-l2-messaging.mdx @@ -211,7 +211,7 @@ In principle, retryable tickets can alternatively be used to deposit Ether; this ## Transacting via the Delayed Inbox -While retryables and Eth deposits _must_ be submitted through the delayed inbox, in principle, _any_ message can be included this way; this is a necessary recourse to ensure the Arbitrum chain preserves censorship resistance even if the Sequencer misbehaves (see [The Sequencer and Censorship Resistance](/how-arbitrum-works/sequencer.md)). However, under ordinary/happy circumstances, the expectation/recommendation is that clients use the delayed inbox only for Retryables and Eth deposits, and transact via the Sequencer for all other messages. +While retryables and Eth deposits _must_ be submitted through the delayed inbox, in principle, _any_ message can be included this way; this is a necessary recourse to ensure the Arbitrum chain preserves censorship resistance even if the Sequencer misbehaves (see [The Sequencer and Censorship Resistance](/how-arbitrum-works/sequencer.mdx)). However, under ordinary/happy circumstances, the expectation/recommendation is that clients use the delayed inbox only for Retryables and Eth deposits, and transact via the Sequencer for all other messages. ### Address Aliasing diff --git a/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.md b/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx similarity index 96% rename from arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.md rename to arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx index 14fc752ea..a7aae98db 100644 --- a/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.md +++ b/arbitrum-docs/how-arbitrum-works/arbos/l2-l1-messaging.mdx @@ -5,7 +5,7 @@ target_audience: developers who want to build on Arbitrum content_type: concept --- -Arbitrum's Outbox system allows for arbitrary L2 to L1 contract calls; i.e., messages initiated from L2 which eventually resolve in execution on L1. L2-to-L1 messages (aka "outgoing" messages) bear many things in common with Arbitrum's [L1-to-L2 messages](/how-arbitrum-works/arbos/l1-l2-messaging.md) (Retryables), "in reverse" though with a few differences. +Arbitrum's Outbox system allows for arbitrary L2 to L1 contract calls; i.e., messages initiated from L2 which eventually resolve in execution on L1. L2-to-L1 messages (aka "outgoing" messages) bear many things in common with Arbitrum's [L1-to-L2 messages](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) (Retryables), "in reverse" though with a few differences. ### Protocol Flow @@ -22,6 +22,6 @@ An important feature in the design of the Outbox system is that calls to `confir Unlike Retryables, which have an option to provide Ether for automatic L2 execution, outgoing messages can't provide in-protocol automatic L1 execution, for the simple reason that Ethereum itself doesn't offer scheduled execution affordances. However, application-layer contracts that interact with the Outbox could in principle be built to provide somewhat-analogous "execution market" functionality for outsourcing the final L1 execution step. Another difference between outgoing messages and Retryables is that Retryables have a limited lifetime before which they must be redeemed (or have their lifetime explicitly extended), whereas L2 to L1 messages are stored in L1 state, and thus persist permanently / have no deadline before which they must be executed. -The week long delay period before outgoing messages can be executed is inherent and fundamental to the nature of Arbitrum Rollup, or any Optimistic Rollup style L2; the moment a transaction is published on-chain, any observer can anticipate its result; however, for Ethereum itself to accept its result, the protocol must give time for Arbitrum validators to detect and prove fault if need-be. For a protocol overview, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.md) +The week long delay period before outgoing messages can be executed is inherent and fundamental to the nature of Arbitrum Rollup, or any Optimistic Rollup style L2; the moment a transaction is published on-chain, any observer can anticipate its result; however, for Ethereum itself to accept its result, the protocol must give time for Arbitrum validators to detect and prove fault if need-be. For a protocol overview, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx) \*\* We refer to `NodeInterface` as a "virtual" contract; its methods are accessible via calls `0x00000000000000000000000000000000000000C8`, but it doesn't really live on chain. It isn't really a precompile, but behaves a lot like a precompile that can't receive calls from other contracts. This is a cute trick that let's us provide Arbitrum-specific data without having to implement a custom RPC. diff --git a/arbitrum-docs/how-arbitrum-works/assertion-tree.md b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx similarity index 79% rename from arbitrum-docs/how-arbitrum-works/assertion-tree.md rename to arbitrum-docs/how-arbitrum-works/assertion-tree.mdx index 6b89d6546..1669c1944 100644 --- a/arbitrum-docs/how-arbitrum-works/assertion-tree.md +++ b/arbitrum-docs/how-arbitrum-works/assertion-tree.mdx @@ -16,7 +16,7 @@ If, however, two or more conflicting assertions exist, the Assertion Tree bifurc Crucially, the rules of advancing an Arbitrum chain are deterministic; this means that given a chain state and some new inputs, there is only one valid output. Thus, if the Assertion Tree contains more than one leaf, then at most only one leaf can represent the valid chain-state; if we assume there is at least one honest active validator, _exactly_ one leaf will be valid. -Two conflicting assertions can be put into a dispute; see [Interactive Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.md) for details on the dispute process. For the sake of understanding the Assertion Tree protocol, suffice it to say that 2-party disputes last at most a fixed amount of time (1 week), at the end of which one of the two conflicting assertions will be rejected, and the validator who posted it will lose their stake. +Two conflicting assertions can be put into a dispute; see [Interactive Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx) for details on the dispute process. For the sake of understanding the Assertion Tree protocol, suffice it to say that 2-party disputes last at most a fixed amount of time (1 week), at the end of which one of the two conflicting assertions will be rejected, and the validator who posted it will lose their stake. In order for an assertion to be confirmed and for its stake to be recovered, two conditions must be met: sufficient time for disputes must have passed, and no other conflicting branches in the Assertion Tree can exist (i.e., they've all been disputed / "pruned" off.) @@ -26,8 +26,8 @@ These properties together ensure that as long as at least one honest, active val Even if the Assertion Tree has multiple conflicting leaves and, say, multiple disputes are in progress, validators can continue making assertions; honest validators will simply build on the one valid leaf (intuitively: an assertion is also an implicit claim of the validity of all of its parent-assertions.) Likewise, users can continue transacting on L2, since transactions continue to be posted in the chain's inbox. -The only delay that users experience during a dispute is of their [L2 to L1 messages](/how-arbitrum-works/arbos/l2-l1-messaging.md) (i.e., "their withdrawals"). Note that a "delay attacker" who seeks to grief the system by deliberately causing such delays will find this attack quite costly, since each bit of delay-time gained requires the attacker lose another stake. +The only delay that users experience during a dispute is of their [L2 to L1 messages](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) (i.e., "their withdrawals"). Note that a "delay attacker" who seeks to grief the system by deliberately causing such delays will find this attack quite costly, since each bit of delay-time gained requires the attacker lose another stake. ### Detailed Spec -For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.md#arbitrum#rollup#protocol). +For a more detailed breakdown / specification of the assertion tree protocol, see [Inside Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). 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.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.md rename to arbitrum-docs/how-arbitrum-works/bold/bold-economics-of-disputes.mdx diff --git a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx similarity index 96% rename from arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md rename to arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx index 63aba1f30..e4c912339 100644 --- a/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.md +++ b/arbitrum-docs/how-arbitrum-works/bold/gentle-introduction.mdx @@ -17,7 +17,7 @@ BoLD will eventually replace the current, permissioned fraud proof mechanism tha ## In a nutshell: - Validation for Arbitrum One and Arbitrum Nova is a privileged action currently limited to an [allow-listed set of parties, maintained by the Arbitrum DAO](https://docs.arbitrum.foundation/state-of-progressive-decentralization#allowlisted-validators) to reduce the risks of _[delay attacks](https://medium.com/offchainlabs/solutions-to-delay-attacks-on-rollups-434f9d05a07a)_. _Delay attacks_ are a class of attacks where malicious entities can open as many disputes as they are willing to forfeit bonds during the challenge period to delay confirmations of assertions (equal to the time needed to resolve those disputes one by one). -- BoLD, an acronym for Bounded Liquidity Delay, is a new challenge resolution protocol for Arbitrum chains that enables permissionless validation by mitigating the risks of delay attacks against [optimistic rollups like Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.md#arbitrum-rollup-protocol). This is possible because BoLD's design ensures disputes will be resolved within a fixed time window, currently set to equal 1 challenge period (~6.4 days) for Arbitrum One and Arbitrum Nova. If there is a dispute, BoLD guarantees the maximum total time to be equal to 2 challenge periods (1 for raising disputes, 1 for resolving disputes), a 2 day grace period for the Security Council to intervene if necessary, and a small delta for computing challenges. +- BoLD, an acronym for Bounded Liquidity Delay, is a new challenge resolution protocol for Arbitrum chains that enables permissionless validation by mitigating the risks of delay attacks against [optimistic rollups like Arbitrum](/how-arbitrum-works/inside-arbitrum-nitro.mdx#arbitrum-rollup-protocol). This is possible because BoLD's design ensures disputes will be resolved within a fixed time window, currently set to equal 1 challenge period (~6.4 days) for Arbitrum One and Arbitrum Nova. If there is a dispute, BoLD guarantees the maximum total time to be equal to 2 challenge periods (1 for raising disputes, 1 for resolving disputes), a 2 day grace period for the Security Council to intervene if necessary, and a small delta for computing challenges. - Enabling permissionless validation is key milestone on [Arbitrum’s journey to becoming a Stage 2 Rollup](https://docs.arbitrum.foundation/state-of-progressive-decentralization) - the most advanced and mature rollup technology categorization, according to [L2Beat](https://medium.com/l2beat/introducing-stages-a-framework-to-evaluate-rollups-maturity-d290bb22befe). With BoLD, **any honest party can validate and bond their funds to post a correct L2 state assertions to win disputes against malicious entities.** - BoLD is currently considered to be in `alpha` release and is deployed on a public testnet. [Follow this guide](https://github.com/OffchainLabs/BoLD-validator-starter-kit) to deploy a BoLD validator to test and explore, first hand, how BoLD works to secure Arbitrum chains. To learn more about BoLD, please check out the [BoLD whitepaper](https://arxiv.org/abs/2404.10491) and [BoLD's code and specifications on Github](https://github.com/OffchainLabs/BoLD). @@ -70,9 +70,9 @@ The BoLD protocol provides the guardrails and rules for how validators challenge Let’s dive in to an overview of how BoLD actually works. -1. **An assertion is made:** Validators begin by taking the most recent confirmed [RBlock](/how-arbitrum-works/inside-arbitrum-nitro.md#the-rollup-chain), called `Block A`, and assert that some number of transactions afterwards, using Nitro’s deterministic State Transition Function (STF), will result in an end state, `Block Z`. If a validator claims that the end state represented by `Block Z` is correct, they will bond their funds to `Block Z` and propose that state to be posted to Ethereum. If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the RBlock `Block Z` is confirmed as the correct state of an Arbitrum chain. However, if someone disagrees with the end state `Block Z`, they can submit a challenge. This is where BoLD comes into play. +1. **An assertion is made:** Validators begin by taking the most recent confirmed [RBlock](/how-arbitrum-works/inside-arbitrum-nitro.mdx#the-rollup-chain), called `Block A`, and assert that some number of transactions afterwards, using Nitro’s deterministic State Transition Function (STF), will result in an end state, `Block Z`. If a validator claims that the end state represented by `Block Z` is correct, they will bond their funds to `Block Z` and propose that state to be posted to Ethereum. If nobody disagrees after a certain amount of time, known as the challenge period, then the state represented by the RBlock `Block Z` is confirmed as the correct state of an Arbitrum chain. However, if someone disagrees with the end state `Block Z`, they can submit a challenge. This is where BoLD comes into play. 2. **A challenge is opened:** When another validator observes and disagrees with the end state represented by `Block Z`, they can permissionlessly open a challenge by asserting and bonding capital to a claim on a different end state, represented by an RBlock `Block Y`. At this point in time, there are now 2 asserted states: `Block A → Block Z` and `Block A → Block Y`. Each of these asserted states, at this point in time now that there's a challenge, are referred to _edges_ while a Merkle tree of asserted states from some start to end point (e.g. `Block A → Block Z`) is more formally known as a _history commitment._ It is important to note that Ethereum at this point in time has no notion of which edge(s) is correct or incorrect - edges are simply a portion of a claim made by a validator about the history of the chain from some end state all the way back to some initial state. Also note that because a bond put up by a validator is tied to an assertion rather than the party who put up that bond, there can be any number of honest, anonymous parties that can open challenges against incorrect claims. It is important to note that the bonds put up to open challenges are held in a Gnosis Safe multi-sig wallet controlled by the Arbitrum Foundation. -3. **Multi-level, interactive dissection begins:** To resolve the dispute, the disagreeing entities will need to come to an agreement on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/inside-arbitrum-nitro.md#why-interactive-proving-is-better) and compare everything from `Block A → Block Z` and `Block A → Block Y`, especially since there could be potentially millions of transactions in between `A`, `Z`, and `Y`. Instead, entities take turns bisecting their respective _history commitments_ until they arrive at a single step of instruction where an arbiter, like Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/inside-arbitrum-nitro.md#challenges) - BoLD only changes some minor, but important, details in the resolution process. Let’s dive into what happens next: +3. **Multi-level, interactive dissection begins:** To resolve the dispute, the disagreeing entities will need to come to an agreement on what the _actual, correct_ asserted state should be. [It would be tremendously expensive to re-execute](/how-arbitrum-works/inside-arbitrum-nitro.mdx#why-interactive-proving-is-better) and compare everything from `Block A → Block Z` and `Block A → Block Y`, especially since there could be potentially millions of transactions in between `A`, `Z`, and `Y`. Instead, entities take turns bisecting their respective _history commitments_ until they arrive at a single step of instruction where an arbiter, like Ethereum, can declare a winner. Note that [this system is very similar to how challenges are resolved on Arbitrum chains today](/how-arbitrum-works/inside-arbitrum-nitro.mdx#challenges) - BoLD only changes some minor, but important, details in the resolution process. Let’s dive into what happens next: 1. **Block challenges**: when a challenge is opened, the edges are called _level-zero edges_ since they are at the granularity of Arbitrum blocks. The disputing parties take turns bisecting their history commitments until they identify the specific block that they disagree on. 2. **Big-step challenge:** now that the parties have narrowed down their dispute to a single block, that we call `Block B`, the back-and-forth bisection exercise continues within that block. Note that `Block B` is claimed by all parties to be some state after the initial state `Block A` but before the final states `Block Z` and `Block Y`. This time, however, the parties will narrow down on a specific _range_ of instructions for the state transition function within the block - essentially working towards identifying a set of instructions within which their disagreement lies. This range is currently defined as 2^20 steps of WASM instructions, which is the assembly of choice for validating Arbitrum chains. 3. **One-step challenge:** within that range of 2^20 instructions, the back and forth bisecting continues until all parties arrive at a single step of instruction that they disagree on. At this point in time, parties agree on the initial state of Arbitrum before the step but disagree on the end state 1 step immediately after. Remember that since Arbitrum’s state is entirely deterministic, there is only 1 correct end state. diff --git a/arbitrum-docs/how-arbitrum-works/bold/partials/_bold-public-preview-banner-partial.md b/arbitrum-docs/how-arbitrum-works/bold/partials/_bold-public-preview-banner-partial.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/bold/partials/_bold-public-preview-banner-partial.md rename to arbitrum-docs/how-arbitrum-works/bold/partials/_bold-public-preview-banner-partial.mdx diff --git a/arbitrum-docs/how-arbitrum-works/bold/public-preview-expectations.md b/arbitrum-docs/how-arbitrum-works/bold/public-preview-expectations.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/bold/public-preview-expectations.md rename to arbitrum-docs/how-arbitrum-works/bold/public-preview-expectations.mdx diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/challenge-manager.mdx diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx similarity index 95% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx index 8e5d1bb01..941fefb5a 100644 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.md +++ b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx @@ -3,7 +3,7 @@ Not all WASM instructions are 1:1 with WAVM opcodes. This document lists those which are not, and explains how they're expressed in WAVM. Many of the WAVM representations use opcodes not in WASM, -which are documented in [`wavm-custom-opcodes.md`](/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.md). +which are documented in [`wavm-custom-opcodes.mdx`](/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx). ## `block` and `loop` diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx similarity index 99% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx index 66fc8c405..bbf75c3b6 100644 --- a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.md +++ b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-custom-opcodes.mdx @@ -11,7 +11,7 @@ which are not part of WASM nor any WASM proposal. Many of these opcodes have implicit invariants about what's on the stack, e.g. "Pops an i32 from the stack" assumes that the top of the stack has an i32. If these conditions are not satisfied, execution is generally not possible. -These invariants are maintained by WASM validation and Arbitrator codegen. (See [One Step Proof Assumptions](/how-arbitrum-works/fraud-proofs/osp-assumptions.md).) +These invariants are maintained by WASM validation and Arbitrator codegen. (See [One Step Proof Assumptions](/how-arbitrum-works/fraud-proofs/osp-assumptions.mdx).) ## Codegen internal @@ -58,7 +58,7 @@ These are only used in the implementation of "host calls". Each of these has an equivalent host call method, which can be invoked from libraries. The exception is `CallerModuleInternalCall`, which is used for the implementation of all of the `wavm_caller_*` host calls. -Those calls are documented in `wavm-modules.md`. +Those calls are documented in `wavm-modules.mdx`. For these instruction descriptions, all pointers and offsets are represented as WASM i32s. diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-floats.mdx diff --git a/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.md b/arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.md rename to arbitrum-docs/how-arbitrum-works/fraud-proofs/wavm-modules.mdx diff --git a/arbitrum-docs/how-arbitrum-works/gas-fees.md b/arbitrum-docs/how-arbitrum-works/gas-fees.mdx similarity index 98% rename from arbitrum-docs/how-arbitrum-works/gas-fees.md rename to arbitrum-docs/how-arbitrum-works/gas-fees.mdx index a3f2b0470..1d8e8df99 100644 --- a/arbitrum-docs/how-arbitrum-works/gas-fees.md +++ b/arbitrum-docs/how-arbitrum-works/gas-fees.mdx @@ -9,7 +9,7 @@ There are two parties a user pays when submitting a tx: - the poster, if reimbursable, for L1 resources such as the L1 calldata needed to post the tx - the network fee account for L2 resources, which include the computation, storage, and other burdens L2 nodes must bear to service the tx -The L1 component is the product of the transaction's estimated contribution to its batch's size — computed using Brotli on the transaction by itself — and the L2's view of the L1 data price, a value which dynamically adjusts over time to ensure the batch-poster is ultimately fairly compensated. For details, see [L1 Pricing](/how-arbitrum-works/l1-gas-pricing.md). +The L1 component is the product of the transaction's estimated contribution to its batch's size — computed using Brotli on the transaction by itself — and the L2's view of the L1 data price, a value which dynamically adjusts over time to ensure the batch-poster is ultimately fairly compensated. For details, see [L1 Pricing](/how-arbitrum-works/l1-gas-pricing.mdx). The L2 component consists of the traditional fees Geth would pay to stakers in a vanilla L1 chain, such as the computation and storage charges applying the state transition function entails. ArbOS charges additional fees for executing its L2-specific [precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), whose fees are dynamically priced according to the specific resources used while executing the call. diff --git a/arbitrum-docs/how-arbitrum-works/inside-anytrust.md b/arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/inside-anytrust.md rename to arbitrum-docs/how-arbitrum-works/inside-anytrust.mdx diff --git a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.md b/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx similarity index 90% rename from arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.md rename to arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx index cc1cb520e..14324abd8 100644 --- a/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.md +++ b/arbitrum-docs/how-arbitrum-works/inside-arbitrum-nitro.mdx @@ -157,7 +157,7 @@ This also allows anyone to be a full participant in the Arbitrum protocol, to ru _Optimistic_ -Arbitrum is optimistic, which means that Arbitrum advances the state of its chain by letting any party (a “validator”) post on Layer 1 a rollup block that that party claims is correct, and then giving everyone else a chance to challenge that claim. If the challenge period (roughly a week) passes and nobody has challenged the claimed rollup block, Arbitrum confirms the rollup block as correct. If someone challenges the claim during the challenge period, then Arbitrum uses an efficient dispute resolution protocol (detailed below) to identify which party is lying. The liar will forfeit a deposit, and the truth-teller will take part of that deposit as a reward for their efforts (some of the deposit is burned, guaranteeing that the liar is punished even if there's some collusion going on). +Arbitrum is optimistic, which means that Arbitrum advances the state of its chain by letting any party (a “validator”) post on Layer 1 a rollup block that that party claims is correct, and then giving everyone else a chance to challenge that claim. If the challenge period (6.4 days) passes and nobody has challenged the claimed rollup block, Arbitrum confirms the rollup block as correct. If someone challenges the claim during the challenge period, then Arbitrum uses an efficient dispute resolution protocol (detailed below) to identify which party is lying. The liar will forfeit a deposit, and the truth-teller will take part of that deposit as a reward for their efforts (some of the deposit is burned, guaranteeing that the liar is punished even if there's some collusion going on). Because a party who tries to cheat will lose a deposit, attempts to cheat should be very rare, and the normal case will be a single party posting a correct rollup block, and nobody challenging it. @@ -209,7 +209,7 @@ You might wonder why we need the rollup protocol. If everyone knows the results With those preliminaries behind us, let’s jump into the details of the rollup protocol. -The parties who participate in the protocol are called _validators_. Some validators will choose to be stakers--they will place an ETH deposit which they’ll be able to recover if they’re not caught cheating. In the common case, it's expected that only one validator will be staked, since as long as it's staked on the current outcome, and there are no conflicting claims, there's no need for other parties to stake / take any action. The protocol allows for these roles to be permissionless in principle; currently on Arbitrum One, validators/stakers are allowlisted (see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization)). "Watchtower validators," who monitor the chain but don't take any on-chain actions, can be run permissionlessly (see ["validators"](#validators) below). +The parties who participate in the protocol are called _validators_. Some validators will choose to be bonders--they will place an ETH deposit which they’ll be able to recover if they’re not caught cheating. In the common case, it's expected that only one validator will be bonded, since as long as it's bonded on the current outcome, and there are no conflicting claims, there's no need for other parties to bond/take any action. The protocol allows for these roles to be permissionless in principle; currently on Arbitrum One, validators/bonders are allowlisted (see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization)). "Watchtower validators," who monitor the chain but don't take any on-chain actions, can be run permissionlessly (see ["validators"](#validators) below). The key security property of the rollup protocol is that any one honest validator can force the correct execution of the chain to be confirmed. This means that execution of an Arbitrum chain is as trustless as Ethereum. You, and you alone (or someone you hire) can force your transactions to be processed correctly. And that is true no matter how many malicious people are trying to stop you. @@ -219,6 +219,12 @@ The rollup protocol tracks a chain of rollup blocks---we'll call these "RBlocks" Validators can propose RBlocks. New RBlocks will be _unresolved_ at first. Eventually every RBlock will be _resolved_, by being either _confirmed_ or _rejected_. The confirmed RBlocks make up the confirmed history of the chain. +:::note + +Validators and proposers serve different roles. Validators validate transactions to the State Transition Function (STF) and chain state, whereas proposers can also assert and challenge the chain state. + +::: + Each RBlock contains: - the RBlock number @@ -233,7 +239,7 @@ An RBlock is implicitly claiming that its predecessor RBlock is correct. This im An RBlock is also implicitly claiming that its older siblings (older RBlocks with the same predecessor), if there are any, are incorrect. If two RBlocks are siblings, and the older sibling is correct, then the younger sibling is considered incorrect, even if everything else in the younger sibling is true. -The RBlock is assigned a deadline, which says how long other validators have to respond to it. If you’re a validator, and you agree that an RBlock is correct, you don’t need to do anything. If you disagree with an RBlock, you can post another RBlock with a different result, and you’ll probably end up in a challenge against the first RBlock's staker. (More on challenges below.) +The RBlock is assigned a deadline, which says how long other validators have to respond to it. If you’re a validator, and you agree that an RBlock is correct, you don’t need to do anything. If you disagree with an RBlock, you can post another RBlock with a different result, and you’ll probably end up in a challenge against the first RBlock's bonder. (More on challenges below.) In the normal case, the rollup chain will look like this: @@ -322,31 +328,31 @@ There’s a lot going on here, so let’s unpack it. - RBlock 110 claims to follow 109. It is unresolved. If 109 is rejected, 110 will be automatically rejected too. - RBlock 111 claims to follow 104. 111 will inevitably be rejected because its predecessor has already been rejected. But it hasn’t been rejected yet, because the protocol resolves RBlocks in RBlock number order, so the protocol will have to resolve 106 through 110, in order, before it can resolve 111. After 110 has been resolved, 111 can be rejected immediately. -Again: this sort of thing is very unlikely in practice. In this diagram, at least four parties must have staked on wrong RBlocks, and when the dust settles at least four parties will have lost their stakes. The protocol handles these cases correctly, of course, but they’re rare corner cases. This diagram is designed to illustrate the variety of situations that are possible in principle, and how the protocol would deal with them. +Again: this sort of thing is very unlikely in practice. In this diagram, at least four parties must have bonded on wrong RBlocks, and when the dust settles at least four parties will have lost their bonds. The protocol handles these cases correctly, of course, but they’re rare corner cases. This diagram is designed to illustrate the variety of situations that are possible in principle, and how the protocol would deal with them. ### Staking -At any given time, some validators will be stakers, and some will not. Stakers deposit funds that are held by the Arbitrum Layer 1 contracts and will be confiscated if the staker loses a challenge. Nitro chains accept stakes in ETH. +At any given time, some validators will be bonders, and some will not. Bonders deposit funds that are held by the Arbitrum Layer 1 contracts and will be confiscated if the bonder loses a challenge. Nitro chains accept bonds in ETH. -A single stake can cover a chain of RBlocks. Every staker is staked on the latest confirmed RBlock; and if you’re staked on an RBlock, you can also stake on one successor of that RBlock. So you might be staked on a sequence of RBlocks that represent a single coherent claim about the correct history of the chain. A single stake suffices to commit you to that sequence of RBlocks. +A single bond can cover a chain of RBlocks. Every bonder is bonded on the latest confirmed RBlock; and if you’re bonded on an RBlock, you can also bond on one successor of that RBlock. So you might be bonded on a sequence of RBlocks that represent a single coherent claim about the correct history of the chain. A single bond suffices to commit you to that sequence of RBlocks. -In order to create a new RBlock, you must be a staker, and you must already be staked on the predecessor of the new RBlock you’re creating. The stake requirement for RBlock creation ensures that anyone who creates a new RBlock has something to lose if that RBlock is eventually rejected. +In order to create a new RBlock, you must be a bonder, and you must already be bonded on the predecessor of the new RBlock you’re creating. The bond requirement for RBlock creation ensures that anyone who creates a new RBlock has something to lose if that RBlock is eventually rejected. -The protocol keeps track of the current required stake amount. Normally this will equal the base stake amount, which is a parameter of the Nitro chain. But if the chain has been slow to make progress lately, the required stake will increase, as described in more detail below. +The protocol keeps track of the current required bond amount. Normally this will equal the base bond amount, which is a parameter of the Nitro chain. But if the chain has been slow to make progress lately, the required bond will increase, as described in more detail below. The rules for staking are as follows: -- If you’re not staked, you can stake on the latest confirmed RBlock. When doing this, you deposit the current minimum stake amount. -- If you’re staked on an RBlock, you can also add your stake to any one successor of that RBlock. (The protocol tracks the maximum RBlock number you’re staked on, and lets you add your stake to any successor of that RBlock, updating your maximum to that successor.) This doesn’t require you to place a new stake. - - A special case of adding your stake to a successor RBlock is when you create a new RBlock as a successor to an RBlock you’re already staked on. -- If you’re staked only on the latest confirmed RBlock (and possibly earlier RBlocks), you or anyone else can ask to have your stake refunded. Your staked funds will be returned to you, and you will no longer be a staker. -- If you lose a challenge, your stake is removed from all RBlocks and you forfeit your staked funds. +- If you’re not bonded, you can bond on the latest confirmed RBlock. When doing this, you deposit the current minimum bond amount. +- If you’re bonded on an RBlock, you can also add your bond to any one successor of that RBlock. (The protocol tracks the maximum RBlock number you’re bonded on, and lets you add your bond to any successor of that RBlock, updating your maximum to that successor.) This doesn’t require you to place a new bond. + - A special case of adding your bond to a successor RBlock is when you create a new RBlock as a successor to an RBlock you’re already bonded on. +- If you’re bonded only on the latest confirmed RBlock (and possibly earlier RBlocks), you or anyone else can ask to have your bond refunded. Your bonded funds will be returned to you, and you will no longer be a bonder. +- If you lose a challenge, your bond is removed from all RBlocks and you forfeit your bonded funds. -Notice that once you are staked on an RBlock, there is no way to unstake. You are committed to that RBlock. Eventually one of two things will happen: that RBlock will be confirmed, or you will lose your stake. The only way to get your stake back is to wait until all of the RBlocks you are staked on are confirmed. +Notice that once you are bonded on an unresolved RBlock, there is no way to unbond. You are committed to that RBlock. Eventually one of two things will happen: that RBlock will be confirmed, or you will lose your bond. The only way to get your bond back is to wait until all of the RBlocks you are bonded on are confirmed. -#### Setting the current minimum stake amount +#### Setting the current minimum bond amount -One detail we deferred earlier is how the current minimum stake amount is set. Normally, this is just equal to the base stake amount, which is a parameter of the Nitro chain. However, if the chain has been slow to make progress in confirming RBlocks, the stake requirement will escalate temporarily. Specifically, the base stake amount is multiplied by a factor that is exponential in the time since the deadline of the first unresolved RBlock passed. This ensures that if malicious parties are placing false stakes to try to delay progress (despite the fact that they’re losing those stakes), the stake requirement goes up so that the cost of such a delay attack increases exponentially. As RBlock resolution starts advancing again, the stake requirement will go back down. +One detail we deferred earlier is how the current minimum bond amount is set. Normally, this is just equal to the base bond amount, which is a parameter of the Nitro chain. However, if the chain has been slow to make progress in confirming RBlocks, the bond requirement will escalate temporarily. Specifically, the base bond amount is multiplied by a factor that is exponential in the time since the deadline of the first unresolved RBlock passed. This ensures that if malicious parties are placing false bonds to try to delay progress (despite the fact that they’re losing those bonds), the bond requirement goes up so that the cost of such a delay attack increases exponentially. As RBlock resolution starts advancing again, the bond requirement will go back down. ### Rules for Confirming or Rejecting RBlocks @@ -356,18 +362,18 @@ The first unresolved RBlock can be confirmed if: - the RBlock's predecessor is the latest confirmed RBlock, and - the RBlock's deadline has passed, and -- there is at least one staker, and -- all stakers are staked on the RBlock. +- there is at least one bonder, and +- All bonders are bonded to the RBlock. The first unresolved RBlock can be rejected if: - the RBlock's predecessor has been rejected, or - all of the following are true: - the RBlock's deadline has passed, and - - there is at least one staker, and - - no staker is staked on the RBlock. + - there is at least one bonder, and + - no bonder is bonded on the RBlock. -A consequence of these rules is that once the first unresolved RBlock's deadline has passed (and assuming there is at least one staker staked on something other than the latest confirmed RBlock), the only way the RBlock can be unresolvable is if at least one staker is staked on it and at least one staker is staked on a different RBlock with the same predecessor. If this happens, the two stakers are disagreeing about which RBlock is correct. It’s time for a challenge, to resolve the disagreement. +A consequence of these rules is that once the first unresolved RBlock's deadline has passed (and assuming there is at least one bonder bonded on something other than the latest confirmed RBlock), the only way the RBlock can be unresolvable is if at least one bonder is bonded on it and at least one bonder is bonded on a different RBlock with the same predecessor. If this happens, the two bonders are disagreeing about which RBlock is correct. It’s time for a challenge, to resolve the disagreement. ## Challenges @@ -375,11 +381,11 @@ Suppose the rollup chain looks like this: ![img](https://lh4.googleusercontent.com/kAZY9H73dqcHvboFDby9nrtbYZrbsHCYtE5X9NIZQsvcz58vV0WUWUq1xsYKzYWQSc1nPZ8W86LLX0lD3y-ctEaG2ISa2Wpz2pYxTzW09P1UvqSDuoqkHlGDYLLMTzLqX4rlP8Ca) -RBlocks 93 and 95 are siblings (they both have 92 as predecessor). Alice is staked on 93 and Bob is staked on 95. +RBlocks 93 and 95 are siblings (they both have 92 as predecessor). Alice is bonded on 93 and Bob is bonded on 95. -At this point we know that Alice and Bob disagree about the correctness of RBlock 93, with Alice committed to 93 being correct and Bob committed to 93 being incorrect. (Bob is staked on 95, and 95 implicitly claims that 92 is the last correct RBlock before it, which implies that 93 must be incorrect.) +At this point we know that Alice and Bob disagree about the correctness of RBlock 93, with Alice committed to 93 being correct and Bob committed to 93 being incorrect. (Bob is bonded on 95, and 95 implicitly claims that 92 is the last correct RBlock before it, which implies that 93 must be incorrect.) -Whenever two stakers are staked on sibling RBlocks, and neither of those stakers is already in a challenge, anyone can start a challenge between the two. The rollup protocol will record the challenge and referee it, eventually declaring a winner and confiscating the loser’s stake. The loser will be removed as a staker. +Whenever two bonders are bonded on sibling RBlocks, and neither of those bonders is already in a challenge, anyone can start a challenge between the two. The rollup protocol will record the challenge and referee it, eventually declaring a winner and confiscating the loser’s bond. The loser will be removed as a bonder. The challenge is a game in which Alice and Bob alternate moves, with an Ethereum contract as the referee. Alice, the defender, moves first. @@ -439,18 +445,18 @@ Offchain Labs provides open source validator software, including a pre-built Doc Every validator can choose their own approach, but we expect validators to follow three common strategies: -- The _active validator_ strategy tries to advance the state of the chain by proposing new RBlocks. An active validator is always staked, because creating an RBlock requires being staked. A chain really only needs one honest active validator; any more is an inefficient use of resources. For the Arbitrum One chain, Offchain Labs runs an active validator. -- The _defensive validator_ strategy watches the rollup protocol operate. If only correct RBlocks are proposed, this strategy doesn't stake. But if an incorrect RBlock is proposed, this strategy intervenes by posting a correct RBlock or staking on a correct RBlock that another party has posted. This strategy avoids staking when things are going well, but if someone is dishonest it stakes in order to defend the correct outcome. -- The _watchtower validator_ strategy never stakes. It simply watches the rollup protocol and if an incorrect RBlock is proposed, it raises the alarm (by whatever means it chooses) so that others can intervene. This strategy assumes that other parties who are willing to stake will be willing to intervene in order to take some of the dishonest proposer’s stake, and that that can happen before the dishonest RBlock’s deadline expires. (In practice this will allow several days for a response.) +- The _active validator_ strategy tries to advance the state of the chain by proposing new RBlocks. An active validator is always bonded, because creating an RBlock requires being bonded. A chain really only needs one honest active validator; any more is an inefficient use of resources. For the Arbitrum One chain, Offchain Labs runs an active validator. +- The _defensive validator_ strategy watches the rollup protocol operate. If only correct RBlocks are proposed, this strategy doesn't bond. But if an incorrect RBlock is proposed, this strategy intervenes by posting a correct RBlock or staking on a correct RBlock that another party has posted. This strategy avoids staking when things are going well, but if someone is dishonest it bonds in order to defend the correct outcome. +- The _watchtower validator_ strategy never bonds. It simply watches the rollup protocol and if an incorrect RBlock is proposed, it raises the alarm (by whatever means it chooses) so that others can intervene. This strategy assumes that other parties who are willing to bond will be willing to intervene in order to take some of the dishonest proposer’s bond, and that that can happen before the dishonest RBlock’s deadline expires. (In practice this will allow several days for a response.) Under normal conditions, validators using the defensive and watchtower strategies won’t do anything except observe. A malicious actor who is considering whether to try cheating won’t be able to tell how many defensive and watchtower validators are operating incognito. Perhaps some defensive validators will announce themselves, but others probably won’t, so a would-be attacker will always have to worry that defenders are waiting to emerge. -The underlying protocol supports permissionless validation, i.e.,--anyone can do it. Currently on Arbitrum One, validators that require stake (i.e., active and defensive validators) are whitelisted; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization). +The underlying protocol supports permissionless validation, i.e.,--anyone can do it. Currently on Arbitrum One, validators that require bond (i.e., active and defensive validators) are whitelisted; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization). Who will be validators? Anyone will be able to do it, but most people will choose not to. In practice we expect people to validate a chain for several reasons. - Validators could be paid for their work, by the party that created the chain or someone else. A chain could be configured such that a portion of the funds from user transaction fees are paid directly to validators. -- Parties who have significant assets at stake on a chain, such as dapp developers, exchanges, power-users, and liquidity providers, may choose to validate in order to protect their investment. +- Parties who have significant assets at bond on a chain, such as dapp developers, exchanges, power-users, and liquidity providers, may choose to validate in order to protect their investment. - Anyone who chooses to validate can do so. Some users will probably choose to validate in order to protect their own interests or just to be good citizens. But ordinary users don’t need to validate, and we expect that the vast majority of users won’t. ## ArbOS @@ -606,7 +612,7 @@ The total fee charged to a transaction is the L2 basefee, multiplied by the sum AnyTrust is a variant of Arbitrum Nitro technology that lowers costs by accepting a mild trust assumption. -The Arbitrum protocol requires that all Arbitrum nodes, including validators (nodes that verify correctness of the chain and are prepared to stake on correct results), have access to the data of every L2 transaction in the Arbitrum chain's inbox. An Arbitrum rollup provides data access by posting the data (in batched, compressed form) on L1 Ethereum as calldata. The Ethereum gas to pay for this is the largest component of cost in Arbitrum. +The Arbitrum protocol requires that all Arbitrum nodes, including validators (nodes that verify correctness of the chain and are prepared to bond on correct results), have access to the data of every L2 transaction in the Arbitrum chain's inbox. An Arbitrum rollup provides data access by posting the data (in batched, compressed form) on L1 Ethereum as calldata. The Ethereum gas to pay for this is the largest component of cost in Arbitrum. AnyTrust relies instead on an external Data Availability Committee (hereafter, "the Committee") to store data and provide it on demand. The Committee has N members, of which AnyTrust assumes at least two are honest. This means that if N - 1 Committee members promise to provide access to some data, at least one of the promising parties must be honest. Since there are two honest members, and only one failed to make the promise, it follows that at least one of the promisers must be honest — and that honest member will provide data when it is needed to ensure the chain can properly function. diff --git a/arbitrum-docs/how-arbitrum-works/l1-gas-pricing.md b/arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx similarity index 100% rename from arbitrum-docs/how-arbitrum-works/l1-gas-pricing.md rename to arbitrum-docs/how-arbitrum-works/l1-gas-pricing.mdx diff --git a/arbitrum-docs/how-arbitrum-works/sequencer.md b/arbitrum-docs/how-arbitrum-works/sequencer.mdx similarity index 82% rename from arbitrum-docs/how-arbitrum-works/sequencer.md rename to arbitrum-docs/how-arbitrum-works/sequencer.mdx index 61e0df99a..80a3d66ca 100644 --- a/arbitrum-docs/how-arbitrum-works/sequencer.md +++ b/arbitrum-docs/how-arbitrum-works/sequencer.mdx @@ -15,7 +15,7 @@ Here, we start by assuming that the Sequencer is fully operational, and is runni If a user is posting a “standard” Arbitrum transaction (i.e., interacting with an L2 native dapp), the user will submit the signed transaction directly to the Sequencer, much like how a user submits a transaction to an Ethereum node when interacting with L1. Upon receiving it, the Sequencer will execute it and nearly instantaneously deliver the user a receipt. Some short time later — [usually no more than a few minutes](https://arbiscan.io/batches) — the Sequencer will include the user’s transaction in a batch and post it on L1 by calling one of the `SequencerInbox`’s `addSequencerL2Batch` methods. Note that only the Sequencer has the authority to call these methods; this assurance that no other party can include a message directly is, in fact, the very thing that gives the Sequencer the unique ability to provide instant, "soft-confirmation" receipts. Once posted in a batch, the transactions have L1-level finality. -Alternatively, a user can submit their L2 message to the Sequencer by posting it on the underlying L1. This path is necessary if the user wishes to perform some [L1 operation along with the L2](/how-arbitrum-works/arbos/l1-l2-messaging.md) message and to preserve atomicity between the two — the textbook example here being a token deposit via a [bridge](/build-decentralized-apps/token-bridging/01-overview.md) (escrow on L1, mint on L2). The user does this by publishing an L1 transaction (i.e., sending a normal transaction to an L1 node) that calls one of the relevant methods on the `Inbox` contract; i.e., `sendUnsignedTransaction`. This adds a message onto what we’ll call “the delayed Inbox”, (represented by the `delayedInboxAccs` in the `Bridge` contract), which is effectively a queue that messages wait in before being moved over to the core `Inbox`. The Sequencer will emit an L2 receipt about ~10 minutes after the transaction has been included in the delayed Inbox (the reason for this delay is to minimize the risk of short term L1 reorgs which could in turn cause an L2 reorg and invalidate the Sequencer’s L2 receipts.) Again, the last step is for the Sequencer to include the L2 message in a batch — when calling the batch submission methods, the Sequencer specifies how many messages in the delayed inbox to include — finalizing the transaction. +Alternatively, a user can submit their L2 message to the Sequencer by posting it on the underlying L1. This path is necessary if the user wishes to perform some [L1 operation along with the L2](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) message and to preserve atomicity between the two — the textbook example here being a token deposit via a [bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) (escrow on L1, mint on L2). The user does this by publishing an L1 transaction (i.e., sending a normal transaction to an L1 node) that calls one of the relevant methods on the `Inbox` contract; i.e., `sendUnsignedTransaction`. This adds a message onto what we’ll call “the delayed Inbox”, (represented by the `delayedInboxAccs` in the `Bridge` contract), which is effectively a queue that messages wait in before being moved over to the core `Inbox`. The Sequencer will emit an L2 receipt about ~10 minutes after the transaction has been included in the delayed Inbox (the reason for this delay is to minimize the risk of short term L1 reorgs which could in turn cause an L2 reorg and invalidate the Sequencer’s L2 receipts.) Again, the last step is for the Sequencer to include the L2 message in a batch — when calling the batch submission methods, the Sequencer specifies how many messages in the delayed inbox to include — finalizing the transaction. In sum — in either happy case, the user first delivers their message to the Sequencer, who in turn ensures that it arrives in the core Inbox. diff --git a/arbitrum-docs/how-arbitrum-works/timeboost/gentle-introduction.mdx b/arbitrum-docs/how-arbitrum-works/timeboost/gentle-introduction.mdx new file mode 100644 index 000000000..aaf7cffaa --- /dev/null +++ b/arbitrum-docs/how-arbitrum-works/timeboost/gentle-introduction.mdx @@ -0,0 +1,142 @@ +--- +title: 'A gentle Introduction: Timeboost' +sidebar_label: 'A gentle introduction' +description: 'Learn how Timeboost works and how it can benefit your Arbitrum-based project.' +author: leeederek +sme: leeederek +user_story: As a current or prospective Arbitrum user, I want to understand how Timeboost works and how to use it. +content_type: gentle-introduction +--- + +import ImageWithCaption from '@site/src/components/ImageCaptions/'; + +This introduction will walk you through Arbitrum Timeboost: a novel transaction ordering policy for Arbitrum chains that allows chain owners to capture the Maximal Extractable Value (MEV) on their chain and reduce spam, all while preserving fast block times and protecting users from harmful types of MEV, such as sandwich attacks and front-running. + +Timeboost is the culmination of over a year of research and development by the team at Offchain Labs and will soon be available for any Arbitrum chain, including Arbitrum One and Arbitrum Nova (should the Arbitrum DAO choose to adopt it). Like all features and upgrades to the Arbitrum technology stack, Timeboost will be rolled out on Arbitrum Sepolia first for testing, and chain owners will have the option of adopting Timeboost at any time or customizing Timeboost in any way they choose. + +### In a nutshell + +- The current "First-Come, First-Serve (FCFS)" ordering policy has many benefits, including a great UX and protection from harmful types of MEV. However, nearly all MEV on the chain is extracted by searchers who invest wastefully in hardware and spamming to win latency races (which negatively strains the network and leads to congestion). Timeboost is a new transaction ordering policy that preserves many of the great benefits of FCFS while unlocking a path for chain owners to capture some of the available MEV on their network and introducing an auction to reduce latency, racing, and, ultimately, spam. +- Timeboost introduces a few new components to an Arbitrum chain’s infrastructure: a sealed-bid second-price auction and a new "express lane" at an Arbitrum chain’s sequencer. Valid transactions submitted to the express lane will be sequenced immediately with no delay, while all other transactions submitted to the chain’s sequencer will experience a nominal delay (default: 200ms). The auction winner is granted the sole right to control the express lane for pre-defined, temporary intervals. The default block time for Arbitrum chains will continue to be industry-leading at 250ms, even with Timeboost enabled. What will change with Timeboost is that some transactions not in the express lane will be delayed to the next block. +- Timeboost is an optional feature for Arbitrum chains aimed at two types of groups of entities: (1) chain owners and their ecosystems and (2) sophisticated on-chain actors and searchers. Chain owners can use Timeboost to capture additional revenue from the MEV their chain generates already, and sophisticated on-chain actors and searchers will spend their resources on buying rights for the express lane (instead of spending those resources on winning latency races, which otherwise leads to spam and congestion on the network). +- Timeboost will work with both centralized and [decentralized sequencer setups](https://medium.com/@espressosys/espresso-systems-and-offchain-labs-publish-decentralized-timeboost-specification-b29ff20c5db8). The specification for a centralized sequencer is public ([here](https://github.com/OffchainLabs/timeboost-design)) and the [proposal before the Arbitrum DAO](https://forum.arbitrum.foundation/t/constitutional-aip-proposal-to-adopt-timeboost-a-new-transaction-ordering-policy/25167/1) allows us to deliver Timeboost to market sooner, rather than waiting until the design with a decentralized sequencer set up and its implementation are complete. + +## Why do Arbitrum chains need Timeboost? + +Today, Arbitrum chains order incoming transactions on a "First-Come, First-Serve (FCFS)" basis. This ordering policy was chosen as the default for Arbitrum chains because it is simple to understand and implement, enables fast block times (starting at 250ms and down to 100ms if desired), and protects users from harmful types of MEV like front-running & sandwich attacks. + +However, there are a few downsides to an FCFS ordering policy. Under FCFS, searchers are incentivized to participate in and try to win latency races through investments in off-chain hardware. This means that for searchers on Arbitrum chains, generating a profit from arbitrage and liquidation opportunities involves a lot of spam, placing stress on chain infrastructure and contributing to congestion. Additionally, all of the captured MEV on an Arbitrum chain today under FCFS goes to searchers - returning none of the available MEV to the chain owner or the applications on the chain. + +Timeboost retains most FCFS benefits while addressing FCFS limitations. + +#### Timeboost preserves the great UX that Arbitrum chains are known for + +- The default block time for Arbitrum chains will continue to be industry-leading at 250ms, even after Timeboost. What will change with Timeboost is that some transactions not in the express lane will be delayed to the next block. + +#### With Timeboost, Arbitrum chains will continue to protect users from harmful types of MEV + +- Timeboost only grants the auction winner a _temporary time advantage_ - not the power to view or reorder incoming transactions or be the first in every block. Furthermore, the transactions mempool will continue to be private, which means users with Timeboost enabled will continue to be protected from harmful MEV-like front-running and sandwich attacks. + +#### Timeboost unlocks a new value accrual path for chain owners + +- Chain owners may use Timeboost to capture a portion of the available MEV on their chain that would have otherwise gone entirely to searchers. There are many flavors of this, too - including custom gas tokens and/or redistribution of these proceeds back to the applications and users on the chain. + +#### Timeboost may help reduce spam and congestion on a network + +- By introducing the ability to “purchase a time advantage” through the Timeboost auction, it is expected that rational, profit-seeking actors will spend on auctions _instead of_ investing in hardware or infrastructure to win latency races. This diversion of resources by these actors is expected to reduce FCFS MEV-driven spam on the network. + +## What is Timeboost, and how does it work? + +Timeboost is a _transaction ordering policy_. It's a set of rules that the sequencer of an Arbitrum chain is trusted to follow when ordering transactions submitted by users. In the near future, multiple sequencers will be able to enforce those rules with decentralized Timeboost. + +For Arbitrum chains, the sequencer’s sole job is to take arriving, valid transactions from users, place them into an order dictated by the transaction ordering policy, and then publish the final sequence to a real-time feed and in compressed batches to the chain’s data availability layer. The current transaction ordering policy is FCFS, and Timeboost is a modified FCFS ordering policy. + +Timeboost is implemented using three separate components that work together: + +- **A special “express lane”** which allows valid transactions to be sequenced as soon as the sequencer receives them for a given round. +- **An off-chain auction** to determine the controller of the express lane for a given round. This auction is managed by an autonomous auctioneer. +- **An auction contract** deployed on the target chain to serve as the canonical source of truth for the auction results and handling of auction proceeds. + +To start, the default duration of a round is 60 seconds. Transactions not in the express lane will be subject to a default 200-millisecond artificial delay to their arrival timestamp before their transaction is sequenced, which means that some non-express lane transactions may get delayed to the next block. It’s important to note that the default Arbitrum block time will remain at 250 milliseconds (which can be adjusted to 100 milliseconds if desired). Let’s dive into how each of these components works. + +### The express lane + +![using the express lane](./images/centralized-timeboost-express-lane-workflow.jpg) +The express lane is implemented using a special endpoint on the sequencer, formally titled `timeboost_sendExpressLaneTransaction`. This endpoint is special because transactions submitted to it will be sequenced immediately by the sequencer, hence the name, express lane. The sequencer will only accept valid transaction payloads to this endpoint if they are correctly signed by the current round’s express lane controller. Other transactions can still be submitted to the sequencer as normal, but these will be considered non-express lane transactions and will, therefore, have their arrival timestamp delayed by 200 milliseconds. It is important to note that transactions from both the express and non-express lanes are eventually sequenced into a single, ordered stream of transactions for node operators to produce an assertion and later post the data to a data availability layer. The express lane controller does _not_: + +- Have the right to re-order transactions. +- Have a guarantee that their transactions will always be first at the “top-of-the-block.” +- Guarantee a profit at all. + +The value of the express lane will be the sum of how much MEV the express lane controller predicts they can extract during the upcoming round (i.e., MEV opportunity estimates made before the auction closes) _plus_ the amount of MEV extracted by the express lane controller while they are in control (that they otherwise did not predict). Understanding how the value of the express lane is determined can be useful for chain owners when adjusting to the artificial delay and the time before the auction closes. + +### The Timeboost auction + +Control of the express lane in each round (default: 60 seconds) is determined by a per-round auction, which is a sealed-bid, second-price auction. This auction is held to determine the express lane controller for the next round. In other words, the express lane controller was determined at any point in time in the previous auction round. Bids for the auction can be made with any ERC20 token, in any amount, and be collected by any address - at the full discretion of the chain owner. + +![timeboost auction workflow](./images/centralized-timeboost-auction-workflow.jpg) + +The auction for a round has a closing time that is `auctionClosingSeconds` (default: 15) seconds before the beginning of the round. This means that, in the default parameters, parties have 45 seconds to submit bids before the auction will no longer accept bids. In the 15 seconds between when bids are no longer accepted and when the new round begins, the autonomous auctioneer will verify all bids, determine the winner, and make a call to the on-chain auction contract to formally resolve the auction. + +### Auction contract + +Before placing a bid in the auction, a party must deposit funds into the Auction Contract. Deposits can be made, or funds can be added to an existing deposit at any time. These deposits are fully withdrawable, with some nominal delay (2 rounds, or 2 minutes by default), so as not to impact the outcome of an existing round. There is no minimum deposit amount, but there is a starting minimum bid of 0.001 ETH (default amount and token) called the "minimum reserve price". The minimum reserve price is set by the chain owner and can be updated at any time up to 30 seconds (default) before the start of the next round to ensure the auction participants will always know the reserve price at least 30 seconds before they must submit their bids. A reserve price can also be set by the chain owner (or by an address designated by the chain owner) as a way to raise the minimum bid as the Auction Contract enforces that the reserve price is never less than the minimum reserve price. + +![timeboost transferring and withdrawing](./images/centralized-timeboost-transfering-and-withdrawing.jpg) + +Once the autonomous auctioneer determines an auction winner, the auction contract will deduct the second-highest bid amount from the account of the highest bidder and transfer those funds to a `beneficiary` account designated by the chain owner by default. The `expressLaneControllerAddress` specified in the highest bid will become the express lane controller for the round. + +The auction contract also has functions that enable the express lane controller to update the address they wish to use for the express lane, which allows unique express lane control reselling use cases. + +### Default parameters + +Below are a few of the default Timeboost parameters mentioned earlier. All these parameters and more are configurable by the chain owner. + +| Parameter name | Description | Recommended default value | +| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------ | +| `roundDurationSeconds` | Duration of time that the sequencer will honor the express lane privileges for transactions signed by the current round’s express lane controller. | 60 seconds | +| `auctionClosingSeconds` | Time before the start of the next round. The autonomous auctioneer will not accept bids during this time interval. | 15 seconds | +| `beneficiary` | Address where proceeds from the Timeboost auction are sent to when `flushBeneficiaryBalance()` gets called on the auction contract. | An address controlled by the chain's owner | +| `_biddingToken` | Address of the token used to make bids in the Timeboost auction. It can be any ERC20 token (assuming the token address chosen does not have fee-on-transfer, rebasing, transfer hooks, or otherwise non-standard ERC20 logic). | WETH | +| `nonExpressDelayMsec` | The artificial delay applied to the arrival timestamp of non-express lane transactions _before_ the non-express lane transactions are sequenced. | 0.2 seconds, or 200 milliseconds | +| `reservePrice` | The minimum bid amount accepted by the auction contract for Timeboost auctions, denominated in `_biddingToken`. | None | +| `_minReservePrice` | A value that must be equal to or below the `reservePrice` to act as a "floor minimum" for Timeboost bids. Enforced by the auction contract. | 0.001 `WETH` | + +## Who is Timeboost for, and how do I use it? + +Timeboost is an optional addition to an Arbitrum chain’s infrastructure, meaning that enabling Timeboost is at the discretion of the chain owner and that an Arbitrum chain can fully function normally without Timeboost. + +When enabled, Timeboost is meant to serve different groups of parties with varying degrees of impact and benefits. Let’s go through them below: + +#### For regular users: + +Timeboost will have a minimal impact. Non-express lane transactions will be delayed by a nominal 200ms, which means to the average user, their transactions will take approximately 450ms to be sequenced and included into a block (up from approximately 200ms). All users will remain protected from harmful MEV activity, such as sandwich attacks and front-running, through the continued use of a private mempool. + +#### For chain owners: + +Timeboost represents a unique way to accrue value to their token and generate revenue for the chain. Explicitly, chain owners can set up their Timeboost auction to collect bid proceeds in the same token used for gas on their network and then choose what to do with these proceeds afterward. + +#### For searchers/arbitrageurs: + +Timeboost adds a unique twist to your existing or prospective MEV strategies that may become more profitable than before. For instance, purchasing the time advantage offered by Timeboost’s auction may end up costing _less_ than the costs to invest in hardware and win latency races. Another example is the potential new business model of reselling express lane rights to other parties in time slots or on a granular, per-transaction basis. + +### Special note on Timeboost for chain owners + +As with many new features and upgrades to Arbitrum Nitro, Timeboost is an optional feature that chain owners may choose to deploy and customize however they see fit. Deploying and enabling/disabling Timeboost on a live Arbitrum chain will not halt or impact the chain but will instead influence the chain's transaction ordering policy. An Arbitrum chain will, by default, fall back to FCFS if Timeboost is deployed but disabled or if there is no express lane controller for a given round. + +It is recommended that Arbitrum teams holistically assess the applicability and use cases of Timeboost for their chain before deploying and enabling Timeboost. This is because some Arbitrum chains may not have that much MEV (e.g., arbitrage) to begin with. Furthermore, we recommend that Arbitrum chains start with the default parameters recommended by Offchain Labs and closely monitor the results and impacts on your chain’s ecosystem over time before considering adjusting any of the parameters. + +### Wen mainnet? + +Timeboost’s auction contract has completed a third-party audit and is rapidly approaching production readiness. Specifically for Arbitrum One and Arbitrum Nova, a [temperature check vote on Snapshot](https://snapshot.box/#/s:arbitrumfoundation.eth/proposal/0xffe9bb38228fdaf3d121140856fd2d51c2ca7f8e0d1021c07e791cebb541129a) has already passed and the AIP will move towards an on-chain Tally vote next hopefully before the end of Q1 2025. + +In the meantime, please read the following resources to learn more about Timeboost: + +- [Arbitrum DAO Forum Post on Timeboost](https://forum.arbitrum.foundation/t/constitutional-aip-proposal-to-adopt-timeboost-a-new-transaction-ordering-policy/25167/86) +- [Timeboost FAQ](https://www.notion.so/bba234acf92e476b8ca5db6855d7da45?pvs=21) +- [Debunking common misconceptions about Timeboost](https://medium.com/offchainlabs/debunking-common-misconceptions-about-timeboost-92d937568494) +- [Technical specification for Timeboost with a centralized sequencer](https://github.com/OffchainLabs/timeboost-design/blob/main/research_spec.md) +- [Engineering design of Timeboost with a centralized sequencer](https://github.com/OffchainLabs/timeboost-design/blob/main/implementation_design.md) +- [Implementation of Timeboost with a centralized sequencer](https://github.com/OffchainLabs/nitro/pull/2561) +- [Technical specification for Timeboost with a decentralized sequencer](https://github.com/OffchainLabs/decentralized-timeboost-spec) +- [Audit report for Timeboost auction contracts](https://github.com/trailofbits/publications/blob/master/reviews/2024-08-offchainlabs-timeboost-auction-contracts-securityreview.pdf) diff --git a/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-auction-workflow.jpg b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-auction-workflow.jpg new file mode 100644 index 000000000..5dc6457bc Binary files /dev/null and b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-auction-workflow.jpg differ diff --git a/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-express-lane-workflow.jpg b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-express-lane-workflow.jpg new file mode 100644 index 000000000..20fdd6d45 Binary files /dev/null and b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-express-lane-workflow.jpg differ diff --git a/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-transfering-and-withdrawing.jpg b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-transfering-and-withdrawing.jpg new file mode 100644 index 000000000..fc914dfb3 Binary files /dev/null and b/arbitrum-docs/how-arbitrum-works/timeboost/images/centralized-timeboost-transfering-and-withdrawing.jpg differ diff --git a/arbitrum-docs/how-arbitrum-works/tx-lifecycle.md b/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx similarity index 89% rename from arbitrum-docs/how-arbitrum-works/tx-lifecycle.md rename to arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx index 722b58a77..4f8c6b4a1 100644 --- a/arbitrum-docs/how-arbitrum-works/tx-lifecycle.md +++ b/arbitrum-docs/how-arbitrum-works/tx-lifecycle.mdx @@ -4,7 +4,7 @@ As an introduction to the various components that compose the Arbitrum protocol, We'll also intersperse it with "finality checks," explaining what guarantees the client has over their transaction's finality (i.e., assurances that their transaction's result is guaranteed and won't later be altered) over the course of a transaction's various stages. -This overview will be focused on the Arbitrum Rollup protocol; see [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.md) for differences in the Arbitrum AnyTrust protocol. Also, for convenience/simplicity, we'll be describing the security properties of the core system itself; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization) for current decentralization status. +This overview will be focused on the Arbitrum Rollup protocol; see [Inside AnyTrust](/how-arbitrum-works/inside-anytrust.mdx) for differences in the Arbitrum AnyTrust protocol. Also, for convenience/simplicity, we'll be describing the security properties of the core system itself; see ["State of Progressive Decentralization"](https://docs.arbitrum.foundation/state-of-progressive-decentralization) for current decentralization status. For clarity on any terminology that may be unfamiliar, see our [glossary](/intro/glossary.mdx). @@ -22,9 +22,9 @@ Alternatively, a client can send a message to the Sequencer by signing and publi **See**: -- [Retryables](/how-arbitrum-works/arbos/l1-l2-messaging.md) -- [The Sequencer](/how-arbitrum-works/sequencer.md) -- [Token Bridge](/build-decentralized-apps/token-bridging/01-overview.md) +- [Retryables](/how-arbitrum-works/arbos/l1-l2-messaging.mdx) +- [The Sequencer](/how-arbitrum-works/sequencer.mdx) +- [Token Bridge](/build-decentralized-apps/token-bridging/01-overview.mdx) ### 2. Sequencer orders transaction (off-chain) @@ -36,9 +36,9 @@ Upon receiving a transaction, the Sequencer will: **See**: -- [ArbOS](/how-arbitrum-works/arbos/introduction.md) -- [Geth](/how-arbitrum-works/arbos/geth.md) -- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.md) / [L2 Gas](/how-arbitrum-works/gas-fees.md) +- [ArbOS](/how-arbitrum-works/arbos/introduction.mdx) +- [Geth](/how-arbitrum-works/arbos/geth.mdx) +- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx) / [L2 Gas](/how-arbitrum-works/gas-fees.mdx) #### ~ ~ ~ FINALITY CHECK: Trusted / Soft Confirmation ~ ~ ~ @@ -66,7 +66,7 @@ The Sequencer is forced to include messages from the delayed Inbox in the queued **See:** -- ["The Sequencer / Censorship Resistance."](/how-arbitrum-works/sequencer.md) +- ["The Sequencer / Censorship Resistance."](/how-arbitrum-works/sequencer.mdx) #### ~ ~ ~ FINALITY CHECK: Ethereum-Equivalent Finality! ~ ~ ~ @@ -85,9 +85,9 @@ A staked, active validator will then run the Arbitrum VM over the inputs in the **See**: -- [ArbOS](/how-arbitrum-works/arbos/introduction.md) -- [Geth](/how-arbitrum-works/arbos/geth.md) -- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.md) / [L2 Gas](/how-arbitrum-works/gas-fees.md) +- [ArbOS](/how-arbitrum-works/arbos/introduction.mdx) +- [Geth](/how-arbitrum-works/arbos/geth.mdx) +- [L1 pricing](/how-arbitrum-works/l1-gas-pricing.mdx) / [L2 Gas](/how-arbitrum-works/gas-fees.mdx) :::note @@ -97,7 +97,7 @@ RBlock assertions include claims about the state of the Outbox; if our transacti **See**: -- [The Outbox](/how-arbitrum-works/arbos/l2-l1-messaging.md) +- [The Outbox](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) #### 4a. RBlock is valid / goes unchallenged @@ -111,14 +111,14 @@ A dispute consists of two staked validators dissecting their disagreement down t **See:** -- [Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.md) -- [Wasm/WAVM](/how-arbitrum-works/fraud-proofs/wasm-wavm.md) +- [Challenges](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx) +- [Wasm/WAVM](/how-arbitrum-works/fraud-proofs/wasm-wavm.mdx) L1 contracts also keep track of the tree of all assertions; i.e., how many stakers are in disagreement, who is currently disputing with whom, etc. We refer to this level of Arbitrum's design architecture as its "assertion tree protocol." **See:** -- [Assertion Tree Protocol](/how-arbitrum-works/assertion-tree.md) +- [Assertion Tree Protocol](/how-arbitrum-works/assertion-tree.mdx) #### ~ ~ ~ FINALITY CHECK: STILL THE SAME Ethereum-Equivalent Finality! ~ ~ ~ diff --git a/arbitrum-docs/how-arbitrum-works/why-nitro.md b/arbitrum-docs/how-arbitrum-works/why-nitro.mdx similarity index 85% rename from arbitrum-docs/how-arbitrum-works/why-nitro.md rename to arbitrum-docs/how-arbitrum-works/why-nitro.mdx index ab690c738..a0d6afe7d 100644 --- a/arbitrum-docs/how-arbitrum-works/why-nitro.md +++ b/arbitrum-docs/how-arbitrum-works/why-nitro.mdx @@ -9,9 +9,9 @@ Nitro represents the latest step in the evolution of Arbitrum technology; it is Viewed from a distance, the Classic and Nitro systems do similar things: both seek to create an execution environment as close to the EVM as possible which operates as a second layer to Ethereum; i.e., safety of the L2 virtual machine’s state updates can be guaranteed and enforced via succinct fraud proofs on Ethereum itself. -In Arbitrum Classic, this was achieved via a custom-made virtual machine, which we call the Arbitrum Virtual Machine (AVM). The implementation of Arbitrum’s L2 state machine—known as [“ArbOS”](/how-arbitrum-works/arbos/introduction.md) — is effectively a program that is compiled and uploaded to the AVM; ArbOS includes (among other things) the ability to emulate EVM execution. +In Arbitrum Classic, this was achieved via a custom-made virtual machine, which we call the Arbitrum Virtual Machine (AVM). The implementation of Arbitrum’s L2 state machine—known as [“ArbOS”](/how-arbitrum-works/arbos/introduction.mdx) — is effectively a program that is compiled and uploaded to the AVM; ArbOS includes (among other things) the ability to emulate EVM execution. -In Nitro, instead of using the AVM for low-level instructions, we use WebAssembly (Wasm). Since Go code can be compiled down to Wasm, we can implement the ArbOS program in Go, and include within it (as a sub-module) [Geth itself](/how-arbitrum-works/arbos/geth.md), the most widely used Ethereum implementation. +In Nitro, instead of using the AVM for low-level instructions, we use WebAssembly (Wasm). Since Go code can be compiled down to Wasm, we can implement the ArbOS program in Go, and include within it (as a sub-module) [Geth itself](/how-arbitrum-works/arbos/geth.mdx), the most widely used Ethereum implementation. This architecture—in which Geth’s EVM implementation can be used directly—is Nitro’s defining feature, and is principally what we’re talking about when we talk about “Nitro.” Most of Nitro’s benefits are a direct or indirect consequence of this design choice. We can summarize these benefits as follows: lower fees, better Ethereum compatibility, and simplicity. @@ -21,7 +21,7 @@ This architecture—in which Geth’s EVM implementation can be used directly— To understand the core of Nitro’s efficiency, we have to dig a little deeper into the classic AVM. In classic, high-level code (Solidity, Vyper, etc.) would be initially compiled down to the EVM bytecode (as though it were to be deployed on Ethereum). This bytecode would then be transpiled to its corresponding AVM instructions by ArbOS; this AVM bytecode would function both as the instructions for running the L2 VM, and the inputs used to prove fraud; in an interactive fraud proof, two validators dissect a segment of AVM bytecode until a “one step proof” — i.e., a state transition that represents a single AVM opcode — would be executed in the EVM of the L1 itself. -Nitro has a similar bytecode-sandwich-like structure; [to prove fraud in Nitro](/how-arbitrum-works/fraud-proofs/challenge-manager.md), the node’s Go code is compiled into WebAssembly (Wasm), the individual instructions of which are ultimately similarly dissected over to zero-in on an invalid state update. There is, however, a crucial difference: Nitro, being essentially the EVM, periodically produces Ethereum-esque blocks; we can think of these blocks as natural state-checkpoints within a larger assertion of an L2 state update. Nitro takes advantage of this by splitting the interactive fraud proof game into 2 phases: first, two disputing parties narrow down their disagreement to a single block; then (and only then) do they compile the block to Wasm, and thereby continue to narrow down their dispute to Wasm instruction. Thus, this Wasm compilation step only needs to happen when a dispute occurs. +Nitro has a similar bytecode-sandwich-like structure; [to prove fraud in Nitro](/how-arbitrum-works/fraud-proofs/challenge-manager.mdx), the node’s Go code is compiled into WebAssembly (Wasm), the individual instructions of which are ultimately similarly dissected over to zero-in on an invalid state update. There is, however, a crucial difference: Nitro, being essentially the EVM, periodically produces Ethereum-esque blocks; we can think of these blocks as natural state-checkpoints within a larger assertion of an L2 state update. Nitro takes advantage of this by splitting the interactive fraud proof game into 2 phases: first, two disputing parties narrow down their disagreement to a single block; then (and only then) do they compile the block to Wasm, and thereby continue to narrow down their dispute to Wasm instruction. Thus, this Wasm compilation step only needs to happen when a dispute occurs. It’s worth reiterating this distinction: in classic, the code executed in the happy/common case is equivalent to the code used in a fraud proof, whereas in Nitro, we can have different contexts for the two cases for execution and for proving. When a claim is being disputed, we ultimately compile down to Wasm bytecode, but in the happy/common case, we can execute the node’s Go code natively, i.e., in whatever execution environment one’s machine uses. Essentially, Nitro is capable of being even more “optimistic” in its execution, compiling to Wasm only just-in-time as required. The common case of native execution is happily far faster and more performant, and better node performance, of course, translates to lower fees for end users. @@ -33,11 +33,11 @@ The flexibility that Arbitrum core architecture offers meant that even in the cl The Nitro architecture, however, fundamentally requires only that its VM can be compiled down to Wasm; so not just Geth, but any Go code can be incorporated. Thus, Nitro can (and does) use widely used, battle-tested compression libraries for calldata compression, and thus significantly reduces the cost of posting transaction batches. -Note that supporting calldata compression also requires a more sophisticated mechanism for [determining the price of calldata](/how-arbitrum-works/l1-gas-pricing.md) and ensuring that batch posters are ultimately properly compensated, a mechanism which Nitro also introduces. +Note that supporting calldata compression also requires a more sophisticated mechanism for [determining the price of calldata](/how-arbitrum-works/l1-gas-pricing.mdx) and ensuring that batch posters are ultimately properly compensated, a mechanism which Nitro also introduces. ## Closer EVM Compatibility -The classic AVM achieved a strong degree of EVM compatibility with its ability to handle any EVM opcodes. However, being a distinct VM, the AVM’s internal behavior in some ways diverged with that of the EVM. Most noticeable for smart contract developers was the denomination of “ArbGas”, whose units didn’t correspond to Ethereum L1 gas; e.g., a simple transfer takes 21,000 gas on L1 but over 100,000 ArbGas in the AVM. This meant that contracts that included gas calculation logic that were initially built for L1 had to be modified accordingly to be deployed on L2, and likewise with any client-side tooling with similar hardcoded expectations about a chain’s gas. With Nitro, [gas](/how-arbitrum-works/gas-fees.md) on L1 and L2 essentially correspond 1:1. +The classic AVM achieved a strong degree of EVM compatibility with its ability to handle any EVM opcodes. However, being a distinct VM, the AVM’s internal behavior in some ways diverged with that of the EVM. Most noticeable for smart contract developers was the denomination of “ArbGas”, whose units didn’t correspond to Ethereum L1 gas; e.g., a simple transfer takes 21,000 gas on L1 but over 100,000 ArbGas in the AVM. This meant that contracts that included gas calculation logic that were initially built for L1 had to be modified accordingly to be deployed on L2, and likewise with any client-side tooling with similar hardcoded expectations about a chain’s gas. With Nitro, [gas](/how-arbitrum-works/gas-fees.mdx) on L1 and L2 essentially correspond 1:1. (Note that transactions have to cover the total cost of both L2 execution and L1 calldata; the value returned by Arbitrum nodes' `eth_estimateGas` RPC — and in turn, the value users will see in their wallets — is calculated to be sufficient to cover this total cost. See [2-D fees](https://medium.com/offchainlabs/understanding-arbitrum-2-dimensional-fees-fd1d582596c9) for more.) 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 e2c53f1ab..737394af6 100644 --- a/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx +++ b/arbitrum-docs/launch-orbit-chain/aep-fee-router-introduction.mdx @@ -10,7 +10,7 @@ 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](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/aep/ArbitrumExpansionProgramTerms.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: diff --git a/arbitrum-docs/launch-orbit-chain/aep-license.mdx b/arbitrum-docs/launch-orbit-chain/aep-license.mdx new file mode 100644 index 000000000..6871fe7b4 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/aep-license.mdx @@ -0,0 +1,23 @@ +--- +title: 'Orbit licensing' +sidebar_label: 'Orbit licensing' +description: 'Learn about the Orbit license and AEP.' +author: SHughes +sme: SHughes +user_story: As a prospective Orbit chain owner, I need to understand the Orbit license. +content_type: get-started +--- + +## What do I need to know about the Orbit license? + +Nitro is currently licensed under a [Business Source License](https://github.com/OffchainLabs/nitro/blob/master/LICENSE.md), similar to DeFi protocols like Uniswap and Aave, among others, with an “Additional Use Grant” to ensure that everyone can have full comfort using and running nodes on all public Arbitrum chains. + +The Additional Use Grant also permits deployment of the Nitro software in a permissionless, zero-cost fashion, as a new blockchain provided that the chain settles to either Arbitrum One or Arbitrum Nova. L3s that settle to Arbitrum One or Nova have no obligation to share revenue with the Arbitrum DAO and remain first class members of the Arbitrum ecosystem. +As an expansion of this license, the [Arbitrum Expansion Program](https://docs.arbitrum.foundation/aep/ArbitrumExpansionProgramTerms.pdf) (AEP) is a self-service licensing model that makes it easy for developers to build and customize L2s/L3s using Arbitrum’s technology alongside different parent chains. + +Benefits: + +- Leverage battle-tested technology to permissionlessly deploy L2s/L3s that settle to any supported parent chain. +- Governance freedom - Orbit chains are not required to be governed by the Arbitrum DAO. +- Flexible licensing allows developers to modify chain configurations. Orbit chains are free to modify any part of the stack, including implementation of custom gas tokens, alternative DA integrations, novel sequencing mechanisms, account abstraction, altVMs, etc. +- L3s that settle to parent chains other than Arb1 and Nova must contribute [net chain revenue](https://docs.arbitrum.io/launch-orbit-chain/how-tos/calculate-aep-fees#calculating-aep-fees), where 8% flows to the DAO and 2% to the developer guild. diff --git a/arbitrum-docs/launch-orbit-chain/assets/bold-orbit-permissionless-vs-permissioned.png b/arbitrum-docs/launch-orbit-chain/assets/bold-orbit-permissionless-vs-permissioned.png new file mode 100644 index 000000000..d13245e44 Binary files /dev/null and b/arbitrum-docs/launch-orbit-chain/assets/bold-orbit-permissionless-vs-permissioned.png differ diff --git a/arbitrum-docs/launch-orbit-chain/bold-adoption-for-orbit-chains.mdx b/arbitrum-docs/launch-orbit-chain/bold-adoption-for-orbit-chains.mdx new file mode 100644 index 000000000..8da2da0c4 --- /dev/null +++ b/arbitrum-docs/launch-orbit-chain/bold-adoption-for-orbit-chains.mdx @@ -0,0 +1,107 @@ +--- +title: 'BoLD for Orbit chains' +description: 'Learn how to integrate BoLD with your Orbit chain' +user_story: 'As a developer or researcher of the Arbitrum product suite, I want to learn about BoLD, a next-generation dispute protocol that enables permissionless validation.' +content_type: release announcement +author: leeederek +sme: leeederek +target_audience: 'Developers who want to build on Arbitrum using popular programming languages, like Rust' +sidebar_position: 1 +--- + +:::info PUBLIC PREVIEW DOCUMENT + +This document is currently in **public preview** and may change significantly as feedback is captured from readers like you. Click the _Request an update_ button at the top of this document or [join the Arbitrum Discord](https://discord.gg/arbitrum) to share your feedback. + +::: + +## Launch details and key dates + +- **Status:** Alpha - continued testing and evaluation of performance of BoLD with Stylus +- **Arbitrum Sepolia** Q4 2024 +- **Arbitrum One** Q1 2025 +- **Arbitrum Nova** Q1 2025 + +### tldr; + +Arbitrum BoLD is an upgrade to the dispute protocol on Arbitrum chains +that delivers both permissionless validation and core security benefits. As with all features on the +Arbitrum stack, Orbit chains can adopt BoLD at their own discretion and on their own timeline. To upgrade +to BoLD, it is required to upgrade both the Nitro node software and the rollup's smart contracts on its +parent chain.{' '} + +### Recommended Adoption Path + +BoLD brings new security benefits to Orbit chains, regardless of whether their validators are permissioned or permissionless. These new security benefits include improved resistance to delay attacks and increased censorship resistance for `L3s`. We strongly recommend Orbit chains adopt Arbitrum BoLD to register these security benefits while **keeping validation permissioned**. + +:::warning + +It is strongly recommended that existing and prospective Orbit chains upgrade to use Arbitrum BoLD but **keep validation permissioned** because of the increased risks associated with allowing any entity to advance and challenge the state of your chain. The risks are summarized below. Rigorous testing and research has been poured into the parameters chosen for Arbitrum One and so we cannot formally support or endorse use of permissionless Arbitrum BoLD in other configurations. + +::: + +Below is a quick breakdown of the benefits of permissioned BoLD vs. permissionless BoLD for your Orbit chain: + +![Alt Text](./assets/bold-orbit-permissionless-vs-permissioned.png) + +### Benefits of adopting Arbitrum BoLD + +Arbitrum BoLD enables an Arbitrum chain to be permissionlessly validated thanks to several key improvements to the existing dispute protocol. These key improvements benefit an Arbitrum Orbit chain even if validation is kept permissioned on a BoLD-enabled Orbit chain. + +Below are some benefits for an Orbit chain that come with adopting Arbitrum BoLD - **regardless of whether validation is kept permissioned or not**: + +#### Improved resistance to delay attacks + +Disputes on a BoLD-enabled chain are resolved in a round-robin style format where disputes can be concurrently resolved. This is an evolution from the current dispute protocol, where challenges are resolved one-by-one. This evolution means that an upper time bound can be placed on all disputes such that a malicious actor cannot delay the chain indefinitely like they can today. Even when validation is kept permissioned, this upper time bound is critical to mitigating the risk of [delay attacks](https://medium.com/offchainlabs/solutions-to-delay-attacks-on-rollups-434f9d05a07a) by parties on the validator allowlist for an Orbit chain. + +#### Being on the latest version of Arbitrum technology + +Adopting Arbitrum BoLD for your Orbit chain will require upgrading the Nitro node software and deploying a new set of contracts on your parent chain. While not specifically related to Arbitrum BoLD, it is always strongly recommended that Orbit chain owners upgrade and keep their chain on the latest stable releases of both Nitro node software and the relevant on-chain contracts. This is critical to ensure your Orbit chain benefits from the latest security improvements and features that the Offchain Labs team is constantly churning out. + +#### Secured by interactive fraud-proofs + +Arbitrum BoLD is not an upgrade to a different type of proving architecture and will continue to be secured with an interactive proving game between validators using fraud proofs. The same single-honest party assumption applies but now with strict improvements to security to the point where chains, like Arbitrum One, can be permissionlessly validated and have their state assertions be permissionlesly challenged. + +#### Use of your project's native token as the bonding asset to secure the chain + +Arbitrum BoLD enables the chain owner to use any `ERC-20` token on the parent chain as the bond for validators to participate in securing the network. By default, this token will be `WETH` for Arbitrum One and we do not recommend teams to use alternative tokens as the bonding asset. For more information on the rationale, we recommend teams consult our documentation to understand [why `WETH` was selected for Arbitrum One](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction#q-why-is-arb-not-the-bonding-token-used-in-bold-on-arbitrum-one) (and not `ARB`). + +#### Increased censorship resistance for `L3` Orbit chains + +Today, the force inclusion window is a fixed 24 hours. This force inclusion window exists to enable both users and validators to force-include their transactions and assertions on the parent chain, with a 24-hour delay, if the sequencer is offline or censoring transactions. Arbitrum BoLD's release will come with the _Censorship Timeout_ feature that will automatically reduce the force inclusion time window if the parent chain or sequencer is maliciously censoring user transactions/assertions or the sequencer goes offline. This massively benefits Orbit `L3` chains (that settle to a BoLD-enabled parent chain) as it ensures the chain can advance with minimal UX degradation during periods of censorship. You can read more about how this feature works in the [gentle introduction to BoLD](https://docs.arbitrum.io/how-arbitrum-works/bold/gentle-introduction#q-how-do-bold-based-l3s-challenge-periods-operate-considering-the-worst-case-scenario). + +### Caveats that come with adopting Arbitrum BoLD for permissionless validation + +Arbitrum BoLD's implementation and specification have been thoroughly tested and audited. The upgrade to Arbitrum BoLD is not the subject of this section, but rather the caveats and nuances that come with whether to enable permissionless validation. + +:::warning + +It is strongly recommended that existing and prospective Orbit chains upgrade to use Arbitrum BoLD but **keep validation permissioned** because of the increased risks associated with allowing any entity to advance and challenge the state of your chain. The risks are summarized below. Rigorous testing and research has been poured into the parameters chosen for Arbitrum One and so we cannot formally support or endorse use of permissionless Arbitrum BoLD in other configurations. + +::: + +Enabling permissionless validation means that any entity can spin up a validator and open challenges to dispute invalid claims made by other validators on the network. This opens up an Orbit chain to the risk of spam and attacks by unknown and malicious entities. To mitigate this risk for Arbitrum One, a considerable amount of research and testing has been done to optimize the trade-offs between deterring attacks and managing the costs of defending Arbitrum for honest parties. This research includes carefully calculating all relevant bond sizes, challenge period durations, and relevant plans for operating the infrastructure. More information on this research can be found in the [BoLD whitepaper](https://arxiv.org/abs/2404.10491). Below are a few examples of various risks that an Orbit chain will hold should they pursue permissionless BoLD: + +#### Risk of resource exhaustion attacks + +Where malicious entities can acquire and utilize more resources than honest parties can put together during a challenge. Such an attack can take many forms and includes both on-chain and off-chain computational/infra costs. For example, a well-coordinated attack on an Orbit chain could overwhelm honest parties if the malicious actors can spend more gas and computational power and acquire more of the bonding asset than the defenders can. This risk can be mitigated by a combination of high bond sizes, use of a price-independent bonding asset, use of a bonding asset with high liquidity, strong economic guarantees that attackers will lose most of their resources, sufficiently long challenge periods, and robust infrastructure operations and resources that can respond and scale up when necessary. More information on resource exhaustion attacks and how Arbitrum BoLD's design accounts for this risk can be found in [Section 6.1.4 of the BoLD whitepaper](https://arxiv.org/abs/2404.10491). We recommend teams consider a resource exhaustion ratio greater than 5 assuming very high L1 gas costs (like 100gwei/gas). + +#### Increased infrastructure costs and overhead + +Related to, and expanding on, the above point about resource exhaustion attacks, the honest parties operating active validators and proposers for a BoLD-enabled chain will need to be ready to vertically scale their infrastructure, and cover the off-chain costs of doing so, in the event of an attack. This is because a malicious actor may choose to spam and overwhelm the honest defenders with multiple challenges. Making moves, honest or malicious, costs resources to perform bisections on history committments down to a single step of execution. If this happens, each malicious challenge must be met with an honest counter-challenge during the interactive fraud proof game. Orbit chains who decide to adopt Arbitrum BoLD in permissionless mode are strongly encouraged to work with their Rollup-as-a-Service (RaaS) team to: deploy robust monitoring for challenges, set aside a budget to vertically scale up infrastructure and fund counter-challenges, and have an incident response plan drafted and rehearsed to ensure prompt and decisive reactionary steps in the event of an attack. + +#### Risks to liveness or delays of the chain + +If the bond sizes are set too low, an adversary can cheaply create a challenge and delay confirmation of an assertion for up to an entire extra challenge period if they can censor honest BoLD moves. Remember that challenges, while time-bound, still take time to complete. Delaying the confirmation of assertions for a chain could negatively impact the chain in many ways that an attacker could benefit from (e.g., profiting from price volatility and price impacts on the Orbit chain's token may make delaying the chain worthwhile for an attacker). We recommend teams set bond sizes to be much greater than the opportunity cost of a week of delay, based on your chain's TVL (e.g. if your chain's TVL is $1B, then the opportunity cost of $1B should be used as a _floor_ for the block level bond amount size). We further recommend that the bonding token used is highly liquid on the parent chain and relatively non-volatile. + +### Conclusion for Orbit chains considering BoLD Permissionless Validation + +Due to the uniquely different tokenomics, sizes, and varying types of Arbitrum Orbit chains deployed (or in active development) today, Offchain Labs does not provide a "one-size-fits-all" recommendation for how best to safely set up and enable permissionless validation for Orbit chains. Instead, we recommend teams adopt Arbitrum BoLD but keep validation permissioned. + +Should Orbit teams strongly desire to adopt Arbitrum BoLD in permissionless mode, we do not endorse using configurations that differ from those on [Arbitrum One](https://github.com/OffchainLabs/nitro-contracts/blob/bold-merge/scripts/files/configs/arb1.ts). We especially do not recommend teams use custom ERC20 tokens as the bonding asset and/or with low bond minimums. If your team would like to have permissionless validation for your Orbit chain, please reach out to us [via this form](https://docs.google.com/forms/d/e/1FAIpQLSe5YWxFbJ8DgWcDNbIW2YYuTRmegtx2FHObym00_sOt0kq4wA/viewform) so that we can schedule some time to understand your needs better. + +### How to adopt Arbitrum BoLD + +As mentioned earlier, the upgrade to the dispute protocol involves both a Nitro node software upgrade and the deployment/upgrade of new smart contracts on your Orbit's parent chain. + +More details on deploying Arbitrum BoLD for your Orbit chain will be added here when they are available. diff --git a/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md b/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md index d62962515..2f6cb58de 100644 --- a/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md +++ b/arbitrum-docs/launch-orbit-chain/concepts/custom-gas-token-sdk.md @@ -21,7 +21,7 @@ Custom gas token support in the Arbitrum SDK introduces a suite of APIs designed 2. **Erc20Bridger Context:** - **APIs:** `getApproveGasTokenRequest` and `approveGasToken`. - - **Purpose:** In the scenario of bridging ERC20 assets to an Orbit chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses Retryable tickets and needs specific amount of fees to be paid for creation and redemption of the ticket. For more information about retryable tickets please take a look at [this](/how-arbitrum-works/arbos/l1-l2-messaging.md#retryable-tickets) part of our docs. The Orbit chain operates as a custom gas token network, necessitating the payment of fees in native tokens for the creation of retryable tickets and their redemption on the Orbit chain. To cover the submission and execution fees associated with retryable tickets on the Orbit chain, an adequate amount of native tokens must be approved and allocated on the parent chain to cover the fees. + - **Purpose:** In the scenario of bridging ERC20 assets to an Orbit chain, these APIs play a crucial role. Token Bridging on Arbitrum Nitro stack uses Retryable tickets and needs specific amount of fees to be paid for creation and redemption of the ticket. For more information about retryable tickets please take a look at [this](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets) part of our docs. The Orbit chain operates as a custom gas token network, necessitating the payment of fees in native tokens for the creation of retryable tickets and their redemption on the Orbit chain. To cover the submission and execution fees associated with retryable tickets on the Orbit chain, an adequate amount of native tokens must be approved and allocated on the parent chain to cover the fees. - **Note** that you should use `Erc20Bridger` when bridging an ERC-20 token between the parent chain and the orbit chain. **Note** that these APIs are just needed for `custom gas token` orbit chains and for ETH-powered rollup and anytrust orbit chains, you don't need to use them. @@ -32,7 +32,7 @@ Custom gas token support in the Arbitrum SDK introduces a suite of APIs designed ### Registering a custom token in the Token Bridge -When [registering a custom token in the Token Bridge](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md#setting-up-your-token-with-the-generic-custom-gateway) of a custom-gas-token Orbit chain, there's an additional step to perform before calling `registerTokenToL2`. +When [registering a custom token in the Token Bridge](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx#setting-up-your-token-with-the-generic-custom-gateway) of a custom-gas-token Orbit chain, there's an additional step to perform before calling `registerTokenToL2`. Since the Token Bridge [router](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/gateway/L1OrbitGatewayRouter.sol#L142-L144) and the [generic-custom gateway](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/ethereum/gateway/L1OrbitCustomGateway.sol#L203-L210) expect to have allowance to transfer the native token from the `msg.sender()` to the inbox contract, it's usually the token in the parent chain who handles those approvals. In the [TestCustomTokenL1](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/test/TestCustomTokenL1.sol#L158-L168), we offer as an example of implementation. We see that the contract transfers the native tokens to itself and then approves the router and gateway contracts. If we follow that implementation, we only need to send an approval transaction to the native token to allow the TestCustomTokenL1 to transfer the native token from the caller of the `registerTokenToL2` function to itself. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/add-orbit-chain-to-bridge-ui.md b/arbitrum-docs/launch-orbit-chain/how-tos/add-orbit-chain-to-bridge-ui.md index 3289c468e..cb029dfa5 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/add-orbit-chain-to-bridge-ui.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/add-orbit-chain-to-bridge-ui.md @@ -10,7 +10,7 @@ This how-to will walk you through the process of adding your Orbit chain to the ## Request adding a mainnet Orbit chain to the Arbitrum bridge -Mainnet Orbit chains can be added to the Arbitrum Bridge by filling out [this form](https://forms.gle/LrVskEd3DTtXSPwx7). +Mainnet Orbit chains can be added to the Arbitrum Bridge by filling out [this form](https://github.com/OffchainLabs/arbitrum-token-bridge/issues/new/choose). Once receiving your request, our team will review and apply internal criteria to include your chain in the bridge. Here are some of the criteria that a chain must follow to be added to the bridge: diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/arbos-upgrade.md b/arbitrum-docs/launch-orbit-chain/how-tos/arbos-upgrade.md index dd453264d..a75c83eaf 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/arbos-upgrade.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/arbos-upgrade.md @@ -10,11 +10,11 @@ sidebar_position: 3 This how-to provides step-by-step instructions for Orbit chain operators who want to upgrade ArbOS on their Orbit chain(s). Familiarity with ArbOS, Orbit, and [chain ownership](../concepts/chain-ownership.md) is expected. Note that Orbit chain owners have full discretion over when and whether to upgrade their ArbOS version. -The specific upgrade requirements for each ArbOS release are located under each reference page for that specific [ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.md#list-of-available-arbos-releases). +The specific upgrade requirements for each ArbOS release are located under each reference page for that specific [ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.mdx#list-of-available-arbos-releases). #### Step 1: Update Nitro on nodes and validators -Refer to the [requirements for the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.md) to identify the specific [Nitro release](https://github.com/OffchainLabs/nitro/releases/) that supports the ArbOS version that you're upgrading to. For example, if your upgrade targets ArbOS 20, you'd use Nitro `v2.3.1` (Docker image: `offchainlabs/nitro-node:v2.3.1-26fad6f`) or higher. This is the version of the Nitro stack that needs to be running on each of your Orbit chain's nodes. A list of [all Nitro releases can be found on Github](https://github.com/OffchainLabs/nitro/releases). +Refer to the [requirements for the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.mdx) to identify the specific [Nitro release](https://github.com/OffchainLabs/nitro/releases/) that supports the ArbOS version that you're upgrading to. For example, if your upgrade targets ArbOS 20, you'd use Nitro `v2.3.1` (Docker image: `offchainlabs/nitro-node:v2.3.1-26fad6f`) or higher. This is the version of the Nitro stack that needs to be running on each of your Orbit chain's nodes. A list of [all Nitro releases can be found on Github](https://github.com/OffchainLabs/nitro/releases). Begin by upgrading your validator node(s) to the specified Nitro version, then update each remaining Orbit node to match this version. @@ -24,9 +24,9 @@ Note that upgrading your node version _must occur_ before the deadline establish While every ArbOS upgrade will require an update to the Wasm module root, not every ArbOS upgrade will require an upgrade to the chain's `nitro-contracts` version. -If necessary, as defined in the release notes for each ArbOS release ([example of ArbOS 20](../../run-arbitrum-node/arbos-releases/arbos20.md)), you may need to deploy new versions of some (or all) of the Nitro contracts to the parent chain of your Orbit chain. These contracts include the rollup logic, bridging logic, fraud-proof contracts, and interfaces for interacting with Nitro precompiles. To verify the current version of your Nitro contracts, follow [these instructions](https://github.com/OffchainLabs/orbit-actions/blob/main/README.md#check-version-and-upgrade-path) while replacing the inbox contract address and network name with that of your Orbit chain. This information will allow you to find the correct upgrade path for your Nitro contracts. +If necessary, as defined in the release notes for each ArbOS release ([example of ArbOS 20](../../run-arbitrum-node/arbos-releases/arbos20.mdx)), you may need to deploy new versions of some (or all) of the Nitro contracts to the parent chain of your Orbit chain. These contracts include the rollup logic, bridging logic, fraud-proof contracts, and interfaces for interacting with Nitro precompiles. To verify the current version of your Nitro contracts, follow [these instructions](https://github.com/OffchainLabs/orbit-actions/blob/main/README.md#check-version-and-upgrade-path) while replacing the inbox contract address and network name with that of your Orbit chain. This information will allow you to find the correct upgrade path for your Nitro contracts. -To update the Wasm module root and deploy your chain's Nitro contracts to the parent chain for the most recent ArbOS release, you will need the following inputs (obtained from the [requirements for the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.md)): +To update the Wasm module root and deploy your chain's Nitro contracts to the parent chain for the most recent ArbOS release, you will need the following inputs (obtained from the [requirements for the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.mdx)): - The WASM module root, and if necessary, - The required `nitro-contracts` version @@ -68,8 +68,8 @@ When scheduling the ArbOS upgrade through `ArbOwner.scheduleArbOSUpgrade` you mu #### Step 4: Enable ArbOS specific configurations or feature flags (not always required) -For some ArbOS upgrades, such as [ArbOS 20 Atlas](/run-arbitrum-node/arbos-releases/arbos20.md), there may be additional requirements or steps that need to be satisfied to ensure your Orbit chain can use all of the new features and improvements made available in that particular ArbOS release. +For some ArbOS upgrades, such as [ArbOS 20 Atlas](/run-arbitrum-node/arbos-releases/arbos20.mdx), there may be additional requirements or steps that need to be satisfied to ensure your Orbit chain can use all of the new features and improvements made available in that particular ArbOS release. -If there are additional requirements for the targeted ArbOS release you're attempting to upgrade to; the additional requirements will be listed on the reference pages for [the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.md#list-of-available-arbos-releases). For example, the additional requirements for Orbit chains upgrading to ArbOS 20 can be found [here on the ArbOS 20 docs](/run-arbitrum-node/arbos-releases/arbos20.md). +If there are additional requirements for the targeted ArbOS release you're attempting to upgrade to; the additional requirements will be listed on the reference pages for [the targeted ArbOS release](/run-arbitrum-node/arbos-releases/01-overview.mdx#list-of-available-arbos-releases). For example, the additional requirements for Orbit chains upgrading to ArbOS 20 can be found [here on the ArbOS 20 docs](/run-arbitrum-node/arbos-releases/arbos20.mdx). Congratulations! You've upgraded your Orbit chain(s) to the specified ArbOS version. 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 43e5769c0..66fd35000 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 @@ -10,7 +10,7 @@ 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. +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 @@ -21,11 +21,11 @@ In a vanilla Orbit chain (a chain without customizations, transaction ordering p - `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. +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).\*\* +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](/how-arbitrum-works/inside-arbitrum-nitro.mdx#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. @@ -41,7 +41,7 @@ As the Orbit license allows chain owners to customize their Rollup, the AEP lice - 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). +You can read the relevant legal terminology in Section 2 of the [AEP Terms](https://docs.arbitrum.foundation/aep/ArbitrumExpansionProgramTerms.pdf). ## Calculating AEP fees @@ -81,7 +81,7 @@ If a team elects to deduct their assertion posting costs from eligible validator - 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. + - 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: @@ -94,15 +94,15 @@ To implement the deduction, the team should do the following: 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 +### 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. +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 an Arbitrum chain, then the L2 token can't 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 Foundation-controlled address. -### Novel Fee-Earning Customizations +### 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. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/customize-arbos.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/customize-arbos.mdx index 5c7c62386..1982278b8 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/customize-arbos.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/customize-arbos.mdx @@ -12,7 +12,7 @@ import CustomizeCautionBannerPartial from '../partials/_orbit-customize-caution- ## Cases where you may want to consider customizing your own ArbOS upgrade -1. When you want to make changes to your Nitro code that affect the State Transition Function, or STF (you may refer to the [Customize STF docs](./customize-stf.mdx#Preface)), and +1. When you want to make changes to your Nitro code that affect the State Transition Function, or STF (you may refer to the [Customize STF docs](./customize-stf.mdx#introduction)), and 2. If your desired changes need to be made to a live and operational Orbit chain @@ -26,7 +26,7 @@ Below, you will find 4 examples of ArbOS-related code changes and, generally, ho ### 1. Add a new method to exsiting precompile on a specific ArbOS version: -After you add `sayHi()` to `ArbSys.go` according to the guide in [customize precompile option 1](./customize-precompile.mdx#option-1-Add-new-methods-to-an-existing-precompile), +After you add `sayHi()` to `ArbSys.go` according to the guide in [customize precompile option 1](./customize-precompile.mdx#option-1-add-new-methods-to-an-existing-precompile), you need continue to modify [precompile.go][precompile_main_file_link]. For example, the original code is: diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/customize-deployment-configuration.md b/arbitrum-docs/launch-orbit-chain/how-tos/customize-deployment-configuration.md index b0c6fb7cf..e7c275b79 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/customize-deployment-configuration.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/customize-deployment-configuration.md @@ -17,7 +17,7 @@ Let's briefly review each of the deployment configuration parameters, the ration ### Chain ID -Don't worry about this; it's inconsequential for devnets. In production scenarios (which aren't yet supported), you'll want to use a unique integer identifier that represents your chain's network on chain indexes like [Chainlist.org](http://chainlist.org). +Don't worry about this; it's inconsequential for devnets. In production scenarios, you'll want to use a unique integer identifier that represents your chain's network on chain indexes like [Chainlist.org](http://chainlist.org). ### Chain name diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/customize-precompile.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/customize-precompile.mdx index 717953e6f..622972e88 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/customize-precompile.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/customize-precompile.mdx @@ -56,7 +56,7 @@ Next, follow the steps in [How to customize your Orbit chain's behavior](./custo :::info -Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.md) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. +Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.mdx) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. ::: @@ -131,7 +131,7 @@ Next, follow the steps in [How to customize your Orbit chain's behavior](./custo :::info -Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.md) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. +Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.mdx) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. ::: @@ -218,7 +218,7 @@ Our function now emits an event, which means that when calling it, the state wil function sayHi() external returns(string memory); ``` -Next, build Nitro by following the instructions in [How to build Nitro locally](/run-arbitrum-node/nitro/01-build-nitro-locally.md). Note that if you've already built the Docker image, you still need run the last step to rebuild. +Next, build Nitro by following the instructions in [How to build Nitro locally](/run-arbitrum-node/nitro/01-build-nitro-locally.mdx). Note that if you've already built the Docker image, you still need run the last step to rebuild. Run Nitro with the following command: @@ -228,7 +228,7 @@ docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum -p 0.0.0.0 :::info -Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.md) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. +Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.mdx) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. ::: @@ -302,7 +302,7 @@ func (con ArbInfo) GetBalanceCustom(c ctx, evm mech, account addr) (huge, error) To register this new precompile method, refer to Option 1 above. -Next, build Nitro by following the instructions in [How to build Nitro locally](/run-arbitrum-node/nitro/01-build-nitro-locally.md). Note that if you've already built the Docker image, you still need run the last step to rebuild. +Next, build Nitro by following the instructions in [How to build Nitro locally](/run-arbitrum-node/nitro/01-build-nitro-locally.mdx). Note that if you've already built the Docker image, you still need run the last step to rebuild. Run Nitro with the following command: @@ -312,7 +312,7 @@ docker run --rm -it -v /some/local/dir/arbitrum:/home/user/.arbitrum -p 0.0.0.0 :::info -Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.md) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. +Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.mdx) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. ::: diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx b/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx index 718391d30..ee642dc66 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx @@ -16,7 +16,7 @@ Before customizing your Orbit chain, it's important to understand what the State The STF defines how new blocks are produced from input messages (i.e. transactions). This guide is only necessary for changes that modify the State Transition Function. To customize other node behavior, such as RPC behavior or the sequencer's ordering policy, you can simply -[build your own node](/run-arbitrum-node/nitro/01-build-nitro-locally.md) without worrying about the rest of this guide. +[build your own node](/run-arbitrum-node/nitro/01-build-nitro-locally.mdx) without worrying about the rest of this guide. However, changes that modify the STF require updating the fraud proving system to recognize the new behavior as correct. Otherwise, the fraud prover would side with unmodified nodes, which would win fraud proofs against your modified node. @@ -136,7 +136,7 @@ docker run --rm -it -v /path/to/your/node/dir:/home/user/.arbitrum -p 0.0.0.0:84 :::info -Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.md) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. +Note that the instructions provided in [How to run a full node](/run-arbitrum-node/03-run-full-node.mdx) **will not** work with your Orbit node. See [Optional parameters (Orbit)](/node-running/how-tos/running-an-orbit-node.mdx#optional-parameters) for Orbit-specific CLI flags. ::: 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 89e0d3547..90cbb2c0b 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx +++ b/arbitrum-docs/launch-orbit-chain/how-tos/fast-withdrawals.mdx @@ -32,7 +32,7 @@ It is possible for an Orbit Rollup to adopt fast withdrawals. However, it would ### Minimum validator and DAC nodes -We recommend that any Fast Withdrawals-enabled chain have at least three DAC members and three validators acting in the fast withdrawals committee. Given that fast withdrawals will enable confirmation of new Rollup state much faster than the usual 7-day challenge period (15 minutes for L2s and 15 seconds for L3s), it becomes even more important to have additional parties involved in validation to further reduce trust assumptions. This requirement can be be met with three total operators, who each run a single DAS node and a single validator. +We recommend that any Fast Withdrawals-enabled chain have at least three DAC members and three validators acting in the fast withdrawals committee. Given that fast withdrawals will enable confirmation of new Rollup state much faster than the usual 6.4-day challenge period (15 minutes for L2s and 15 seconds for L3s), it becomes even more important to have additional parties involved in validation to further reduce trust assumptions. This requirement can be be met with three total operators, who each run a single DAS node and a single validator. ## Technical lower bound for fast withdrawals @@ -194,3 +194,9 @@ The following parameters need to be configured in those nodes. | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `--node.staker.enable-fast-confirmation=true` | Enables fast withdrawals in the validator node | | `--node.staker.make-assertion-interval=0h15m0s` | Since assertions need to be created for them to be confirmed, the minimum interval to create these assertions should be set to an amount close to the `minimumAssertionPeriod` defined in the Rollup contract. Modify `0h15m0s` to the configured value. | + +:::note + +Immediately after configuring fast withdrawals, your chain may not operate at full speed yet. This ramp-up is because the validators must work through the backlog of assertions that have yet to be confirmed. You will see a series of 'NodeCreated' and 'NodeConfirmed' events. Once the backlog is processed, your chain should operate fully at speed. + +::: diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md b/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md index ba9297906..04501b651 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/manage-fee-collectors.md @@ -25,8 +25,8 @@ There are four fee types that are collected on every transaction of an Orbit cha You can find more detailed information about these fee types in these pages: -- [L2 fees](/how-arbitrum-works/gas-fees.md) for the Orbit base fee and surplus fee -- [L1 fees](/how-arbitrum-works/l1-gas-pricing.md) for the Parent chain base fee and surplus fee +- [L2 fees](/how-arbitrum-works/gas-fees.mdx) for the Orbit base fee and surplus fee +- [L1 fees](/how-arbitrum-works/l1-gas-pricing.mdx) for the Parent chain base fee and surplus fee ## How to configure the fee collector addresses? diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md index 696540215..9a5b1d8cc 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-chain-finality.md @@ -9,11 +9,11 @@ content_type: how-to ## Child chain transactions -Generally, transactions executed through the sequencer on Orbit chains [achieve finality](/how-arbitrum-works/tx-lifecycle.md) equivalent to their parent chain once the relevant transaction data has been [posted in a batch](/how-arbitrum-works/sequencer.md). This means that transactions on Orbit chains are considered final in minutes. +Generally, transactions executed through the sequencer on Orbit chains [achieve finality](/how-arbitrum-works/tx-lifecycle.mdx) equivalent to their parent chain once the relevant transaction data has been [posted in a batch](/how-arbitrum-works/sequencer.mdx). This means that transactions on Orbit chains are considered final in minutes. ## Parent chain → child chain transactions -Messages being sent through the delayed inbox of a parent chain as [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.md#retryable-tickets), including deposits through token bridges, are released by the [sequencer](/how-arbitrum-works/inside-arbitrum-nitro.md#if-the-sequencer-is-well-behaved) once it has reasonable confidence of finality on the parent chain. For example, on an L2 chain settling to Ethereum, the sequencer will release delayed messages to the inbox after 40 blocks. Following this, the transaction must complete another finality period for the Ethereum transaction that promoted it to achieve finality. +Messages being sent through the delayed inbox of a parent chain as [retryable tickets](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets), including deposits through token bridges, are released by the [sequencer](/how-arbitrum-works/inside-arbitrum-nitro.mdx#if-the-sequencer-is-well-behaved) once it has reasonable confidence of finality on the parent chain. For example, on an L2 chain settling to Ethereum, the sequencer will release delayed messages to the inbox after 40 blocks. Following this, the transaction must complete another finality period for the Ethereum transaction that promoted it to achieve finality. Orbit L3s may configure the finality of transactions executed through the delayed inbox to depend on different layers of finality. By default, Orbit chains will rely on the number of L1 block confirmations, effectively finalizing an L3 deposit as soon as L1 finalizes the batch posted by Arbitrum One or when a DACert is posted by Arbitrum Nova. This would be on the order of tens of minutes. @@ -33,4 +33,4 @@ Note, however, that if you choose to enable fast bridging, a re-org of un-finali ## Child chain → parent chain transactions -Normally, [outgoing transactions](/how-arbitrum-works/arbos/l2-l1-messaging.md) must wait until the assertion that includes their L2 message is confirmed (~one week) before a client can execute the message on L1. However, in the near future [Anytrust](/how-arbitrum-works/inside-anytrust.md) chains will be able to leverage their DAC to enable fast confirmations of withdrawals through the native token bridge. By immediately confirming assertions that have been signed by the DAC, finality can be reduced to ~fifteen minutes. +Normally, [outgoing transactions](/how-arbitrum-works/arbos/l2-l1-messaging.mdx) must wait until the assertion that includes their L2 message is confirmed (~one week) before a client can execute the message on L1. However, in the near future [Anytrust](/how-arbitrum-works/inside-anytrust.mdx) chains will be able to leverage their DAC to enable fast confirmations of withdrawals through the native token bridge. By immediately confirming assertions that have been signed by the DAC, finality can be reduced to ~fifteen minutes. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-configuring-orbit-chain.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-configuring-orbit-chain.md index 1425a1de8..6e4fa3e36 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-configuring-orbit-chain.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-configuring-orbit-chain.md @@ -26,7 +26,7 @@ Orbit chains have three areas of configuration: ## 1. Parent chain configuration -Configuring the parent chain is the initial step to setting up your Orbit chain. Most of the parent chain configurations are specified during the setup phase. Detailed instructions can be found in the [Rollup Deployment Parameters](orbit-sdk-deploying-rollup-chain#rollup-deployment-parameter) section of the Rollup deployment guide. +Configuring the parent chain is the initial step to setting up your Orbit chain. Most of the parent chain configurations are specified during the setup phase. Detailed instructions can be found in the [Rollup Deployment Parameters](/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md#rollup-deployment-parameters) section of the Rollup deployment guide. After the initial setup, the chain owner can modify configurations as needed. For instance, the validator set can be updated by invoking the [`setValidKeyset`](https://github.com/OffchainLabs/nitro-contracts/blob/90037b996509312ef1addb3f9352457b8a99d6a6/src/bridge/SequencerInbox.sol#L751) function with a new set of validators. This adaptability facilitates your chain's optimization and management. @@ -53,7 +53,7 @@ You can use these setter functions to configure the child chain parameters: | `setInfraFeeAccount` | Sets the infrastructure fee account address, which receives all fees collected on the child chain. It is meant to receive the minimum base fee, with any amount above that going to the network fee account. | | `setNetworkFeeAccount` | Sets the network fee account address. As mentioned, this address collects all fees above the base fee. Note that if you set this amount to the 0 address on your chain, all fees will be deposited into the infrastructure fee account. | | `scheduleArbOSUpgrade` | If you plan to upgrade the ArbOS version of your chain, this method can help you schedule the upgrade. For a complete guide, please refer to the explanation for the [arbos upgrade](arbos-upgrade.md). | -| `setChainConfig` | We discussed the `chainConfig` in the [Rollup deployment guide](orbit-sdk-deploying-rollup-chain.md#chain-config-parameter) in detail. If you wish to change any field of the `chainConfig`, you need to use this method on the child chain. | +| `setChainConfig` | We discussed the `chainConfig` in the [Rollup deployment guide](./orbit-sdk-deploying-rollup-chain.md#4-chainconfig) in detail. If you wish to change any field of the `chainConfig`, you need to use this method on the child chain. | ### Getter functions diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-anytrust-chain.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-anytrust-chain.md index 558543234..64f56802c 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-anytrust-chain.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-anytrust-chain.md @@ -30,7 +30,7 @@ AnyTrust chains implement the Arbitrum AnyTrust protocol, an alternative to the ### Deployment steps -The deployment process of AnyTrust chains is very similar to that of [Rollup chains](orbit-sdk-deploying-rollup-chain.md#rollup-config-param), but with some differences that we'll discuss in this guide. +The deployment process of AnyTrust chains is very similar to that of [Rollup chains](/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md#rollup-configuration-parameters), but with some differences that we'll discuss in this guide. Here are the steps involved in the deployment process: @@ -116,7 +116,7 @@ In this example, `txReceipt` refers to the transaction receipt you received afte ### 4. Setting valid keyset on parent chain -The final step is to set up a valid keyset for your Data Availability Committee (DAC) on the parent chain. See [How to configure a DAC](/run-arbitrum-node/data-availability-committees/04-configure-dac.md) for instructions. +The final step is to set up a valid keyset for your Data Availability Committee (DAC) on the parent chain. See [How to configure a DAC](/run-arbitrum-node/data-availability-committees/04-configure-dac.mdx) for instructions. Once created, your keyset needs to be established on your Orbit chain's `SequencerInbox` contract on the parent chain. To facilitate this, we provide an API in Orbit SDK named `setValidKeysetPrepareTransactionRequest`. This API requires specific information you can gather at [step three](#3-getting-the-anytrust-orbit-chain-information-after-deployment). This includes the `upgradeExecutor` and `sequencerInbox` addresses of your Orbit chain, the generated keyset for your committee, and the owner's account. diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md index acdcf4aa2..eefa942a0 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-rollup-chain.md @@ -194,7 +194,7 @@ The Orbit SDK provides two APIs, `createRollupPrepareDeploymentParamsConfig` and This API is designed to take parameters defined in the Config struct and fill in the rest with default values. It outputs a complete Config struct that is ready for use. -For example, to create a Config struct with a specific chain ID (`chainId`), an owner address (`deployer_address`), and a `chainConfig` as described in the [previous section](#chain-config-parameter), you would use the Orbit SDK as follows: +For example, to create a Config struct with a specific chain ID (`chainId`), an owner address (`deployer_address`), and a `chainConfig` as described in the [previous section](#rollup-configuration-parameters), you would use the Orbit SDK as follows: ```js import { createPublicClient, http } from 'viem'; diff --git a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md index 619f57ea2..4ff984ea8 100644 --- a/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md +++ b/arbitrum-docs/launch-orbit-chain/how-tos/orbit-sdk-deploying-token-bridge.md @@ -22,7 +22,7 @@ This document is under construction and may change significantly as we incorpora :::info -See the [`ERC-20` token bridge overview](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.md) for more information about the token bridge's design and operational dynamics, and the ["create-token-bridge-eth" example ](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/create-token-bridge-eth) for additional guidance. +See the [`ERC-20` token bridge overview](/build-decentralized-apps/token-bridging/03-token-bridge-erc20.mdx) for more information about the token bridge's design and operational dynamics, and the ["create-token-bridge-eth" example ](https://github.com/OffchainLabs/arbitrum-orbit-sdk/tree/main/examples/create-token-bridge-eth) for additional guidance. ::: @@ -44,8 +44,8 @@ Once an Orbit chain has been deployed and initialized, the bridge contracts need The token bridge deployment process is the same for all Orbit chains types except for the following: -- **Custom fee token Orbit chains** which require [token approval](#step-1). -- **`ETH`-based Orbit chains**, for which you need to [set up a WETH gateway](#step-5). +- **Custom fee token Orbit chains** which require [token approval](#1-token-approval). +- **`ETH`-based Orbit chains**, for which you need to [set up a WETH gateway](#5-setting-up-the-weth-gateway). ::: @@ -93,7 +93,7 @@ Please note that after generating the raw transaction, the deployer must still s Deploying token bridge contracts is the first step in creating a bridge between the parent and the Orbit chain. -The deployment process is the same as Orbit chain contracts', where a primary contract facilitates the deployment of core contracts. The token bridge contracts are deployed on the parent and child chains by `TokenBridgeCreator`. `TokenBridgeCreator` does it in a single transaction using the [ Retryable Tickets protocol ](/how-arbitrum-works/arbos/l1-l2-messaging.md#retryable-ticketsO). +The deployment process is the same as Orbit chain contracts', where a primary contract facilitates the deployment of core contracts. The token bridge contracts are deployed on the parent and child chains by `TokenBridgeCreator`. `TokenBridgeCreator` does it in a single transaction using the [ Retryable Tickets protocol ](/how-arbitrum-works/arbos/l1-l2-messaging.mdx#retryable-tickets). Orbit SDK provides an API that automates the deployment by interacting with the `TokenBridgeCreator` contract. The API is `createTokenBridgePrepareTransactionRequest`, which processes the necessary inputs and generates a transaction request tailored for token bridge deployment. 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 8b5ac2d7e..937294cb3 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 @@ -10,49 +10,48 @@ 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) +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 + ## The AEP fee router contract system -_Link to the [Router contracts' source code](https://github.com/OffchainLabs/fund-distribution-contracts/tree/main/src/FeeRouter)._ +This section describes the different fee distribution and router contracts that are available. You can find their source code [here](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. +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 target address 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. +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 an address controlled by the Arbitrum Foundation on Ethereum. ## 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. +An Orbit chain is responsible for deploying all `ChildToParentRouters` necessary for their AEP funds to arrive at the address controlled by the Arbitrum Foundation 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) + - An address controlled by the Arbitrum Foundation 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. +In the event that a `ChildToParentRouter` does not connect to the address controlled by the Arbitrum Foundation on Ethereum, an Orbit chain must deploy successive `ChildToParentRouter` contracts until a connection to such address 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: +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:
Arbitrum-native USDCUSDC Bridged USDC
Token NameUSD CoinUSDC Bridged USDC