mirror of
https://github.com/sonr-io/sonr.git
synced 2026-09-17 07:26:25 +00:00
docs(docs): add documentation site with Blume config and initial MDX pages
This commit is contained in:
Prad Nukala
@@ -0,0 +1,8 @@
|
||||
---
|
||||
title: Production Network Deployment
|
||||
description: Complete guide for becoming a Sonr blockchain validator - from setup to operations
|
||||
icon: "ship"
|
||||
sidebar:
|
||||
label: Deploy Network & Services
|
||||
---
|
||||
|
||||
@@ -0,0 +1,13 @@
|
||||
import { defineMeta } from "blume";
|
||||
|
||||
export default defineMeta({
|
||||
"title": "Run a Node",
|
||||
"icon": "server",
|
||||
"collapsed": false,
|
||||
"pages": [
|
||||
"onboarding",
|
||||
"deployment",
|
||||
"vrf-key-management",
|
||||
"vrf-migration"
|
||||
]
|
||||
});
|
||||
@@ -0,0 +1,280 @@
|
||||
---
|
||||
title: Validator Node Onboarding
|
||||
description: Complete guide for becoming a Sonr blockchain validator from setup to operations
|
||||
icon: "boxes"
|
||||
sidebar:
|
||||
label: Become a Validator
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Sonr is a Cosmos SDK-based blockchain focused on decentralized identity and asset management. This guide provides comprehensive information for validators interested in securing the Sonr network and participating in its specialized identity infrastructure ecosystem.
|
||||
|
||||
:::note
|
||||
Sonr is currently in testnet/development phase. While there's no confirmed
|
||||
mainnet launch date, early participation in testnet operations is highly
|
||||
recommended for prospective validators.
|
||||
:::
|
||||
|
||||
## Network Positioning
|
||||
|
||||
Sonr differentiates itself within the Cosmos ecosystem through:
|
||||
|
||||
- **Decentralized Identity Focus**: Implementing W3C DID standards and WebAuthn integration
|
||||
- **Highway Architecture**: Specialized node infrastructure for identity services
|
||||
- **Fast Wallet Generation**: 600ms wallet creation with IPFS storage capabilities
|
||||
- **Developer Tools**: React SDKs and identity-focused APIs
|
||||
|
||||
## Hardware Requirements
|
||||
|
||||
Professional validator operations require substantial infrastructure investment to ensure network security and reliability.
|
||||
|
||||
### Essential Specifications
|
||||
|
||||
<Card title="CPU">
|
||||
**Minimum**: 4 cores x86 processor **Recommended**: 8+ cores for production
|
||||
</Card>
|
||||
<Card title="RAM">
|
||||
**Minimum**: 16GB with NVMe swap **Recommended**: 32GB+ for optimal
|
||||
performance
|
||||
</Card>
|
||||
<Card title="Storage">
|
||||
**Required**: 1TB+ NVMe SSD **Note**: Regular SSDs often insufficient for
|
||||
I/O demands
|
||||
</Card>
|
||||
<Card title="Network">
|
||||
**Minimum**: 100Mbps dedicated bandwidth **Usage**: Multi-gigabyte daily
|
||||
traffic expected
|
||||
</Card>
|
||||
|
||||
### Infrastructure Investment
|
||||
|
||||
- **Initial Setup**: Professional-grade hardware required for reliable operations
|
||||
- **Monthly Operating**: Tier 3+ datacenter colocation recommended for optimal performance
|
||||
- **Redundancy**: Full backup server with identical specifications required
|
||||
|
||||
## Quick Setup with NPX
|
||||
|
||||
Sonr provides an NPX-based tool to streamline validator deployment:
|
||||
|
||||
```bash
|
||||
npx @sonr/validator-setup my-validator --chain=sonr-testnet-1
|
||||
```
|
||||
|
||||
The interactive wizard guides you through:
|
||||
|
||||
<Steps>
|
||||
<Step>
|
||||
### Network Configuration Select testnet or mainnet and configure chain
|
||||
parameters
|
||||
</Step>
|
||||
<Step>
|
||||
### Hardware Verification Automated check of system requirements and
|
||||
recommendations
|
||||
</Step>
|
||||
<Step>### Key Generation Secure key creation with HSM support options</Step>
|
||||
<Step>
|
||||
### Sentry Architecture Deploy protective sentry node infrastructure
|
||||
</Step>
|
||||
<Step>
|
||||
### Monitoring Setup Install Prometheus + Grafana monitoring stack
|
||||
</Step>
|
||||
<Step>
|
||||
### Security Hardening Configure firewalls and security best practices
|
||||
</Step>
|
||||
</Steps>
|
||||
|
||||
## Network Parameters
|
||||
|
||||
### Validator Network Structure
|
||||
|
||||
For a 50-validator network with 1 billion token supply:
|
||||
|
||||
#### Early Network Phase (30% staking ratio)
|
||||
|
||||
- **Inflation**: 15% (bootstrap incentives)
|
||||
- **Validator Participation**: Commission-based earnings structure
|
||||
- **Delegator Rewards**: High early participation incentives
|
||||
|
||||
#### Bootstrap Phase (50% staking ratio)
|
||||
|
||||
- **Inflation**: 12% (balanced growth)
|
||||
- **Validator Participation**: Balanced commission structure
|
||||
- **Delegator Rewards**: Sustainable growth incentives
|
||||
|
||||
#### Mature Network (67% staking ratio)
|
||||
|
||||
- **Inflation**: 7% (long-term stability)
|
||||
- **Validator Participation**: Stable commission structure
|
||||
- **Delegator Rewards**: Long-term participation incentives
|
||||
|
||||
### Recommended Parameters
|
||||
|
||||
- **Minimum validator stake**: 1,000,000 SNR (0.1% of supply)
|
||||
- **Optimal self-bond**: 2,000,000 SNR (0.2% of supply)
|
||||
- **Commission range**: 5-15% (5% mandatory minimum)
|
||||
- **Inflation range**: 5-18% with 8% target at 65% staking
|
||||
- **Unbonding period**: 21 days standard
|
||||
|
||||
## Operational Considerations
|
||||
|
||||
### Infrastructure Requirements
|
||||
|
||||
Validators should ensure adequate infrastructure to support reliable network participation.
|
||||
|
||||
### Reward Sources
|
||||
|
||||
- **Block Rewards**: Inflation-based token issuance for network security
|
||||
- **Transaction Fees**: Gas fees and proposer bonuses from network activity
|
||||
- **Additional Rewards**: ICS rewards, cross-chain fees, and ecosystem participation
|
||||
|
||||
## Security Architecture
|
||||
|
||||
### Sentry Node Design
|
||||
|
||||
Implement a multi-layered security approach:
|
||||
|
||||
```
|
||||
Internet → Sentry Nodes (3-5) → Private Network → Validator Node
|
||||
```
|
||||
|
||||
### Critical Security Implementations
|
||||
|
||||
<Card title="Key Management">
|
||||
- Hardware Security Modules (HSM) - Tendermint Key Management System (TMKMS)
|
||||
- Remote signing capabilities
|
||||
</Card>
|
||||
<Card title="Network Security">
|
||||
- Geographic distribution across datacenters - Automated double-sign
|
||||
prevention - Comprehensive monitoring and alerting
|
||||
</Card>
|
||||
<Card title="Operational Security">
|
||||
- 99.9%+ uptime requirements - Encrypted backups across locations - Strict
|
||||
access controls and audits
|
||||
</Card>
|
||||
|
||||
### Key Types
|
||||
|
||||
1. **Consensus Key**: Hot key for block signing (ed25519)
|
||||
2. **Operator Key**: Cold storage for validator transactions (secp256k1)
|
||||
3. **Node Key**: P2P network identification
|
||||
|
||||
## Implementation Roadmap
|
||||
|
||||
### Phase 1: Testnet Participation (Months 1-3)
|
||||
|
||||
:::note
|
||||
Begin with testnet operations to gain experience without operational risk.
|
||||
:::
|
||||
|
||||
- Hardware procurement and datacenter setup
|
||||
- Team training on Cosmos SDK operations
|
||||
- Security procedure development
|
||||
- Community engagement and reputation building
|
||||
|
||||
### Phase 2: Infrastructure Preparation (Month 4)
|
||||
|
||||
- Deploy production hardware in Tier 3+ datacenters
|
||||
- Implement sentry node architecture across regions
|
||||
- Configure monitoring and alerting systems
|
||||
- Establish 24/7 operational procedures
|
||||
|
||||
### Phase 3: Mainnet Genesis (Month 5+)
|
||||
|
||||
- Participate in genesis ceremony
|
||||
- Self-bond required SNR tokens (1-2M recommended)
|
||||
- Configure optimal commission rates (start at 5-7%)
|
||||
- Launch validator with foundation delegation support
|
||||
|
||||
### Phase 4: Operational Excellence (Ongoing)
|
||||
|
||||
- Maintain 99.9%+ uptime through redundant systems
|
||||
- Actively participate in governance proposals
|
||||
- Provide regular updates to delegators
|
||||
- Contribute to ecosystem development
|
||||
|
||||
## Foundation Support Programs
|
||||
|
||||
### Delegation Program
|
||||
|
||||
Sonr implements a foundation delegation program allocating 10-15% of total supply:
|
||||
|
||||
- **Coverage**: 30-35 validators (60-70% of active set)
|
||||
- **Requirements**: 3-month testnet participation
|
||||
- **Terms**: 6-12 month delegation periods
|
||||
- **Renewal**: Performance-based criteria
|
||||
- **Focus**: Geographic distribution and community contributions
|
||||
|
||||
### Testnet Incentives
|
||||
|
||||
- **Monthly Rewards**: Testnet participation incentives for active validators
|
||||
- **Mainnet Slots**: Top performers receive guaranteed mainnet positions
|
||||
- **Foundation Delegations**: 6-month delegations of 2M tokens for top testnet validators
|
||||
|
||||
## Monitoring and Operations
|
||||
|
||||
### Prometheus Metrics
|
||||
|
||||
- System metrics (CPU, RAM, disk, network)
|
||||
- Tendermint consensus metrics (height, voting power, peer count)
|
||||
- Custom application metrics (missed blocks, proposal statistics)
|
||||
|
||||
### Critical Alerts
|
||||
|
||||
- Low peer count (less than 5 peers)
|
||||
- High block time intervals
|
||||
- Resource utilization warnings
|
||||
- Disk space projections
|
||||
|
||||
### Grafana Dashboards
|
||||
|
||||
- Real-time performance monitoring
|
||||
- Historical trend analysis
|
||||
- Multi-validator comparison views
|
||||
|
||||
## Risk Management
|
||||
|
||||
### Technical Risks
|
||||
|
||||
- **Double-signing prevention**: Proper key management and TMKMS
|
||||
- **State corruption recovery**: Automated backup systems
|
||||
- **Network partitions**: Geographic distribution strategies
|
||||
- **Upgrade failures**: Staging environment testing
|
||||
|
||||
### Operational Risks
|
||||
|
||||
- **Network participation**: Maintain consistent validator performance
|
||||
- **Delegation concentration**: Limits on single delegator exposure
|
||||
- **Commission optimization**: Community-competitive rates
|
||||
- **Infrastructure management**: Efficient operational procedures
|
||||
|
||||
## Future Opportunities
|
||||
|
||||
As Sonr matures, validators can explore additional network services:
|
||||
|
||||
- **Relayer Operations**: IBC connection services
|
||||
- **RPC Endpoints**: Developer infrastructure services
|
||||
- **Archive Nodes**: Historical data provision
|
||||
- **Identity Services**: Custom solutions leveraging Sonr infrastructure
|
||||
- **Interchain Security**: Consumer chain participation
|
||||
|
||||
## Getting Started
|
||||
|
||||
<Card title="Join Testnet" href="/development/validators/testnet">
|
||||
Start with testnet participation to gain operational experience
|
||||
</Card>
|
||||
<Card title="Hardware Setup" href="/development/validators/setup">
|
||||
Detailed hardware and infrastructure deployment guide
|
||||
</Card>
|
||||
<Card title="Security Guide" href="/development/validators/security">
|
||||
Comprehensive security implementation and best practices
|
||||
</Card>
|
||||
<Card title="Monitoring" href="/development/validators/monitoring">
|
||||
Setup monitoring and alerting systems for your validator
|
||||
</Card>
|
||||
|
||||
:::note
|
||||
Sonr presents a compelling opportunity for validators seeking exposure to the
|
||||
decentralized identity market within the Cosmos ecosystem. Early preparation
|
||||
and professional operations are key to success.
|
||||
:::
|
||||
@@ -0,0 +1,296 @@
|
||||
---
|
||||
title: VRF Key Management
|
||||
description: Guide to managing VRF keys for multi-validator encryption
|
||||
icon: "key-round"
|
||||
sidebar:
|
||||
label: "VRF Keys"
|
||||
---
|
||||
|
||||
VRF (Verifiable Random Function) keys are essential for consensus-based encryption in multi-validator Sonr networks. This guide explains how VRF keys work, how to manage them, and how to troubleshoot common issues.
|
||||
|
||||
## Overview
|
||||
|
||||
VRF keys enable:
|
||||
- **Deterministic randomness** in distributed systems
|
||||
- **Multi-validator encryption** key derivation
|
||||
- **Consensus-based key rotation** when validator sets change
|
||||
- **Secure encryption** without requiring shared secrets
|
||||
|
||||
## Automatic Generation
|
||||
|
||||
VRF keys are automatically generated when you initialize a new node:
|
||||
|
||||
```bash
|
||||
snrd init <moniker> --chain-id sonrtest_1-1
|
||||
```
|
||||
|
||||
This creates:
|
||||
- VRF keypair at `~/.sonr/vrf_secret.key`
|
||||
- Deterministic generation from chain-id
|
||||
- Secure 0600 permissions (owner read/write only)
|
||||
|
||||
## VRF Key Commands
|
||||
|
||||
The `snrd keys vrf` command suite provides complete VRF key management:
|
||||
|
||||
### Show VRF Key Information
|
||||
|
||||
Display your node's VRF public key and verify configuration:
|
||||
|
||||
```bash
|
||||
snrd keys vrf show
|
||||
```
|
||||
|
||||
Example output:
|
||||
```
|
||||
VRF Key Information:
|
||||
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
|
||||
Key Path: /home/user/.sonr/vrf_secret.key
|
||||
Public Key: d2d8f52119ba12f7f41b004314e3d040526393f09ba434f5b4196c4242ddac0d
|
||||
Key Size: 64 bytes
|
||||
Public Key Size: 32 bytes
|
||||
Permissions: -rw----
|
||||
---
|
||||
Modified: 2025-09-27 00:33:11
|
||||
|
||||
✓ VRF keys are properly configured
|
||||
```
|
||||
|
||||
### Verify VRF Functionality
|
||||
|
||||
Test that VRF keys are working correctly:
|
||||
|
||||
```bash
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
This performs:
|
||||
- VRF key loading
|
||||
- Public key derivation
|
||||
- Test VRF computation with proof
|
||||
- Cryptographic verification
|
||||
|
||||
### Generate New VRF Keys
|
||||
|
||||
Generate or regenerate VRF keys (with backup):
|
||||
|
||||
```bash
|
||||
# Generate for current chain
|
||||
snrd keys vrf generate
|
||||
|
||||
# Generate for specific chain
|
||||
snrd keys vrf generate --chain-id sonrtest_1-1
|
||||
|
||||
# Force regenerate (creates backup)
|
||||
snrd keys vrf generate --force
|
||||
```
|
||||
|
||||
**⚠️ Warning**: Regenerating VRF keys will invalidate existing consensus-based encryption keys. Only do this if you understand the implications.
|
||||
|
||||
## Multi-Validator Testnet Setup
|
||||
|
||||
When setting up a multi-validator testnet, ensure each validator generates unique VRF keys:
|
||||
|
||||
### Using Scripts
|
||||
|
||||
The testnet scripts automatically generate VRF keys:
|
||||
|
||||
```bash
|
||||
# Single node testnet
|
||||
CHAIN_ID="sonrtest_1-1" CLEAN=true bash scripts/test_node.sh
|
||||
|
||||
# Multi-node testnet with Starship
|
||||
make start
|
||||
```
|
||||
|
||||
### Manual Setup
|
||||
|
||||
For manual validator setup:
|
||||
|
||||
1. **Initialize each validator**:
|
||||
```bash
|
||||
snrd init validator-01 --chain-id sonrtest_1-1
|
||||
```
|
||||
|
||||
2. **Verify VRF keys**:
|
||||
```bash
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
3. **Check permissions**:
|
||||
```bash
|
||||
ls -la ~/.sonr/vrf_secret.key
|
||||
# Should show: -rw------- (0600)
|
||||
```
|
||||
|
||||
## Encryption Configuration
|
||||
|
||||
VRF keys are only required when encryption is enabled. You can control encryption via module parameters:
|
||||
|
||||
### Check Encryption Status
|
||||
|
||||
```bash
|
||||
snrd query dwn params
|
||||
```
|
||||
|
||||
Look for the `encryption_enabled` field.
|
||||
|
||||
### Disable Encryption
|
||||
|
||||
If you don't need encryption features, you can disable them:
|
||||
|
||||
```bash
|
||||
# Via governance proposal
|
||||
snrd tx gov submit-proposal param-change proposal.json
|
||||
```
|
||||
|
||||
With `proposal.json`:
|
||||
```json
|
||||
{
|
||||
"title": "Disable DWN Encryption",
|
||||
"description": "Disable encryption features",
|
||||
"changes": [
|
||||
{
|
||||
"subspace": "dwn",
|
||||
"key": "EncryptionEnabled",
|
||||
"value": "false"
|
||||
}
|
||||
]
|
||||
}
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Error: "VRF keys not loaded"
|
||||
|
||||
**Cause**: VRF keys are missing or corrupted.
|
||||
|
||||
**Solution**:
|
||||
1. Check if keys exist:
|
||||
```bash
|
||||
ls -la ~/.sonr/vrf_secret.key
|
||||
```
|
||||
|
||||
2. If missing, generate keys:
|
||||
```bash
|
||||
snrd keys vrf generate --chain-id sonrtest_1-1
|
||||
```
|
||||
|
||||
3. If present but corrupted, regenerate:
|
||||
```bash
|
||||
snrd keys vrf generate --force
|
||||
```
|
||||
|
||||
### Error: "Failed to check and perform key rotation"
|
||||
|
||||
**Cause**: VRF keys not available during EndBlock, but encryption is enabled.
|
||||
|
||||
**Solution**:
|
||||
1. Verify VRF keys:
|
||||
```bash
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
2. Or disable encryption if not needed:
|
||||
```bash
|
||||
# Check current params
|
||||
snrd query dwn params
|
||||
|
||||
# Submit governance proposal to disable
|
||||
```
|
||||
|
||||
### Incorrect Permissions
|
||||
|
||||
**Cause**: VRF key file has insecure permissions.
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
```
|
||||
|
||||
### Single-Node vs Multi-Validator
|
||||
|
||||
- **Single-node development**: Works without VRF keys (deterministic fallback)
|
||||
- **Multi-validator testnet**: Requires VRF keys for consensus encryption
|
||||
- **Production**: Always use VRF keys with proper security
|
||||
|
||||
## Security Best Practices
|
||||
|
||||
### Key Storage
|
||||
|
||||
- **Never share** VRF private keys between validators
|
||||
- **Backup** VRF keys securely (offline storage)
|
||||
- **Rotate** validator nodes if keys are compromised
|
||||
- **Monitor** file permissions regularly
|
||||
|
||||
### File Permissions
|
||||
|
||||
Always ensure restrictive permissions:
|
||||
|
||||
```bash
|
||||
# Check permissions
|
||||
ls -la ~/.sonr/vrf_secret.key
|
||||
|
||||
# Fix if needed
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
chown $(whoami):$(whoami) ~/.sonr/vrf_secret.key
|
||||
```
|
||||
|
||||
### Key Backup
|
||||
|
||||
Backup your VRF keys securely:
|
||||
|
||||
```bash
|
||||
# Create encrypted backup
|
||||
tar -czf vrf-backup.tar.gz -C ~/.sonr vrf_secret.key
|
||||
gpg --symmetric --cipher-algo AES256 vrf-backup.tar.gz
|
||||
|
||||
# Store vrf-backup.tar.gz.gpg securely offline
|
||||
```
|
||||
|
||||
### Recovery
|
||||
|
||||
Restore from backup:
|
||||
|
||||
```bash
|
||||
# Decrypt backup
|
||||
gpg --decrypt vrf-backup.tar.gz.gpg > vrf-backup.tar.gz
|
||||
|
||||
# Extract to correct location
|
||||
tar -xzf vrf-backup.tar.gz -C ~/.sonr/
|
||||
|
||||
# Verify permissions
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
## Advanced Topics
|
||||
|
||||
### Deterministic Generation
|
||||
|
||||
VRF keys are generated deterministically from the chain-id using SHA256. This means:
|
||||
- Same chain-id = same VRF keys
|
||||
- Different validators should use different chain configurations
|
||||
- Re-running `snrd init` with same chain-id produces same keys
|
||||
|
||||
### VRF Algorithm
|
||||
|
||||
Sonr uses **VRF based on Ed25519** (Curve25519):
|
||||
- Private key: 64 bytes (32 bytes secret + 32 bytes public)
|
||||
- Public key: 32 bytes
|
||||
- Proof: 80 bytes
|
||||
- Output: 32 bytes of verifiable randomness
|
||||
|
||||
### Consensus Encryption
|
||||
|
||||
Multi-validator encryption key derivation:
|
||||
1. Each validator computes VRF output from consensus input
|
||||
2. VRF outputs are combined to derive encryption key
|
||||
3. Automatic rotation when validator set changes
|
||||
4. Keys are never transmitted over network
|
||||
|
||||
## See Also
|
||||
|
||||
- [Configure Local Node](/configure-local-node) - Node setup guide
|
||||
- [Development](/development) - Development environment setup
|
||||
- [Deployment](/deployment) - Production deployment guide
|
||||
@@ -0,0 +1,563 @@
|
||||
---
|
||||
title: VRF Key Migration Guide
|
||||
description: Migrate existing validator nodes to use VRF keys without downtime
|
||||
icon: "arrow-right-left"
|
||||
sidebar:
|
||||
label: "VRF Migration"
|
||||
---
|
||||
|
||||
This guide provides step-by-step instructions for adding VRF keys to existing Sonr validator nodes that were initialized before VRF key support was added.
|
||||
|
||||
## Overview
|
||||
|
||||
VRF (Verifiable Random Function) keys are required for:
|
||||
- Multi-validator encryption features (added in v0.1.12)
|
||||
- Consensus-based key rotation
|
||||
- Secure encryption key derivation
|
||||
|
||||
Existing nodes initialized before v0.1.12 may not have VRF keys generated.
|
||||
|
||||
## Pre-Migration Checklist
|
||||
|
||||
Before starting the migration:
|
||||
|
||||
- [ ] **Backup** your validator keys and configuration
|
||||
- [ ] **Identify** which validators need VRF keys
|
||||
- [ ] **Plan** migration during low-traffic period
|
||||
- [ ] **Coordinate** with other validators (for governance proposals)
|
||||
- [ ] **Test** on testnet first
|
||||
|
||||
## Migration Scenarios
|
||||
|
||||
### Scenario 1: Encryption Not Needed
|
||||
|
||||
If your network doesn't use encryption features, you can disable encryption instead of generating VRF keys.
|
||||
|
||||
**Option A: Disable via Governance**
|
||||
|
||||
1. Create governance proposal:
|
||||
|
||||
```bash
|
||||
cat > disable-encryption-proposal.json <<EOF
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"@type": "/cosmos.params.v1beta1.MsgUpdateParams",
|
||||
"authority": "sonr10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t",
|
||||
"params": {
|
||||
"encryption_enabled": false
|
||||
}
|
||||
}
|
||||
],
|
||||
"metadata": "Disable encryption until VRF keys are configured",
|
||||
"deposit": "10000000usnr",
|
||||
"title": "Disable DWN Encryption",
|
||||
"summary": "Temporary disable encryption to allow gradual VRF key rollout"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
2. Submit proposal:
|
||||
|
||||
```bash
|
||||
snrd tx gov submit-proposal disable-encryption-proposal.json \
|
||||
--from validator \
|
||||
--chain-id sonrtest_1-1 \
|
||||
--gas auto \
|
||||
--gas-adjustment 1.5
|
||||
```
|
||||
|
||||
3. Vote and wait for execution.
|
||||
|
||||
**Option B: Genesis Parameter (New Networks Only)**
|
||||
|
||||
For new networks, set in genesis:
|
||||
|
||||
```json
|
||||
{
|
||||
"app_state": {
|
||||
"dwn": {
|
||||
"params": {
|
||||
"encryption_enabled": false
|
||||
}
|
||||
}
|
||||
}
|
||||
}
|
||||
```
|
||||
|
||||
### Scenario 2: Gradual Migration (Recommended)
|
||||
|
||||
Migrate validators one at a time to minimize risk.
|
||||
|
||||
**Step 1: Disable Encryption Temporarily**
|
||||
|
||||
Follow Scenario 1, Option A to disable encryption via governance.
|
||||
|
||||
**Step 2: Generate VRF Keys for Each Validator**
|
||||
|
||||
On each validator node:
|
||||
|
||||
1. **Stop the validator** (optional, but recommended):
|
||||
```bash
|
||||
systemctl stop snrd
|
||||
# or
|
||||
pkill snrd
|
||||
```
|
||||
|
||||
2. **Generate VRF keys**:
|
||||
```bash
|
||||
snrd keys vrf generate --chain-id sonrtest_1-1
|
||||
```
|
||||
|
||||
3. **Verify generation**:
|
||||
```bash
|
||||
snrd keys vrf show
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
4. **Check permissions**:
|
||||
```bash
|
||||
ls -la ~/.sonr/vrf_secret.key
|
||||
# Should show: -rw------- (0600)
|
||||
```
|
||||
|
||||
5. **Restart validator**:
|
||||
```bash
|
||||
systemctl start snrd
|
||||
# or start manually
|
||||
```
|
||||
|
||||
6. **Verify node is syncing**:
|
||||
```bash
|
||||
snrd status | jq '.SyncInfo'
|
||||
```
|
||||
|
||||
**Step 3: Verify All Validators Have VRF Keys**
|
||||
|
||||
On each validator, run:
|
||||
|
||||
```bash
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
All validators should show:
|
||||
```
|
||||
✓ VRF keys are fully functional
|
||||
```
|
||||
|
||||
**Step 4: Re-enable Encryption**
|
||||
|
||||
Once all validators have VRF keys:
|
||||
|
||||
1. Create governance proposal:
|
||||
|
||||
```bash
|
||||
cat > enable-encryption-proposal.json <<EOF
|
||||
{
|
||||
"messages": [
|
||||
{
|
||||
"@type": "/cosmos.params.v1beta1.MsgUpdateParams",
|
||||
"authority": "sonr10d07y265gmmuvt4z0w9aw880jnsr700j8yv32t",
|
||||
"params": {
|
||||
"encryption_enabled": true
|
||||
}
|
||||
}
|
||||
],
|
||||
"metadata": "Re-enable encryption after VRF key deployment",
|
||||
"deposit": "10000000usnr",
|
||||
"title": "Enable DWN Encryption",
|
||||
"summary": "Re-enable encryption now that all validators have VRF keys"
|
||||
}
|
||||
EOF
|
||||
```
|
||||
|
||||
2. Submit and execute proposal.
|
||||
|
||||
### Scenario 3: Coordinated Network Upgrade
|
||||
|
||||
For critical production networks, coordinate a network-wide upgrade.
|
||||
|
||||
**Phase 1: Preparation (1-2 weeks before)**
|
||||
|
||||
1. **Announce upgrade** to all validators
|
||||
2. **Share migration plan** and timeline
|
||||
3. **Test on testnet** with same validator set
|
||||
4. **Prepare rollback plan**
|
||||
|
||||
**Phase 2: Pre-Upgrade (1 day before)**
|
||||
|
||||
1. **Verify all validators** are ready:
|
||||
```bash
|
||||
# Check validator set
|
||||
snrd query staking validators --output json | jq '.validators[] | {moniker, status}'
|
||||
```
|
||||
|
||||
2. **Backup critical data**:
|
||||
```bash
|
||||
# Backup validator state
|
||||
tar -czf validator-backup-$(date +%Y%m%d).tar.gz \
|
||||
~/.sonr/config/ \
|
||||
~/.sonr/data/priv_validator_state.json
|
||||
```
|
||||
|
||||
3. **Sync upgrade binary**:
|
||||
```bash
|
||||
# Ensure all validators have same version
|
||||
snrd version
|
||||
```
|
||||
|
||||
**Phase 3: Migration Window**
|
||||
|
||||
1. **Stop network** at agreed block height:
|
||||
```bash
|
||||
# All validators stop
|
||||
systemctl stop snrd
|
||||
```
|
||||
|
||||
2. **Generate VRF keys** on each validator:
|
||||
```bash
|
||||
snrd keys vrf generate --chain-id sonrtest_1-1
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
3. **Verify permissions**:
|
||||
```bash
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
```
|
||||
|
||||
4. **Restart validators** in coordination:
|
||||
```bash
|
||||
systemctl start snrd
|
||||
```
|
||||
|
||||
5. **Monitor network recovery**:
|
||||
```bash
|
||||
# Watch consensus
|
||||
snrd status | jq '.SyncInfo.catching_up'
|
||||
|
||||
# Watch block production
|
||||
watch -n 1 'snrd status | jq ".SyncInfo.latest_block_height"'
|
||||
```
|
||||
|
||||
**Phase 4: Post-Migration Verification**
|
||||
|
||||
1. **Check all validators online**:
|
||||
```bash
|
||||
snrd query tendermint-validator-set | jq '.validators[].address'
|
||||
```
|
||||
|
||||
2. **Verify VRF functionality**:
|
||||
```bash
|
||||
# On each validator
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
3. **Test encryption features**:
|
||||
```bash
|
||||
# Create encrypted record
|
||||
snrd tx dwn create-record \
|
||||
--protocol "encrypted-protocol" \
|
||||
--data "test-data" \
|
||||
--from validator
|
||||
```
|
||||
|
||||
4. **Monitor for errors**:
|
||||
```bash
|
||||
journalctl -u snrd -f | grep -i "vrf\|encryption"
|
||||
```
|
||||
|
||||
## Rollback Procedures
|
||||
|
||||
If issues arise during migration:
|
||||
|
||||
### Emergency Rollback
|
||||
|
||||
1. **Stop affected validators**:
|
||||
```bash
|
||||
systemctl stop snrd
|
||||
```
|
||||
|
||||
2. **Disable encryption via governance** (if network is running):
|
||||
```bash
|
||||
# Submit emergency proposal
|
||||
snrd tx gov submit-proposal disable-encryption-proposal.json --expedited
|
||||
```
|
||||
|
||||
3. **Restore from backup**:
|
||||
```bash
|
||||
# Stop node
|
||||
systemctl stop snrd
|
||||
|
||||
# Restore backup
|
||||
tar -xzf validator-backup-YYYYMMDD.tar.gz -C ~/
|
||||
|
||||
# Restart
|
||||
systemctl start snrd
|
||||
```
|
||||
|
||||
4. **Verify recovery**:
|
||||
```bash
|
||||
snrd status
|
||||
```
|
||||
|
||||
### Gradual Rollback
|
||||
|
||||
If only some validators have issues:
|
||||
|
||||
1. Keep VRF keys on working validators
|
||||
2. Remove VRF keys from problematic validators:
|
||||
```bash
|
||||
mv ~/.sonr/vrf_secret.key ~/.sonr/vrf_secret.key.backup
|
||||
```
|
||||
3. Disable encryption temporarily
|
||||
4. Debug issues before retry
|
||||
|
||||
## Validation & Testing
|
||||
|
||||
### Pre-Migration Testing
|
||||
|
||||
Test on a private testnet first:
|
||||
|
||||
```bash
|
||||
# Setup test network
|
||||
CHAIN_ID="test-migration" make localnet
|
||||
|
||||
# Test VRF generation
|
||||
snrd keys vrf generate --chain-id test-migration
|
||||
snrd keys vrf verify
|
||||
|
||||
# Test with encryption enabled
|
||||
snrd query dwn params
|
||||
|
||||
# Test key rotation
|
||||
# (trigger validator set change)
|
||||
```
|
||||
|
||||
### Post-Migration Validation
|
||||
|
||||
After migration, verify:
|
||||
|
||||
1. **All validators have VRF keys**:
|
||||
```bash
|
||||
# On each validator
|
||||
snrd keys vrf show
|
||||
```
|
||||
|
||||
2. **No VRF errors in logs**:
|
||||
```bash
|
||||
journalctl -u snrd --since "1 hour ago" | grep -i "vrf" | grep -i "error"
|
||||
# Should return nothing
|
||||
```
|
||||
|
||||
3. **Encryption working**:
|
||||
```bash
|
||||
snrd query dwn params | jq '.params.encryption_enabled'
|
||||
# Should return: true
|
||||
```
|
||||
|
||||
4. **Key rotation functional**:
|
||||
```bash
|
||||
# Check encryption state
|
||||
snrd query dwn encryption-state
|
||||
```
|
||||
|
||||
## Troubleshooting
|
||||
|
||||
### Issue: "VRF keys not loaded"
|
||||
|
||||
**Cause**: Keys not generated or file permissions incorrect.
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Regenerate keys
|
||||
snrd keys vrf generate --chain-id <your-chain-id> --force
|
||||
|
||||
# Fix permissions
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
|
||||
# Verify
|
||||
snrd keys vrf verify
|
||||
```
|
||||
|
||||
### Issue: "Failed to check and perform key rotation"
|
||||
|
||||
**Cause**: Encryption enabled but VRF keys missing on some validators.
|
||||
|
||||
**Fix**:
|
||||
1. Identify validators without VRF keys
|
||||
2. Temporarily disable encryption
|
||||
3. Generate VRF keys on all validators
|
||||
4. Re-enable encryption
|
||||
|
||||
### Issue: Network Stalled During Migration
|
||||
|
||||
**Cause**: Too many validators offline simultaneously.
|
||||
|
||||
**Fix**:
|
||||
1. Ensure >2/3 voting power online
|
||||
2. Coordinate restart timing
|
||||
3. Use smaller migration windows per validator
|
||||
|
||||
### Issue: Inconsistent VRF Keys
|
||||
|
||||
**Cause**: Different chain-id used during generation.
|
||||
|
||||
**Fix**:
|
||||
```bash
|
||||
# Check chain-id in genesis
|
||||
jq '.chain_id' ~/.sonr/config/genesis.json
|
||||
|
||||
# Regenerate with correct chain-id
|
||||
snrd keys vrf generate --chain-id <correct-chain-id> --force
|
||||
```
|
||||
|
||||
## Best Practices
|
||||
|
||||
### Before Migration
|
||||
|
||||
- ✅ Test on testnet with same topology
|
||||
- ✅ Backup all validator data
|
||||
- ✅ Document rollback procedures
|
||||
- ✅ Prepare monitoring dashboards
|
||||
- ✅ Schedule during low-traffic period
|
||||
|
||||
### During Migration
|
||||
|
||||
- ✅ Migrate one validator at a time (gradual)
|
||||
- ✅ Monitor logs continuously
|
||||
- ✅ Verify each step before proceeding
|
||||
- ✅ Keep communication channels open
|
||||
- ✅ Document any issues encountered
|
||||
|
||||
### After Migration
|
||||
|
||||
- ✅ Verify all validators functional
|
||||
- ✅ Test encryption features
|
||||
- ✅ Monitor performance metrics
|
||||
- ✅ Update documentation
|
||||
- ✅ Schedule follow-up verification
|
||||
|
||||
## Timeline Recommendations
|
||||
|
||||
### Small Network (3-5 validators)
|
||||
- **Preparation**: 3-5 days
|
||||
- **Migration**: 1-2 hours
|
||||
- **Verification**: 1 day
|
||||
|
||||
### Medium Network (10-20 validators)
|
||||
- **Preparation**: 1 week
|
||||
- **Migration**: 4-6 hours (gradual) or 30 minutes (coordinated)
|
||||
- **Verification**: 2-3 days
|
||||
|
||||
### Large Network (50+ validators)
|
||||
- **Preparation**: 2-3 weeks
|
||||
- **Migration**: 1-2 days (gradual) or network upgrade
|
||||
- **Verification**: 1 week
|
||||
|
||||
## Support & Resources
|
||||
|
||||
- **VRF Key Management Guide**: `/vrf-key-management`
|
||||
- **GitHub Issues**: https://github.com/sonr-io/sonr/issues
|
||||
- **Discord**: Validator support channel
|
||||
- **Documentation**: https://docs.sonr.io
|
||||
|
||||
## Appendix: Automation Script
|
||||
|
||||
For networks with many validators, use this automation script:
|
||||
|
||||
```bash
|
||||
#!/bin/bash
|
||||
# vrf-migration.sh - Automated VRF key migration helper
|
||||
|
||||
set -e
|
||||
|
||||
CHAIN_ID="${CHAIN_ID:-sonrtest_1-1}"
|
||||
BACKUP_DIR="${BACKUP_DIR:-$HOME/vrf-backup}"
|
||||
|
||||
# Colors for output
|
||||
RED='\033[0;31m'
|
||||
GREEN='\033[0;32m'
|
||||
YELLOW='\033[1;33m'
|
||||
NC='\033[0m' # No Color
|
||||
|
||||
log_info() {
|
||||
echo -e "${GREEN}[INFO]${NC} $1"
|
||||
}
|
||||
|
||||
log_warn() {
|
||||
echo -e "${YELLOW}[WARN]${NC} $1"
|
||||
}
|
||||
|
||||
log_error() {
|
||||
echo -e "${RED}[ERROR]${NC} $1"
|
||||
}
|
||||
|
||||
# Backup existing data
|
||||
backup_validator() {
|
||||
log_info "Creating backup..."
|
||||
mkdir -p "$BACKUP_DIR"
|
||||
tar -czf "$BACKUP_DIR/validator-$(date +%Y%m%d-%H%M%S).tar.gz" \
|
||||
~/.sonr/config/ \
|
||||
~/.sonr/data/priv_validator_state.json 2>/dev/null || true
|
||||
log_info "Backup created at $BACKUP_DIR"
|
||||
}
|
||||
|
||||
# Generate VRF keys
|
||||
generate_vrf() {
|
||||
log_info "Generating VRF keys for chain: $CHAIN_ID"
|
||||
if snrd keys vrf generate --chain-id "$CHAIN_ID"; then
|
||||
log_info "VRF keys generated successfully"
|
||||
else
|
||||
log_error "Failed to generate VRF keys"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Verify VRF keys
|
||||
verify_vrf() {
|
||||
log_info "Verifying VRF keys..."
|
||||
if snrd keys vrf verify; then
|
||||
log_info "VRF keys verified successfully"
|
||||
else
|
||||
log_error "VRF key verification failed"
|
||||
exit 1
|
||||
fi
|
||||
}
|
||||
|
||||
# Fix permissions
|
||||
fix_permissions() {
|
||||
log_info "Fixing VRF key permissions..."
|
||||
chmod 0600 ~/.sonr/vrf_secret.key
|
||||
log_info "Permissions set to 0600"
|
||||
}
|
||||
|
||||
# Main migration flow
|
||||
main() {
|
||||
log_info "Starting VRF key migration..."
|
||||
log_info "Chain ID: $CHAIN_ID"
|
||||
|
||||
# Backup
|
||||
backup_validator
|
||||
|
||||
# Generate keys
|
||||
generate_vrf
|
||||
|
||||
# Fix permissions
|
||||
fix_permissions
|
||||
|
||||
# Verify
|
||||
verify_vrf
|
||||
|
||||
log_info "Migration completed successfully!"
|
||||
log_info "Please restart your validator node"
|
||||
}
|
||||
|
||||
# Run migration
|
||||
main
|
||||
```
|
||||
|
||||
Save and run:
|
||||
```bash
|
||||
chmod +x vrf-migration.sh
|
||||
CHAIN_ID="sonrtest_1-1" ./vrf-migration.sh
|
||||
```
|
||||
Reference in New Issue
Block a user