Merge branch 'master' into md-to-mdx-misc

.gitignore

@@ -1,3 +1,3 @@
 .vscode
 arbitrum-docs/sdk
-arbitrum-docs/stylus-by-example
+arbitrum-docs/stylus-by-example

arbitrum-docs/build-decentralized-apps/04-cross-chain-messaging.mdx

@@ -9,15 +9,15 @@ The Arbitrum protocol and related tooling makes it easy for developers to build
 
 ## Ethereum-to-Arbitrum messaging
 
-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.md#arbretryabletx) precompile.
+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 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).
 
 ## Arbitrum-to-Ethereum messaging
 
-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.md#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.
+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).
 

arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/01-comparison-overview.mdx

@@ -36,7 +36,7 @@ Similarly, Arbitrum chains can also send messages to the parent chain. Find more
 
 ## Precompiles
 
-Besides supporting all precompiles available in Ethereum, Arbitrum provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. You can find a full reference of them in [Precompiles](/build-decentralized-apps/precompiles/01-overview.md).
+Besides supporting all precompiles available in Ethereum, Arbitrum provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. You can find a full reference of them in [Precompiles](/build-decentralized-apps/precompiles/01-overview.mdx).
 
 ## NodeInterface
 

arbitrum-docs/build-decentralized-apps/arbitrum-vs-ethereum/02-block-numbers-and-time.mdx

@@ -62,7 +62,7 @@ const txnReceipt = await arbitrumProvider.getTransactionReceipt('0x...');
 */
 ```
 
-The Arbitrum block number can also be retrieved within an Arbitrum contract via [ArbSys](/build-decentralized-apps/precompiles/02-reference.md#arbsys) precompile:
+The Arbitrum block number can also be retrieved within an Arbitrum contract via [ArbSys](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) precompile:
 
 ```sol
  ArbSys(100).arbBlockNumber() // returns Arbitrum block number

arbitrum-docs/build-decentralized-apps/precompiles/01-overview.md → arbitrum-docs/build-decentralized-apps/precompiles/01-overview.mdx

@@ -7,4 +7,4 @@ content_type: concept
 
 Precompiles are predefined smart contracts that have special addresses and provide specific functionality which is executed not at the EVM bytecode level, but natively by the Arbitrum client itself. Precompiles are primarily used to introduce specific functions that would be computationally expensive if executed in EVM bytecode, and functions that facilitate the interaction between the Layer 1 (L1) and the Layer 2 (L2). By having them natively in the Arbitrum client, they can be optimized for performance.
 
-Besides supporting all precompiles available in Ethereum, Arbitrum provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. For more details on the addresses these precompiles live, and the specific methods available, please refer to the [methods documentation](/build-decentralized-apps/precompiles/02-reference.md).
+Besides supporting all precompiles available in Ethereum, Arbitrum provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. For more details on the addresses these precompiles live, and the specific methods available, please refer to the [methods documentation](/build-decentralized-apps/precompiles/02-reference.mdx).

arbitrum-docs/build-decentralized-apps/precompiles/02-reference.md → arbitrum-docs/build-decentralized-apps/precompiles/02-reference.mdx

@@ -5,7 +5,7 @@ user_story: As a developer, I want to understand the most useful precompiles ava
 content_type: reference
 ---
 
-ArbOS provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. This reference page exhaustively documents the specific calls ArbOS makes available through precompiles. For a more conceptual description of what precompiles are and how they work, please refer to the [precompiles conceptual page](/build-decentralized-apps/precompiles/01-overview.md).
+ArbOS provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. This reference page exhaustively documents the specific calls ArbOS makes available through precompiles. For a more conceptual description of what precompiles are and how they work, please refer to the [precompiles conceptual page](/build-decentralized-apps/precompiles/01-overview.mdx).
 
 This reference page is divided into two sections. The first one lists all precompiles in a summary table with links to the reference of the specific precompile, along with the address where they live, their purpose and links to the go implementation and solidity interface. The second one details the methods available in each precompile with links to the specific implementation.
 

arbitrum-docs/build-decentralized-apps/token-bridging/02-token-bridge-ether.md

@@ -28,7 +28,7 @@ As far as the L1 knows, all deposited funds are held by Arbitrum's Bridge contra
 
 ## Withdrawing ether
 
-Withdrawing ether can be done using the [ArbSys precompile](/build-decentralized-apps/precompiles/02-reference.md#arbsys)'s `withdrawEth` method:
+Withdrawing ether can be done using the [ArbSys precompile](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys)'s `withdrawEth` method:
 
 ```sol
 ArbSys(100).withdrawEth{ value: 2300000 }(destAddress)

arbitrum-docs/build-decentralized-apps/token-bridging/bridge-tokens-programmatically/04-how-to-bridge-tokens-custom-gateway.mdx

@@ -38,7 +38,7 @@ On the other hand, the **L2 counterpart of the gateway**, must conform to the [I
 - A method `outboundTransfer`, to handle external calls, and forwarded calls from `L2GatewayRouter.outboundTransfer`.
 - A method `finalizeInboundTransfer`, to handle messages coming ONLY from L1’s gateway.
 - Two methods `calculateL2TokenAddress` and `getOutboundCalldata` to handle other bridging operations.
-- Methods to send cross-chain messages through the [ArbSys precompile](/build-decentralized-apps/precompiles/02-reference.md#arbsys). An example implementation can be found in `sendTxToL1` on [L2ArbitrumMessenger](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/L2ArbitrumMessenger.sol).
+- Methods to send cross-chain messages through the [ArbSys precompile](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys). An example implementation can be found in `sendTxToL1` on [L2ArbitrumMessenger](https://github.com/OffchainLabs/token-bridge-contracts/blob/main/contracts/tokenbridge/arbitrum/L2ArbitrumMessenger.sol).
 
 ### What about my custom tokens?
 

arbitrum-docs/how-arbitrum-works/arbos/geth.md

@@ -70,7 +70,7 @@ If the user attempts to purchase compute gas in excess of ArbOS's per-block gas
 
 ### [`PushCaller`][pushcaller_link]{#PushCaller}
 
-These hooks track the callers within the EVM callstack, pushing and popping as calls are made and complete. This provides [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.md#arbsys) with info about the callstack, which it uses to implement the methods `WasMyCallersAddressAliased` and `MyCallersAddressWithoutAliasing`.
+These hooks track the callers within the EVM callstack, pushing and popping as calls are made and complete. This provides [`ArbSys`](/build-decentralized-apps/precompiles/02-reference.mdx#arbsys) with info about the callstack, which it uses to implement the methods `WasMyCallersAddressAliased` and `MyCallersAddressWithoutAliasing`.
 
 ### [`L1BlockHash`][l1blockhash_link]
 
@@ -180,7 +180,7 @@ Represents a retryable submission and may schedule an [`ArbitrumRetryTx`](#Arbit
 
 ### [`ArbitrumRetryTx`][arbitrumretrytx_link]{#ArbitrumRetryTx}
 
-These are scheduled by calls to the `redeem` method of the [ArbRetryableTx](/build-decentralized-apps/precompiles/02-reference.md#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/introduction.md#Retryables) for more info.
 
 ### [`ArbitrumInternalTx`][arbitruminternaltx_link]{#ArbitrumInternalTx}
 
@@ -265,7 +265,7 @@ Retryables are mostly implemented in [ArbOS](/how-arbitrum-works/arbos/introduct
 
 Added [`UnderlyingTransaction`][underlyingtransaction_link] to Message interface
 Added [`GetCurrentTxLogs`](https://github.com/OffchainLabs/go-ethereum/tree/7503143fd13f73e46a966ea2c42a058af96f7fcf/core/state/statedb_arbitrum.go) to StateDB
-We created the AdvancedPrecompile interface, which executes and charges gas with the same function call. This is used by [Arbitrum's precompiles](/build-decentralized-apps/precompiles/01-overview.md), and also wraps Geth's standard precompiles.
+We created the AdvancedPrecompile interface, which executes and charges gas with the same function call. This is used by [Arbitrum's precompiles](/build-decentralized-apps/precompiles/01-overview.mdx), and also wraps Geth's standard precompiles.
 
 ### WASM build support
 

arbitrum-docs/how-arbitrum-works/arbos/introduction.md

@@ -4,7 +4,7 @@ ArbOS is the Layer 2 EVM hypervisor that facilitates the execution environment o
 
 ## Precompiles
 
-ArbOS provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. Visit the [precompiles conceptual page](/build-decentralized-apps/precompiles/01-overview.md) for more information about how these work, and the [precompiles reference page](/build-decentralized-apps/precompiles/02-reference.md) for a full reference of the precompiles available in Arbitrum chains.
+ArbOS provides L2-specific precompiles with methods smart contracts can call the same way they can solidity functions. Visit the [precompiles conceptual page](/build-decentralized-apps/precompiles/01-overview.mdx) for more information about how these work, and the [precompiles reference page](/build-decentralized-apps/precompiles/02-reference.mdx) for a full reference of the precompiles available in Arbitrum chains.
 
 A precompile consists of a solidity interface in [`contracts/src/precompiles/`][nitro_precompiles_dir] and a corresponding Golang implementation in [`precompiles/`][precompiles_dir]. Using Geth's ABI generator, [`solgen/gen.go`][gen_file] generates [`solgen/go/precompilesgen/precompilesgen.go`][precompilesgen_link], which collects the ABI data of the precompiles. The [runtime installer][installer_link] uses this generated file to check the type safety of each precompile's implementer.
 
@@ -42,7 +42,7 @@ ArbOS's state is viewed and modified via [`ArbosState`][arbosstate_link] objects
 
 Because two [`ArbosState`][arbosstate_link] objects with the same [`backingStorage`][backingstorage_link] contain and mutate the same underlying state, different [`ArbosState`][arbosstate_link] objects can provide different views of ArbOS's contents. [`Burner`][burner_link] objects, which track gas usage while working with the [`ArbosState`][arbosstate_link], provide the internal mechanism for doing so. Some are read-only, causing transactions to revert with `vm.ErrWriteProtection` upon a mutating request. Others demand the caller have elevated privileges. While yet others dynamically charge users when doing stateful work. For safety the kind of view is chosen when [`OpenArbosState()`][openarbosstate_link] creates the object and may never change.
 
-Much of ArbOS's state exists to facilitate its [precompiles](/build-decentralized-apps/precompiles/02-reference.md). The parts that aren't are detailed below.
+Much of ArbOS's state exists to facilitate its [precompiles](/build-decentralized-apps/precompiles/02-reference.mdx). The parts that aren't are detailed below.
 
 [arbosstate_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/arbosState/arbosstate.go#L36
 [backingstorage_link]: https://github.com/OffchainLabs/nitro/blob/fa36a0f138b8a7e684194f9840315d80c390f324/arbos/storage/storage.go#L51
@@ -71,7 +71,7 @@ This component maintains the last 256 L1 block hashes in a circular buffer. This
 
 ### [`l1PricingState`][l1pricingstate_link]
 
-In addition to supporting the [`ArbAggregator precompile`](/build-decentralized-apps/precompiles/02-reference.md#arbaggregator), the L1 pricing state provides tools for determining the L1 component of a transaction's gas costs. This part of the state tracks both the total amount of funds collected from transactions in L1 gas fees, as well as the funds spent by batch posters to post data batches on L1.
+In addition to supporting the [`ArbAggregator precompile`](/build-decentralized-apps/precompiles/02-reference.mdx#arbaggregator), the L1 pricing state provides tools for determining the L1 component of a transaction's gas costs. This part of the state tracks both the total amount of funds collected from transactions in L1 gas fees, as well as the funds spent by batch posters to post data batches on L1.
 
 Based on this information, ArbOS maintains an L1 data fee, also tracked as part of this state, which determines how much transactions will be charged for L1 fees. ArbOS dynamically adjusts this value so that fees collected are approximately equal to batch posting costs, over time.
 
@@ -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.md#arbgasinfo) and [`ArbOwner`](/build-decentralized-apps/precompiles/02-reference.md#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](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].
 
 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.