# All Recommendations and Suggestions for Improvements

**Purpose:** Single consolidated list of all recommendations and improvement suggestions referenced across the repository.  
**Last Updated:** 2026-02-22  
**Source docs:** See links at the end of each section.

**Full plan (required / optional / recommended, execution order):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).

---

## 1. Proxmox / Validated Set (High priority)

| # | Recommendation | Notes |
|---|----------------|------|
| 1 | Secure .env file permissions | `chmod 600 ~/.env` |
| 2 | Secure validator key permissions | chmod 600, chown besu |
| 3 | SSH key-based authentication (disable password) | |
| 4 | Firewall rules for Proxmox API (port 8006) | Restrict to specific IPs |
| 5 | Network segmentation (VLANs) | VLAN enablement phase |
| 6 | Basic metrics collection (Prometheus, Besu 9545) | |
| 7 | Health check monitoring + alerting | |
| 8 | Automated backup script + encrypted validator keys | |
| 9 | Backup configuration files + version control | |
| 10 | Integration tests for deployment scripts | |
| 11 | Runbooks (add/remove validator, upgrade Besu, key rotation, recovery, consensus) | |

**Source:** [10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md](../10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md), [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md)

---

## 2. Proxmox / Validated Set (Medium priority)

| # | Recommendation | Notes |
|---|----------------|------|
| 12 | Enhanced error handling (retry, timeout, circuit breaker, rollback) | retry_with_backoff.sh exists |
| 13 | Structured logging (levels, JSON, IDs, rotation) | |
| 14 | Centralized log collection (Loki/ELK) | |
| 15 | Resource optimization (right-size, CPU pinning, quotas) | |
| 16 | Network optimization (P2P, buffers, jumbo frames, static-nodes) | |
| 17 | Database optimization (size, cache, backups, pruning) | |
| 18 | Java/Besu tuning (heap, GC, flight recorder) | |
| 19 | CI/CD pipeline (testing, blue-green, rollback, canary) | |
| 20 | CLI tool for operations | |

---

## 3. Proxmox / Validated Set (Low priority & quick wins)

| # | Recommendation | Notes |
|---|----------------|------|
| 21–30 | Auto-scaling, dynamic validator set, load balancing, multi-region, HA validators, network upgrades, Web UI, HSM, audit logging, security scanning | Future |
| 31 | Add progress indicators to scripts | |
| 32 | Integrate --dry-run into deployment/change scripts | dry-run-example.sh exists |
| 33 | Integrate config validation into CI/pre-deploy | validate-config-files.sh exists |
| 34 | Create troubleshooting FAQ | |
| 35 | Add inline comments to complex scripts | |

---

## 4. Code quality & scripts

| # | Recommendation | Priority |
|---|----------------|----------|
| 36 | Script shebang: standardize on `#!/usr/bin/env bash` | Medium |
| 37 | Error handling: standardize on `set -euo pipefail` + traps | High |
| 38 | Script header template (metadata, usage, exit codes) | Medium |
| 39 | Code formatting & linting (shellcheck, shfmt, pre-commit, yamllint) | Medium |
| 40 | Script consolidation (140 deployment scripts, reduce overlap) | Medium |
| 41 | Expand shared function library (scripts/lib/) | Medium |
| 42 | Script performance (profile, parallelize, cache) | Low |
| 43 | Auto-generate script documentation | Low |

**Source:** [smom-dbis-138/docs/ADDITIONAL_OPTIMIZATION_RECOMMENDATIONS.md](../../smom-dbis-138/docs/ADDITIONAL_OPTIMIZATION_RECOMMENDATIONS.md)

---

## 5. Documentation enhancements

| # | Recommendation | Priority |
|---|----------------|----------|
| 44 | Documentation consolidation (archive old status reports) | Medium |
| 45 | Documentation accuracy review (quarterly, links, obsolete removal) | Medium |
| 46 | Inline code documentation | Low |
| 47 | API documentation (RPC, contracts, examples) | Medium |
| 68 | Quick reference cards (network, VMID, commands, troubleshooting) | High |
| 69 | Decision trees (troubleshooting, configuration, deployment) | Medium |
| 70 | Configuration templates (ER605, Proxmox, Cloudflare, Besu) | High |
| 71 | Examples and use cases (deployment, troubleshooting, migration) | Medium |
| 72 | Glossary and terminology | Medium |
| 73 | Visual elements (diagrams, tables, flowcharts) | Various |
| 74 | Organization (TOC, cross-links, maintenance schedule) | Various |

**Source:** [00-meta/DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md](DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md)

---

## 6. Security

| # | Recommendation | Priority |
|---|----------------|----------|
| 48 | Secret management audit (no hardcoded secrets, rotation, CI scanning) | High |
| 49 | Input validation in all scripts | High |
| 50 | Security scanning automation (CI, container image scanning) | High |
| 51 | Access control review (RBAC, least privilege) | Medium |
| 52 | Configuration validation (JSON/YAML schema, pre-deploy) | High |

**Source:** [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md), [04-configuration/MASTER_SECRETS.md](../04-configuration/MASTER_SECRETS.md)

---

## 7. Configuration, testing, monitoring & DX

| # | Recommendation | Priority |
|---|----------------|----------|
| 53 | Configuration templates / .example expansion | Medium |
| 54 | Environment management standardization | Medium |
| 55 | Test coverage (unit, integration, E2E, performance) | Medium |
| 56 | Automate all tests in CI | Medium |
| 57 | Test data management (fixtures, generators) | Low |
| 58 | Logging standardization (structured, levels, rotation) | Medium |
| 59 | Metrics collection for script execution | Low |
| 60 | Health check enhancement (dependencies, dashboard) | Medium |
| 61 | Dev environment setup (script, DevContainer, quick start) | Medium |
| 62 | IDE configuration (VS Code, editorconfig) | Low |
| 63 | Developer documentation (guide, standards, architecture) | Medium |
| 64 | Dependency updates (dependabot/renovate, process doc) | Medium |
| 65 | Formalize code review process | Medium |
| 66 | Change management (changelog, versioning) | Low |
| 67 | Backup & recovery review and testing | High |

---

## 8. Infrastructure & deployment

| # | Recommendation | Notes |
|---|----------------|------|
| 75 | VLAN enablement (UDM Pro, Proxmox bridge, service migration) | Phase 1 optional |
| 76 | Observability (Prometheus, Grafana, Loki, Alertmanager, Cloudflare Access) | Phase 2 |
| 77 | CCIP fleet (VMID 5400–5476) | Phase 3 |
| 78 | Sovereign tenants (VLANs, isolation, access control) | Phase 4 |
| 79 | Besu RPC — missing containers (canonical list) | High |
| 80 | Hyperledger (Firefly, Cacti, Fabric, Indy) containers | High/Medium |
| 81 | Blockscout (5000) container | High |

---

## 9. Codebase & placeholders

| # | Recommendation | Priority |
|---|----------------|----------|
| 82 | Security audits (VLT-024, ISO-024) | Critical |
| 83 | Bridge integrations (BRG-VLT, BRG-ISO) | High |
| 84 | CCIP AMB full implementation | High |
| 85 | dbis_core TypeScript/Prisma fixes (~1186 errors) | High |
| 86 | IRU remaining tasks | High |
| 87 | Canonical addresses env-only (token-aggregation) | Medium |
| 88 | AlltraAdapter fee (TODO: actual fee) | Medium |
| 89 | Smart accounts kit placeholders | Medium |
| 90 | Quote service Fabric chainId 999 | Low |
| 91 | .bak script/test restoration or deprecation | Low |

---

## 10. MetaMask & explorer

| # | Recommendation | Effort |
|---|----------------|--------|
| 92 | Token-aggregation production deployment | 2–3 h |
| 93 | Token-aggregation: external API keys (CoinGecko, CMC, DexScreener) | 30 min |
| 94 | Chain 138 Snap: market data UI | 4–6 h |
| 95 | Chain 138 Snap: swap quotes | 8–12 h |
| 96 | Chain 138 Snap: bridge routes | 8–12 h |
| 97 | Chain 138 Snap: testing & distribution | 2–4 h |
| 98 | CoinGecko submission (Chain 138) | 1–2 h |
| 99 | Consensys outreach (Swaps/Bridge support) | 1 h |
| 100 | Paymaster deployment (gas abstraction) | 2–3 h |
| 101 | Explorer: add "Wallet" link to navbar | 15 min |
| 102 | Explorer: sync status indicator | 1 h |
| 103 | Explorer: network selector | 2–3 h |
| 104 | Explorer: dark mode toggle | 2–3 h |
| 105 | Token-aggregation: monitoring, auth for admin endpoints | 1–3 h |

---

## 11. Tezos / Etherlink / CCIP

| # | Recommendation | Category |
|---|----------------|----------|
| 106 | Verify Etherlink in CCIP supported networks | External verification |
| 107 | Verify Jumper API support (138, 651940, 42793, Tezos) | External verification |
| 108 | Verify LiFi for Etherlink (chain 42793) | External verification |
| 109–121 | InitializeRegistry, DeployAllAdapters, Etherlink receiver, token list governance, finality, Tezos L1 relay, Etherlink relay, rate limits, Jumper integration, DON registration, metrics, production enablement, tests | Contracts / Off-chain / Routing / Testing |

**Source:** [07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md](../07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md)

---

## 12. Besu / blockchain

| # | Recommendation | Notes |
|---|----------------|------|
| 122 | RPC config file location (for tx pool) | Needs investigation |
| 123 | Transaction pool clearing / gas price verification | Pending |
| 124 | Layered tx-pool tuning, gas price, network connectivity | Phase 2 |
| 125 | Automated monitoring setup (cron/systemd) for health script | Phase 3 |
| 126 | Logging configuration for monitoring | Phase 3 |

**Source:** [06-besu/COMPLETE_RECOMMENDATIONS_SUMMARY.md](../06-besu/COMPLETE_RECOMMENDATIONS_SUMMARY.md)

---

## 13. RPC translator

| # | Recommendation | Priority |
|---|----------------|----------|
| 128 | Client-side retry logic (exponential backoff, 502) | High |
| 129 | Set up monitoring/alerting | High |
| 130 | Short/medium/long-term improvements (see ALL_RECOMMENDATIONS.md) | Various |

**Source:** [rpc-translator-138/ALL_RECOMMENDATIONS.md](../../rpc-translator-138/ALL_RECOMMENDATIONS.md)

---

## 14. Orchestration portal

| # | Recommendation | Priority |
|---|----------------|----------|
| 131 | P0: Auth, state, real-time, error handling, security headers, validation, testing, CI/CD | Must have |
| 132 | P1: Advanced components, PostgreSQL migration, Redis caching, background jobs, performance, monitoring | Should have |
| 133 | P2: GraphQL, i18n, PWA, multi-tenancy, microservices | Nice to have |
| 134 | Quick wins (see QUICK_WINS.md in portal) | — |

**Source:** [smom-dbis-138/orchestration/portal/RECOMMENDATIONS_SUMMARY.md](../../smom-dbis-138/orchestration/portal/RECOMMENDATIONS_SUMMARY.md)

---

## 15. Maintenance (ongoing)

| # | Task | Frequency |
|---|------|-----------|
| 135 | Monitor explorer sync status | Daily |
| 136 | Monitor RPC node health (e.g. VMID 2201) | Daily |
| 137 | Check config API uptime | Weekly |
| 138 | Review explorer logs | Weekly |
| 139 | Update token list | As needed |

---

## 16. Operator checklist (R1–R24)

| # | Action | When |
|---|--------|------|
| R1 | Verify every deployed contract on Blockscout | After each deployment |
| R2 | Keep CONTRACT_ADDRESSES_REFERENCE and ADDRESS_MATRIX_AND_STATUS updated | When new contracts deployed/deprecated |
| R3 | Run check-contracts-on-chain-138.sh; fix any MISSING/EMPTY | Periodically or after deploy |
| R4 | Do not use deprecated CCIPWETH9Bridge; use 0x971c... and set env | Always |
| R5 | Never commit .env or private keys; rotate exposed keys | Always |
| R6 | API keys in .env.example placeholders | — |
| R7 | Restrict deployer key and RPC admin access | Access review |
| R8 | Set RPC_URL_138; run from LAN/VPN if needed | Before deploy |
| R9 | Use GAS_PRICE=1000000000 (or current min) on Chain 138 | Every forge script on 138 |
| R10 | Phased core deploy order: 01_DeployCore, set env, 02_DeployBridges | Deploy order |
| R11 | If tx stuck, manage nonce; see DEPLOYMENT_STRATEGY_EVALUATION | Troubleshooting |
| R12 | Keep CONTRACT_DEPLOYMENT_RUNBOOK, BLOCKSCOUT_VERIFICATION_GUIDE in sync | After script/URL changes |
| R13 | Document addresses in CONTRACT_ADDRESSES_REFERENCE per chain | Per-chain deploy |
| R14 | Run run-contract-verification-with-proxy.sh after deployments in CI | CI after deploy |
| R15 | Consider single script: check env → deploy → verify → update config | Automation |
| R16 | Use .env.development / .env.staging / .env.production or JSON per chain | Config hygiene |
| R17 | Monitor critical bridge/oracle events | Ongoing |
| R18 | Ensure Blockscout (VMID 5000) is up and /api reachable | Health checks |
| R19 | Run forge test before deploying; integration tests where available | Pre-deploy |
| R20 | NatSpec on public contract functions | Code quality |
| R21 | **Done 2026-03:** NPMplus Order via 10210; documented in RPC_ENDPOINTS_MASTER, ALL_VMIDS | Complete |
| R22 | Document or configure blocks #2–#6 in NETWORK_ARCHITECTURE | When decided |
| R23 | Scripts: progress indicators; --dry-run; config validation | Script updates |
| R24 | Keep config/token-mapping.json as single source of truth for 138↔Mainnet | Adding tokens |

**Source:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md)

---

## 17. Chain 138 Snap (pre-publish)

| Recommendation | Notes |
|----------------|-------|
| Run Snapper / MetaMask security scanner locally before publish | If available |
| Test with real wallet on Chain 138 (small balance) | In-wallet balance, Send page |
| Test from deployed companion site and different origin | CORS, Connected sites |
| Confirm token-aggregation (or API) up; /api/v1/networks, token-list, bridge/routes, quote, tokens | Before release |
| Keep changelog; bump version deliberately; note breaking changes for integrators | |
| When adding tokens: always set logoURI so MetaMask never shows token without logo | |
| When adding/changing chains: set iconUrls; ensure URLs stable and reachable | |

**Source:** [metamask-integration/chain138-snap/docs/PRE_PUBLISH_TESTING.md](../../metamask-integration/chain138-snap/docs/PRE_PUBLISH_TESTING.md) §9

---

## 18. Configuration & DNS (gaps)

| Item | Recommendation |
|------|----------------|
| the-order.sankofa.nexus | **Live:** NPM → `192.168.11.39:80` (10210 → portal :3000) |
| Sankofa cutover plan | **Updated** v1.1 (2026-03-27); legacy API snippets may still use <TARGET_*> |
| sankofa.nexus / phoenix routing | Ensure NPMplus proxy targets 192.168.11.51:3000 and 192.168.11.50:4000 per master docs; only explorer.d-bis.org → 192.168.11.140 |
| Public blocks #2–#6 | Document in NETWORK_ARCHITECTURE / NETWORK_CONFIGURATION_MASTER when assigned or mark reserved |

**Source:** [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md)

---

## 19. dbis_core

| Recommendation | Priority |
|----------------|----------|
| HSM Integration | Critical |
| Zero-Trust Authentication | Critical |
| Database Backups | Critical |
| Post-Quantum Cryptography Migration | Critical |
| Data Retention Policies | Critical |
| Database Connection Pooling, Caching, API Rate Limiting, Horizontal Scaling, Logging, Metrics | High |
| Query Optimization, Distributed Tracing, Test Coverage, Documentation | Medium |
| Microservices, Sharding, Refactoring | Low |

**Source:** [dbis_core/docs/RECOMMENDATIONS.md](../../dbis_core/docs/RECOMMENDATIONS.md)

---

## 20. Verification / optional tooling

| Recommendation | Notes |
|----------------|-------|
| Optional tools for automation | sshpass, rsync, dig, ss, sqlite3, **wscat**, websocat, screen, tmux, htop, shellcheck, parallel |
| Run shellcheck | `bash scripts/verify/run-shellcheck.sh --optional` or install shellcheck and fix issues |
| E2E strict mode | Set `E2E_OPTIONAL_WHEN_FAIL=` (empty) for strict domain/RPC pass |
| Public RPC stability | `bash scripts/verify/check-public-rpc-stability-e2e.sh` |

**Source:** [04-configuration/verification-evidence/NEXT_STEPS_RUN_*.md](../04-configuration/verification-evidence/), [09-troubleshooting/README.md](../09-troubleshooting/README.md)

---

## Summary

| Category | Approx. count | Master index |
|----------|---------------|--------------|
| Proxmox / validated set | 35 | ALL_IMPROVEMENTS_AND_GAPS_INDEX §1 |
| Code quality & scripts | 32 | §2 |
| Documentation | 7 + enhancements | §3, DOCUMENTATION_ENHANCEMENTS |
| Security, config, testing, DX | 25 | §4–7 |
| Infrastructure & deployment | 17 | §8 |
| Codebase & placeholders | 10 | §9 |
| MetaMask & explorer | 14 | §10 |
| Tezos / Etherlink / CCIP | 16 | §11 |
| Besu / blockchain | 5 | §12 |
| RPC translator | 4 | §13 |
| Orchestration portal | 4 | §14 |
| Maintenance | 5 | §15 |
| Operator checklist | 24 | RECOMMENDATIONS_OPERATOR_CHECKLIST |
| Snap pre-publish | 7 | PRE_PUBLISH_TESTING §9 |
| **Total distinct items** | **~139+** | |

---

## Where to read more

- **Derived views:** [ALL_RECOMMENDATIONS_HIGH_PRIORITY.md](ALL_RECOMMENDATIONS_HIGH_PRIORITY.md) (high-priority only) | [ALL_RECOMMENDATIONS_OPERATOR_ONLY.md](ALL_RECOMMENDATIONS_OPERATOR_ONLY.md) (operator/LAN checklist)
- **Legacy index (same 139 items):** [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) — superseded by this doc
- **Gaps and placeholders:** [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md)
- **Operator checklist:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md)
- **Operator/external-only (what to run from LAN):** [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md)
- **Script header template:** [10-best-practices/SCRIPT_HEADER_TEMPLATE.md](../10-best-practices/SCRIPT_HEADER_TEMPLATE.md)
- **Best practices:** [10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md](../10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md), [10-best-practices/IMPLEMENTATION_CHECKLIST.md](../10-best-practices/IMPLEMENTATION_CHECKLIST.md)
- **Next steps / runbooks:** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md)
- **Optional index:** [OPTIONAL_RECOMMENDATIONS_INDEX.md](../OPTIONAL_RECOMMENDATIONS_INDEX.md)