smom-dbis-138/runbooks/parameter-change.md

Parameter Change Runbook

Overview

This runbook provides procedures for changing QBFT parameters and other network parameters.

QBFT Parameters

Block Period

Current: 2 seconds
Change Procedure:

1. Plan the Change

   • Review impact on network performance
   • Coordinate with validator operators
   • Schedule maintenance window

2. Update Genesis File

   # Update blockperiodseconds in genesis.json
   jq '.config.qbft.blockperiodseconds = 5' config/genesis.json > config/genesis-new.json
   mv config/genesis-new.json config/genesis.json
   

3. Restart Validators

   # Rolling restart of validators
   kubectl rollout restart statefulset/besu-validator -n besu-network
   

4. Verify Change

   # Check block time
   curl -X POST -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_getBlockByNumber","params":["latest", false],"id":1}' \
     http://<rpc-endpoint>
   

Epoch Length

Current: 30,000 blocks
Change Procedure:

1. Plan the Change

   • Review impact on validator set updates
   • Coordinate with validator operators
   • Schedule maintenance window

2. Update Genesis File

   # Update epochlength in genesis.json
   jq '.config.qbft.epochlength = 50000' config/genesis.json > config/genesis-new.json
   mv config/genesis-new.json config/genesis.json
   

3. Restart Validators

   # Rolling restart of validators
   kubectl rollout restart statefulset/besu-validator -n besu-network
   

4. Verify Change

   # Check current block number
   curl -X POST -H "Content-Type: application/json" \
     --data '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}' \
     http://<rpc-endpoint>
   

Request Timeout

Current: 10 seconds
Change Procedure:

1. Update Genesis File

   # Update requesttimeoutseconds in genesis.json
   jq '.config.qbft.requesttimeoutseconds = 15' config/genesis.json > config/genesis-new.json
   mv config/genesis-new.json config/genesis.json
   

2. Restart Validators

   kubectl rollout restart statefulset/besu-validator -n besu-network
   

Gas Limit

Current: ~30,000,000
Change Procedure:

1. Update Genesis File

   # Update gasLimit in genesis.json
   jq '.gasLimit = "0x3d0900"' config/genesis.json > config/genesis-new.json
   mv config/genesis-new.json config/genesis.json
   

2. Restart All Nodes

   kubectl rollout restart statefulset/besu-validator -n besu-network
   kubectl rollout restart statefulset/besu-sentry -n besu-network
   kubectl rollout restart statefulset/besu-rpc -n besu-network
   

Validator Set Changes

Add Validator

1. Generate Validator Keys

   ./scripts/key-management/generate-validator-keys.sh 1
   

2. Update Genesis File

   • Add validator address to extraData
   • Regenerate genesis file

3. Update Static Nodes

   • Add validator enode to static-nodes.json

4. Deploy Validator

   • Update StatefulSet replica count
   • Deploy new validator pod

5. Verify Validator

   • Check validator is producing blocks
   • Verify validator is in validator set

Remove Validator

1. Plan Removal

   • Coordinate with validator operator
   • Schedule maintenance window

2. Update Genesis File

   • Remove validator address from extraData
   • Regenerate genesis file

3. Update Static Nodes

   • Remove validator enode from static-nodes.json

4. Remove Validator Pod

   kubectl scale statefulset/besu-validator --replicas=3 -n besu-network
   

5. Verify Removal

   • Check validator set
   • Verify network is still producing blocks

Network Parameter Changes

Chain ID

Current: 138
Warning: Changing Chain ID requires network restart and may break compatibility.

Change Procedure:

1. Update Genesis File

   # Update chainId in genesis.json
   jq '.config.chainId = 139' config/genesis.json > config/genesis-new.json
   mv config/genesis-new.json config/genesis.json
   

2. Update Configuration Files

   • Update chain ID in all configuration files
   • Update deployment scripts
   • Update documentation

3. Restart All Nodes

   kubectl rollout restart statefulset/besu-validator -n besu-network
   kubectl rollout restart statefulset/besu-sentry -n besu-network
   kubectl rollout restart statefulset/besu-rpc -n besu-network
   

Rollback Procedures

Rollback Parameter Change

1. Restore Previous Genesis File

   # Restore from backup
   cp config/genesis.json.backup config/genesis.json
   

2. Restart Nodes

   kubectl rollout restart statefulset/besu-validator -n besu-network
   

3. Verify Rollback

   • Check network is producing blocks
   • Verify parameters are correct

Testing Parameter Changes

Test Environment

1. Deploy to Test Environment

   # Deploy to test cluster
   kubectl apply -f k8s/base/ -n besu-network-test
   

2. Test Parameter Changes

   • Apply parameter changes
   • Verify network operation
   • Test edge cases

3. Monitor Performance

   • Check block production
   • Monitor network performance
   • Verify consensus

Production Deployment

1. Schedule Maintenance Window

   • Notify stakeholders
   • Coordinate with validators
   • Plan rollback procedure

2. Apply Changes

   • Update genesis file
   • Restart nodes
   • Verify changes

3. Monitor Network

   • Check block production
   • Monitor performance
   • Verify consensus

Best Practices

1. Test in Test Environment First

   • Always test parameter changes in test environment
   • Verify network operation
   • Test edge cases

2. Coordinate with Validators

   • Notify all validators before changes
   • Schedule maintenance windows
   • Plan rollback procedures

3. Monitor Network

   • Monitor block production
   • Check network performance
   • Verify consensus

4. Document Changes

   • Document all parameter changes
   • Update configuration files
   • Update documentation

5. Have Rollback Plan

   • Always have rollback plan
   • Test rollback procedures
   • Keep backups

Contacts

• Network Operators: operators@d-bis.org
• Validators: validators@d-bis.org
• Emergency: +1-XXX-XXX-XXXX

References

• QBFT Documentation
• Network Configuration
• Deployment Guide