docs: Ledger Live integration, contract deploy learnings, NEXT_STEPS updates
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
- ADD_CHAIN138_TO_LEDGER_LIVE: Ledger form done; public code review repo bis-innovations/LedgerLive; init/push commands - CONTRACT_DEPLOYMENT_RUNBOOK: Chain 138 gas price 1 gwei, 36-addr check, TransactionMirror workaround - CONTRACT_*: AddressMapper, MirrorManager deployed 2026-02-12; 36-address on-chain check - NEXT_STEPS_FOR_YOU: Ledger done; steps completable now (no LAN); run-completable-tasks-from-anywhere - MASTER_INDEX, OPERATOR_OPTIONAL, SMART_CONTRACTS_INVENTORY_SIMPLE: updates - LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE: bis-innovations/LedgerLive reference Co-authored-by: Cursor <cursoragent@cursor.com>
This commit is contained in:
defiQUG
@@ -1,5 +1,11 @@
|
||||
# Best Practices Summary
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
Quick reference of best practices for validated set deployment.
|
||||
|
||||
## 🔒 Security
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Comprehensive Recommendations and Suggestions
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
**Date**: $(date)
|
||||
**Purpose**: Complete list of recommendations for optimizing and maintaining the cross-chain bridge system
|
||||
|
||||
|
||||
62
docs/10-best-practices/CONFIGURATION_DECISION_TREE.md
Normal file
62
docs/10-best-practices/CONFIGURATION_DECISION_TREE.md
Normal file
@@ -0,0 +1,62 @@
|
||||
# Configuration Decision Tree
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
## Overview
|
||||
|
||||
Use this tree to choose the right configuration path (which VLAN, which service, deployment path).
|
||||
|
||||
---
|
||||
|
||||
## Which VLAN?
|
||||
|
||||
1. **Management / admin / Proxmox hosts?** → VLAN 11 (192.168.11.0/24). See [NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md).
|
||||
2. **Besu validator?** → VLAN 110 (10.110.0.0/24). Planned; currently flat LAN.
|
||||
3. **Besu sentry?** → VLAN 111 (10.111.0.0/24). Planned.
|
||||
4. **Besu RPC / gateway?** → VLAN 112 (10.112.0.0/24). Planned.
|
||||
5. **CCIP Commit?** → VLAN 132 (10.132.0.0/24). Planned.
|
||||
6. **CCIP Execute?** → VLAN 133 (10.133.0.0/24). Planned.
|
||||
7. **CCIP RMN?** → VLAN 134 (10.134.0.0/24). Planned.
|
||||
8. **Sankofa/Phoenix service?** → VLAN 160 (10.160.0.0/22). Planned.
|
||||
9. **Sovereign tenant?** → VLAN 200–203. Planned.
|
||||
|
||||
**Current:** Most services are on flat LAN 192.168.11.0/24 (VLAN 11). See [NETWORK_CONFIGURATION_MASTER.md](../11-references/NETWORK_CONFIGURATION_MASTER.md).
|
||||
|
||||
---
|
||||
|
||||
## Which Service / VMID Range?
|
||||
|
||||
| Service type | VMID range | Doc |
|
||||
|--------------|------------|-----|
|
||||
| Infrastructure | 100–130 | NETWORK_CONFIGURATION_MASTER |
|
||||
| Besu validators | 1000–1499 | VMID_ALLOCATION_FINAL |
|
||||
| Besu sentries | 1500–1999 | VMID_ALLOCATION_FINAL |
|
||||
| RPC nodes | 2101, 2201, 2301–2308, 2400–2403 | NETWORK_CONFIGURATION_MASTER |
|
||||
| Explorer | 5000 | NETWORK_CONFIGURATION_MASTER |
|
||||
| NPMplus | 10233 | NETWORK_CONFIGURATION_MASTER |
|
||||
| CCIP | 5400–5599 | CCIP_DEPLOYMENT_SPEC |
|
||||
|
||||
**See:** [02-architecture/VMID_ALLOCATION_FINAL.md](../02-architecture/VMID_ALLOCATION_FINAL.md).
|
||||
|
||||
---
|
||||
|
||||
## Deployment Path
|
||||
|
||||
1. **New deployment from scratch?** → [01-getting-started/PREREQUISITES.md](../01-getting-started/PREREQUISITES.md) → [03-deployment/DEPLOYMENT_READINESS.md](../03-deployment/DEPLOYMENT_READINESS.md) → [02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md](../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md).
|
||||
2. **Validated set only?** → [03-deployment/VALIDATED_SET_DEPLOYMENT_GUIDE.md](../03-deployment/VALIDATED_SET_DEPLOYMENT_GUIDE.md) → [12-quick-reference/VALIDATED_SET_QUICK_REFERENCE.md](../12-quick-reference/VALIDATED_SET_QUICK_REFERENCE.md).
|
||||
3. **Production vs staging?** → Use VMID ranges and VLANs per [02-architecture/NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md); staging can share flat LAN with reserved VMIDs.
|
||||
4. **Which components?** → See [03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md) and [MASTER_INDEX.md](../MASTER_INDEX.md).
|
||||
|
||||
---
|
||||
|
||||
## Related Documentation
|
||||
|
||||
- [NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md) - Full network architecture
|
||||
- [NETWORK_CONFIGURATION_MASTER.md](../11-references/NETWORK_CONFIGURATION_MASTER.md) - IP and VMID reference
|
||||
- [VMID_ALLOCATION_FINAL.md](../02-architecture/VMID_ALLOCATION_FINAL.md) - VMID registry
|
||||
- [ORCHESTRATION_DEPLOYMENT_GUIDE.md](../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md) - Deployment workflow
|
||||
- [TROUBLESHOOTING_FAQ.md](../09-troubleshooting/TROUBLESHOOTING_FAQ.md) - Troubleshooting flow
|
||||
@@ -2,6 +2,7 @@
|
||||
|
||||
**Last Updated:** 2025-01-20
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
**Source:** [RECOMMENDATIONS_AND_SUGGESTIONS.md](RECOMMENDATIONS_AND_SUGGESTIONS.md)
|
||||
|
||||
---
|
||||
@@ -266,14 +267,13 @@ This checklist consolidates all recommendations and suggestions from the compreh
|
||||
- [ ] Add progress bars to scripts
|
||||
- [ ] Show current step in multi-step processes
|
||||
|
||||
- [ ] **Add --dry-run flag** (2 hours)
|
||||
- [ ] Implement --dry-run for all scripts
|
||||
- [ ] Show what would be done without executing
|
||||
- [x] **Add --dry-run flag** (2 hours) — **Script added**
|
||||
- [x] Example pattern in `scripts/utils/dry-run-example.sh` (use `DRY_RUN=1` or `--dry-run`)
|
||||
- [ ] Integrate --dry-run into deployment/change scripts as needed
|
||||
|
||||
- [ ] **Add configuration validation** (2 hours)
|
||||
- [ ] Validate all configuration files before use
|
||||
- [ ] Check for required vs optional fields
|
||||
- [ ] Provide helpful error messages
|
||||
- [x] **Add configuration validation** (2 hours) — **Script added**
|
||||
- [x] `scripts/validation/validate-config-files.sh` — validate required files and optional env
|
||||
- [ ] Set `VALIDATE_REQUIRED_FILES='path1 path2'` or use default checks; integrate into CI/pre-deploy
|
||||
|
||||
---
|
||||
|
||||
@@ -286,14 +286,14 @@ This checklist consolidates all recommendations and suggestions from the compreh
|
||||
| **High Priority** | 25 | 5 | 0 | 20 |
|
||||
| **Medium Priority** | 20 | 0 | 0 | 20 |
|
||||
| **Low Priority** | 15 | 0 | 0 | 15 |
|
||||
| **Quick Wins** | 8 | 5 | 0 | 3 |
|
||||
| **TOTAL** | **68** | **10** | **0** | **58** |
|
||||
| **Quick Wins** | 8 | 7 | 0 | 1 |
|
||||
| **TOTAL** | **68** | **12** | **0** | **56** |
|
||||
|
||||
### Completion Rate
|
||||
|
||||
- **Overall:** 14.7% (10/68)
|
||||
- **Overall:** ~17.6% (12/68)
|
||||
- **High Priority:** 20% (5/25)
|
||||
- **Quick Wins:** 62.5% (5/8)
|
||||
- **Quick Wins:** 87.5% (7/8) — dry-run example and config validation scripts added (see [OPTIONAL_RECOMMENDATIONS_INDEX.md](../OPTIONAL_RECOMMENDATIONS_INDEX.md))
|
||||
|
||||
---
|
||||
|
||||
@@ -332,7 +332,7 @@ This checklist consolidates all recommendations and suggestions from the compreh
|
||||
|
||||
- **[RECOMMENDATIONS_AND_SUGGESTIONS.md](RECOMMENDATIONS_AND_SUGGESTIONS.md)** - Source of all recommendations
|
||||
- **[BEST_PRACTICES_SUMMARY.md](BEST_PRACTICES_SUMMARY.md)** - Best practices summary
|
||||
- **[ORCHESTRATION_DEPLOYMENT_GUIDE.md](ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Deployment guide
|
||||
- **[ORCHESTRATION_DEPLOYMENT_GUIDE.md](../02-architecture/ORCHESTRATION_DEPLOYMENT_GUIDE.md)** - Deployment guide
|
||||
|
||||
---
|
||||
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Proxmox VE Complete Recommendations and Review
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
**Date:** 2025-01-20
|
||||
**Review Status:** ✅ Complete
|
||||
**Deployment Readiness:** ✅ Ready
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Proxmox VE Final Recommendations and Summary
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
**Date:** 2025-01-20
|
||||
**Status:** Complete Review with Actionable Recommendations
|
||||
|
||||
|
||||
@@ -1,13 +1,22 @@
|
||||
# Quick Wins - Immediate Improvements
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
These are high-impact, low-effort improvements that can be implemented quickly.
|
||||
|
||||
## 🔒 Security Quick Wins (5-30 minutes each)
|
||||
|
||||
### 1. Secure .env File Permissions
|
||||
```bash
|
||||
chmod 600 ~/.env
|
||||
chown $USER:$USER ~/.env
|
||||
# From project root (covers .env and subproject env files):
|
||||
bash scripts/security/secure-env-permissions.sh
|
||||
# Or manually:
|
||||
chmod 600 .env unifi-api/.env smom-dbis-138/.env dbis_core/.env 2>/dev/null
|
||||
chown $USER:$USER .env # adjust for other env files if needed
|
||||
```
|
||||
**Impact**: Prevents unauthorized access to credentials
|
||||
**Time**: 1 minute
|
||||
@@ -83,8 +92,10 @@ scrape_configs:
|
||||
|
||||
### 7. Create Basic Health Check Cron Job
|
||||
```bash
|
||||
# Add to crontab
|
||||
*/5 * * * * /opt/smom-dbis-138-proxmox/scripts/health/check-node-health.sh 1000 >> /var/log/besu-health.log 2>&1
|
||||
# Option A: Besu node health (run on Proxmox host; requires scripts/health/check-node-health.sh)
|
||||
# See: scripts/archive/consolidated/deploy/setup-health-check-cron.sh
|
||||
# Option B: From project root, blockchain RPC health:
|
||||
# */5 * * * * cd /path/to/proxmox && bash scripts/monitoring/monitor-blockchain-health.sh >> logs/blockchain-health.log 2>&1
|
||||
```
|
||||
**Impact**: Automated health monitoring
|
||||
**Time**: 15 minutes
|
||||
@@ -148,14 +159,14 @@ progress() {
|
||||
|
||||
## ✅ Implementation Checklist
|
||||
|
||||
- [ ] Secure .env file permissions
|
||||
- [ ] Secure validator key permissions
|
||||
- [ ] Create backup script
|
||||
- [ ] Add snapshot before changes
|
||||
- [ ] Secure .env file permissions (`scripts/security/secure-env-permissions.sh` or chmod 600)
|
||||
- [ ] Secure validator key permissions (`scripts/secure-validator-keys.sh [--dry-run]` on Proxmox host)
|
||||
- [ ] Create backup script (NPMplus: `scripts/verify/backup-npmplus.sh [--dry-run]`; cron: `scripts/maintenance/schedule-npmplus-backup-cron.sh --install`)
|
||||
- [ ] Add snapshot before changes (`pct snapshot <vmid> pre-change-$(date +%Y%m%d-%H%M%S)`; see docs/03-deployment/PRE_START_CHECKLIST.md)
|
||||
- [ ] Enable metrics scraping
|
||||
- [ ] Set up health check cron
|
||||
- [ ] Set up health check cron (`scripts/health/check-node-health.sh` + wrapper or `scripts/monitoring/monitor-blockchain-health.sh`)
|
||||
- [ ] Create basic alerts
|
||||
- [ ] Add --dry-run flag
|
||||
- [ ] Add --dry-run flag (many scripts already support it; see scripts/README.md)
|
||||
- [ ] Create troubleshooting FAQ
|
||||
- [ ] Review and update inline comments
|
||||
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Best Practices & Recommendations
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
This directory contains best practices, recommendations, and implementation guides.
|
||||
|
||||
## Documents
|
||||
@@ -8,6 +14,7 @@ This directory contains best practices, recommendations, and implementation guid
|
||||
- **[IMPLEMENTATION_CHECKLIST.md](IMPLEMENTATION_CHECKLIST.md)** ⭐⭐ - Implementation checklist - **Track progress here**
|
||||
- **[BEST_PRACTICES_SUMMARY.md](BEST_PRACTICES_SUMMARY.md)** ⭐⭐ - Best practices summary
|
||||
- **[QUICK_WINS.md](QUICK_WINS.md)** ⭐ - Quick wins implementation guide
|
||||
- **[CONFIGURATION_DECISION_TREE.md](CONFIGURATION_DECISION_TREE.md)** ⭐ - Which VLAN, service, deployment path
|
||||
|
||||
## Quick Reference
|
||||
|
||||
|
||||
@@ -1,5 +1,11 @@
|
||||
# Recommendations and Suggestions - Validated Set Deployment
|
||||
|
||||
**Last Updated:** 2026-01-31
|
||||
**Document Version:** 1.0
|
||||
**Status:** Active Documentation
|
||||
|
||||
---
|
||||
|
||||
This document provides comprehensive recommendations, best practices, and suggestions for the validated set deployment system.
|
||||
|
||||
## 📋 Table of Contents
|
||||
@@ -436,31 +442,7 @@ pct rollback <vmid> pre-upgrade-20241219-120000
|
||||
- ✅ Implement error reporting/notification
|
||||
- ✅ Add rollback on critical failures
|
||||
|
||||
**Example**:
|
||||
```bash
|
||||
# Retry function
|
||||
retry_with_backoff() {
|
||||
local max_attempts=$1
|
||||
local delay=$2
|
||||
shift 2
|
||||
local attempt=1
|
||||
|
||||
while [ $attempt -le $max_attempts ]; do
|
||||
if "$@"; then
|
||||
return 0
|
||||
fi
|
||||
if [ $attempt -lt $max_attempts ]; then
|
||||
log_warn "Attempt $attempt failed, retrying in ${delay}s..."
|
||||
sleep $delay
|
||||
delay=$((delay * 2)) # Exponential backoff
|
||||
fi
|
||||
attempt=$((attempt + 1))
|
||||
done
|
||||
|
||||
log_error "Failed after $max_attempts attempts"
|
||||
return 1
|
||||
}
|
||||
```
|
||||
**Implementation:** See **`scripts/utils/retry_with_backoff.sh`** — source it or run `./retry_with_backoff.sh 3 2 your_command [args]`.
|
||||
|
||||
### 2. Logging Enhancement
|
||||
|
||||
@@ -499,6 +481,8 @@ retry_with_backoff() {
|
||||
- ✅ Estimate resource usage
|
||||
- ✅ Check prerequisites without making changes
|
||||
|
||||
**Implementation:** See **`scripts/utils/dry-run-example.sh`** — use `DRY_RUN=1` or `--dry-run`; wrap destructive commands with `run_or_echo` to preview.
|
||||
|
||||
---
|
||||
|
||||
## 📚 Documentation Enhancements
|
||||
@@ -724,13 +708,15 @@ Track these metrics to measure success:
|
||||
|
||||
## 🔗 Related Documentation
|
||||
|
||||
- [Source Project Structure](SOURCE_PROJECT_STRUCTURE.md)
|
||||
- [Validated Set Deployment Guide](VALIDATED_SET_DEPLOYMENT_GUIDE.md)
|
||||
- [Besu Nodes File Reference](BESU_NODES_FILE_REFERENCE.md)
|
||||
- [Network Bootstrap Guide](NETWORK_BOOTSTRAP_GUIDE.md)
|
||||
- [Project Structure](../../PROJECT_STRUCTURE.md)
|
||||
- [Validated Set Deployment Guide](../03-deployment/VALIDATED_SET_DEPLOYMENT_GUIDE.md)
|
||||
- [Besu Nodes File Reference](../06-besu/BESU_NODES_FILE_REFERENCE.md)
|
||||
- [Network Architecture](../02-architecture/NETWORK_ARCHITECTURE.md) (network layout and bootstrap)
|
||||
|
||||
---
|
||||
|
||||
**Last Updated**: $(date)
|
||||
**Version**: 1.0
|
||||
**Last Updated:** 2026-02-01
|
||||
**Version:** 1.0
|
||||
|
||||
**Completion status:** See [IMPLEMENTATION_CHECKLIST.md](IMPLEMENTATION_CHECKLIST.md) and [OPTIONAL_RECOMMENDATIONS_INDEX.md](../OPTIONAL_RECOMMENDATIONS_INDEX.md) for implemented items (e.g. retry_with_backoff, dry-run pattern, config validation script).
|
||||
|
||||
|
||||
@@ -342,7 +342,7 @@ systemctl start <service>
|
||||
|
||||
- **[OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md)** ⭐⭐ - Operational procedures
|
||||
- **[TROUBLESHOOTING_FAQ.md](/docs/09-troubleshooting/TROUBLESHOOTING_FAQ.md)** ⭐⭐⭐ - Troubleshooting guide
|
||||
- **[BESU_NODE_STARTUP_SEQUENCE.md](../06-besu/BESU_NODE_STARTUP_SEQUENCE.md)** ⭐ - Besu startup sequence
|
||||
- **[BESU_ALLOWLIST_RUNBOOK.md](../06-besu/BESU_ALLOWLIST_RUNBOOK.md)** ⭐ - Besu allowlist and node operations
|
||||
|
||||
---
|
||||
|
||||
|
||||
Reference in New Issue
Block a user