Add arbos customize docs page

arbitrum-docs/launch-orbit-chain/how-tos/customize-arbos.mdx

@@ -0,0 +1,148 @@
+---
+title: "How to customize ArbOS on your Orbit chain"
+description: "Learn how to customize your ArbOS version"
+author: jasonwan
+sidebar_position: 7
+content_type: how-to
+---
+
+import PublicPreviewBannerPartial from '../partials/_orbit-public-preview-banner-partial.md';
+import CustomizeCautionBannerPartial from '../partials/_orbit-customize-caution-banner-partial.md'
+
+<PublicPreviewBannerPartial />
+
+<CustomizeCautionBannerPartial />
+
+## 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
+
+2. If your desired changes need to be made to a live and operational Orbit chain
+
+If your changes meet both those 2 points, then you need to customize the ArbOS upgrade.
+
+Also, if you made changes to a live and operational chain and want to upgrade them later in the future, then you will likely need an ArbOS upgrade to facilitate the upgrade.
+
+## Where should I insert ArbOS Upgrade related code?
+Below, you will find 4 examples of ArbOS-related code changes and, generally, how to make them:
+### 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),
+you need continue to modify [precompile.go][precompile_main_file_link]. 
+
+For example, the original code is:
+```go
+ArbSys := insert(MakePrecompile(pgen.ArbSysMetaData, &ArbSys{Address: types.ArbSysAddress}))
+arbos.ArbSysAddress = ArbSys.address
+arbos.L2ToL1TransactionEventID = ArbSys.events["L2ToL1Transaction"].template.ID
+arbos.L2ToL1TxEventID = ArbSys.events["L2ToL1Tx"].template.ID
+```
+You need to append the following code to it:
+```go
+ArbSys := insert(MakePrecompile(pgen.ArbSysMetaData, &ArbSys{Address: types.ArbSysAddress}))
+arbos.ArbSysAddress = ArbSys.address
+arbos.L2ToL1TransactionEventID = ArbSys.events["L2ToL1Transaction"].template.ID
+arbos.L2ToL1TxEventID = ArbSys.events["L2ToL1Tx"].template.ID
+// The arbos version control logic
+ArbOwner.methodsByName["SayHi"].arbosVersion = ${The arbos version you want to activate this method}
+```
+In this way, this method will be executed normally and return results only after you update ArbOS to the target version.
+
+### 2. Create a new precompile contract on a specific ArbOS version
+After you add a new precompile named `ArbHi` according to the guide in [customize precompile option 2](./customize-precompile.mdx#option-2-create-a-new-precompile) and make changes to [precompile.go][precompile_main_file_link], 
+you also need to make the following changes:
+```go
+ArbHi := insert(MakePrecompile(pgen.ArbHiMetaData, &ArbHi{Address: types.ArbHiAddress})) // types.ArbHiAddress here is an example address
+// Set activate version to the precompile
+ArbHi.arbosVersion = ${The arbos version you want to activate this precompile}
+// Set activate version to all method
+for _, method := range ArbHi.methods {
+   method.arbosVersion = ${The arbos version you want to activate this precompile}
+}
+```
+In this way, ArbHi and all its methods will be activated after the ArbOS version you set.
+
+### 3. Create a new ArbOS state on a specific ArbOS version
+
+After you add a new state `myNumber` according to the guide in [customize precompile Option 5](./customize-precompile.mdx#option-5-call-and-modify-state), you also need to rewrite [UpgradeArbosVersion][arbosstate_updatearbosversion_method_link] in [arbosstate.go][arbosstate_file_link]:
+Add your expected ArbOS version to the switch case statement of nextArbosVersion. Here we will take ArbOS V21 as an example:
+```go
+ensure := func(err error) {
+    if err != nil {
+        message := fmt.Sprintf(
+            "Failed to upgrade ArbOS version %v to version %v: %v",
+            state.arbosVersion, state.arbosVersion+1, err,
+        )
+        panic(message)
+    }
+}
+nextArbosVersion := state.arbosVersion + 1
+switch nextArbosVersion {
+    case 1:
+        //.....
+    case 2:
+        //....
+    //.....
+    case 21:
+        // Set your new ArbOS state value here
+        ensure(state.SetNewMyNumber(${random number}))
+    //....
+} 
+```
+
+Here, we will ensure that the initial value of $(a random number) after ArbOS is upgraded to V21.
+
+
+:::caution
+It should be noted that when you initialize the state (initial code is in [customize precompile Option 5](./customize-precompile.mdx#option-5-call-and-modify-state)), you need to initialize it to 0 or null value first to avoid a potential re-org on your chain.
+:::
+
+Also, please make sure your program cannot call the `state.SetNewMyNumber` or other functions may change the value of `myNumber` before ArbOS V21. 
+To prevent this, if you are using an external call to the precompile contract to change the value, you can refer to [point 1](./customize-arbos.mdx#1-add-a-new-method-to-exsiting-precompile-on-a-specific-arbos-version) or
+[point 2](./customize-arbos.mdx#2-create-a-new-precompile-contract-on-a-specific-arbos-version) to set the activation time of the precompile contract method.
+If your nitro code needs to call this method to change the state, you can continue reading [point 4](./customize-arbos.mdx#4-any-changes-in-the-stf-logic-that-will-affect-the-final-execution-result).
+
+### 4. Any changes in the STF logic that will affect the final execution result
+If you change the logic in STF, it will cause the execution result of the transaction to be different, 
+you need to keep the original execution logic and put the new logic into another branch.
+You can use an `if else` statement to control it.
+
+For example, we change the `SayHi` return after upgrading the ArbOS version:
+```go
+// The method in ArbHi precompile
+func (con *ArbHi) SayHi(c ctx, evm mech) (string, error) {
+    if p.state.ArbOSVersion() >= ${The arbos you want to upgrade to} {
+        // Your new logic code
+        return "hi, new ArbOS version", nil
+    } else {
+        // The old logic code needs to be kept
+        return "hi", nil
+    }
+}
+```
+
+In the above code, we use precompiles as an example. Some logic might also affect the STF, such as the methods in [block_process.go][block_processor_file_link], [internal_tx.go][internal_tx_file_link], [tx_processor.go][tx_processor_file_link] and so on.
+You also need to use those ArbOS control methods for different logic versions.
+
+:::tip Backward compatibility
+
+Wasm module roots are backward compatible, so upgrading them before an ArbOS version upgrade will not disrupt your chain's functionality.
+
+:::
+
+## Upgrade WASM Module Root on the parent chain
+Afterward, since Arbitrum might need to execute the validation and fraud proofs on the parent chain, you need to update the Wasm Module Root recorded on the parent chain.
+Please continue reading [customize stf](./customize-stf.mdx#step-3-run-the-node-without-fraud-proofs) for follow-up operations.
+
+
+## Schedule ArbOS upgrade
+After you add ArbOS version control to the nitro code, you can update ArbOS. You can refer to the document [ArbOS upgrade](/launch-orbit-chain/how-tos/arbos-upgrade) to upgrade.
+It should be noted that if you set a higher ArbOS version as the upgrade target, all the features added between the current and target versions will be activated.
+For example, if your current version is ArbOS v18 and you set the target version to v25, all the features between v18 and v25 will be loaded.
+
+[precompile_main_file_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/@nitroPathToPrecompiles@/precompile.go
+[arbosstate_file_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/v3.1.0/@nitroPathToArbosState@/arbosstate.go
+[arbosstate_updatearbosversion_method_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/v3.1.0/arbos/@nitroPathToArbosState@/arbosstate.go#L253
+[block_processor_file_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/@nitroPathToArbos@/block_processor.go
+[internal_tx_file_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/@nitroPathToArbos@/internal_tx.go
+[tx_processor_file_link]: https://github.com/OffchainLabs/@nitroRepositorySlug@/blob/@nitroVersionTag@/@nitroPathToArbos@/tx_processor.go

arbitrum-docs/launch-orbit-chain/how-tos/customize-precompile.mdx

@@ -7,12 +7,15 @@ content_type: how-to
 ---
 
 import PublicPreviewBannerPartial from '../partials/_orbit-public-preview-banner-partial.md';
+import CustomizeCautionBannerPartial from '../partials/_orbit-customize-caution-banner-partial.md'
 
 <PublicPreviewBannerPartial />
 
+<CustomizeCautionBannerPartial />
+
 :::caution
 
-The guidance in this document will work only if you use `eth_call` to call the new precompiles. If you're calling from other contracts or adding non-view/pure methods, this approach will break block validation.
+The guidance in this document will only work if you use `eth_call` to call the new precompiles. If you call them from other contracts or add non-view/pure methods, this approach will break the block validation.
 
 To support these additional use-cases, follow the instructions described in [How to customize your Orbit chain's behavior](/launch-orbit-chain/how-tos/customize-stf.mdx).
 
@@ -111,7 +114,7 @@ func (con *ArbHi) SayHi(c ctx, evm mech) (string, error) {
 Then, update [precompile.go][precompile_main_file_link] to register the new precompile under the `Precompiles()` method:
 
 ```go
-insert(MakePrecompile(templates.ArbHiMetaData, &ArbHi{Address: hex("11a")})) // 0x011a here is an example address
+insert(MakePrecompile(pgen.ArbHiMetaData, &ArbHi{Address: hex("11a")})) // 0x011a here is an example address
 ```
 
 Navigate to the [precompiles interface][precompile_interface_dir_link] directory, `/@nitroContractsPathToPrecompilesInterface@`, create `ArbHi.sol`, and add the required interface. Ensure that the method name on the interface matches the name of the function you introduced in the previous step, `camelCased`:
@@ -185,9 +188,9 @@ type ArbSys struct {
 	L2ToL1TransactionGasCost func(addr, addr, huge, huge, huge, huge, huge, huge, huge, []byte) (uint64, error)
 
 	// Add your customize event here:
-	Hi						func(ctx, mech, addr) error
+	Hi						       func(ctx, mech, addr) error
 	// This is needed and will tell you how much gas it will cost, the param is the same as your event but without the first two (ctx, mech), the return param is always (uint64, error)
-	HiGasCost				func(addr) (uint64, error)
+	HiGasCost				    func(addr) (uint64, error)
 }
 ```
 
@@ -529,6 +532,9 @@ You should see something like this:
 2
 ```
 
+## Incorporate your changes to precompile into the ArbOS upgrade
+If you do not customize the precompile before launching your Orbit network, please continue to follow [customize arbos] to perform an ArbOS version control to avoid blockchain reorg.
+
 <!-- For clarity in the code, we add here all links to github, using "link references" (First the interfaces, and below the implementations) -->
 <!--
 Note that nitro-contracts repository is hardcoded because atm we use the "nitro" repository for referencing precompiles for the current released nitro version  (for Arb chains),

arbitrum-docs/launch-orbit-chain/how-tos/customize-stf.mdx

@@ -7,10 +7,13 @@ content_type: how-to
 ---
 
 import PublicPreviewBannerPartial from '../partials/_orbit-public-preview-banner-partial.md';
+import CustomizeCautionBannerPartial from '../partials/_orbit-customize-caution-banner-partial.md'
 
 <PublicPreviewBannerPartial />
 
-## Preface
+<CustomizeCautionBannerPartial />
+
+## Introduction
 
 Before customizing your Orbit chain, it's important to understand what the State Transition Function (aka the STF) is.
 The STF defines how new blocks are produced from input messages (i.e. transactions).
@@ -82,6 +85,9 @@ git submodule update --init --recursive --force
 
 Next, make your changes to the State Transition Function. For example, you could [add a custom precompile](./customize-precompile.mdx).
 
+After this step, you should visit [Customize ArbOS version](./customize-arbos.mdx) to see if your changes need to upgrade the ArbOS version. If so, please continue 
+follow that document to add an ArbOS upgrade logic to your code.
+
 ### Step 3. Run the node without fraud proofs
 
 To build the Arbitrum Nitro node image, you'll first need to install Docker.
@@ -268,4 +274,4 @@ Make some transactions on your new blockchain, test out your modifications to th
 wait for a batch to be posted, and you should be seeing "validation succeeded" log lines!
 
 If you see "Error during validation", then the replay binary is likely not up-to-date with your modifications to the State Transition Function.
-Ensure that the replay binary is freshly built and is not missing any modifications, and that the WASM module root set in the rollup contract matches your replay binary.
+Ensure that the replay binary is freshly built, not missing any modifications, and that the WASM module root set in the rollup contract matches your replay binary.

arbitrum-docs/launch-orbit-chain/partials/_orbit-customize-caution-banner-partial.md

@@ -0,0 +1,8 @@
+:::caution 
+### Customizations require expertise
+Customizing your chain is a core benefit of building with Arbitrum Orbit. We strongly recommend that teams interested in customizations work alongside a partner with ArbOS and Nitro software expertise, such as a Rollup-as-a-Service team. 
+
+Working alongside an experienced Orbit operator can help your team navigate the complex tradeoff space of rollup customizations, which can include performance, security, and cost considerations. Offchain Labs is positioned to train and enable Rollup-as-a-Service in their work with clients to scale support to the Orbit ecosystem as a whole. As such, Offchain Labs does not necessarily have the capacity to review code changes made by individual Orbit chains. 
+
+We encourage you to leverage your in-house expertise, collaborate with expert partners, and allocate appropriate resources for both an initial implementation (including an audit) and ongoing maintenance and security management of your customization. 
+:::

website/sidebars.js

@@ -297,6 +297,11 @@ const sidebars = {
               id: 'launch-orbit-chain/how-tos/manage-fee-collectors',
               label: `Manage the fee collectors`,
             },
+            {
+              type: 'doc',
+              id: 'launch-orbit-chain/how-tos/customize-arbos',
+              label: `Customize ArbOS version`,
+            },
             {
               type: 'doc',
               id: 'launch-orbit-chain/how-tos/usdc-standard-bridge',

website/src/resources/globalVars.js

@@ -40,6 +40,7 @@ const globalVars = {
 
   goEthereumCommit: 'e35bf9cdd3d02034ac1be34a479d101f12012ba6',
 
+  nitroPathToArbos: 'arbos',
   nitroPathToArbosState: 'arbos/arbosState',
   nitroPathToStorage: 'arbos/storage',