275 lines
6.5 KiB
Markdown
275 lines
6.5 KiB
Markdown
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# Rolling restart of validators
|
|
kubectl rollout restart statefulset/besu-validator -n besu-network
|
|
```
|
|
|
|
4. **Verify Change**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# Rolling restart of validators
|
|
kubectl rollout restart statefulset/besu-validator -n besu-network
|
|
```
|
|
|
|
4. **Verify Change**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
kubectl rollout restart statefulset/besu-validator -n besu-network
|
|
```
|
|
|
|
## Gas Limit
|
|
|
|
**Current**: ~30,000,000
|
|
**Change Procedure**:
|
|
|
|
1. **Update Genesis File**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
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**
|
|
```bash
|
|
./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**
|
|
```bash
|
|
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**
|
|
```bash
|
|
# 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**
|
|
```bash
|
|
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**
|
|
```bash
|
|
# Restore from backup
|
|
cp config/genesis.json.backup config/genesis.json
|
|
```
|
|
|
|
2. **Restart Nodes**
|
|
```bash
|
|
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**
|
|
```bash
|
|
# 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](https://besu.hyperledger.org/private-networks/how-to/configure/consensus/qbft)
|
|
- [Network Configuration](../docs/architecture/NETWORK.md)
|
|
- [Deployment Guide](../docs/deployment/DEPLOYMENT.md)
|