From f42e0a17fc10b1c7d80ef88a1ffc3b7f8455e9aa Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Fri, 6 Jun 2025 14:56:31 +0800 Subject: [PATCH 1/6] add key rotation docs --- .../04-guidance/06-key-rotation.mdx | 130 ++++++++++++++++++ 1 file changed, 130 insertions(+) create mode 100644 arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx diff --git a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx new file mode 100644 index 0000000000..069c084ae8 --- /dev/null +++ b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx @@ -0,0 +1,130 @@ +# Arbitrum Node Key Rotation Guide + +This guide covers how to rotate keys for different roles in your Arbitrum Orbit chain: batch poster, validator/staker, and Data Availability Servers (DAS). + +## ⚠️ Important Prerequisites + +- **Backup**: Always backup your current configuration and private keys before starting +- **Testing**: Test key rotation on a testnet environment first if possible +- **Downtime**: Plan for potential brief service interruptions during the rotation process +- **Permissions**: Ensure you have the necessary permissions to call the required smart contract functions + +## 1. Batch Poster Key Rotation + +> **Critical Warning**: For sequencer nodes running both sequencer and batch poster on the same server, you **must** split them first and configure Redis for message synchronization. Failure to do so may cause chain reorganizations. Refer to the [High Availability Sequencer documentation](/run-arbitrum-node/sequencer/05-high-availability-sequencer-docs.mdx) for setup instructions. + +### Prerequisites + +- New batch poster account funded with sufficient ETH for gas fees +- Access to call functions on the `SequencerInbox` contract +- Current batch poster should be stopped gracefully + +### Steps + +1. **Enable new batch poster** + + ``` + Call setIsBatchPoster(address=, enabled=true) on SequencerInbox contract + Call setBatchPosterManager(address=) on SequencerInbox contract if you want to change batch poster manager + ``` + +2. **Update node configuration** + + - Update your node configuration to use the new private key + - Restart the batch poster service with the new configuration + +3. **Handle potential mempool issues** + If you encounter the error: `"posting this transaction will exceed max mempool size: transaction nonce: xxx, unconfirmed nonce: xx, max mempool size: xx"` + + **Temporary fix**: + + - Add `--node.batch-poster.data-poster.dangerous.clear-dbstorage` flag + - Restart the batch poster + - Remove this flag for next start + +4. **Verify operation** + + - Monitor logs to confirm the new batch poster is successfully submitting batches + - Check that transactions are being processed normally + +5. **Disable old batch poster** + ``` + Call setIsBatchPoster(address=, enabled=false) on SequencerInbox contract + ``` + +## 2. Validator/Staker Key Rotation + +### Prerequisites + +- New validator account funded with sufficient ETH +- Required stake amount available for the new validator +- Access to call functions on the `Rollup` contract + +### Steps + +1. **Enable new validator** + + ``` + Call setValidator(addr=, val=true) on Rollup contract + ``` + +2. **Update node configuration** + + - Update your validator node configuration to use the new private key + - Restart the validator service + +3. **Handle potential mempool issues** + If you encounter the error: `"posting this transaction will exceed max mempool size: transaction nonce: xxx, unconfirmed nonce: xx, max mempool size: xx"` + + - Add `--node.staker.data-poster.dangerous.clear-dbstorage` flag temporarily + - Restart the validator + - Remove this flag for next start + +4. **Verify new validator operation** + + - Monitor that the new validator successfully posts stake transactions + - Confirm assertion and confirmation transactions are being submitted + +5. **Disable old validator** + + ``` + Call setValidator(addr=, val=false) on Rollup contract + ``` + +6. **Recover old validator stake** (if applicable) + - Wait your old validator's latest stake assertion to be confirmed + - call reduceDeposit() on Rollup Contract + - Call withdrawStakerFunds() to get your stake back + +## 3. AnyTrust Data Availability Committee (DAC) Rotation + +### Prerequisites + +- New DAC keyset generated +- Access to call functions on the `SequencerInbox` contract + +### Steps + +1. **Generate new keyset** + + - Follow the [Generate Keyset documentation](/run-arbitrum-node/data-availability-committees/configure-dac#step-1-generate-the-keyset-and-keyset-hash-with-all-the-information-from-the-servers) with your new group of DAS servers + - Ensure all new DAS are properly configured and accessible + +2. **Update keyset on-chain** + + ``` + Call setValidKeyset(keyset=, assumedHonest=1) on SequencerInbox contract + ``` + + Note: `assumedHonest=1` assumes at least one committee member is honest + +3. **Deploy new DAS servers** + + - Start the new DAS with the updated configuration + - Verify they are accessible and responding to health checks + +4. **Verify integration** + + - Monitor that the batch poster can successfully write batches to the new DAS servers + - Check DAS server logs for successful data storage operations + - Confirm data availability requests are being handled correctly From f2b72b9462c1abc36cbf170c3e89f4e33d9e2991 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Fri, 6 Jun 2025 15:02:29 +0800 Subject: [PATCH 2/6] add router --- stylus-by-example | 2 +- website/sidebars.js | 5 +++++ 2 files changed, 6 insertions(+), 1 deletion(-) diff --git a/stylus-by-example b/stylus-by-example index 24eb919c99..a4ea27d6d6 160000 --- a/stylus-by-example +++ b/stylus-by-example @@ -1 +1 @@ -Subproject commit 24eb919c99079bada64c30db1cb2896fbada8a1f +Subproject commit a4ea27d6d6268d506e22e3c505d088763d03239f diff --git a/website/sidebars.js b/website/sidebars.js index a3672164c9..c4bdfda14a 100644 --- a/website/sidebars.js +++ b/website/sidebars.js @@ -449,6 +449,11 @@ const sidebars = { id: 'launch-arbitrum-chain/maintain-your-chain/guidance/post-launch-contract-deployments', label: `Post-launch deployments`, }, + { + type: 'doc', + id: 'launch-arbitrum-chain/maintain-your-chain/guidance/key-rotation', + label: `Key rotation`, + }, ], }, { From 54a802763e6bc8abdc2f92609c0b8362a1c7e5d4 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Fri, 6 Jun 2025 15:10:43 +0800 Subject: [PATCH 3/6] smol fix --- .../04-maintain-your-chain/04-guidance/06-key-rotation.mdx | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx index 069c084ae8..2a19ae2bba 100644 --- a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx +++ b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx @@ -93,7 +93,7 @@ This guide covers how to rotate keys for different roles in your Arbitrum Orbit 6. **Recover old validator stake** (if applicable) - Wait your old validator's latest stake assertion to be confirmed - - call reduceDeposit() on Rollup Contract + - Call reduceDeposit() on Rollup Contract - Call withdrawStakerFunds() to get your stake back ## 3. AnyTrust Data Availability Committee (DAC) Rotation From e9770572975c71ac0a783af224e9857045e1c451 Mon Sep 17 00:00:00 2001 From: Jason-Wanxt Date: Fri, 6 Jun 2025 15:36:06 +0800 Subject: [PATCH 4/6] update --- stylus-by-example | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/stylus-by-example b/stylus-by-example index a4ea27d6d6..24eb919c99 160000 --- a/stylus-by-example +++ b/stylus-by-example @@ -1 +1 @@ -Subproject commit a4ea27d6d6268d506e22e3c505d088763d03239f +Subproject commit 24eb919c99079bada64c30db1cb2896fbada8a1f From 880e7ec30eb91d0eb441f2de3dd042d9273ac4c4 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 6 Jun 2025 07:37:14 -0500 Subject: [PATCH 5/6] readability/styling --- .../04-guidance/06-key-rotation.mdx | 90 +++++++++++-------- 1 file changed, 53 insertions(+), 37 deletions(-) diff --git a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx index 2a19ae2bba..2308702946 100644 --- a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx +++ b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx @@ -1,34 +1,46 @@ -# Arbitrum Node Key Rotation Guide +--- +title: 'Arbitrum Node Key Rotation Guide' +description: 'Learn how to rotate keys for the different roles in your Arbitrum chain.' +author: Jason-W123 +sme: Jason-W123 +content_type: how-to +--- -This guide covers how to rotate keys for different roles in your Arbitrum Orbit chain: batch poster, validator/staker, and Data Availability Servers (DAS). +This guide covers how to rotate keys for different roles in your Arbitrum Orbit chain: batch poster, validator/bonder, and Data Availability Servers (DAS). -## ⚠️ Important Prerequisites +::: warning Important Prerequisites - **Backup**: Always backup your current configuration and private keys before starting - **Testing**: Test key rotation on a testnet environment first if possible - **Downtime**: Plan for potential brief service interruptions during the rotation process - **Permissions**: Ensure you have the necessary permissions to call the required smart contract functions -## 1. Batch Poster Key Rotation +::: -> **Critical Warning**: For sequencer nodes running both sequencer and batch poster on the same server, you **must** split them first and configure Redis for message synchronization. Failure to do so may cause chain reorganizations. Refer to the [High Availability Sequencer documentation](/run-arbitrum-node/sequencer/05-high-availability-sequencer-docs.mdx) for setup instructions. +## 1. Batch poster key rotation + +:::danger Critical warning + +For sequencer nodes running both the sequencer and batch poster on the same server, you **must** first split them and then configure Redis for message synchronization. Failure to do so may cause chain reorganizations. Refer to the [High Availability Sequencer documentation](/run-arbitrum-node/sequencer/05-high-availability-sequencer-docs.mdx) for setup instructions. + +::: ### Prerequisites -- New batch poster account funded with sufficient ETH for gas fees +- A new batch poster account funded with sufficient `ETH` for gas fees - Access to call functions on the `SequencerInbox` contract -- Current batch poster should be stopped gracefully +- Gracefully stop the current batch poster ### Steps -1. **Enable new batch poster** +1. **Enable the new batch poster** - ``` + ```sh Call setIsBatchPoster(address=, enabled=true) on SequencerInbox contract Call setBatchPosterManager(address=) on SequencerInbox contract if you want to change batch poster manager ``` -2. **Update node configuration** +2. **Update the node configuration** - Update your node configuration to use the new private key - Restart the batch poster service with the new configuration @@ -38,37 +50,37 @@ This guide covers how to rotate keys for different roles in your Arbitrum Orbit **Temporary fix**: - - Add `--node.batch-poster.data-poster.dangerous.clear-dbstorage` flag + - Add the `--node.batch-poster.data-poster.dangerous.clear-dbstorage` flag - Restart the batch poster - - Remove this flag for next start + - **Remove this flag** before the next start 4. **Verify operation** - Monitor logs to confirm the new batch poster is successfully submitting batches - - Check that transactions are being processed normally + - Check that transactions are processing normally -5. **Disable old batch poster** - ``` +5. **Disable the old batch poster** + ```sh Call setIsBatchPoster(address=, enabled=false) on SequencerInbox contract ``` -## 2. Validator/Staker Key Rotation +## 2. Validator/bonder key rotation ### Prerequisites -- New validator account funded with sufficient ETH -- Required stake amount available for the new validator +- A new validator account funded with sufficient `ETH` +- The required bond amount available for the new validator - Access to call functions on the `Rollup` contract ### Steps 1. **Enable new validator** - ``` + ```sh Call setValidator(addr=, val=true) on Rollup contract ``` -2. **Update node configuration** +2. **Update the node configuration** - Update your validator node configuration to use the new private key - Restart the validator service @@ -78,29 +90,29 @@ This guide covers how to rotate keys for different roles in your Arbitrum Orbit - Add `--node.staker.data-poster.dangerous.clear-dbstorage` flag temporarily - Restart the validator - - Remove this flag for next start + - **Remove this flag** before the next start -4. **Verify new validator operation** +4. **Verify the new validator operation** - - Monitor that the new validator successfully posts stake transactions - - Confirm assertion and confirmation transactions are being submitted + - Monitor that the new validator successfully posts bond transactions + - Confirm assertion and confirmation transactions are submitted successfully -5. **Disable old validator** +5. **Disable the old validator** - ``` + ```sh Call setValidator(addr=, val=false) on Rollup contract ``` -6. **Recover old validator stake** (if applicable) - - Wait your old validator's latest stake assertion to be confirmed - - Call reduceDeposit() on Rollup Contract - - Call withdrawStakerFunds() to get your stake back +6. **Recover old validator bond** (if applicable) + - Wait for your old validator's latest bond assertion to be confirmed + - Call `reduceDeposit()` on the `Rollup` Contract + - Call `withdrawStakerFunds()` to get your bond back -## 3. AnyTrust Data Availability Committee (DAC) Rotation +## 3. AnyTrust Data Availability Committee (DAC) rotation ### Prerequisites -- New DAC keyset generated +- A new DAC keyset generated - Access to call functions on the `SequencerInbox` contract ### Steps @@ -108,15 +120,19 @@ This guide covers how to rotate keys for different roles in your Arbitrum Orbit 1. **Generate new keyset** - Follow the [Generate Keyset documentation](/run-arbitrum-node/data-availability-committees/configure-dac#step-1-generate-the-keyset-and-keyset-hash-with-all-the-information-from-the-servers) with your new group of DAS servers - - Ensure all new DAS are properly configured and accessible + - Ensure that all new DAS's are properly configured and accessible -2. **Update keyset on-chain** +2. **Update keyset onchain** - ``` + ```sh Call setValidKeyset(keyset=, assumedHonest=1) on SequencerInbox contract ``` - Note: `assumedHonest=1` assumes at least one committee member is honest + :::note + + `assumedHonest=1` assumes at least one committee member is honest + + ::: 3. **Deploy new DAS servers** @@ -127,4 +143,4 @@ This guide covers how to rotate keys for different roles in your Arbitrum Orbit - Monitor that the batch poster can successfully write batches to the new DAS servers - Check DAS server logs for successful data storage operations - - Confirm data availability requests are being handled correctly + - Confirm data availability requests are getting handled successfully From 3e7ee5c43f3cb141d286846b1c6df978d1053ff6 Mon Sep 17 00:00:00 2001 From: Pete Date: Fri, 6 Jun 2025 07:42:35 -0500 Subject: [PATCH 6/6] yarn format --- .../04-guidance/06-key-rotation.mdx | 10 +++++----- 1 file changed, 5 insertions(+), 5 deletions(-) diff --git a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx index 2308702946..ccccee8688 100644 --- a/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx +++ b/arbitrum-docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx @@ -8,7 +8,7 @@ content_type: how-to This guide covers how to rotate keys for different roles in your Arbitrum Orbit chain: batch poster, validator/bonder, and Data Availability Servers (DAS). -::: warning Important Prerequisites +:::warning Important Prerequisites - **Backup**: Always backup your current configuration and private keys before starting - **Testing**: Test key rotation on a testnet environment first if possible @@ -31,7 +31,7 @@ For sequencer nodes running both the sequencer and batch poster on the same serv - Access to call functions on the `SequencerInbox` contract - Gracefully stop the current batch poster -### Steps +### Generate new batch poster keys 1. **Enable the new batch poster** @@ -72,7 +72,7 @@ For sequencer nodes running both the sequencer and batch poster on the same serv - The required bond amount available for the new validator - Access to call functions on the `Rollup` contract -### Steps +### Activate new keys 1. **Enable new validator** @@ -115,7 +115,7 @@ For sequencer nodes running both the sequencer and batch poster on the same serv - A new DAC keyset generated - Access to call functions on the `SequencerInbox` contract -### Steps +### Generate, deploy, and verify new DAC keys 1. **Generate new keyset** @@ -129,7 +129,7 @@ For sequencer nodes running both the sequencer and batch poster on the same serv ``` :::note - + `assumedHonest=1` assumes at least one committee member is honest :::