diff --git a/.gitignore b/.gitignore index 03f7b111a..68f823fca 100644 --- a/.gitignore +++ b/.gitignore @@ -15,6 +15,7 @@ build .cache-loader # Misc +.env .DS_Store .env .env.local diff --git a/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx b/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx new file mode 100644 index 000000000..ccccee868 --- /dev/null +++ b/docs/launch-arbitrum-chain/04-maintain-your-chain/04-guidance/06-key-rotation.mdx @@ -0,0 +1,146 @@ +--- +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/bonder, and Data Availability Servers (DAS). + +:::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 + +:::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 + +- A new batch poster account funded with sufficient `ETH` for gas fees +- Access to call functions on the `SequencerInbox` contract +- Gracefully stop the current batch poster + +### Generate new batch poster keys + +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 the 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 the `--node.batch-poster.data-poster.dangerous.clear-dbstorage` flag + - Restart the batch poster + - **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 processing normally + +5. **Disable the old batch poster** + ```sh + Call setIsBatchPoster(address=, enabled=false) on SequencerInbox contract + ``` + +## 2. Validator/bonder key rotation + +### Prerequisites + +- 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 + +### Activate new keys + +1. **Enable new validator** + + ```sh + Call setValidator(addr=, val=true) on Rollup contract + ``` + +2. **Update the 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** before the next start + +4. **Verify the new validator operation** + + - Monitor that the new validator successfully posts bond transactions + - Confirm assertion and confirmation transactions are submitted successfully + +5. **Disable the old validator** + + ```sh + Call setValidator(addr=, val=false) on Rollup contract + ``` + +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 + +### Prerequisites + +- A new DAC keyset generated +- Access to call functions on the `SequencerInbox` contract + +### Generate, deploy, and verify new DAC keys + +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 that all new DAS's are properly configured and accessible + +2. **Update keyset onchain** + + ```sh + 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 getting handled successfully diff --git a/sidebars.js b/sidebars.js index 5041c21db..6a5f16cdb 100644 --- a/sidebars.js +++ b/sidebars.js @@ -498,6 +498,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`, + }, ], }, {