d-bis/proxmox
4
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

chore: sync all changes to Gitea
Some checks failed
Deploy to Phoenix / deploy (push) Has been cancelled
Details

Browse Source 
- Config, docs, scripts, and backup manifests
- Submodule refs unchanged (m = modified content in submodules)

Made-with: Cursor
This commit is contained in:
defiQUG
2026-03-02 11:37:34 -08:00
parent ed85135249
commit b3a8fe4496
883 changed files with 73580 additions and 4796 deletions
Download Patch File Download Diff File Expand all files Collapse all files

373
docs/00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md Normal file
View File

@@ -0,0 +1,373 @@
# 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 | When The Order deployed: NPMplus proxy host; document in RPC_ENDPOINTS_MASTER | Sankofa/The Order go-live |
| 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 | When The Order portal deployed: add NPMplus proxy host; document in RPC_ENDPOINTS_MASTER, ALL_VMIDS_ENDPOINTS |
| Sankofa cutover plan | Replace <TARGET_IP>, <TARGET_PORT>, TBDs with actual IPs/ports when deployed |
| 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)

136
docs/00-meta/ALL_RECOMMENDATIONS_HIGH_PRIORITY.md Normal file
View File

@@ -0,0 +1,136 @@
# All Recommendations — High-Priority Only
**Purpose:** Filtered view of high-priority and critical items from the canonical list.
**Canonical source:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (~139 items, 20 sections).
---
## 1. Proxmox / Validated Set (High) — Items 1–11
| # | 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) | |
---
## 2. Code quality & scripts (High) — Items 36–37
| # | Recommendation | Priority |
|---|----------------|----------|
| 36 | Script shebang: standardize on `#!/usr/bin/env bash` | Medium |
| 37 | Error handling: standardize on `set -euo pipefail` + traps | **High** |
---
## 3. Documentation (High) — Items 68, 70
| # | Recommendation | Priority |
|---|----------------|----------|
| 68 | Quick reference cards (network, VMID, commands, troubleshooting) | High |
| 70 | Configuration templates (ER605, Proxmox, Cloudflare, Besu) | High |
---
## 4. Security — Items 48–52
| # | 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 |
---
## 5. Configuration, testing & DX (High) — Item 67
| # | Recommendation | Priority |
|---|----------------|----------|
| 67 | Backup & recovery review and testing | High |
---
## 6. Infrastructure & deployment (High) — Items 79–81
| # | Recommendation | Notes |
|---|----------------|------|
| 79 | Besu RPC — 2506–2508 destroyed 2026-02-08; replaced by new VMID structure; RPC 2500–2505 only. See MISSING_CONTAINERS_LIST.md | Done (doc) |
| 80 | Hyperledger (Firefly, Cacti, Fabric, Indy) containers | High/Medium |
| 81 | Blockscout (5000) container | High |
---
## 7. Codebase & placeholders (Critical/High) — Items 82–86
| # | 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 |
---
## 8. RPC translator — Items 128–129
| # | Recommendation | Priority |
|---|----------------|----------|
| 128 | Client-side retry logic (exponential backoff, 502) | High |
| 129 | Set up monitoring/alerting | High |
---
## 9. Orchestration portal (P0) — Item 131
| # | Recommendation | Priority |
|---|----------------|----------|
| 131 | P0: Auth, state, real-time, error handling, security headers, validation, testing, CI/CD | Must have |
---
## 10. dbis_core (Critical)
| Recommendation | Priority |
|----------------|----------|
| HSM Integration | Critical |
| Zero-Trust Authentication | Critical |
| Database Backups | Critical |
| Post-Quantum Cryptography Migration | Critical |
| Data Retention Policies | Critical |
**Source:** [dbis_core/docs/RECOMMENDATIONS.md](../../dbis_core/docs/RECOMMENDATIONS.md)
---
## 11. Operator checklist (R1–R24)
Full operator actions: **[RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md)** and **[OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md)**.
| # | Action |
|---|--------|
| R1–R3 | Verify contracts on Blockscout; keep CONTRACT_ADDRESSES_REFERENCE and ADDRESS_MATRIX_AND_STATUS updated; run check-contracts-on-chain-138.sh |
| R4–R7 | Use 0x971c... CCIPWETH9Bridge only; no .env/keys in repo; restrict deployer/RPC access |
| R8–R11 | RPC_URL_138; GAS_PRICE on 138; phased deploy; nonce/tx stuck runbooks |
| R12–R16 | Keep runbooks in sync; document addresses per chain; run verification after deploy; env per env |
| R17–R20 | Monitor bridges; Blockscout up; forge test pre-deploy; NatSpec |
| R21–R24 | The Order NPMplus; blocks #2–#6; script progress/dry-run/validation; token-mapping.json source of truth |
---
## Where to read more
- **Full list (all priorities):** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md)
- **Operator-only checklist:** [ALL_RECOMMENDATIONS_OPERATOR_ONLY.md](ALL_RECOMMENDATIONS_OPERATOR_ONLY.md)
- **Implementation checkboxes:** [10-best-practices/IMPLEMENTATION_CHECKLIST.md](../10-best-practices/IMPLEMENTATION_CHECKLIST.md)

140
docs/00-meta/ALL_RECOMMENDATIONS_OPERATOR_ONLY.md Normal file
View File

@@ -0,0 +1,140 @@
# All Recommendations — Operator-Only Checklist
**Purpose:** Single checklist for all recommendations that require **LAN/Proxmox access**, **operator credentials**, **external services**, or **ongoing maintenance**. Use when you have operator or LAN access.
**Sources:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (items 1–11, 75–81, 98–99, 106–121, 135–139, R1–R24), [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md), [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md).
---
## 1. Proxmox / security (LAN or host access)
| # | Action | Command or notes |
|---|--------|------------------|
| 1 | Secure .env permissions | `chmod 600 .env` (and subproject .env files) |
| 2 | Secure validator key permissions | On host: `chmod 600` keys, `chown -R besu:besu` validator dirs |
| 3 | SSH key-only auth | On Proxmox/containers: `PasswordAuthentication no`, `PubkeyAuthentication yes` in sshd_config |
| 4 | Firewall for Proxmox API (8006) | Restrict to specific IPs (iptables or UDM Pro rules) |
| 5 | Network segmentation (VLANs) | Per NETWORK_ARCHITECTURE; switches, Proxmox bridges, ER605 |
| 6 | Metrics (Prometheus, Besu 9545) | Deploy Prometheus scrape; enable Besu metrics port |
| 7 | Health check + alerting | Configure Alertmanager / PagerDuty / Slack per MASTER_SECRETS |
| 8 | Automated backup + encrypted validator keys | Run backup script; store encrypted copies off-host |
| 9 | Backup configs + version control | Commit configs to repo or backup store from LAN |
---
## 2. Deployment and runbooks (operator)
| # | Action | When |
|---|--------|------|
| **Priority** | **Mainnet liquidity + ramps** | [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md), [MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md) |
| 10 | Integration tests for deployment scripts | Run from LAN against staging/dev |
| 11 | Runbooks: add/remove validator, upgrade Besu, key rotation, recovery, consensus | Document and run from LAN when needed |
| 12–20 | Error handling, logging, Loki, resource/network/DB tuning, CI/CD, CLI tool | Implement on infra from operator environment |
---
## 3. Contracts and verification (R1–R3, R8–R9, R14)
| # | Action | Command |
|---|--------|--------|
| R1 | Verify every deployed contract on Blockscout | After each deploy when Blockscout reachable |
| R2 | Keep CONTRACT_ADDRESSES_REFERENCE and ADDRESS_MATRIX_AND_STATUS updated | When new contracts deployed or deprecated |
| R3 | Run on-chain check | `./scripts/verify/check-contracts-on-chain-138.sh` (set RPC_URL_138 from LAN) |
| R8 | Set RPC_URL_138; run from LAN if 192.168.11.x not reachable | Before any deploy |
| R9 | Use GAS_PRICE=1000000000 (or current min) on Chain 138 | Every forge script on 138 |
| R14 | Run verification after deploy in CI | When Blockscout reachable from runner |
---
## 4. Security and secrets (R4–R7, 48–52)
| # | Action | Notes |
|---|--------|-------|
| 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 |
| 48–52 | Secret audit, input validation, security scanning, RBAC, config validation | git-secrets, gitleaks, bandit, trivy as applicable |
---
## 5. Documentation and runbooks (R12–R13, R15–R16)
| # | Action | When |
|---|--------|------|
| 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 |
| 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 |
---
## 6. Monitoring and operations (R17–R18, 135–139)
| # | Task | Frequency |
|---|------|-----------|
| R17 | Monitor critical bridge/oracle events | Ongoing |
| R18 | Ensure Blockscout (VMID 5000) up and /api reachable | Health checks |
| 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 |
---
## 7. Testing and quality (R19–R20)
| # | Action | When |
|---|--------|------|
| R19 | Run forge test before deploying; integration tests where available | Pre-deploy |
| R20 | NatSpec on public contract functions | Code quality |
---
## 8. Configuration and DNS (R21–R22, infrastructure 75–81)
| # | Action | When |
|---|--------|------|
| R21 | The Order / Sankofa NPMplus proxy host | When The Order portal deployed: add proxy; document in RPC_ENDPOINTS_MASTER, ALL_VMIDS_ENDPOINTS |
| R22 | Document or configure blocks #2–#6 in NETWORK_ARCHITECTURE | When decided |
| Sankofa cutover | Replace <TARGET_IP>, <TARGET_PORT>, TBDs in SANKOFA_CUTOVER_PLAN | When deployed |
| 75–81 | VLAN enablement, observability stack, CCIP fleet, sovereign tenants, missing containers | Per NEXT_STEPS_MASTER and deployment phases |
---
## 9. Quick wins and token mapping (R23–R24)
| # | Action | When |
|---|--------|------|
| 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 |
---
## 10. External services and submissions
| # | Action | Where |
|---|--------|-------|
| 98 | CoinGecko submission (Chain 138) | [CoinGecko](https://www.coingecko.com/) |
| 99 | Consensys outreach (Swaps/Bridge support) | MetaMask/Consensys channels |
| 106–108 | Verify Etherlink/Jumper/LiFi for chains 138, 651940, 42793 | External APIs / docs |
| 109–121 | Tezos/Etherlink contracts and relay services | Deploy and run from operator env |
---
## 11. Optional tools (install for full automation)
- **shellcheck** — `apt install shellcheck` or `brew install shellcheck`
- **wscat** — `npm i -g wscat` or `npx -y wscat` for WebSocket RPC tests
- **sqlite3, websocat, sshpass, dig, parallel** — per verification evidence NEXT_STEPS_RUN_*.md
---
## Where to read more
- **Full recommendations list:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md)
- **High-priority only:** [ALL_RECOMMENDATIONS_HIGH_PRIORITY.md](ALL_RECOMMENDATIONS_HIGH_PRIORITY.md)
- **Operator runbook (copy-paste):** [NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md)
- **Operator ready checklist:** [OPERATOR_READY_CHECKLIST.md](../04-configuration/OPERATOR_READY_CHECKLIST.md)
- **Detailed operator/external:** [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md)

8
docs/00-meta/ARCHIVE_CANDIDATES.md
View File

@@ -1,7 +1,7 @@
# Documentation Archive Candidates
**Last Updated:** 2026-02-08
**Last reviewed:** 2026-02-20
**Last Updated:** 2026-03-02
**Last reviewed:** 2026-03-02
**Purpose:** List of docs/folders that may be archived to reduce clutter. Review before moving.
**Use:** Run in full parallel with other Wave 1 doc tasks. See [FULL_PARALLEL_EXECUTION_ORDER.md](FULL_PARALLEL_EXECUTION_ORDER.md).
@@ -44,3 +44,7 @@
**2026-02-16:** **Batch 3:** 3 Blitzkrieg dated exports (Blitzkrieg_Super_Pro_Max_Plan_2026-02-13.md, .txt, .json) → `archive/00-meta-pruned/`. Canonical plan remains `00-meta/BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md`. **Note:** `DOCUMENTATION_FIXES_COMPLETE.md` does not exist; completed fixes are in [DOCUMENTATION_FIX_TASK_LIST.md](DOCUMENTATION_FIX_TASK_LIST.md).
**2026-02-20:** **Batch 4:** 12 one-off/dated docs from 00-meta → `archive/00-meta-pruned/`: COMPLETION_STATUS_20260215, MASTER_DOCUMENTATION_REVIEW_20260205, DOCUMENTATION_REVIEW_20260216, DOCUMENTATION_REVIEW_CONTINUED_20260216, COMPREHENSIVE_DOCUMENTATION_REVIEW_2026-01-31, DOCUMENTATION_UPGRADE_SUMMARY, DOCUMENTATION_REVIEW, DOCUMENTATION_METRICS, DOCUMENTATION_RELATIONSHIP_MAP (duplicate of DOCUMENT_RELATIONSHIP_MAP), JNA_WHY_NOT_WORKING_REVIEW, VMID_2101_CHANGES_AND_FAILURES, COMPREHENSIVE_PROJECT_REVIEW. **Batch 5:** CONTINUE_AND_COMPLETE, FULL_PARALLEL_RUN_LOG → 00-meta-pruned. **Root cleanup:** ALL_TASKS_COMPLETE → archive/root-status-reports; 40+ root status/temp files + screenshots → [archive/root-cleanup-20260220/](../archive/root-cleanup-20260220/README.md). fix-wsl-ip.sh → scripts/. **Added:** DOCUMENTATION_CONSOLIDATION_PLAN, NEXT_STEPS_INDEX. See archive/00-meta-pruned/README.md Batches 4–5.
**2026-03-02:** Review only. docs/MASTER_INDEX.md and docs/README.md created; RUNBOOKS_MASTER_INDEX.md added (redirect). Deprecated list in MASTER_INDEX. ALL_IMPROVEMENTS_AND_GAPS_INDEX remains as redirect; canonical = ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.
**2026-03-02:** **Review only.** No new files archived. docs/MASTER_INDEX.md and docs/README.md created; docs/RUNBOOKS_MASTER_INDEX.md added (redirect to OPERATIONAL_RUNBOOKS). Deprecated/superseded list documented in MASTER_INDEX § Deprecated. ALL_IMPROVEMENTS_AND_GAPS_INDEX remains in place as redirect stub; canonical list is 00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md.

53
docs/00-meta/BLITZKRIEG_SOURCE_DOCUMENT_INDEX.md
View File

@@ -1,53 +0,0 @@
# Blitzkrieg — Source Document Index (Where to Update When Completed)
**Purpose:** When you complete a task or close a gap from the [BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN](BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md) or the Blitzkrieg Execution Plan, update the corresponding source doc below so the repo stays in sync. This file is the single checklist for "where to update when completed."
**Related:** [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) | [PLACEHOLDERS_AND_COMPLETION_MASTER_LIST](PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md) | [MASTER_PLAN](MASTER_PLAN.md) §8
---
## Index: Document → Path → When to update
| Document | Path | When to update |
|----------|------|-----------------|
| REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS | [docs/00-meta/REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) | Mark tasks/recommendations done; Part 1–4 |
| NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS | [docs/00-meta/NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS.md](NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS.md) | Mark section steps done |
| GAPS_AND_RECOMMENDATIONS_CONSOLIDATED | [docs/GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md) | Close security/config/code gaps |
| PLACEHOLDERS_AND_COMPLETION_MASTER_LIST | [docs/00-meta/PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md](PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md) | Mark placeholder completed; §13 "Where to update" |
| CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE | [docs/11-references/CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE.md](../11-references/CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE.md) | Operator/pending status |
| TEZOS_CCIP_REMAINING_ITEMS | [docs/07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md](../07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md) | External/contracts/off-chain/routing/DON/monitoring/testing |
| REQUIRED_FIXES_UPDATES_GAPS | [docs/REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) | Build/canonical/placeholders/docs/tests |
| ALL_REQUIREMENTS | [docs/00-meta/ALL_REQUIREMENTS.md](ALL_REQUIREMENTS.md) | Foundation, security, deployment blocks |
| CONTRACT_ADDRESSES_REFERENCE | [docs/11-references/CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) | New/deprecated addresses; canonical source |
| CONTRACT_INVENTORY_AND_VERIFICATION | [docs/11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md](../11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md) | Deployed/verified status |
| BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN | [docs/00-meta/BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md](BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md) | §2 three-column table; §3 numbered trail; §5 phase/category |
| MASTER_PLAN / MASTER_INDEX | [docs/00-meta/MASTER_PLAN.md](MASTER_PLAN.md), [docs/MASTER_INDEX.md](../MASTER_INDEX.md) | Link to Blitzkrieg; §8 file summary |
| STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS | [docs/00-meta/STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md](STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md) | When LAN/Proxmox steps change |
| OPERATOR_OPTIONAL_CHECKLIST | [docs/11-references/OPERATOR_OPTIONAL_CHECKLIST.md](../11-references/OPERATOR_OPTIONAL_CHECKLIST.md) | Blockscout, trustless, mainnet, CREATE2, Vault, Dodo, etc. |
| PLACEHOLDERS_AND_TBD | [docs/00-meta/PLACEHOLDERS_AND_TBD.md](../PLACEHOLDERS_AND_TBD.md) | AlltraAdapter fee; other TBDs |
| TOKEN_MAPPING_AND_MAINNET_ADDRESSES | [docs/07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md) | Token mapping (138↔Mainnet); relay-supported tokens; when adding tokens update this and config/token-mapping.json |
| REMAINING_WORK_BREAKDOWN_AND_ANSWERS | [docs/00-meta/REMAINING_WORK_BREAKDOWN_AND_ANSWERS.md](REMAINING_WORK_BREAKDOWN_AND_ANSWERS.md) | Per-item breakdown: prerequisites, owner, steps to complete, where to update; add "Done [date]" when item completed |
| token-mapping.json | [config/token-mapping.json](../../config/token-mapping.json) | Single source of truth for Chain 138↔Mainnet token addresses; add/update entries when adding tokens or enabling relay for LINK |
---
## Key operator commands (Blitzkrieg steps)
| Step | Action | Command |
|------|--------|---------|
| 0 | Config validation | `./scripts/validation/validate-config-files.sh` |
| 0 / 16 | Completable from anywhere (all 4 steps) | `./scripts/run-completable-tasks-from-anywhere.sh` [`--dry-run`] |
| 11 | On-chain check (Chain 138, 36 addresses) | `./scripts/verify/check-contracts-on-chain-138.sh` (uses `RPC_URL_138`; optional arg overrides) |
| 11 | Blockscout source verification | `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh` |
Full command list: [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) Part 3.
---
## Quick reference
- **Tasks 1–30 / R1–R24:** Update [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md).
- **Code placeholders (AlltraAdapter, Smart accounts, TezosRelay, etc.):** Update [NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS](NOT_CHANGED_BY_DESIGN_ACTIONABLE_STEPS.md) and [PLACEHOLDERS_AND_COMPLETION_MASTER_LIST](PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md).
- **New contract / address:** Update [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) and [CONTRACT_INVENTORY_AND_VERIFICATION](../11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md).
- **New token or bridge in the march:** Update [BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN](BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md) §2 (three-column table) and §3 (numbered trail).
- **New token (Chain 138 or bridged):** Update [config/token-mapping.json](../../config/token-mapping.json) and optionally [TOKEN_MAPPING_AND_MAINNET_ADDRESSES](../07-ccip/TOKEN_MAPPING_AND_MAINNET_ADDRESSES.md), [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md).

72
docs/00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md Normal file
View File

@@ -0,0 +1,72 @@
# Complete Required, Optional, and Recommended — Index
**Purpose:** Single entry point for the full execution plan (required, optional, and recommended work). Execution order: Wave 0 → Wave 1 → Wave 2 → Wave 3 → Ongoing.
**Sources:** [PHASES_AND_TASKS_MASTER.md](PHASES_AND_TASKS_MASTER.md), [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md), [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md), [FULL_PARALLEL_EXECUTION_ORDER.md](FULL_PARALLEL_EXECUTION_ORDER.md).
---
## Wave 0 — Gates (do first when creds allow)
| Task | Blocker | Command / doc |
|------|---------|----------------|
| W0-1 NPMplus RPC fix (405) | Host on LAN (192.168.11.x) | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W0-1. `bash scripts/run-wave0-from-lan.sh` or `bash scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh`. |
| W0-2 sendCrossChain (real) | PRIVATE_KEY, LINK approved | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W0-2. `bash scripts/bridge/run-send-cross-chain.sh <amount> [recipient]`. Bridge: `0x971cD9D156f193df8051E48043C476e53ECd4693`. |
| W0-3 NPMplus backup | NPM_PASSWORD in .env | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W0-3. `bash scripts/verify/backup-npmplus.sh` or `scripts/run-wave0-from-lan.sh`. |
---
## Required work
- **Deployment phases:** [PHASES_AND_TASKS_MASTER.md](PHASES_AND_TASKS_MASTER.md) — Phase 2 (observability), Phase 3 (CCIP fleet), Phase 4 (sovereign tenants). Runbooks: [OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md).
- **Codebase:** smom audits (VLT-024, ISO-024), bridge integrations (BRG-VLT, BRG-ISO); dbis_core IRU + [DBIS_CORE_TS_FIXES_DETAILED_LIST.md](DBIS_CORE_TS_FIXES_DETAILED_LIST.md); OMNIS per PHASES_AND_TASKS_MASTER.
- **Security & verification:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md) R1–R24; [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W1-1, W1-2.
---
## Optional work
- **Infrastructure:** Phase 1 VLAN, NPMplus HA. (2506–2508 destroyed 2026-02-08; RPC 2500–2505 only.) [OPTIONAL_RECOMMENDATIONS_INDEX.md](../OPTIONAL_RECOMMENDATIONS_INDEX.md), [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md), [NPMPLUS_HA_SETUP_GUIDE.md](../04-configuration/NPMPLUS_HA_SETUP_GUIDE.md).
- **Docs/tooling:** Documentation consolidation; Paymaster deploy when ready.
- **MetaMask/explorer:** Token-aggregation, CoinGecko, Snap features, explorer enhancements. [COINGECKO_SUBMISSION.md](../../smom-dbis-138/services/token-aggregation/docs/COINGECKO_SUBMISSION.md).
---
## Recommended work (139+ items)
- **Full list:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (20 sections).
- **High priority only:** [ALL_RECOMMENDATIONS_HIGH_PRIORITY.md](ALL_RECOMMENDATIONS_HIGH_PRIORITY.md).
- **Operator-only (LAN/creds/external):** [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md).
- **Parallel order:** [FULL_PARALLEL_EXECUTION_ORDER.md](FULL_PARALLEL_EXECUTION_ORDER.md).
---
## Execution order summary
1. **Wave 0:** W0-1, W0-2, W0-3 when LAN/creds available.
2. **Wave 1 (parallel):** [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) "Can Be Accomplished Now"; validation: `bash scripts/verify/run-all-validation.sh [--skip-genesis]`, `scripts/validation/validate-config-files.sh`.
3. **Wave 2 / Wave 3:** [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md).
4. **Ongoing:** Maintenance 135–139; `schedule-daily-weekly-cron.sh --install`.
---
## Fixes status (in-repo)
All required fixes in [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) §§1–6 are **Done** or **Documented**. Placeholders (canonical addresses, AlltraAdapter, smart accounts, quote FABRIC_CHAIN_ID, .bak) are complete per that doc. Remaining work: operator/LAN tasks, deferred dbis_core TS (~1186), and external (audits, Ledger, CoinGecko).
**Still not done — execution checklist:** [STILL_NOT_DONE_EXECUTION_CHECKLIST.md](STILL_NOT_DONE_EXECUTION_CHECKLIST.md) — copy-paste commands and links for every operator/LAN, dbis_core TS, security-audit, external, and maintenance item.
---
## Key references
| Purpose | Document |
|---------|----------|
| Step-by-step for every task | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) |
| Copy-paste operator runbook | [NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md) |
| Master task list | [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) |
| Required fixes (all Done/Documented) | [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) |
| Still not done (operator/external/TS) | [STILL_NOT_DONE_EXECUTION_CHECKLIST.md](STILL_NOT_DONE_EXECUTION_CHECKLIST.md) |
| Breakdown: missing info per task | [REMAINING_TASKS_BREAKDOWN_MISSING_INFO.md](REMAINING_TASKS_BREAKDOWN_MISSING_INFO.md) |
| dbis_core TS fixes (deferred) | [DBIS_CORE_TS_FIXES_DETAILED_LIST.md](DBIS_CORE_TS_FIXES_DETAILED_LIST.md) |
| DBIS Rail + project completion (status and full task list, required + optional) | [DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md](../dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md) |

118
docs/00-meta/CW_BRIDGE_TASK_LIST.md Normal file
View File

@@ -0,0 +1,118 @@
# cW* Bridge Support — Detailed Task List
**Created:** 2026-02-27
**Updated:** 2026-02-27 — In-repo tasks completed (Phase A, C1, F); operator tasks (D, E, C2–C3) have runbook.
**Context:** After setting `CW_BRIDGE_<CHAIN>` from the deployed bridge suite (CCIPRelayBridge on Mainnet, CCIPWETH9_BRIDGE_* on other chains), this document reviews the note that those contracts may need extension for cW* and turns it into a concrete task list.
**Completion summary (in-repo):** Phase A (approach decided and documented), Phase C1 (CompliantWrappedToken.burnFrom added, tests added), Phase F (docs and runbook). Phase B marked N/A (Option 2 chosen). **Remaining steps script:** [run-cw-remaining-steps.sh](../../scripts/deployment/run-cw-remaining-steps.sh) — `--dry-run` (default), `--deploy`, `--update-mapping`, `--verify`. Phase D/E and C2–C3: run script with `--deploy` when RPC/keys are set; then set CWUSDT_*/CWUSDC_* in .env and run `--update-mapping`; see [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md).
---
## 1. Note reviewed
**Note (from previous setup):**
*"Mainnet uses CCIPRelayBridge; other chains use CCIPWETH9_BRIDGE_*. Those contracts are currently WETH-oriented; if they do not yet implement cW* mint/burn, they will need to be extended (or replaced with a cW*-capable receiver) before cW* transfers work."*
**Verification (checks performed):**
| Check | Result |
|-------|--------|
| **CCIPRelayBridge.sol** (Mainnet) | `ccipReceive` only accepts `message.tokenAmounts[0].token == weth9` and does `IERC20(weth9).transfer(recipient, amount)`. **Does not call any cW*.mint().** |
| **CCIPWETH9Bridge.sol** (all chains) | Same: validates token == weth9, then `transfer(recipient, amount)`. **Does not mint cW*.** |
| **CCIPWETH10Bridge.sol** | Same for WETH10; no cW* logic. |
| **CompliantWrappedToken.sol** | Has `mint`, `burn`, and `burnFrom` (BURNER_ROLE). `burnFrom` added in Phase C1 for TwoWayTokenBridgeL2 outbound. |
| **TwoWayTokenBridgeL2.sol** | `ccipReceive` calls `IMintableERC20(mirroredToken).mint(recipient, amount)` — **would mint cW*** if `mirroredToken` = cWUSDT/cWUSDC. Outbound uses `burnFrom`; CompliantWrappedToken does not implement `burnFrom`. |
| **DeployCWTokens.s.sol** | Grants MINTER_ROLE and BURNER_ROLE to `CW_BRIDGE_ADDRESS` (per-chain in .env). So the *address* we set will have roles, but the *contract code* at that address (CCIPWETH9Bridge/CCIPRelayBridge) never calls `mint`/`burn` on cW*. |
**Conclusion:** The current bridge suite is **WETH-only**. Granting MINTER/BURNER to it allows deployment of cW* but **does not** enable cross-chain mint/burn of cW* until the receiver logic is extended or a dedicated cW* receiver is deployed.
---
## 2. Checks performed (summary)
- [x] **Contract audit:** CCIPRelayBridge, CCIPWETH9Bridge, CCIPWETH10Bridge — ccipReceive only transfers the received token (WETH9/WETH10), no mint path.
- [x] **CompliantWrappedToken:** mint/burn roles and interface; no burnFrom.
- [x] **TwoWayTokenBridgeL2:** Mint-on-receive pattern; requires burnFrom for outbound.
- [x] **.env:** CW_BRIDGE_<CHAIN> set from existing deployed addresses (Mainnet, Cronos, BSC, Polygon, Gnosis, Avalanche, Base, Arbitrum, Optimism).
- [x] **Deploy path:** DeployCWTokens grants roles to CW_BRIDGE_*; deploy script uses per-chain bridge from .env.
---
## 3. Detailed task list
### Phase A: Decide and document approach
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| A1 | **Decide cW* receive strategy:** (1) Extend existing CCIPWETH9Bridge/CCIPRelayBridge to support cW* mint in ccipReceive, or (2) Deploy dedicated cW* receiver per chain (e.g. TwoWayTokenBridgeL2 or new CCIPReceiverCW). | Operator/Dev | Option 2 chosen. | ✅ Done |
| A2 | **Document chosen approach** in `docs/07-ccip/CW_BRIDGE_APPROACH.md` (create): flow 138→chain (lock c* on 138, mint cW* on dest), chain→138 (burn cW*, release c*), and which contract(s) implement receive/send. | Dev | | ✅ Done |
### Phase B: Contract changes (if extending existing bridge)
**Not applied** — Option 2 (dedicated receiver) chosen; Phase B is the alternative path if extending existing bridges instead.
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| B1 | **Design bridge extension:** In CCIPWETH9Bridge (and/or CCIPRelayBridge), allow ccipReceive to accept more than WETH9: e.g. token whitelist (cWUSDT, cWUSDC) and on receive either transfer (if token is WETH9) or mint (if token is cW* and bridge has MINTER_ROLE). | Dev | Match data encoding (recipient, amount, sender, nonce) with existing. | N/A (Option 2) |
| B2 | **Implement and test:** Add tests for ccipReceive with token = cWUSDT and assert cWUSDT.mint(recipient, amount) and balance increase. | Dev | | N/A (Option 2) |
| B3 | **Deploy upgraded bridge** (or new implementation + upgrade if proxy) on each chain; update .env and config if address changes. | Operator | If new contract, set CW_BRIDGE_<CHAIN> to new address and re-grant MINTER/BURNER on cW* to new bridge. | N/A (Option 2) |
### Phase C: Contract changes (if dedicated cW* receiver)
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| C1 | **CompliantWrappedToken:** Add `burnFrom(address from, uint256 amount)` that checks BURNER_ROLE and calls `burn(from, amount)` (or implement ERC20Burnable and grant BURNER to bridge). | Dev | Required if using TwoWayTokenBridgeL2 for outbound. | ✅ Done |
| C2 | **Deploy TwoWayTokenBridgeL2** (or new CCIPReceiverCW) per chain: constructor(router, cWUSDT, feeToken). Configure destination (Chain 138 selector, L1 bridge address). | Operator | TwoWayTokenBridgeL2 is not upgradeable; one deployment per (chain, token) or generic with token in message. See [CW_DEPLOY_AND_WIRE_RUNBOOK.md](CW_DEPLOY_AND_WIRE_RUNBOOK.md). | Pending |
| C3 | **Point CW_BRIDGE_<CHAIN> to new receiver** and re-run DeployCWTokens so MINTER/BURNER are on the new receiver, or grant roles to new receiver after deploy. | Operator | If receiver is separate from CCIPWETH9_BRIDGE, set CW_BRIDGE_<CHAIN> to receiver address. | Pending |
| C4 | **Chain 138 send side:** Ensure a sender/bridge on 138 sends CCIP messages with receiver = new cW* receiver on destination and data encoding (recipient, amount). | Dev/Operator | Documented in [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md). | ✅ Documented |
### Phase D: Deploy cW* and wire config
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| D1 | **Run cW* deploy** on each target chain: `./scripts/deployment/deploy-tokens-and-weth-all-chains-skip-canonical.sh --deploy-cw` (with CW_BRIDGE_<CHAIN> already set). | Operator | Records CWUSDT_<CHAIN>, CWUSDC_<CHAIN> in script output. Runbook: [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md) § D1. | Operator |
| D2 | **Set CWUSDT_<CHAIN> and CWUSDC_<CHAIN>** in smom-dbis-138/.env from deploy output for each chain. | Operator | Runbook § D2. | Operator |
| D3 | **Update token-mapping-multichain.json** for each chain: set `addressTo` for Compliant_USDT_cW, Compliant_USDC_cW (and Compliant_EURC_cW if deployed) from CWUSDT_*/CWUSDC_* addresses. | Operator | Replace 0x0 placeholders. Runbook § D3. | Operator |
| D4 | **Verify on-chain:** On each chain, confirm cWUSDT/cWUSDC exist, and bridge/receiver address has MINTER_ROLE and BURNER_ROLE. | Operator | Runbook § D4. | Operator |
### Phase E: Relay and send path (138 → other chains)
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| E1 | **Relay service (138→Mainnet):** If using CCIPRelayBridge for cW*, extend relay to support cUSDT/cUSDC: relay must send CCIP with token = cUSDT (or lock-and-mint semantics) and destination = Mainnet bridge; Mainnet bridge must mint cWUSDT. | Operator/Dev | See RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md pattern (extend bridge or new receiver). Runbook § E1. | Operator |
| E2 | **Direct CCIP (138→chain):** If Chain 138 uses UniversalCCIPBridge or CCIPWETH9Bridge to send c* to destination, add destination config for c* and ensure receiver on destination mints cW*. | Dev | Documented in approach; runbook § E2. | Documented |
| E3 | **Test E2E:** Lock cUSDT on 138, trigger send, verify cWUSDT minted on destination to recipient. | Operator | Runbook § E3. | Operator |
### Phase F: Documentation and runbooks
| # | Task | Owner | Notes | Status |
|---|------|--------|-------|--------|
| F1 | **Update docs/11-references/CW_TOKENS_AND_NETWORKS.md:** Add section "Bridge support status" — which chains have bridge code that mints cW* (none until Phase B or C done). | Dev | | ✅ Done |
| F2 | **Update docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md:** Note that addressTo for _cW is 0x0 until cW* deployed and that bridge must support mint. | Dev | | ✅ Done |
| F3 | **Create runbook** (e.g. docs/07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md): steps to deploy cW* on a new chain, set CW_BRIDGE_<CHAIN>, update token-mapping, verify roles. | Dev | | ✅ Done |
---
## 4. Dependency order
1. **A1 → A2** (decide approach, document).
2. **A1 → B or C** (implementation depends on choice).
3. **B or C → D1** (deploy cW* after bridge/receiver can mint; or deploy cW* and grant roles to existing bridge, then extend bridge later so it actually mints).
4. **D1 → D2, D3, D4** (config and verify).
5. **D + (B or C) → E** (send path and relay).
6. **F** can be done in parallel or after each phase.
**Minimal path to “cW* deployed and roles set” (no cross-chain mint yet):** D1, D2, D4 — already possible with current .env. To **actually mint cW* on receive**, complete Phase A, then B or C, then E.
---
## 5. References
- [CW_TOKENS_AND_NETWORKS.md](../11-references/CW_TOKENS_AND_NETWORKS.md)
- [C_TO_CW_MAPPER_MAPPING.md](../04-configuration/C_TO_CW_MAPPER_MAPPING.md)
- [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md) — Chosen approach (Option 2) and flows.
- [CW_DEPLOY_AND_WIRE_RUNBOOK.md](../07-ccip/CW_DEPLOY_AND_WIRE_RUNBOOK.md) — Operator steps for D1–D4, E1–E3.
- [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) (pattern for extending bridge)
- `smom-dbis-138/contracts/relay/CCIPRelayBridge.sol`, `contracts/ccip/CCIPWETH9Bridge.sol`
- `smom-dbis-138/contracts/bridge/TwoWayTokenBridgeL2.sol`
- `smom-dbis-138/contracts/tokens/CompliantWrappedToken.sol` (includes `burnFrom` for TwoWayTokenBridgeL2)

184
docs/00-meta/DBIS_CORE_TS_FIXES_DETAILED_LIST.md Normal file
View File

@@ -0,0 +1,184 @@
# dbis_core ~1186 TypeScript Errors (Deferred) — Detailed Fix List
**Status:** Deferred (W1-14)
**References:** [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) §8, [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) W1-14, [dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md](../../dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md), [dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md](../../dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md)
**Context:** Phases 1–4 were executed (2026-01-31); ~1186 TS errors remain. Remaining errors are in **defi**, **exchange**, **governance/msgf**, **gateway**, and other modules.
---
## 1. Prerequisites (Do First)
| # | Fix | Action |
|---|-----|--------|
| 1.1 | **Prisma client** | In `dbis_core/`: run `npx prisma generate` (or `pnpm exec prisma generate`) to fix `@prisma/client` types. If you see `MODULE_NOT_FOUND` for prisma, run `pnpm install` from repo root (or `cd dbis_core && pnpm install`) so Prisma is available, then retry. |
| 1.2 | **Verification** | After any batch of fixes, run `pnpm exec tsc --noEmit` (or `npx tsc --noEmit`) in `dbis_core/` to confirm error count. |
| 1.3 | **Sample reference** | A sample fix was applied in `dbis_core/src/core/admin/dbis-admin/dashboards/cbdc-fx.service.ts`; use as pattern for Prisma/Decimal and explicit return types. |
---
## 2. Priority 1 — Quick Wins (Est. ~50–70 errors)
### 2.1 Missing Imports (~10–15 errors)
- **Pattern:** Add missing imports.
- **Imports to add where used:**
- `import { v4 as uuidv4 } from 'uuid'`
- `import { Decimal } from '@prisma/client/runtime/library'` (or project’s Decimal source)
- `import { Prisma } from '@prisma/client'`
- **Example files:**
`mrecp-harmonization.service.ts`, `multiverse-fx.service.ts`, `multiverse-ssu.service.ts`, and any file using `uuidv4`/`Decimal`/`Prisma` without import.
### 2.2 Missing Return Statements in Routes (~30–40 errors)
- **Pattern:** Add `return` before `res.json()`, `res.status().json()`, and `next(error)` in Express route handlers.
- **Example files:**
`dbis-admin.routes.ts`, `scb-admin.routes.ts`, `beie.routes.ts`, `gase.routes.ts`, `rssck.routes.ts`, and all other `*.routes.ts`.
### 2.3 Simple Type Assertions (~10–15 errors)
- **Pattern:** Use `as unknown as TargetType` when TS rejects direct cast (e.g. `request as Record<string, unknown>` → `request as unknown as Record<string, unknown>`).
---
## 3. Priority 2 — Pattern-Based Fixes (Est. ~200–250 errors)
### 3.1 JsonValue Type Mismatches (~100–120 errors)
- **Pattern:** Cast to `Prisma.InputJsonValue` when assigning to Prisma `Json` fields.
- `Record<string, unknown>` → `as Prisma.InputJsonValue`
- Nullable: `value ? (value as Prisma.InputJsonValue) : Prisma.JsonNull`
- `JsonValue` → `as Prisma.InputJsonValue`
- **High-impact files:**
`uhem-encoding.service.ts`, `defi-module.service.ts`, `gdsl-clearing.service.ts`, `gsds-contract.service.ts`, `msgf-*.service.ts` (governance/msgf), and ~40–50 other files.
### 3.2 Property Access on Unknown Types (~80–100 errors)
- **Pattern:** Add type assertions or type guards: e.g. `(data as Record<string, unknown>).property` or specific interfaces.
- **High-impact files:**
`reporting-engine.service.ts`, `sandbox.service.ts`, `supervision-engine.service.ts`, and ~30–40 other files.
### 3.3 Type Conversion via Unknown (~50–70 errors)
- **Pattern:** Use `as unknown as TargetType` for conversions TS rejects.
- **Example files:**
`corridor-controls.service.ts`, `gru-controls.service.ts`, `network-controls.service.ts`, `dscn-aml-scanner.service.ts`, `rssck.service.ts`, and ~20–30 other files.
---
## 4. Priority 3 — Type System Fixes (Est. ~150–200 errors)
### 4.1 Missing Properties on Prisma Types (~60–80 errors)
- **Pattern:** Use correct Prisma schema field names and/or add `include` for relations; use type assertions only when schema is correct but types are narrow.
- **Common issues:**
- Use `indexValue` not `price` on index history; include relations for `bondName`/`bondCode`; verify `circuitBreakerEnabled` and filterable fields (e.g. `createdAt`).
- **High-impact files:**
`global-overview.service.ts`, `gru-command.service.ts`, `cbdc-fx.service.ts`, `supervisory-ai.service.ts`, and ~25–35 other files.
### 4.2 Prisma UpdateMany Property Errors (~10–15 errors)
- **Pattern:** Use correct Prisma update input types; use `update` instead of `updateMany` if the field is not in `*UpdateManyMutationInput`.
- **Known issues:**
- `circuitBreakerEnabled` not in `GruIndexUpdateManyMutationInput`; `issuanceWindowOpen` not in `GruBondUpdateManyMutationInput`.
- **Files:**
`gru-controls.service.ts` and ~3–5 other files.
### 4.3 Request Type Extensions (~20–30 errors)
- **Pattern:** Extend Express `Request` (e.g. in `src/types/express.d.ts`) with `sovereignBankId?: string`, or use `(req as { sovereignBankId?: string }).sovereignBankId`.
- **Files:**
`dbis-admin.routes.ts`, `scb-admin.routes.ts`, and ~10–15 other route files.
### 4.4 Null Safety (~15–20 errors)
- **Pattern:** Add optional chaining (`?.`), null checks, or non-null assertion (`!`) where “possibly null” is reported.
- **Example files:**
`gru-command.service.ts`, `multiverse-fx.service.ts`, `uhem-analytics.service.ts`, and ~10–15 other files.
---
## 5. Priority 4 — Schema & Property Fixes (Est. ~100–150 errors)
### 5.1 Prisma Schema Mismatches (~30–40 errors)
- **Pattern:** Align code with `prisma/schema.prisma` model and field names; do not change schema unless a field is truly missing.
- **Known mappings:**
- `prisma.settlement` → `prisma.gasSettlement` (or correct model per schema);
- `prisma.commodityToken` — verify existence;
- `prisma.aiAutonomousAction` → `prisma.aIAutonomousAction` (or actual schema name);
- Missing fields: e.g. `divergenceAmount`, `realityId` — add to schema only if required.
- **Files:**
`legal-harmonization.service.ts`, `trade-harmonization.service.ts`, `scdc-ai-mandate.service.ts`, `mrecp-convergence.service.ts`, and ~15–20 other files.
### 5.2 Complex Type Assignments (~40–50 errors)
- **Pattern:** Fix array/object type mismatches (e.g. missing `id` or required fields), object spread types, and function parameter types.
- **Files:**
`global-overview.service.ts`, `gdsl-contract.service.ts`, `gsds-contract.service.ts`, `multiverse-fx.service.ts`, and ~20–25 other files.
### 5.3 Decimal Type Operations (~5–10 errors)
- **Pattern:** Use Decimal API: e.g. `decimal.plus(n)` instead of `decimal + n`, `decimal.toString()` for string conversion.
- **Files:**
`regulatory-equivalence.service.ts`, `zk-balance-proof.service.ts`, and ~3–5 other files.
---
## 6. Implicit `any` and Callbacks (Documented Strategy)
- **Source:** [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) W1-14.
- **Action:** Add explicit types for implicit `any` (e.g. callback parameters, event handlers). Tackle by module or file; can be parallelized by file.
---
## 7. Module-Level Focus (Where ~1186 Errors Remain)
After Phases 1–4, remaining errors are concentrated in:
| Module / Area | Notes |
|---------------|--------|
| **defi** | e.g. `defi-module.service.ts`, arbitrage, tezos-usdtz, sovereign. |
| **exchange** | Exchange adapters, registry, OTC, price adapters. |
| **governance/msgf** | `msgf-*.service.ts` and related governance services. |
| **gateway** | API gateway, admin-central, middleware. |
| **Other** | Compliance, derivatives (gdsl/gsds), economics (uhem, mrecp), admin dashboards, integration. |
**Strategy:** Fix by module (or by file within a module); run `tsc --noEmit` periodically. Prefer parallelizing by file when multiple people work on it.
---
## 8. Execution Order (Recommended)
1. **Prerequisites:** `npx prisma generate` in `dbis_core/`; confirm `tsc --noEmit` baseline.
2. **Priority 1:** Quick wins (imports, route returns, simple assertions).
3. **Priority 2:** Pattern fixes (JsonValue, unknown property access, conversion via `unknown`).
4. **Priority 3:** Type system (Prisma props, Request extension, null safety).
5. **Priority 4:** Schema alignment and complex types (including Decimal).
6. **Sweep:** Implicit `any` and callbacks by module/file.
---
## 9. Risk and Automation
- **Low risk (safe to automate):** Missing imports, missing returns, simple type assertions, JsonValue casts.
- **Medium risk (review):** Property access on unknown, type conversions, null safety.
- **High risk (manual review):** Prisma schema changes, complex type assignments, Request extensions.
---
## 10. References in This Repo
- **Fix plan (in dbis_core):**
[dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md](../../dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md)
[dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md](../../dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md)
- **Phase status:**
[reports/REMAINING_TASKS_MASTER_20260201.md](../../reports/REMAINING_TASKS_MASTER_20260201.md) (Phases 1–4 review).
- **Task tracking:**
[TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) W1-14, [ALL_TASKS_DETAILED_STEPS.md](ALL_TASKS_DETAILED_STEPS.md).
- **Express types:**
[dbis_core/src/types/express.d.ts](../../dbis_core/src/types/express.d.ts) (for Request extension).
---
*Last updated: 2026-02-23. Error count ~1186 is from post–Phase 1–4 state; re-run `tsc --noEmit` in dbis_core for current count.*

17
docs/00-meta/DOCUMENTATION_CONSOLIDATION_PLAN.md
View File

@@ -1,6 +1,6 @@
# Documentation Consolidation Plan
**Last Updated:** 2026-02-20
**Last Updated:** 2026-03-02
**Purpose:** Review, consolidate, and prune markdown docs. Single reference for what to keep, merge, or archive.
**Related:** [ARCHIVE_CANDIDATES.md](ARCHIVE_CANDIDATES.md) | [archive/00-meta-pruned/README.md](../archive/00-meta-pruned/README.md). (Dated review docs, e.g. DOCUMENTATION_REVIEW_20260216, are in archive/00-meta-pruned.)
@@ -134,13 +134,26 @@ Moved to `docs/archive/00-meta-pruned/` in 2026-02-20 batch:
---
## 5. Next steps for maintainers
## 5. Eliminating deprecated and inconsistent content
- **Single entry point:** [docs/MASTER_INDEX.md](../MASTER_INDEX.md) — use as the documentation index; it lists canonical sources and a "Deprecated / superseded" table.
- **Recommendations canonical:** [00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md). Do not use [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) as primary; it is superseded (stub/redirect only).
- **Contract/address status:** [11-references/ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md). CONTRACT_INVENTORY_AND_VERIFICATION and SMART_CONTRACTS_INVENTORY are deleted/superseded.
- **Runbooks:** [03-deployment/OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md) is the single runbook index. [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md) is a redirect stub for backward compatibility.
- When adding or updating docs, link to MASTER_INDEX and the canonical doc for that topic; avoid creating new "master" or "index" docs that duplicate existing ones.
---
## 6. Next steps for maintainers
1. Run link check quarterly (MASTER_INDEX, docs/README).
2. Each quarter: move clearly one-off/dated 00-meta docs to archive/00-meta-pruned per this plan.
3. Consider merging REMAINING_* and NEXT_STEPS_* into 2–3 canonical files (entry: NEXT_STEPS_INDEX.md).
4. Add "Last reviewed" to ARCHIVE_CANDIDATES after each consolidation run.
5. **Eliminate deprecated content:** Do not reference ALL_IMPROVEMENTS_AND_GAPS_INDEX, CONTRACT_INVENTORY_AND_VERIFICATION, or SMART_CONTRACTS_INVENTORY as primary sources; use MASTER_INDEX and the canonical docs it points to.
---
**Consolidation run 2026-02-20:** NEXT_STEPS_INDEX.md added; Batch 4 (12 files) archived to 00-meta-pruned; ARCHIVE_CANDIDATES and MASTER_INDEX updated. **Follow-up:** Batch 5 (CONTINUE_AND_COMPLETE, FULL_PARALLEL_RUN_LOG) → 00-meta-pruned; ALL_TASKS_COMPLETE → root-status-reports; project root cleanup → docs/archive/root-cleanup-20260220; fix-wsl-ip.sh → scripts/.
**Consolidation run 2026-03-02:** docs/MASTER_INDEX.md and docs/README.md created; docs/RUNBOOKS_MASTER_INDEX.md added (redirect stub); DOCUMENTATION_CONSOLIDATION_PLAN §5 (eliminating deprecated content) and §6 (maintainers) updated; ARCHIVE_CANDIDATES Last reviewed set to 2026-03-02.

4
docs/00-meta/FULL_PARALLEL_EXECUTION_ORDER.md
View File

@@ -3,7 +3,7 @@
**Last Updated:** 2026-02-05
**Purpose:** Order all remaining tasks into waves so that **within each wave, every item can run in parallel**. Run in full maximum parallel mode: execute all items in Wave 0 concurrently (where different owners), then all in Wave 1, then Wave 2, then Wave 3. No artificial sequencing within a wave.
**Sources:** [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [REMAINING_TASKS_NEXT_STEPS_PHASES_REVIEW.md](REMAINING_TASKS_NEXT_STEPS_PHASES_REVIEW.md), [PARALLEL_TASK_STRUCTURE.md](PARALLEL_TASK_STRUCTURE.md), [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md).
**Sources:** [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [REMAINING_TASKS_NEXT_STEPS_PHASES_REVIEW.md](REMAINING_TASKS_NEXT_STEPS_PHASES_REVIEW.md), [PARALLEL_TASK_STRUCTURE.md](PARALLEL_TASK_STRUCTURE.md), [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md). **Single plan (required/optional/recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
**Run log:** [FULL_PARALLEL_RUN_LOG.md](../archive/00-meta-pruned/FULL_PARALLEL_RUN_LOG.md) (archived) — record of what was executed by wave (2026-02-05).
**Wave 1 status:** [WAVE1_COMPLETION_SUMMARY.md](WAVE1_COMPLETION_SUMMARY.md). **Wave 2/3 checklist:** [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md).
@@ -142,7 +142,7 @@
| W2-3 | VLAN enablement: apply UDM Pro VLAN config; Proxmox bridge; migrate services to VLANs | By VLAN or by host |
| W2-4 | Phase 3 CCIP: Ops/Admin (5400-5401); NAT pools; commit/execute/RMN script expansion | Ops first, then NAT, then scripts |
| W2-5 | Phase 4: Sovereign tenant VLANs; isolation; access control | By tenant or by VLAN |
| W2-6 | Missing containers: 3 VMIDs only (2506, 2507, 2508) — see MISSING_CONTAINERS_LIST.md | By VMID or by host |
| W2-6 | 2506–2508 destroyed 2026-02-08; RPC 2500–2505 only. See MISSING_CONTAINERS_LIST.md | Done (doc) |
| W2-7 | DBIS services start (10100–10151, etc.); additional Hyperledger | By host |
| W2-8 | NPMplus HA (Keepalived, secondary 10234) | Optional; single change |

41
docs/00-meta/GAPS_STATUS.md Normal file
View File

@@ -0,0 +1,41 @@
# Gaps Status — Consolidated View
**Last Updated:** 2026-03-02
**Purpose:** Single reference for all gap sources and current status. Use this to see what is fixed in-repo vs what remains operator/external.
---
## Gap sources (canonical)
| Document | Scope | Status |
|----------|--------|--------|
| [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) | Build, contracts, canonical list, placeholders, docs, tests | All §§1–6 **Done** or Documented. §9 optional/informational. |
| [04-configuration/DETAILED_GAPS_AND_ISSUES_LIST.md](../04-configuration/DETAILED_GAPS_AND_ISSUES_LIST.md) | Explorer API, token-aggregation, nginx order, tests, CI | §1–2, 5–8 **Fixed**. §3–4 **Addressed** (nginx order documented; Explorer/Wallet timeouts 25s). §9 optional. §12 operator. |
| [04-configuration/VERIFICATION_GAPS_AND_TODOS.md](../04-configuration/VERIFICATION_GAPS_AND_TODOS.md) | Missing scripts, placeholders, runbook .env | backup-npmplus.sh **Created**. Runbook production note **Added** (INGRESS_VERIFICATION_RUNBOOK; VERIFICATION_GAPS doc). Sankofa/TBD remain until services deployed. |
| [00-meta/CW_BRIDGE_TASK_LIST.md](CW_BRIDGE_TASK_LIST.md) | cW* bridge mint/receive | Phases A, C1, F **Done** (in-repo). C2–C3, D, E **Operator** (deploy receiver, wire, test E2E). |
| [00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) | 139+ recommendations (Proxmox, code, docs, security, infra) | Many done or ongoing. Track per section; high-priority security/config items in §1–2, 6. |
---
## Fixes applied in this pass (2026-03-02)
| Gap | Fix |
|-----|-----|
| Explorer homepage / Wallet page tests intermittent | `scripts/verify-all-systems.sh`: timeout for Explorer homepage and Wallet page increased 15s → 25s. |
| Nginx proxy order (§3 DETAILED_GAPS) | Confirmed `fix-nginx-conflicts-vmid5000.sh` has `location /api/v1/` before `location /api/`; status set to Addressed; operator should use this script. |
| Runbook placeholders / .env in production | INGRESS_VERIFICATION_RUNBOOK.md: production note added in Prerequisites. VERIFICATION_GAPS_AND_TODOS: documentation note added. |
---
## Remaining (operator / external)
- **Operator (LAN/Proxmox):** Apply nginx config on VMID 5000; create token_aggregation DB and run migrations; restart token-aggregation; run run-all-operator-tasks-from-lan.sh; deploy TwoWayTokenBridgeL2 (or cW* receiver) per chain; wire CW_BRIDGE_* and test E2E. See [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md), [CW_BRIDGE_TASK_LIST.md](CW_BRIDGE_TASK_LIST.md), [DETAILED_GAPS_AND_ISSUES_LIST.md](../04-configuration/DETAILED_GAPS_AND_ISSUES_LIST.md) §12.
- **External / TBD:** Sankofa cutover placeholders until services deployed; CMC/CoinGecko submission; ramp provider outreach for Chain 138. See [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md).
---
## Quick reference
- **In-repo actionable gaps:** Addressed or documented; see REQUIRED_FIXES_UPDATES_GAPS §§1–6 and this doc.
- **Operator copy-paste:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
- **Remaining tasks (one page):** [REMAINING_TASKS.md](REMAINING_TASKS.md).

112
docs/00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md Normal file
View File

@@ -0,0 +1,112 @@
# Priority: Obtain Liquid on Mainnet & Wire Off-Ramps / On-Ramps
**Purpose:** Single priority plan: (1) get liquidity on Ethereum Mainnet so 138→mainnet flows complete, then (2) wire fiat off-ramps and on-ramps so users can move value in and out.
**Status:** Operator-focused. Repo has scripts and contracts; execution depends on deployer mainnet balance and ramp API keys/partnerships.
---
## Priority 1 — Obtain liquid on Mainnet
Without mainnet liquidity, users cannot receive value when bridging from Chain 138 to Mainnet. Two destinations need funding.
### 1.1 Trustless LiquidityPoolETH (Mainnet)
**What it does:** Pays out ETH/WETH to users who lock on 138 and claim on Mainnet (trustless bridge).
**Prerequisite:** Deployer must have **ETH (and optionally WETH)** on Ethereum Mainnet.
| Step | Action |
|------|--------|
| 1 | Fund deployer on mainnet (exchange withdrawal, bridge from L2, or another wallet). See [FUNDING_AND_DEPLOYMENT_CHECKLIST](../03-deployment/FUNDING_AND_DEPLOYMENT_CHECKLIST.md) § Ethereum Mainnet. |
| 2 | Set in `.env`: `LIQUIDITY_POOL_ETH_MAINNET` (or `LIQUIDITY_POOL`), `ETHEREUM_MAINNET_RPC`, `PRIVATE_KEY`. |
| 3 | Run: `cd smom-dbis-138 && ./scripts/deployment/fund-mainnet-lp.sh --eth 1 --weth 0.5` (or interactive; use `--dry-run` first). |
| 4 | Verify: `cast call $LIQUIDITY_POOL_ETH_MAINNET "totalLiquidity()" --rpc-url $ETHEREUM_MAINNET_RPC` (or use [live-test-trustless-bridge.sh](../../smom-dbis-138/scripts/deployment/live-test-trustless-bridge.sh) with `--check`). |
**Scripts:** [fund-mainnet-lp.sh](../../smom-dbis-138/scripts/deployment/fund-mainnet-lp.sh), [FundMainnetLP.s.sol](../../smom-dbis-138/script/bridge/trustless/FundMainnetLP.s.sol).
**Refs:** [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md), [trustless DEPLOYMENT_GUIDE](../../smom-dbis-138/docs/bridge/trustless/DEPLOYMENT_GUIDE.md).
### 1.2 Mainnet Relay Bridge (WETH9) — CCIP payouts
**What it does:** Holds WETH9 on Mainnet so CCIP relay can complete 138→mainnet WETH transfers.
**Prerequisite:** Deployer must have **WETH9** on Ethereum Mainnet.
| Step | Action |
|------|--------|
| 1 | Ensure deployer has WETH on mainnet (swap ETH→WETH or receive WETH). |
| 2 | Run: `./scripts/bridge/fund-mainnet-relay-bridge.sh [amount_wei]` (omit for full balance). Env: `PRIVATE_KEY`, `ETHEREUM_MAINNET_RPC` (or `RPC_URL_MAINNET`). |
| 3 | Verify bridge balance: `cast call 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 "balanceOf(address)(uint256)" 0xF9A32F37099c582D28b4dE7Fca6eaC1e5259f939 --rpc-url $ETHEREUM_MAINNET_RPC`. |
**Refs:** [CCIP_BRIDGE_MAINNET_CONNECTION](../07-ccip/CCIP_BRIDGE_MAINNET_CONNECTION.md), [REMAINING_WORK_BREAKDOWN_AND_ANSWERS](REMAINING_WORK_BREAKDOWN_AND_ANSWERS.md) § 2.6.
### 1.3 One-line summary (Priority 1)
1. Fund deployer with ETH (and WETH) on mainnet.
2. Set `LIQUIDITY_POOL_ETH_MAINNET`, `ETHEREUM_MAINNET_RPC` in .env.
3. Run `fund-mainnet-lp.sh --eth 1 --weth 0.5`.
4. Run `fund-mainnet-relay-bridge.sh` if using CCIP relay.
---
## Priority 2 — Wire off-ramps and on-ramps
Once mainnet has liquidity, 138→mainnet flows can complete. Next: connect fiat entry/exit (on-ramp = fiat→crypto, off-ramp = crypto→fiat).
### 2.1 Current wiring
| Component | Location | Role |
|-----------|----------|------|
| **Ramp API** | `metamask-integration/src/ramps/` | `POST /ramps/on-ramp/session`, `POST /ramps/off-ramp/session`, `GET /ramps/quote`, `GET /ramps/providers`. |
| **Providers** | MoonPay, Ramp Network, Onramper, Transak, Banxa, Coinbase, Stripe, Cybrid, Sardine, HoneyCoin | Require API keys; most support mainnet, not Chain 138. |
| **Chain support** | MetaMask ramp partners | Typically Ethereum, BNB, Polygon, etc. **Chain 138 not natively supported** by most ramp partners. |
**Refs:** [INTEGRATIONS_QUICK_REFERENCE](../../INTEGRATIONS_QUICK_REFERENCE.md), [MASTER_INDEX](../MASTER_INDEX.md) § Fiat On/Off Ramps, [METAMASK_BRIDGE_SWAP](../../smom-dbis-138/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md).
### 2.2 On-ramp wiring (fiat → crypto)
| Step | Action |
|------|--------|
| 1 | **Mainnet path (works today):** User buys ETH/tokens on a supported chain (e.g. mainnet) via ramp → then bridges to Chain 138. Document this path in companion/dApp and [METAMASK_BRIDGE_SWAP](../../smom-dbis-138/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md). |
| 2 | **Ramp API:** Ensure `metamask-integration` ramp server runs (`pnpm ramps:dev` or as part of app). Set API keys in .env: `MOONPAY_API_KEY`, `RAMP_NETWORK_API_KEY`, `ONRAMPER_API_KEY`, etc. See [MASTER_SECRETS_INVENTORY](../04-configuration/MASTER_SECRETS_INVENTORY.md), [API_KEYS_REQUIRED](../../reports/API_KEYS_REQUIRED.md). |
| 3 | **Companion/dApp:** Call `POST /ramps/on-ramp/session` with `chainId: 1` (or supported chain); show widget; instruct user to bridge to 138 if target is 138. |
| 4 | **Chain 138 native (future):** Partner with one or more ramp providers to add Chain 138. See [CONSENSYS_OUTREACH_PACKAGE](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md), [ON_RAMP_INTEGRATION_GUIDE](../../metamask-integration/docs/ON_RAMP_INTEGRATION_GUIDE.md). |
### 2.3 Off-ramp wiring (crypto → fiat)
| Step | Action |
|------|--------|
| 1 | **Mainnet path (works once liquid):** User bridges 138→mainnet (trustless or CCIP), then sells on mainnet via off-ramp. Ensure mainnet liquidity (Priority 1) so bridge payouts succeed. |
| 2 | **Ramp API:** `POST /ramps/off-ramp/session` with `chainId: 1` (mainnet) and user’s mainnet address (or wallet that received bridged funds). |
| 3 | **Companion/dApp:** After bridge, show “Sell” / off-ramp option targeting mainnet; link to ramp provider or use embedded widget. |
| 4 | **Chain 138 native (future):** Same as on-ramp — partner with providers to support 138 for direct off-ramp from 138. |
### 2.4 Checklist — ramps
- [ ] Deployer/mainnet funded → Priority 1 done.
- [ ] Ramp API keys set in `metamask-integration/.env` (MoonPay, Ramp, etc.).
- [ ] Ramp server reachable from companion/dApp (`/ramps/on-ramp/session`, `/ramps/off-ramp/session`).
- [ ] Companion/dApp: on-ramp flow (buy on mainnet → bridge to 138) documented and linked → **[MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md)**.
- [ ] Companion/dApp: off-ramp flow (138 → mainnet bridge → sell on mainnet) documented and linked → **[MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md)**.
- [ ] (Optional) Outreach to ramp partners for Chain 138 support.
---
## Order of operations
1. **Obtain liquid on mainnet** — fund LiquidityPoolETH and (if used) Relay Bridge so 138→mainnet completes.
2. **Wire ramps to mainnet** — enable buy on mainnet (on-ramp) and sell on mainnet after bridge (off-ramp).
3. **Document user flows** — “Buy ETH on mainnet → bridge to 138” and “Bridge 138→mainnet → sell”.
4. **Later:** Ramp partner outreach for native Chain 138 on/off-ramp.
---
## Related
- [MAINNET_RAMP_USER_FLOWS](../04-configuration/MAINNET_RAMP_USER_FLOWS.md) — on-ramp and off-ramp user flows (buy on mainnet → bridge to 138; 138→mainnet → sell).
- [ALL_NEXT_STEPS_CURRENT](../../smom-dbis-138/docs/deployment/ALL_NEXT_STEPS_CURRENT.md) — runbook order (G4 fund mainnet LP is step 2).
- [FUNDING_AND_DEPLOYMENT_CHECKLIST](../03-deployment/FUNDING_AND_DEPLOYMENT_CHECKLIST.md) — where to get ETH/WETH per network.
- [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md) — LP controls and funding.
- [CHAIN138_ONLY_TO_CANONICAL_OTHER_NETWORKS](../../smom-dbis-138/docs/bridge/CHAIN138_ONLY_TO_CANONICAL_OTHER_NETWORKS.md) — who prefunds (operator).
- [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md).

41
docs/00-meta/MASTER_DOCUMENTATION_INDEX.md
View File

@@ -1,41 +0,0 @@
# Master Documentation Index — Source of Truth
**Last Updated:** 2026-02-12
**Purpose:** Treat these documents as the **Bible** for URL, VMID, and port mappings. When fixing placeholders or cleaning up projects, use them as the verifiably correct source.
---
## Domain → VMID:port and infrastructure
| Document | Scope | Use when |
|----------|--------|----------|
| **[ALL_VMIDS_ENDPOINTS.md](../04-configuration/ALL_VMIDS_ENDPOINTS.md)** | Complete VMID, IP, hostname, port, and public domain mapping | Resolving which VMID:port a domain or service must use; checking that **only** explorer points to Blockscout. |
| **[RPC_ENDPOINTS_MASTER.md](../04-configuration/RPC_ENDPOINTS_MASTER.md)** | RPC URLs, public domain → NPMplus backend, canonical .env values | Setting RPC_* in .env, configuring NPMplus proxy hosts, Chain 138 / ThirdWeb / DBIS / Sankofa / MIM4U. |
| **[DNS_NPMPLUS_VM_COMPREHENSIVE_ARCHITECTURE.md](../04-configuration/DNS_NPMPLUS_VM_COMPREHENSIVE_ARCHITECTURE.md)** | DNS → NPMplus → VM table | Aligning NPMplus backend targets with VMIDs; must match ALL_VMIDS and RPC_ENDPOINTS_MASTER. |
---
## Critical rule: Explorer vs other services
**Only** the **Explorer** (Blockscout) should be pointed at **192.168.11.140** (VMID 5000):
- `explorer.d-bis.org` → 192.168.11.140:80 (web), :4000 (API) ✅
**All other domains** must point to their **correct VMID and port** (see the master docs above). Examples of **incorrect** routing (do not use):
- `sankofa.nexus`, `phoenix.sankofa.nexus` → ~~192.168.11.140~~ ❌
- Correct: `sankofa.nexus` → 192.168.11.51:3000 (VMID 7801), `phoenix.sankofa.nexus` → 192.168.11.50:4000 (VMID 7800).
When reviewing or fixing documentation and NPMplus config:
1. Resolve every domain from **ALL_VMIDS_ENDPOINTS** or **RPC_ENDPOINTS_MASTER**.
2. Update any doc or script that points a non-explorer domain to 192.168.11.140.
3. Ensure placeholder lists (e.g. [PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md](PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md), [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md)) reference these master docs and the correct targets.
---
## Related
- [PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md](PLACEHOLDERS_AND_COMPLETION_MASTER_LIST.md) — What to complete for each placeholder
- [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) — Remaining tasks and recommendations
- [NETWORK_CONFIGURATION_MASTER.md](../11-references/NETWORK_CONFIGURATION_MASTER.md) — Network and IP reference

6
docs/00-meta/MASTER_PLAN.md
View File

@@ -1,6 +1,6 @@
# Master Plan — Gaps, Protection Layer, and Granular Admin Control
**Last Updated:** 2026-02-05
**Last Updated:** 2026-02-28
**Status:** Active
**Purpose:** Single source of truth for what to do: consolidates gaps, placeholders, and recommendations; defines the full protection layer and granular admin control panels at all levels; provides phased execution with references to detailed indexes.
@@ -15,7 +15,7 @@ This document does not duplicate the full 139-item tables or every recommendatio
| Index / list | Document | Item range or scope |
|--------------|----------|---------------------|
| **All requirements (master)** | [ALL_REQUIREMENTS.md](ALL_REQUIREMENTS.md) | Foundation, security, deployment (phases, CCIP, missing containers), backup, config, codebase, protection layer, waves, validation, optional |
| All improvements and gaps | [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) | 139 items (1–11 Proxmox high, 12–20 medium, 21–30 low, 31–35 quick wins, 36–67 code/scripts, 68–74 docs, 75–91 infra, 92–105 MetaMask/explorer, 106–121 Tezos/CCIP, 122–126 Besu, 127–130 RPC translator, 131–134 orchestration portal, 135–139 maintenance) |
| All improvements and gaps (canonical) | [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) | 139 items, 20 sections (do not use ALL_IMPROVEMENTS_AND_GAPS_INDEX—deprecated) |
| Gaps and recommendations | [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md) | Security, config/DNS, code TODOs, docs, token aggregation, Tezos, operational |
| Next steps | [NEXT_STEPS_MASTER.md](NEXT_STEPS_MASTER.md) | Immediate, deployment phases, missing containers, codebase, optional, maintenance |
| TODO task list | [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) | Critical fixes, gas, verification, improvements 1–139, security, monitoring, phases, codebase, docs |
@@ -185,7 +185,7 @@ All recommendations from [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENT
| Step | Action | Doc reference |
|------|--------|----------------|
| 3.1 | CCIP fleet: CCIP Ops/Admin (5400–5401), commit/execute/RMN nodes, NAT pools. | NEXT_STEPS_MASTER Phase 3; [CCIP_DEPLOYMENT_SPEC.md](../07-ccip/CCIP_DEPLOYMENT_SPEC.md) |
| 3.2 | Missing containers: 3 only (2506, 2507, 2508). Canonical list: [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) | [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) |
| 3.2 | 2506–2508 destroyed 2026-02-08; RPC 2500–2505 only. See [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) | Done (doc) |
### Phase 4 — Granular admin panels and infra protection

80
docs/00-meta/NEXT_STEPS_2101_AND_STORAGE.md Normal file
View File

@@ -0,0 +1,80 @@
# Concrete Next Steps: RPC 2101 and Storage (thin5 / data)
**Last updated:** 2026-02-28
---
## 1. VMID 2101 (Core RPC) — RPC not responding
**Symptom:** Container running, `besu-rpc` active, but RPC (e.g. `eth_blockNumber`) returns no response from 192.168.11.211:8545.
### Run order (from project root, on LAN with SSH to r630-01)
| Step | Action | Command |
|------|--------|---------|
| 1 | **Diagnose** | `bash scripts/maintenance/health-check-rpc-2101.sh` |
| 2a | If **read-only / database not writable** | `bash scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` (then re-run step 1) |
| 2b | If **JNA / NoClassDefFoundError** in logs | `bash scripts/maintenance/fix-rpc-2101-jna-reinstall.sh` (then step 3) |
| 3 | **Fix** (start CT if needed, restart Besu, verify) | `bash scripts/maintenance/fix-core-rpc-2101.sh` |
| 4 | **Verify** | `bash scripts/health/check-rpc-vms-health.sh` — 2101 should show block number |
**Optional:** `fix-core-rpc-2101.sh --restart-only` if the container is already running and you only want to restart the Besu service.
**Docs:** `docs/09-troubleshooting/RPC_NODES_BLOCK_PRODUCTION_FIX.md`, `docs/03-deployment/RPC_2101_READONLY_FIX.md` (if present).
---
## 2. r630-02 thin5 — 84.6% used (monitor / reduce)
**Risk:** thin5 is approaching the 85% WARN threshold; LVM thin pools can become slow or fail above ~90%.
### Immediate
| Step | Action | Command / notes |
|------|--------|------------------|
| 1 | **See which containers use thin5** | On r630-02: `ssh root@192.168.11.12 'pct list; for v in $(pct list 2>/dev/null | awk "NR>1{print \$1}"); do grep -l thin5 /etc/pve/lxc/$v.conf 2>/dev/null && echo "VMID $v uses thin5"; done'` |
| 2 | **Check disk usage inside those CTs** | `bash scripts/maintenance/check-disk-all-vmids.sh` — find VMIDs on r630-02 with high % |
| 3 | **Free space inside CTs** (Besu/DB, logs) | Per VMID: `pct exec <vmid> -- du -sh /data /var/log 2>/dev/null`; prune logs, old snapshots, or Besu temp if safe |
| 4 | **Optional: migrate one CT to another thin** | If thin5 stays high: backup CT, restore to thin2/thin3/thin4/thin6 (e.g. `pct restore <vmid> /path/to/dump --storage thin2`) |
### Ongoing
| Step | Action | Command / notes |
|------|--------|------------------|
| 5 | **Track growth** | `bash scripts/monitoring/collect-storage-growth-data.sh --append` (or install cron: `bash scripts/maintenance/schedule-storage-growth-cron.sh --install`) |
| 6 | **Prune old snapshots** (on host) | `bash scripts/monitoring/prune-storage-snapshots.sh` (weekly; keeps last 30 days) |
---
## 3. r630-01 data / local-lvm — 71.9% used (monitor)
**Risk:** Still healthy; monitor so it does not reach 85%+.
### Immediate
| Step | Action | Command / notes |
|------|--------|------------------|
| 1 | **Snapshot + growth check** | `bash scripts/monitoring/collect-storage-growth-data.sh` — review `logs/storage-growth/` |
| 2 | **Identify large CTs on r630-01** | `bash scripts/maintenance/check-disk-all-vmids.sh` — ml110 + r630-01; VMIDs 2101, 2500–2505 are on r630-01 |
### Ongoing
| Step | Action | Command / notes |
|------|--------|------------------|
| 3 | **Same as thin5** | Use `schedule-storage-growth-cron.sh --install` for weekly collection + prune |
| 4 | **Before new deployments** | Re-run `bash scripts/audit-proxmox-rpc-storage.sh` and check data% / local-lvm% |
---
## Quick reference
| Item | Script | Purpose |
|------|--------|---------|
| 2101 health | `scripts/maintenance/health-check-rpc-2101.sh` | Diagnose Core RPC |
| 2101 fix | `scripts/maintenance/fix-core-rpc-2101.sh` | Restart Besu, verify RPC |
| 2101 read-only | `scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` | e2fsck RPC VMIDs on r630-01 |
| 2101 JNA | `scripts/maintenance/fix-rpc-2101-jna-reinstall.sh` | Reinstall Besu in 2101 |
| Storage audit | `scripts/audit-proxmox-rpc-storage.sh` | All hosts + RPC rootfs mapping |
| Disk in CTs | `scripts/maintenance/check-disk-all-vmids.sh` | Root / usage per running CT |
| Storage growth | `scripts/monitoring/collect-storage-growth-data.sh` | Snapshot pvesm/lvs/df |
| Growth cron | `scripts/maintenance/schedule-storage-growth-cron.sh --install` | Weekly collect + prune |

6
docs/00-meta/NEXT_STEPS_ALL.md
View File

@@ -81,9 +81,9 @@ Org **d-bis** and 18 repos created. **Pushed** to Gitea: proxmox (master), dbis_
---
## 9. General — 2506–2508 JWT / identity
## 9. General — 2506–2508 (destroyed 2026-02-08)
Containers 2506, 2507, 2508 exist. Remaining: JWT auth in front of Besu RPC per [CHAIN138_JWT_AUTH_REQUIREMENTS.md](../04-configuration/CHAIN138_JWT_AUTH_REQUIREMENTS.md); permissioned identity (2506→Luis, 2507/2508→Putu). Use `scripts/generate-jwt-token-for-container.sh`; JWT secrets on containers, not in repo .env. See [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md).
Containers 2506, 2507, 2508 were **destroyed 2026-02-08** on all Proxmox hosts. Besu RPC range is **2500–2505** only. No JWT/identity action for 2506–2508. See [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md).
---
@@ -101,7 +101,7 @@ If verification reports "cert files missing": NPMplus at https://192.168.11.167:
## 12. General — Wave 2 & 3
Per [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md): monitoring stack, Grafana + Cloudflare Access, VLAN enablement, CCIP Ops/Admin (5400–5401), 2506–2508 JWT/identity, DBIS services, NPMplus HA (optional), CCIP Fleet, Phase 4 tenant isolation.
Per [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md): monitoring stack, Grafana + Cloudflare Access, VLAN enablement, CCIP Ops/Admin (5400–5401), DBIS services, NPMplus HA (optional), CCIP Fleet, Phase 4 tenant isolation. (2506–2508 destroyed 2026-02-08.)
---

105
docs/00-meta/NEXT_STEPS_AND_REMAINING_TODOS.md
View File

@@ -1,16 +1,111 @@
# Next Steps and Remaining TODOs — Consolidated List
**Last Updated:** 2026-02-20
**Last Updated:** 2026-03-02
**Purpose:** Single checklist of all next steps and remaining tasks. **Single-file task list:** [TODOS_CONSOLIDATED.md](TODOS_CONSOLIDATED.md). Items marked **Operator/LAN** require Proxmox access, deploy keys, or external parties; others can be done in-repo (code, config, docs).
**👉 Single list (runbooks not yet run + remaining deployments + recommendations):** [TASKS_RUNBOOKS_REMAINING_AND_RECOMMENDATIONS.md](TASKS_RUNBOOKS_REMAINING_AND_RECOMMENDATIONS.md).
**👉 Single list (runbooks not yet run + remaining deployments + recommendations):** this document ([NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md)).
**See also:** [RECOMMENDED_COMPLETION_CHECKLIST.md](../07-ccip/RECOMMENDED_COMPLETION_CHECKLIST.md) (CCIP/mapper), [NEXT_STEPS_FOR_YOU.md](NEXT_STEPS_FOR_YOU.md), [NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md), [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
**See also:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) (full deployment order Phase 0–6 + preflight), [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md), [RECOMMENDED_COMPLETION_CHECKLIST.md](../07-ccip/RECOMMENDED_COMPLETION_CHECKLIST.md), [NEXT_STEPS_FOR_YOU.md](NEXT_STEPS_FOR_YOU.md), [NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md), [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md), [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
**Single ordered list (runnable):** [OPTIONAL_DEPLOYMENTS_START_HERE §5](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md#5-next-steps--complete-in-order) — from-anywhere commands (1–4) then operator/LAN (5–10). **Operator copy-paste:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
---
## Remaining tasks (summary)
Steps 1–2 and the Chain 138 “all in one” run (step 3) are **done** (2026-03-02). **Task check (2026-03-02):** Each remaining task was verified; see [TASK_CHECK_REPORT.md](TASK_CHECK_REPORT.md) for per-task status and what can be completed only by Operator/LAN or externally. What remains:
| # | Task | Who | Command / doc |
|---|------|-----|----------------|
| 4 | **Full deployment order (Phase 0–6)** | Operator | [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) — prereqs → core → PMM pools → provider → optional → cW* → verify |
| 5 | **Chain 138 PMM:** add liquidity, ensure DODOPMMProvider registered | Operator/LAN | [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md); add liquidity per [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) |
| 6 | **Operator tasks:** Blockscout verify, 502 fix, NPMplus backup, optional deploy | Operator/LAN | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy]`; [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) |
| 7 | **Gnosis, Celo, Wemix CCIP bridges** | Operator/LAN | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md); DeployWETHBridges + destinations + fund LINK |
| 8 | **LINK support on Mainnet relay** | Operator/LAN | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
| 9 | **Repos & PRs:** Ledger, Trust Wallet, Chainlist, on-ramps | External | [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md) |
| 10 | **PR-ready files:** Chainlist, Trust Wallet forms | Anyone | [04-configuration/pr-ready/README.md](../04-configuration/pr-ready/README.md) |
| 11 | **E2E flow waves E1–E7** (add liquidity, CCIP fund, token-aggregation, Blockscout, L2 PMM, bridge UI, docs) | Operator/Dev | `./scripts/run-e2e-flow-tasks-full-parallel.sh`; [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md) |
**Optional / lower priority:** Wemix token verification; mint tokens to deployer for LPs/bridges ([TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md)); AddressMapper on other chains; Mainnet trustless stack; cW* on public chains. See [TODOS_CONSOLIDATED.md](TODOS_CONSOLIDATED.md).
---
## Next steps (ordered)
| # | Step | Who | Command / doc |
|---|------|-----|----------------|
| 1 | **From anywhere (no LAN):** config + on-chain + validation | Anyone | `./scripts/run-completable-tasks-from-anywhere.sh` |
| 2 | **Before any Chain 138 deploy:** preflight (RPC, dotenv, nonce, optional cost) | Anyone with .env | `./scripts/deployment/preflight-chain138-deploy.sh [--cost]` |
| 3 | **Full deployment order** | Operator | [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) Phase 0–6: prereqs → core → PMM pools → provider → optional → cW* → verify |
| 4 | **Chain 138 PMM:** create pools, deploy DODOPMMProvider | Operator/LAN | [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md); `create-all-pmm-pools-chain138.sh`, then DeployDODOPMMProvider |
| 5 | **Operator tasks (Blockscout, 502, backup, deploy)** | Operator/LAN | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]`; [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) |
---
## Completed in this pass (2026-03-02) — Documentation and completable run
| # | Item |
|---|------|
| — | **Documentation consolidation:** [MASTER_INDEX.md](../MASTER_INDEX.md) and [README.md](../README.md) created; [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md) added (redirect); [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) deprecated (redirect stub). DOCUMENTATION_CONSOLIDATION_PLAN §5 (eliminating deprecated content) and ARCHIVE_CANDIDATES updated. |
| — | **Completable-from-anywhere run:** `./scripts/run-completable-tasks-from-anywhere.sh` — config validation OK; on-chain 38/38 (Chain 138); run-all-validation --skip-genesis OK; reconcile-env --print. E2E flow tasks dry-run: `./scripts/run-e2e-flow-tasks-full-parallel.sh --dry-run` (waves E0–E7 listed). |
| — | **Preflight:** `./scripts/deployment/preflight-chain138-deploy.sh` — passed (dotenv, RPC Core, nonce consistent). |
| — | **Chain 138 next steps (full run):** `./scripts/deployment/run-all-next-steps-chain138.sh` — Step 1 preflight OK; Step 2 TransactionMirror already deployed, cUSDT/cUSDC pool already exists (continued); Step 3 Register c* as GRU: all 12 c* already registered (skip); Step 4 on-chain verification 38/38. Exit 0. |
---
## Completed in this pass (2026-02-27)
| # | Item |
|---|------|
| — | **Deployment order of operations:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) — full Phase 0–6 sequence (prereqs → core → PMM/pools → provider → optional → cW* → verification) and remaining recommendations (R1–R24, ~139 items). |
| — | **Deployment safety (four rules):** Correct RPC (Core only), correct dotenv (`smom-dbis-138/.env` only), Gas API/cost estimate before deploy, do not deploy when transactions stuck. Documented in DEPLOYMENT_ORDER_OF_OPERATIONS, PRE_DEPLOYMENT_CHECKLIST, CONTRACT_DEPLOYMENT_RUNBOOK. |
| — | **Preflight script:** `./scripts/deployment/preflight-chain138-deploy.sh [--cost]` — checks dotenv, env keys, RPC (Core, chainId 138), deployer nonce (fails if stuck); optional `--cost` runs cost estimate. Linked from runbook and Phase 0. |
| — | **Todo/docs sync:** NEXT_STEPS_AND_REMAINING_TODOS, TODOS_CONSOLIDATED, TODO_TASK_LIST_MASTER updated with 2026-02-27 completion and deployment order/preflight refs. |
| — | **Completable run (2026-02-27):** `run-completable-tasks-from-anywhere.sh` — config validation OK; on-chain 38/38 (Chain 138); run-all-validation --skip-genesis OK; reconcile-env --print. |
---
## Completed in this pass (2026-02-28) — “What’s left” execution
| # | Item |
|---|------|
| — | **Preflight:** Passed (RPC Core, dotenv, nonce). |
| — | **PMM pools:** All three created (cUSDT/cUSDC `0x9fcB…`, cUSDT/USDT `0xa3Ee…`, cUSDC/USDC `0x90bd…`). |
| — | **DODOPMMProvider:** Deployed at `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; all three pools registered via `RegisterDODOPools.s.sol`. |
| — | **Operator script:** NPMplus RPC fix + backup + Blockscout verify run. |
| — | **Wemix:** Re-fetched scan.wemix.com/tokens; WEMIX_TOKEN_VERIFICATION.md updated. |
| — | **Docs:** PRE_DEPLOYMENT_CHECKLIST, LIQUIDITY_POOLS_MASTER_MAP updated. **Remaining (operator/external):** [WHATS_LEFT_OPERATOR_AND_EXTERNAL.md](WHATS_LEFT_OPERATOR_AND_EXTERNAL.md). |
---
## Completed in this pass (2026-02-24)
| # | Item |
|---|------|
| — | **Required next steps (complete):** Re-ran `run-completable-tasks-from-anywhere.sh` — config validation OK, on-chain 36/36 (Chain 138), run-all-validation --skip-genesis OK, reconcile-env --print. All in-repo required checks pass. |
| — | **Completable tasks:** `run-completable-tasks-from-anywhere.sh` — config OK, on-chain 36/36, run-all-validation --skip-genesis OK, reconcile-env. |
| — | **Forge tests:** smom-dbis-138 434 tests passed; alltra-lifi-settlement 8 tests passed. |
| — | **Bridge dry-run:** `run-send-cross-chain.sh 0.01 --dry-run` run (simulation; real send needs PRIVATE_KEY + LINK from LAN). |
| — | **CCIP checklist:** `ccip-deploy-checklist.sh` run — deployment order and VMID ranges confirmed; mainnet CCIP env (CCIP_ETH_ROUTER, CCIP_ETH_LINK_TOKEN, ETH_MAINNET_SELECTOR) noted for operator. |
| — | **Evidence:** [COMPLETION_RUN_20260224_TASKS_AND_TODOS.md](../04-configuration/verification-evidence/COMPLETION_RUN_20260224_TASKS_AND_TODOS.md). |
| — | **Full plan implementation:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) added; cross-links from phases, TODO, operator checklist, runbooks, recommendations. Re-ran run-completable-tasks-from-anywhere.sh (config OK, on-chain 36/36); phase4-sovereign-tenants.sh --show-steps and schedule-daily-weekly-cron.sh --show. |
| — | **Placeholders:** Canonical addresses (env-only) and AlltraAdapter fee (setBridgeFee) marked Done in [PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md](PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md). [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) updated with Wave 0 (sendCrossChain, NPMplus backup, RPC fix) and plan index link. dbis_core TS doc: prisma generate note added for MODULE_NOT_FOUND (run pnpm install first). |
| — | **All fixes (in-repo):** [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) §§1–6 already Done/Documented. TODOS_CONSOLIDATED, NEXT_STEPS_AND_REMAINING_TODOS, NEXT_STEPS_FOR_YOU synced to §4 (smart accounts kit, quote FABRIC_CHAIN_ID, .bak). No remaining in-repo fixes; operator/LAN and deferred (dbis_core TS, audits) unchanged. |
## Completed in this pass (2026-02-23)
| # | Item |
|---|------|
| — | **smom-dbis-138 deployment (all steps including optional):** Chain 138 verification (14 ok, 2 warnings); fund CCIP and fund mainnet LP dry-runs; optional G1 PMM on Polygon and run-all-four-gaps G1; optional G2 Trustless on Polygon; run-all-four-gaps and CCIPLogger documented. Report: [COMPLETION_RUN_20260223_ALL_STEPS.md](../../smom-dbis-138/docs/deployment/COMPLETION_RUN_20260223_ALL_STEPS.md). Runbook: [ALL_NEXT_STEPS_CURRENT.md](../../smom-dbis-138/docs/deployment/ALL_NEXT_STEPS_CURRENT.md). |
| — | **Optional and next steps:** Completable run (config OK, on-chain 36/36, run-all-validation --skip-genesis, reconcile-env). Shellcheck with `--optional` made non-fatal so CI and validate pass. Validate via Proxmox SSH: full shellcheck + genesis validation; jq/shellcheck installed on host when missing; genesis passed. TODOS_CONSOLIDATED, OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST, NEXT_STEPS_FOR_YOU, NEXT_STEPS_INDEX, verification evidence updated. |
## Completed in this pass (2026-02-22)
| # | Item |
|---|------|
| — | **DApp production UX:** Single “Connect Wallet” button with modal; nav Bridge \| Swap \| History \| Explorer (Admin/Reserve removed from main nav); text-only tabs; typography and form controls; “Start Bridge Transfer” CTA; trust footer in Layout; mobile layout. |
| — | **DApp console errors (MetaMask):** ObjectMultiplex/StreamMiddleware/“Lost connection” messages are from the MetaMask extension, not the DApp. Added disconnect handling: when the wallet disconnects unexpectedly, the DApp shows a toast (“Wallet disconnected. Please reconnect or reload the page.”). Doc: [DAPP_CONSOLE_ERRORS_METAMASK.md](../09-troubleshooting/DAPP_CONSOLE_ERRORS_METAMASK.md). |
## Completed in this pass (2026-02-20)
| # | Item |
@@ -50,7 +145,7 @@
| 3 | **Bridge UIs / Snap use token-mapping** | ✅ Done | Token-aggregation returns `tokenMappingApi`; Snap has `get_token_mapping`; see REST_API_REFERENCE. |
| 4 | **LINK support on Mainnet relay:** Choose Option A (extend CCIPRelayBridge) or B (separate LINK receiver); implement, deploy, fund LINK; set `relaySupported: true` for LINK in token-mapping.json; update docs. | **Operator/LAN** | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
| 5 | **Run "from anywhere" checks:** Run `./scripts/run-completable-tasks-from-anywhere.sh` periodically (config, on-chain, validation, reconcile-env). | Anyone | NEXT_STEPS_FOR_YOU §2 |
| 6 | **Placeholders (code):** Canonical addresses in token-aggregation (env); AlltraAdapter fee (set via setBridgeFee); smart accounts kit; quote service Fabric chainId; .bak (see BAK_FILES_DEPRECATION). | Dev | REQUIRED_FIXES_UPDATES_GAPS |
| 6 | **Placeholders (code):** All done or documented per [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) §4: canonical addresses (env), AlltraAdapter setBridgeFee, smart accounts kit (env + runbook), quote service FABRIC_CHAIN_ID (default 999), .bak (BAK_FILES_DEPRECATION). | Dev | REQUIRED_FIXES_UPDATES_GAPS |
| 7 | **API keys:** Sign up per [reports/API_KEYS_REQUIRED.md](../../reports/API_KEYS_REQUIRED.md); add to `.env`. | Anyone | NEXT_STEPS_FOR_YOU §2 |
---
@@ -110,7 +205,7 @@
| # | Task | Owner | Ref |
|---|------|--------|-----|
| 24 | Work through [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) as needed; run `bash scripts/verify/run-all-validation.sh [--skip-genesis]`. | Dev/Ops | TODO_TASK_LIST_MASTER |
| 24 | Work through [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (canonical) or [ALL_RECOMMENDATIONS_HIGH_PRIORITY.md](ALL_RECOMMENDATIONS_HIGH_PRIORITY.md) (high-priority only); run `bash scripts/verify/run-all-validation.sh [--skip-genesis]`. | Dev/Ops | TODO_TASK_LIST_MASTER |
| 25 | **Security:** smom audits VLT-024, ISO-024; bridge integrations BRG-VLT, BRG-ISO. | Security | TODO_TASK_LIST_MASTER §5 |
| 26 | **Paymaster (optional):** Deploy per SMART_ACCOUNTS_DEPLOYMENT_NOTE when sources ready. | Optional | TODO_TASK_LIST_MASTER §2 |
| 27 | **dbis_core:** ~1186 TS errors (deferred). | Dev | TODO_TASK_LIST_MASTER §8 |

19
docs/00-meta/NEXT_STEPS_FOR_YOU.md
View File

@@ -1,8 +1,16 @@
# Your next steps — one place
**Last Updated:** 2026-02-20
**Last Updated:** 2026-03-02
**Purpose:** Single list of what **you** need to do next (no infra/automation). Everything else the repo can do has been completed or documented.
**Completed 2026-03-02:** Documentation consolidation: [MASTER_INDEX.md](../MASTER_INDEX.md), [README.md](../README.md), [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md) created; deprecated content (ALL_IMPROVEMENTS_AND_GAPS_INDEX) marked redirect-only. `run-completable-tasks-from-anywhere.sh` run: config OK, on-chain 38/38, validation OK, reconcile-env. **Preflight** and **run-all-next-steps-chain138.sh** run: preflight passed; mirror/pool already deployed; all 12 c* already registered as GRU; verification 38/38. Next steps index and TODOS_CONSOLIDATED updated.
**Completed 2026-02-27:** Chain 138 "run all next steps" script added: `./scripts/deployment/run-all-next-steps-chain138.sh` (preflight → mirror+pool → register c* as GRU → verify). Docs updated: NEXT_STEPS_INDEX, DEPLOYMENT_ORDER_OF_OPERATIONS, TODOS_CONSOLIDATED, CONTRACT_NEXT_STEPS_LIST.
**Completed 2026-03-01:** Recommended next steps: `run-completable-tasks-from-anywhere.sh` (config OK, on-chain 38/38, validation OK, reconcile-env). Progress indicators added (Step 1/4–4/4). E2E flow tasks script: `./scripts/run-e2e-flow-tasks-full-parallel.sh [--dry-run] [--wave E1]`. CONTRACT_ADDRESSES_REFERENCE and RECOMMENDATIONS_OPERATOR_CHECKLIST updated to use ADDRESS_MATRIX_AND_STATUS for correlated address matrix.
**Completed 2026-02-23:** Optional and next steps: `run-completable-tasks-from-anywhere.sh` run (config OK, on-chain 36/36, run-all-validation --skip-genesis OK, reconcile-env). Shellcheck with `--optional` now non-fatal (CI and validate pass). Validate via Proxmox SSH: `bash scripts/run-via-proxmox-ssh.sh validate [--host IP]` runs full shellcheck + genesis validation; jq/shellcheck installed on host when missing. TODOS_CONSOLIDATED and OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST updated.
**Completed 2026-02-20:** Documentation consolidation and root cleanup (NEXT_STEPS_INDEX, DOCUMENTATION_CONSOLIDATION_PLAN; 00-meta Batch 4+5 archived; root status/temp files → docs/archive/root-cleanup-20260220; fix-wsl-ip.sh → scripts/). `run-completable-tasks-from-anywhere.sh` run: config validation OK, on-chain 45/45, run-all-validation --skip-genesis OK, reconcile-env --print.
**Completed 2026-02-12:** `run-completable-tasks-from-anywhere.sh` run successfully (config validation, on-chain check 36/36, validation, reconcile-env). app-ethereum README updated with BOLOS_SDK note. See [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) § Completed in this pass.
@@ -28,14 +36,17 @@ These can be run from your current machine (dev, WSL, CI) without Proxmox or Led
| Step | Command / action |
|------|------------------|
| **Run all “from anywhere” checks** | `./scripts/run-completable-tasks-from-anywhere.sh` — config validation, on-chain check (SKIP_EXIT=1 if RPC unreachable), run-all-validation --skip-genesis, reconcile-env --print |
| **On-chain address list (no RPC)** | `./scripts/verify/check-contracts-on-chain-138.sh --dry-run` — lists 36 addresses only |
| **Chain 138 next steps (all in one)** | `./scripts/deployment/run-all-next-steps-chain138.sh` — preflight → mirror+pool (or `--skip-mirror`) → register c* as GRU → verify. Use `--dry-run`; set `TRANSACTION_MIRROR_ADDRESS` if mirror exists. See [TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX](../03-deployment/TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md) if CreateCollision. |
| **E2E flows (full parallel)** | `./scripts/run-e2e-flow-tasks-full-parallel.sh [--dry-run] [--wave E1]` — run E2E flow tasks by wave; see [TASKS_TO_INCREASE_ALL_E2E_FLOWS](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md). |
| **On-chain address list (no RPC)** | `./scripts/verify/check-contracts-on-chain-138.sh --dry-run` — lists addresses only (no RPC) |
| **Config validation** | `./scripts/validation/validate-config-files.sh` or `... --dry-run` (print only) |
| **Bridge deploy dry-run** | `./scripts/deploy-and-configure-weth9-bridge-chain138.sh --dry-run` (no keys/network) |
| **Shellcheck (optional)** | `bash scripts/verify/run-shellcheck.sh --optional` — lint scripts; use without `--optional` to fix issues if shellcheck installed |
| **Shellcheck (optional)** | `bash scripts/verify/run-shellcheck.sh --optional` — lint scripts (reports findings, does not fail); use without `--optional` to fail on any finding |
| **Validate via Proxmox SSH** | `bash scripts/run-via-proxmox-ssh.sh validate [--host 192.168.11.10]` — full shellcheck + genesis validation on host; installs jq/shellcheck if missing |
| **CCIP checklist (dry)** | `bash scripts/ccip/ccip-deploy-checklist.sh` — validates env and prints deploy order (no deploy) |
| **Tests** | `cd smom-dbis-138 && forge test` (e2e/integration subset if full suite slow); `cd alltra-lifi-settlement && forge test && npm run test:e2e -- --forceExit` |
| **Quick wins (code)** | Add progress indicators to scripts; add `--dry-run` to scripts that lack it; extend config validation (see [IMPLEMENTATION_CHECKLIST](../10-best-practices/IMPLEMENTATION_CHECKLIST.md)) |
| **Placeholders (code)** | canonical addresses in token-aggregation; AlltraAdapter fee (AlltraAdapter.sol); smart accounts kit placeholders; quote service Fabric chainId 999; .bak deprecation — see [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) |
| **Placeholders (code)** | All done or documented — see [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) §4 (canonical addresses, AlltraAdapter setBridgeFee, smart accounts env, quote FABRIC_CHAIN_ID, .bak BAK_FILES_DEPRECATION). |
| **API keys** | Sign up at URLs in [reports/API_KEYS_REQUIRED.md](../../reports/API_KEYS_REQUIRED.md); add any new keys to `.env` |
**Reference:** [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § “Can Be Accomplished Now”.

42
docs/00-meta/NEXT_STEPS_INDEX.md
View File

@@ -1,8 +1,36 @@
# Next Steps — Index
**Last Updated:** 2026-02-20 (completable run + doc updates completed)
**Last Updated:** 2026-03-02
**Purpose:** Single entry point for "what to do next." Pick by audience and granularity.
**Documentation index:** [../MASTER_INDEX.md](../MASTER_INDEX.md) — canonical docs, deprecated list, and navigation.
---
## Next steps (ordered)
| # | Action | Command / doc | Status |
|---|--------|----------------|--------|
| 1 | From anywhere: config + on-chain + validation | `./scripts/run-completable-tasks-from-anywhere.sh` | Done 2026-03-02 |
| 2 | Before Chain 138 deploy: preflight (RPC, dotenv, nonce, cost) | `./scripts/deployment/preflight-chain138-deploy.sh [--cost]` | Done 2026-03-02 |
| 3 | **Chain 138 next steps (all in one):** preflight → mirror+pool → register c* as GRU → verify | `./scripts/deployment/run-all-next-steps-chain138.sh [--dry-run] [--skip-mirror] [--skip-register-gru] [--skip-verify]` | Done 2026-03-02 |
| 4 | Full deployment order (Phase 0–6) | [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) | Remaining (Operator) |
| 5 | Operator: Blockscout, 502 fix, backup, deploy | [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) | Remaining (Operator/LAN) |
| 6 | Repos & PRs (Ledger, Trust, Chainlist, on-ramps; forms pending) | [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md) | Remaining (External) |
| 7 | PR-ready files (Chainlist, Trust Wallet) | [04-configuration/pr-ready/README.md](../04-configuration/pr-ready/README.md) | Remaining |
**Remaining tasks (full list):** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) § Remaining tasks.
**Full list:** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) § Next steps (ordered). **E2E flows (swap, bridge, swap-bridge-swap):** [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md). Run E2E tasks in full parallel: `./scripts/run-e2e-flow-tasks-full-parallel.sh [--dry-run] [--wave E1]`. **Task list review (deprecated/duplicates):** [TASK_LIST_REVIEW_2026_03_01.md](TASK_LIST_REVIEW_2026_03_01.md).
---
## Priority: Mainnet liquidity & ramps
| Document | Description |
|----------|-------------|
| **[MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md)** | Obtain liquid on Mainnet (fund LP + relay bridge), then wire off-ramps and on-ramps. Operator steps, scripts, and ramp API wiring. |
---
## By audience
@@ -16,6 +44,14 @@
---
## Execution plan (required / optional / recommended)
| Document | Description |
|----------|-------------|
| **[COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md)** | Single index: Wave 0 gates, required (phases, codebase, security), optional (VLAN, HA, MetaMask/explorer), recommended (139+ items). Execution order and key refs. |
---
## By granularity
| Document | Granularity | Description |
@@ -40,6 +76,10 @@
## Related
- **Full deployment order of operations:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) — Phase 0–6 (prerequisites → core → PMM/pools → provider → optional → cW* → verification) and remaining recommendations (R1–R24, ~139 items).
- **PMM full parity and deploy all pools:** [NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md) — Chain 138 (verify/create pools, add liquidity, register) → multichain (deploy integration + pools on L2s) → XAU/cEURT and cW* mesh.
- **Deployment (Chain 138 / smom-dbis-138):** [PRE_DEPLOYMENT_CHECKLIST (DODO PMM, pools, provider)](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md) | [All Next Steps (Current)](../../smom-dbis-138/docs/deployment/ALL_NEXT_STEPS_CURRENT.md) | [Completion run 2026-02-23 (all steps + optional)](../../smom-dbis-138/docs/deployment/COMPLETION_RUN_20260223_ALL_STEPS.md)
- **Dev/Codespaces (76.53.10.40):** [../04-configuration/DEV_CODESPACES_NEXT_STEPS_CHECKLIST.md](../04-configuration/DEV_CODESPACES_NEXT_STEPS_CHECKLIST.md)
- **Deployment status:** [../03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md](../03-deployment/DEPLOYMENT_STATUS_CONSOLIDATED.md) | [../03-deployment/DEPLOYMENT_STATUS_MASTER.md](../03-deployment/DEPLOYMENT_STATUS_MASTER.md)
- **cW* bridge (note review + task list):** [CW_BRIDGE_TASK_LIST.md](CW_BRIDGE_TASK_LIST.md) — Checks performed, bridge extension vs dedicated receiver, deploy/wire/E2E phases. **Run remaining steps:** `./scripts/deployment/run-cw-remaining-steps.sh [--dry-run|--deploy|--update-mapping|--verify]`.
- **Blitzkrieg / execution spine:** [BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md](BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md) | [BLITZKRIEG_SOURCE_DOCUMENT_INDEX.md](BLITZKRIEG_SOURCE_DOCUMENT_INDEX.md)

7
docs/00-meta/NEXT_STEPS_MASTER.md
View File

@@ -97,7 +97,7 @@ AddressMapper and MirrorManager deployed. TransactionMirror: deploy when needed;
| Category | Missing | Total | Priority |
|----------|---------|-------|----------|
| Besu RPC (only) | 3 (2506, 2507, 2508) | 19 | High |
| Besu RPC (2506–2508) | 0 (destroyed 2026-02-08) | 16 | Done — RPC 2500–2505 only |
| Hyperledger / Blockscout | 0 | 6 | — (deployed) |
**Reference:** MISSING_CONTAINERS_LIST.md for the full list and deployment checklist.
@@ -229,5 +229,6 @@ AddressMapper and MirrorManager deployed. TransactionMirror: deploy when needed;
---
**Last Updated:** 2026-02-16
**Maintained By:** Infrastructure Team
**Last Updated:** 2026-03-02
**Maintained By:** Infrastructure Team
**Entry point:** Use [NEXT_STEPS_INDEX.md](NEXT_STEPS_INDEX.md) as the single entry for "what to do next"; this document is the expanded master list.

122
docs/00-meta/OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md Normal file
View File

@@ -0,0 +1,122 @@
# Operator and External Completion Checklist
**Purpose:** Items from [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) that **cannot** be completed from repo-only (e.g. from this workspace). They require **LAN/Proxmox access**, **operator credentials**, **external services**, or **ongoing maintenance**.
Use this checklist when you have operator or LAN access to complete the remaining recommendations.
**Full plan (Wave 0–3, required/optional/recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
---
## 1. Proxmox / security (LAN or host access)
| # | Action | Command or notes |
|---|--------|------------------|
| 1 | Secure .env permissions | `chmod 600 .env` (and subproject .env files); run from project root or use `scripts/security/secure-env-permissions.sh` if present |
| 2 | Secure validator key permissions | On host: `chmod 600` keys, `chown -R besu:besu` validator dirs |
| 3 | SSH key-only auth | On Proxmox/containers: set `PasswordAuthentication no`, `PubkeyAuthentication yes` in sshd_config |
| 4 | Firewall for Proxmox API (8006) | Restrict to specific IPs (e.g. iptables or UDM Pro rules) |
| 5 | Network segmentation (VLANs) | Per NETWORK_ARCHITECTURE; configure switches, Proxmox bridges, ER605 |
| 6 | Metrics (Prometheus, Besu 9545) | Deploy/configure Prometheus scrape; enable Besu metrics port |
| 7 | Health check + alerting | Configure Alertmanager / PagerDuty / Slack per MASTER_SECRETS |
| 8 | Automated backup + encrypted validator keys | Run backup script; store encrypted copies off-host |
| 9 | Backup configs + version control | Commit configs to repo or backup store from LAN |
---
## 2. Deployment and runbooks (operator)
| # | Action | When |
|---|--------|------|
| **Priority** | **Mainnet liquidity + ramps** | Fund mainnet LP and relay bridge; wire ramp API; document user flows. See [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md) and [MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md). |
| 10 | Integration tests for deployment scripts | Run from LAN against staging/dev |
| 11 | Runbooks: add/remove validator, upgrade Besu, key rotation, recovery, consensus | Document and run from LAN when needed |
| 12–20 | Error handling, logging, Loki, resource/network/DB tuning, CI/CD, CLI tool | Implement on infra from operator environment |
---
## 3. Infrastructure and DNS (operator / when services go live)
| # | Action | Notes |
|---|--------|-------|
| R21 | The Order / Sankofa NPMplus proxy host | When The Order portal deployed: add proxy in NPMplus; document in RPC_ENDPOINTS_MASTER, ALL_VMIDS_ENDPOINTS |
| Sankofa cutover | Replace &lt;TARGET_IP&gt;, &lt;TARGET_PORT&gt;, TBDs in SANKOFA_CUTOVER_PLAN with actual values |
| Blocks #2–#6 | Document in NETWORK_ARCHITECTURE / NETWORK_CONFIGURATION_MASTER when assigned or mark reserved |
| 75–81 | VLAN enablement, observability stack, CCIP fleet, sovereign tenants, missing containers | Per NEXT_STEPS_MASTER and deployment phases |
---
## 4. Contracts and verification (operator / after deploy)
| # | Action | Command |
|---|--------|--------|
| R1 | Verify every deployed contract on Blockscout | After each deploy when Blockscout reachable |
| R2 | Keep CONTRACT_ADDRESSES_REFERENCE and [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md) updated | When new contracts deployed or deprecated |
| R3 | Run on-chain check | `./scripts/verify/check-contracts-on-chain-138.sh` (set RPC_URL_138 from LAN) |
| R8 | Set RPC_URL_138; run from LAN if 192.168.11.x not reachable | Before any deploy |
| R9 | Use GAS_PRICE=1000000000 (or current min) on Chain 138 | Every forge script on 138 |
| R14 | Run verification after deploy in CI | When Blockscout reachable from runner |
---
## 5. Secrets and access (operator / security)
| # | Action | Notes |
|---|--------|-------|
| R4 | Do not use deprecated CCIPWETH9Bridge; use 0x971c... and set env | Always |
| R5 | Never commit .env or private keys; rotate exposed keys | Always |
| R7 | Restrict deployer key and RPC admin access | Access review |
| 48–52 | Secret audit, input validation, security scanning, RBAC, config validation | Run from secure env; use git-secrets, gitleaks, bandit, trivy as applicable |
---
## 6. External services and submissions
| # | Action | Where |
|---|--------|-------|
| 98 | CoinGecko submission (Chain 138) | [CoinGecko](https://www.coingecko.com/) |
| 99 | Consensys outreach (Swaps/Bridge support) | MetaMask/Consensys channels |
| 106–108 | Verify Etherlink/Jumper/LiFi for chains 138, 651940, 42793 | External APIs / docs |
| 109–121 | Tezos/Etherlink contracts and relay services | Deploy and run from operator env |
---
## 7. 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 |
| R17 | Monitor critical bridge/oracle events | Ongoing |
| R18 | Ensure Blockscout (VMID 5000) up and /api reachable | Health checks |
---
## 8. Optional tools (install for full automation)
Install for scripts that recommend them:
- **shellcheck** — `apt install shellcheck` or `brew install shellcheck`. With `--optional`, run reports findings but does not fail (CI and validate pass).
- **jq** — Required on Proxmox host for genesis validation; `run-via-proxmox-ssh.sh validate` installs it when missing.
- **wscat** — `npm i -g wscat` or use `npx -y wscat` for WebSocket RPC tests
- **sqlite3, websocat, sshpass, dig, parallel** — per verification evidence NEXT_STEPS_RUN_*.md
---
## What was completed in-repo (no operator needed)
- **Validate via Proxmox SSH (2026-02-23):** `run-via-proxmox-ssh.sh validate` runs full shellcheck on `scripts/verify/*.sh` and genesis validation (smom-dbis-138); installs shellcheck and jq on the host when missing. Shellcheck with `--optional` is non-fatal so CI and validate complete successfully.
- **Mainnet liquidity & ramps priority:** [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md) and [MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md) — priority plan (fund LP + relay bridge, wire ramps) and user flows for on-ramp/off-ramp; linked from ALL_NEXT_STEPS_CURRENT, NEXT_STEPS_INDEX, METAMASK_BRIDGE_SWAP, and this checklist.
- **smom-dbis-138 deployment (2026-02-23):** Chain 138 verification, fund CCIP/mainnet LP dry-runs, optional G1 PMM and G2 Trustless on L2s, run-all-four-gaps and CCIPLogger documented. See [COMPLETION_RUN_20260223_ALL_STEPS.md](../../smom-dbis-138/docs/deployment/COMPLETION_RUN_20260223_ALL_STEPS.md) and [ALL_NEXT_STEPS_CURRENT.md](../../smom-dbis-138/docs/deployment/ALL_NEXT_STEPS_CURRENT.md).
- **Shebang:** Active (non-archive) scripts under `scripts/` updated from `#!/bin/bash` to `#!/usr/bin/env bash`.
- **Script header template:** [10-best-practices/SCRIPT_HEADER_TEMPLATE.md](../10-best-practices/SCRIPT_HEADER_TEMPLATE.md) added.
- **Config validation in CI:** `.github/workflows/validate-config.yml` already runs config validation and completable-tasks dry-run; **shellcheck** added as optional step.
- **Documentation:** Quick reference cards, troubleshooting FAQ, and decision tree already exist and are linked from ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md.
- **Operator checklist:** This file; R1–R24 and remaining items are in [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md) and [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md).
---
**Related:** [NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md), [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md), [OPERATOR_READY_CHECKLIST.md](../04-configuration/OPERATOR_READY_CHECKLIST.md).

19
docs/00-meta/OPERATOR_CONTEXT_VERIFIED.md Normal file
View File

@@ -0,0 +1,19 @@
# Operator context — verified (remember)
**Last verified:** 2026-03-01
**Purpose:** Record that **this machine** has LAN and Proxmox host access so operator scripts can be run from here.
## LAN access — OK
- **Proxmox hosts (SSH 22):** 192.168.11.10, 192.168.11.11, 192.168.11.12 — reachable
- **Proxmox API (8006):** All three hosts — reachable
- **Chain 138 RPC (Core):** 192.168.11.211:8545 — reachable, `eth_chainId` = 0x8a (138)
- **NPMplus:** 192.168.11.167:80 — reachable
- **Blockscout API:** 192.168.11.140:4000 — reachable
## Proxmox host access — OK
- **SSH:** Login to `root@192.168.11.10` (ml110) succeeded (key-based).
- Operator scripts that require LAN + Proxmox (e.g. `run-all-operator-tasks-from-lan.sh`, contract verification, backup) can be run from this machine when `.env` has the required secrets (e.g. `NPM_PASSWORD`, `PRIVATE_KEY`).
**Re-verify anytime:** From repo root, run TCP checks to the above IPs/ports or use `./scripts/verify/check-contracts-on-chain-138.sh` (uses RPC 192.168.11.211:8545).

39
docs/00-meta/OPERATOR_READY_CHECKLIST.md
View File

@@ -1,6 +1,6 @@
# Operator Ready Checklist — Copy-Paste Commands
**Last Updated:** 2026-02-20
**Last Updated:** 2026-03-02
**Purpose:** Single page with exact commands to complete every pending todo. Run from **repo root** on a host with **LAN** access (and `smom-dbis-138/.env` with `PRIVATE_KEY`, `NPM_PASSWORD` where noted).
**From anywhere (no LAN):** `./scripts/run-completable-tasks-from-anywhere.sh`
@@ -81,6 +81,20 @@ Single contract retry: `./scripts/verify/run-contract-verification-with-proxy.sh
---
## 5b. LAN: Chain 138 next steps (Phase 2: preflight → mirror+pool → register c* as GRU → verify)
**Ref:** [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) Phase 2. Use when mirror/pool/GRU registration or verify are pending.
```bash
./scripts/deployment/run-all-next-steps-chain138.sh --dry-run # print steps only
./scripts/deployment/run-all-next-steps-chain138.sh # run all (preflight, deploy mirror+pool, register c*, verify)
./scripts/deployment/run-all-next-steps-chain138.sh --skip-mirror # pool + register + verify only (set TRANSACTION_MIRROR_ADDRESS in smom-dbis-138/.env first)
```
If TransactionMirror deploy fails with **CreateCollision:** set `TRANSACTION_MIRROR_ADDRESS=0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141` in `smom-dbis-138/.env` and re-run with `--skip-mirror`. See [TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX](../03-deployment/TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md).
---
## 6. Low: DODO PMM on Chain 138
**Ref:** [OPTIONAL_DEPLOYMENTS_START_HERE](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §2B
@@ -110,7 +124,27 @@ forge script script/bridge/trustless/DeployTrustlessBridge.s.sol:DeployTrustless
---
## 8. Wemix token verification (High)
## 8. Wave 0: sendCrossChain (real) and NPMplus backup
**sendCrossChain (real):** Requires `PRIVATE_KEY` and LINK approved in `.env`. Bridge: `0x971cD9D156f193df8051E48043C476e53ECd4693`.
```bash
bash scripts/bridge/run-send-cross-chain.sh 0.01 [recipient_address]
# Omit --dry-run to execute. Example: bash scripts/bridge/run-send-cross-chain.sh 0.01 0x...
```
**NPMplus backup:** Requires `NPM_PASSWORD` in `.env` and host on LAN.
```bash
bash scripts/verify/backup-npmplus.sh
# Or combined Wave 0: bash scripts/run-wave0-from-lan.sh
```
**NPMplus RPC fix (405):** From LAN: `bash scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh`. Verify: `bash scripts/verify/verify-end-to-end-routing.sh`.
---
## 9. Wemix token verification (High)
Open [scan.wemix.com/tokens](https://scan.wemix.com/tokens); confirm WETH, USDT, USDC addresses. If different, update `config/token-mapping-multichain.json` and [WEMIX_TOKEN_VERIFICATION.md](../07-ccip/WEMIX_TOKEN_VERIFICATION.md). Then:
@@ -122,6 +156,7 @@ Open [scan.wemix.com/tokens](https://scan.wemix.com/tokens); confirm WETH, USDT,
## References
- [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) — full plan (required, optional, recommended)
- [TODOS_CONSOLIDATED.md](TODOS_CONSOLIDATED.md) — full task list
- [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) — detail and completed items
- [STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md](STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md) — full LAN steps

4
docs/00-meta/PHASES_AND_TASKS_MASTER.md
View File

@@ -6,6 +6,8 @@
**For parallel execution:** See [PARALLEL_TASK_STRUCTURE.md](PARALLEL_TASK_STRUCTURE.md) — tasks are grouped by cohort; order of operations does not block parallel completion. Split large tasks into smaller units to maximize automation.
**Full plan (required / optional / recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) — Wave 0 gates, phases, codebase, operator checklist.
---
## Deployment Phases
@@ -44,7 +46,7 @@
| 16 execute nodes (5440-5455) | Required | ⏳ Pending | |
| 7 RMN nodes (5470-5476) | Required | ⏳ Pending | |
| NAT pools configured | Required | ⏳ Pending | |
| Missing containers (3 only: 2506, 2507, 2508) | Optional | ⏳ Pending | [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) |
| 2506–2508 (destroyed 2026-02-08) | — | Done | [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) |
### Phase 4 — Sovereign Tenants ⏳

4
docs/00-meta/PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md
View File

@@ -12,8 +12,8 @@
| Item | Location | Description | Priority |
|------|----------|-------------|----------|
| **Canonical addresses env-only** | `services/token-aggregation/src/config/canonical-tokens.ts` | All token addresses from env (e.g. `CUSDC_ADDRESS_138`, `WETH_ADDRESS_138`). Unset → filtered out. **Required env:** see `services/token-aggregation/README.md` and root/smom `.env.example`; document any new tokens in env or add fallback (config/DB). | Medium |
| **AlltraAdapter fee** | `contracts/bridge/adapters/evm/AlltraAdapter.sol` | `getBridgeFee()` / `setBridgeFee()` — update with actual ALL Mainnet fee after verification. Default 0.001 ALL. | Medium |
| **Canonical addresses env-only** | `services/token-aggregation/src/config/canonical-tokens.ts` | **Implemented:** Addresses from env via `SYMBOL_ADDRESS_CHAINID` (e.g. `CUSDC_ADDRESS_138`); unset → filtered out. Fallbacks in FALLBACK_ADDRESSES for 138/651940/25. See `services/token-aggregation/README.md` and `.env.example`. | Done |
| **AlltraAdapter fee** | `contracts/bridge/adapters/evm/AlltraAdapter.sol` | **Implemented:** `getBridgeFee()` / `setBridgeFee()` (admin); default 0.001 ALL. Operator: call `setBridgeFee(actualFee)` after verifying ALL Mainnet fee structure. | Done |
| **Smart accounts kit** | `script/smart-accounts/DeploySmartAccountsKit.s.sol` | EntryPoint, AccountFactory, Paymaster from env; deploy and set in .env if not already. | Medium |
| **Quote service Fabric chainId** | `orchestration/bridge/quote-service.ts` | Uses `FABRIC_CHAIN_ID` or fallback 999 until Fabric integrated. | Low |
| **EnhancedSwapRouter / DODOPMMProvider** | `contracts/bridge/trustless/EnhancedSwapRouter.sol`, `DODOPMMProvider.sol` | Some fee/size logic returns 0 or “placeholder”; optimize when oracle/pool config ready. | Low |

8
docs/00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md
View File

@@ -2,7 +2,7 @@
**Purpose:** Single checklist for all recommendations from [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) Part 2. Use when deploying, verifying, or operating.
**Related:** [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) | [MASTER_SECRETS_INVENTORY](../04-configuration/MASTER_SECRETS_INVENTORY.md)
**Related:** [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md) | [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) | [MASTER_SECRETS_INVENTORY](../04-configuration/MASTER_SECRETS_INVENTORY.md) | [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) (full plan: required / optional / recommended).
---
@@ -11,7 +11,7 @@
| # | Action | When |
|---|--------|------|
| R1 | Verify every deployed contract on Blockscout (Forge Verification Proxy or BLOCKSCOUT_VERIFICATION_GUIDE) | After each deployment when Blockscout is reachable |
| R2 | Keep CONTRACT_ADDRESSES_REFERENCE and SMART_CONTRACTS_INVENTORY_ALL_CHAINS updated; reconcile duplicate .env entries | When new contracts are deployed or deprecated |
| R2 | Keep [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) and [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md) updated; reconcile duplicate .env entries | When new contracts are deployed or deprecated |
| R3 | Run `./scripts/verify/check-contracts-on-chain-138.sh [RPC]`; fix any MISSING/EMPTY | Periodically or after deploy |
## Security and secrets (R4–R7)
@@ -37,7 +37,7 @@
| # | Action | When |
|---|--------|------|
| R12 | Keep CONTRACT_DEPLOYMENT_RUNBOOK, BLOCKSCOUT_VERIFICATION_GUIDE, BLOCKSCOUT_FIX_RUNBOOK in sync with scripts and Blockscout URL | After script or URL changes |
| R13 | When deploying to mainnet or other chains, document addresses in CONTRACT_ADDRESSES_REFERENCE or chain-specific doc; link from SMART_CONTRACTS_INVENTORY_ALL_CHAINS | Per-chain deploy |
| R13 | When deploying to mainnet or other chains, document addresses in CONTRACT_ADDRESSES_REFERENCE or chain-specific doc; update [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md) | Per-chain deploy |
## Automation and CI/CD (R14–R16)
@@ -72,7 +72,7 @@
| # | Action | When |
|---|--------|------|
| R23 | Scripts: add progress indicators; add --dry-run where missing; extend config validation (IMPLEMENTATION_CHECKLIST) | Script updates |
| R23 | Scripts: add progress indicators; add --dry-run where missing; extend config validation (IMPLEMENTATION_CHECKLIST). **Done:** `run-completable-tasks-from-anywhere.sh` has Step 1/4–4/4; `validate-config-files.sh`, `run-e2e-flow-tasks-full-parallel.sh`, `run-all-operator-tasks-from-lan.sh` support `--dry-run`. | Script updates |
## Token mapping (R24)

4
docs/00-meta/REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md
View File

@@ -112,7 +112,7 @@ See **Part 2** and [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED](../GAPS_AND_RECOMMEND
| # | Recommendation | Action |
|---|----------------|--------|
| R1 | **Verify every deployed contract on Blockscout** | Use [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) and Forge Verification Proxy so source is public and matches bytecode. |
| R2 | **Single source of truth** | Keep [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) and [SMART_CONTRACTS_INVENTORY_ALL_CHAINS](../11-references/SMART_CONTRACTS_INVENTORY_ALL_CHAINS.md) updated when new contracts are deployed or deprecated; reconcile duplicate .env entries. |
| R2 | **Single source of truth** | Keep [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) and [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md) updated when new contracts are deployed or deprecated; reconcile duplicate .env entries. |
| R3 | **On-chain confirmation** | Periodically run on-chain checklist or `check-contracts-on-chain-138.sh`; fix any MISSING/EMPTY. |
### 2.2 Security and secrets
@@ -138,7 +138,7 @@ See **Part 2** and [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED](../GAPS_AND_RECOMMEND
| # | Recommendation | Action |
|---|----------------|--------|
| R12 | **Runbooks in sync** | Keep [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md), [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md), [BLOCKSCOUT_FIX_RUNBOOK](../03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md) in sync with scripts and Blockscout URL. |
| R13 | **Per-chain addresses** | When deploying to mainnet or other chains, document addresses in CONTRACT_ADDRESSES_REFERENCE or chain-specific doc and link from SMART_CONTRACTS_INVENTORY_ALL_CHAINS. |
| R13 | **Per-chain addresses** | When deploying to mainnet or other chains, document addresses in CONTRACT_ADDRESSES_REFERENCE or chain-specific doc and update ADDRESS_MATRIX_AND_STATUS. |
### 2.5 Automation and CI/CD

2
docs/00-meta/REMAINING_ITEMS_FULL_PARALLEL_LIST.md
View File

@@ -121,7 +121,7 @@
| W2-3 | VLAN enablement: UDM Pro VLAN; Proxmox bridge; migrate services to VLANs | By VLAN/host |
| W2-4 | Phase 3 CCIP: Ops/Admin (5400-5401); NAT pools; commit/execute/RMN scripts | Ops → NAT → scripts |
| W2-5 | Phase 4: Sovereign tenant VLANs; isolation; access control | By tenant/VLAN |
| W2-6 | **Missing containers: 3 only (2506, 2507, 2508)** — [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) | By VMID/host |
| W2-6 | ~~2506–2508~~ Destroyed 2026-02-08; RPC 2500–2505 only. [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) | Done (doc) |
| W2-7 | DBIS services start (10100–10151); Hyperledger | By host |
| W2-8 | NPMplus HA (Keepalived, 10234) | Optional |

31
docs/00-meta/REMAINING_TASKS.md Normal file
View File

@@ -0,0 +1,31 @@
# Remaining Tasks
**Last Updated:** 2026-03-02
**Purpose:** Single-page list of what is left to do. Completed: preflight, run-all-next-steps-chain138 (38/38 on-chain, 12 c* GRU-registered).
**Detail:** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) § Remaining tasks · **Operator commands:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
**Task check (2026-03-02):** Each task below was verified before completion. See **[TASK_CHECK_REPORT.md](TASK_CHECK_REPORT.md)** for per-task status, what is already done (e.g. Phase 0–3, DODOPMMProvider, pools), and what still requires Operator/LAN or external submission. Completable + preflight both passed.
---
## Remaining (ordered)
| # | Task | Who | Command / doc |
|---|------|-----|----------------|
| 1 | **Full deployment order (Phase 0–6)** | Operator | [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) |
| 2 | **Chain 138 PMM:** add liquidity, DODOPMMProvider | Operator/LAN | [PRE_DEPLOYMENT_CHECKLIST.md](../03-deployment/PRE_DEPLOYMENT_CHECKLIST.md), [LIQUIDITY_POOLS_MASTER_MAP](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) |
| 3 | **Operator tasks:** Blockscout verify, 502 fix, NPMplus backup, deploy | Operator/LAN | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy]` · [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) |
| 4 | **Gnosis, Celo, Wemix CCIP bridges** | Operator/LAN | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) |
| 5 | **LINK support on Mainnet relay** | Operator/LAN | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
| 6 | **Repos & PRs:** Ledger, Trust Wallet, Chainlist, on-ramps | External | [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md) |
| 7 | **PR-ready files:** Chainlist, Trust Wallet | Anyone | [04-configuration/pr-ready/README.md](../04-configuration/pr-ready/README.md) |
| 8 | **E2E flow waves E1–E7** | Operator/Dev | `./scripts/run-e2e-flow-tasks-full-parallel.sh` · [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md) |
---
## Optional / lower priority
- Wemix token verification (scan.wemix.com/tokens)
- Mint tokens to deployer for LPs/bridges: [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md)
- AddressMapper on other chains; Mainnet trustless stack; cW* on public chains
See [TODOS_CONSOLIDATED.md](TODOS_CONSOLIDATED.md) for the full task list.

248
docs/00-meta/REMAINING_TASKS_BREAKDOWN_MISSING_INFO.md Normal file
View File

@@ -0,0 +1,248 @@
# Remaining Tasks — Breakdown and Missing Information
**Purpose:** For each remaining task, this doc states **what is needed**, **what is missing**, and **where to get it or what to create** so you can start completing everything.
**Source:** [STILL_NOT_DONE_EXECUTION_CHECKLIST.md](STILL_NOT_DONE_EXECUTION_CHECKLIST.md), [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md), [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md), [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
---
## How to use this doc
- **Needed** = inputs/access required to run the task.
- **Missing** = what you don’t have yet (or is TBD).
- **Where to get / What to do** = concrete action to obtain the missing piece or create it.
---
## 1. Operator / LAN — Wave 0 and runbooks
### W0-1: NPMplus RPC fix (405)
| | Detail |
|---|--------|
| **Needed** | Host on LAN (192.168.11.x); script exists: `scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh`. |
| **Missing** | 1) Physical/VPN access to 192.168.11.x. 2) `NPM_PASSWORD` (and optionally `NPM_URL`, `NPM_EMAIL`) in root `.env` so the script can call NPMplus API. |
| **Where to get** | **LAN:** Use a machine on the same network as NPMplus (e.g. office, VPN, or jump host). **NPM_PASSWORD:** From whoever manages NPMplus (default admin password or reset via container). If you have it but it’s hardcoded in a script, move it to `.env` only; see [MASTER_SECRETS_INVENTORY.md](../04-configuration/MASTER_SECRETS_INVENTORY.md). |
| **Doc** | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W0-1. |
### W0-2: sendCrossChain (real)
| | Detail |
|---|--------|
| **Needed** | `PRIVATE_KEY` in `.env` (wallet with gas + LINK for fees); bridge `0x971cD9D156f193df8051E48043C476e53ECd4693`; recipient address. |
| **Missing** | 1) A wallet private key you control. 2) LINK approved for the bridge fee (if the bridge charges LINK). 3) Optional: recipient address (script may have default). |
| **Where to get** | **PRIVATE_KEY:** Create or use an existing funded wallet; set in root or `smom-dbis-138/.env`. **LINK:** On Chain 138, approve LINK for the bridge contract (amount depends on fee). **Recipient:** Any valid address on the destination chain. |
| **Doc** | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) § W0-2; [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) §8. |
### W0-3: NPMplus backup
| | Detail |
|---|--------|
| **Needed** | `NPM_PASSWORD` in `.env`; host that can reach NPMplus API (LAN). |
| **Missing** | Same as W0-1: LAN access and NPM_PASSWORD. |
| **Where to get** | Same as W0-1. Script: `scripts/verify/backup-npmplus.sh` or `scripts/run-wave0-from-lan.sh` (no `--skip-backup`). |
### Blockscout verification
| | Detail |
|---|--------|
| **Needed** | Blockscout reachable (e.g. from LAN or via proxy); `smom-dbis-138/.env` with keys if verification uses Etherscan/Blockscout API. |
| **Missing** | 1) Network path to Blockscout (or proxy). 2) Any API key/token if Blockscout requires it for verification. |
| **Where to get** | Run from LAN: `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh`. Retry one contract: `--only ContractName`. If Blockscout is only on 192.168.11.x, run from a host that can reach that IP. |
### Fix E2E 502s
| | Detail |
|---|--------|
| **Needed** | SSH from your machine to Proxmox hosts (r630-01, r630-02, ml110); optional: `NPM_PASSWORD` for NPMplus proxy update step. |
| **Missing** | 1) SSH access (key or password) to root@192.168.11.11, .12, and ml110. 2) Which backends are actually down (can discover by running the script with --dry-run or diagnose-only). |
| **Where to get** | **SSH:** Use same credentials as for Proxmox management. **Discovery:** Run `./scripts/maintenance/address-all-remaining-502s.sh --run-besu-fix --e2e` (or first `diagnose-and-fix-502s-via-ssh.sh --diagnose-only`). Runbook: [502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md](502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md). |
### Run all operator tasks
| | Detail |
|---|--------|
| **Needed** | LAN; `.env` with NPM_PASSWORD and optionally PRIVATE_KEY; SSH to Proxmox. |
| **Missing** | Same as above: LAN, NPM_PASSWORD, SSH, and (for deploy) PRIVATE_KEY. |
| **Where to get** | `./scripts/run-all-operator-tasks-from-lan.sh --dry-run` to print steps; then run without `--dry-run`, optionally `--deploy` or `--create-vms`. |
### Gnosis, Celo, Wemix CCIP bridges
| | Detail |
|---|--------|
| **Needed** | Per chain: RPC URL, CCIP Router address, LINK token address, WETH9/WETH10 addresses, deployer private key with **native gas** (xDAI, CELO, WEMIX). |
| **Missing** | 1) **CCIP Router + LINK + WETH9/WETH10** for each chain — from [Chainlink CCIP supported networks](https://docs.chain.link/ccip/supported-networks). 2) **Deployer wallets** funded with native gas on Gnosis, Celo, Wemix. 3) After deploy: bridge addresses for Step 2/3 (add destinations, fund LINK). |
| **Where to get** | **Addresses:** CCIP directory + chain docs (e.g. Gnosis/Celo/Wemix WETH contracts). **Gas:** Send xDAI/CELO/WEMIX to deployer. **Steps:** [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) Step 1–4. |
### LINK support on Mainnet relay
| | Detail |
|---|--------|
| **Needed** | Code/contract change (extend CCIPRelayBridge for LINK or deploy LINK receiver); deploy; set `relaySupported: true` for LINK in `config/token-mapping.json`; restart relay on r630-01. |
| **Missing** | 1) Decision: Option A (extend bridge) vs Option B (separate LINK receiver). 2) Mainnet deployer key and gas. 3) Access to relay host (r630-01) to restart service. |
| **Where to get** | **Spec:** [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md). **Contract:** `smom-dbis-138/contracts/relay/CCIPRelayBridge.sol`. **Relay path:** `/opt/smom-dbis-138/services/relay` (restart from LAN/SSH). |
### Wemix token verification
| | Detail |
|---|--------|
| **Needed** | Correct WETH, USDT, USDC contract addresses on Wemix; update `config/token-mapping-multichain.json` and [WEMIX_TOKEN_VERIFICATION.md](../07-ccip/WEMIX_TOKEN_VERIFICATION.md) if different. |
| **Missing** | Confirmation that addresses in config match [scan.wemix.com/tokens](https://scan.wemix.com/tokens). |
| **Where to get** | Open scan.wemix.com/tokens; look up WETH, USDT, USDC; compare to repo config; edit JSON + doc; run `./scripts/validation/validate-config-files.sh`. |
### Phase 2–4 deployment
| | Detail |
|---|--------|
| **Needed** | Prometheus/Grafana/Loki/Alertmanager configs; VLAN design (UDM Pro + Proxmox); Phase 4 tenant list; SSH to Proxmox; optional CCIP NAT pools (ER605 Blocks #2–4). |
| **Missing** | 1) **Phase 2:** Which host(s) run monitoring stack; Alertmanager routes (email/Slack/PagerDuty). 2) **Phase 3:** NAT pool IPs/ranges for ER605 if not already set. 3) **Phase 4:** UDM Pro VLAN IDs (200–203 doc’d); which containers map to which tenant. |
| **Where to get** | **Configs:** `smom-dbis-138/monitoring/`, `scripts/monitoring/`; [OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md); [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md). **Phase 4 steps:** `bash scripts/deployment/phase4-sovereign-tenants.sh --show-steps`. **VLANs:** [NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md) §3–5; [UDM_PRO_FIREWALL_MANUAL_CONFIGURATION.md](../04-configuration/UDM_PRO_FIREWALL_MANUAL_CONFIGURATION.md). |
### Proxmox/security (1–9)
| | Detail |
|---|--------|
| **Needed** | Root/SSH to Proxmox hosts; list of allowed IPs/CIDRs for API 8006; validator VMIDs and paths; backup destination. |
| **Missing** | 1) **CIDR for 8006:** Which IPs may access Proxmox API (e.g. 192.168.11.0/24 or admin VPN). 2) **Validator key paths** on each host (e.g. /var/lib/besu on VMIDs 1000–1004). 3) **Backup store** for configs and encrypted validator keys. |
| **Where to get** | **Checklist:** [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md) §1. **Scripts:** `scripts/security/secure-env-permissions.sh`, `scripts/security/setup-ssh-key-auth.sh`, `scripts/security/firewall-proxmox-8006.sh`, `scripts/secure-validator-keys.sh`. **Backup:** `scripts/backup/automated-backup.sh`; decide where to store outputs (off-host, encrypted). |
---
## 2. Sankofa cutover (missing TBDs)
| | Detail |
|---|--------|
| **Needed** | For each Sankofa domain: target VMID, target IP, target port, service type. |
| **Missing** | **the-order.sankofa.nexus:** VMID, IP, port, service type still **TBD** in [SANKOFA_CUTOVER_PLAN.md](../04-configuration/SANKOFA_CUTOVER_PLAN.md). Other four domains have values (e.g. 7801/192.168.11.51/3000 for sankofa.nexus). |
| **Where to get** | Deploy The Order portal; assign VMID and IP; document in SANKOFA_CUTOVER_PLAN.md table; then run cutover steps (replace proxy backends in NPMplus). |
---
## 3. dbis_core TypeScript (~1186 errors)
| | Detail |
|---|--------|
| **Needed** | `npx prisma generate` succeeding in `dbis_core/`; then systematic edits per [DBIS_CORE_TS_FIXES_DETAILED_LIST.md](DBIS_CORE_TS_FIXES_DETAILED_LIST.md). |
| **Missing** | 1) **Prisma generate:** Currently fails with “path argument must be of type string. Received undefined” (possible Prisma + large schema). Fix: try Prisma 5.22+ or ensure `DATABASE_URL` in `dbis_core/.env`; or run from a clean `cd dbis_core && npm install` and retry. 2) **Bulk fixes:** Prioritized list exists; need to apply Priority 1–4 by module (imports, return statements, JsonValue, Prisma types, etc.). |
| **Where to get** | **Prisma:** Set `DATABASE_URL` in `dbis_core/.env` (e.g. postgresql://user:pass@host:5432/dbis_core); try `npx prisma generate` again; if still failing, try upgrading Prisma. **Fixes:** [DBIS_CORE_TS_FIXES_DETAILED_LIST.md](DBIS_CORE_TS_FIXES_DETAILED_LIST.md); sample return fixes already applied in market-admin, peg-admin, bridge-admin routes. **Verify:** `pnpm exec tsc --noEmit` in dbis_core. |
---
## 4. Security audits and bridge integrations
| | Detail |
|---|--------|
| **Needed** | Assignee/owner for smom audits (VLT-024, ISO-024) and bridge items (BRG-VLT, BRG-ISO); no repo automation. |
| **Missing** | Decision on who runs or commissions the audits; backlog/roadmap slot. |
| **Where to get** | Track in smom backlog; see [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) §5. |
---
## 5. External / third-party
### Ledger
| | Detail |
|---|--------|
| **Needed** | Tally form submitted; Ledger’s response and agreement/integration steps. |
| **Missing** | Ledger’s reply and next steps (form already submitted per [ADD_CHAIN138_TO_LEDGER_LIVE.md](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md)). |
| **Where to get** | Wait for Ledger; follow any link/instructions they send. |
### Trust Wallet
| | Detail |
|---|--------|
| **Needed** | PR to [trustwallet/wallet-core](https://github.com/trustwallet/wallet-core) with Chain 138 registry entry (CoinID 10000138, etc.). |
| **Missing** | PR not yet opened; repo fork and branch; chain 138 JSON/config per Trust’s “new EVM chain” docs. |
| **Where to get** | [ADD_CHAIN138_TO_TRUST_WALLET.md](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md) (steps + CoinID 10000138); clone wallet-core, add chain 138, open PR. |
### Consensys (MetaMask Swaps/Bridge)
| | Detail |
|---|--------|
| **Needed** | Outreach to Consensys/MetaMask for native Swaps/Bridge support for Chain 138. |
| **Missing** | Contact channel (form, email, or partner program) and a short pitch (chain live, RPC, explorer, use case). |
| **Where to get** | [metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md); MetaMask/Consensys partner or developer pages. |
### CoinGecko / CMC
| | Detail |
|---|--------|
| **Needed** | Token Aggregation report API reachable; chain + token data; 512×512 logos; CoinGecko/CMC submission forms. |
| **Missing** | 1) **Report API:** Service running and URL (e.g. for `/api/v1/report/coingecko?chainId=138`). 2) **Platform support:** CoinGecko/CMC may not list Chain 138/651940 until they add the chain. 3) **Logos:** Per-token and chain logos in required format. |
| **Where to get** | **Runbook:** [docs/04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md](../04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md); [smom-dbis-138/services/token-aggregation/docs/COINGECKO_SUBMISSION.md](../../smom-dbis-138/services/token-aggregation/docs/COINGECKO_SUBMISSION.md). **Export:** `curl "https://<token-aggregation-url>/api/v1/report/coingecko?chainId=138"`. If platforms don’t support 138 yet, keep runbook and submit when they do. |
---
## 6. API keys (for scripts and services)
| | Detail |
|---|--------|
| **Needed** | Keys for Li.Fi, Jumper, 1inch, MoonPay, Ramp, DocuSign, Slack, PagerDuty, Etherscan, CoinGecko, CMC, etc., in root and subproject `.env`. |
| **Missing** | Actual key values; sign-up and approval for each service. |
| **Where to get** | [reports/API_KEYS_REQUIRED.md](../../reports/API_KEYS_REQUIRED.md) (sign-up URLs and env var names); [docs/00-meta/API_KEYS_DOTENV_STATUS.md](API_KEYS_DOTENV_STATUS.md). Copy into `.env` (never commit); restart services that use them. |
---
## 7. Maintenance (cron and ongoing)
| | Detail |
|---|--------|
| **Needed** | Host where crontab can be installed (e.g. jump host or Proxmox node); scripts exist. |
| **Missing** | Decision on which host runs daily/weekly cron; one-time install. |
| **Where to get** | **Cron install (once, from LAN):** `bash scripts/maintenance/schedule-daily-weekly-cron.sh --show` then `--install`. **NPMplus backup cron:** `scripts/maintenance/schedule-npmplus-backup-cron.sh --install`. **Checks:** `scripts/maintenance/daily-weekly-checks.sh daily` / `weekly`. |
---
## 8. Quick reference: scripts that exist
| Script | Purpose |
|--------|--------|
| `scripts/run-wave0-from-lan.sh` | W0-1 + W0-3 (RPC fix + backup); run from LAN. |
| `scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh` | NPMplus RPC fix only; needs NPM_PASSWORD. |
| `scripts/verify/backup-npmplus.sh` | NPMplus backup only. |
| `scripts/bridge/run-send-cross-chain.sh` | sendCrossChain; omit --dry-run to execute. |
| `scripts/verify/run-contract-verification-with-proxy.sh` | Blockscout verification. |
| `scripts/maintenance/address-all-remaining-502s.sh` | Fix 502s (+ optional --run-besu-fix --e2e). |
| `scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` | Full maintenance + E2E. |
| `scripts/run-all-operator-tasks-from-lan.sh` | Backup + verify ± deploy ± create-vms. |
| `scripts/security/setup-ssh-key-auth.sh` | SSH key-only auth (--dry-run then --apply). |
| `scripts/security/firewall-proxmox-8006.sh` | Restrict Proxmox API to CIDR. |
| `scripts/secure-validator-keys.sh` | chmod 600 + chown besu for validator keys. |
| `scripts/maintenance/schedule-daily-weekly-cron.sh` | Daily/weekly checks cron. |
---
## 9. One-page “start here” order
1. **Get unblocked on LAN and secrets**
- Arrange VPN or machine on 192.168.11.x.
- Get NPM_PASSWORD (and optionally PRIVATE_KEY) into `.env` (never commit).
2. **Wave 0**
- Run `scripts/run-wave0-from-lan.sh` (or RPC fix + backup separately).
- Run sendCrossChain once if you have PRIVATE_KEY and LINK.
3. **502s and verification**
- Run `address-all-remaining-502s.sh --run-besu-fix --e2e` from LAN.
- Run Blockscout verification script.
4. **Fill TBDs**
- Sankofa: set the-order.sankofa.nexus target (VMID, IP, port) in SANKOFA_CUTOVER_PLAN.md.
- CCIP: collect per-chain addresses (CCIP directory) and fund deployer wallets for Gnosis/Celo/Wemix.
5. **dbis_core**
- Fix Prisma generate (DATABASE_URL, Prisma version); then apply TS fixes by priority.
6. **External**
- Trust Wallet: open wallet-core PR.
- CoinGecko/CMC: get report API URL and logos; submit when platform supports 138.
- Consensys: send outreach using CONSENSYS_OUTREACH_PACKAGE.
- Ledger: follow up when they respond.
7. **Maintenance**
- Install cron for daily/weekly checks and NPMplus backup on chosen host.
---
**Related:** [STILL_NOT_DONE_EXECUTION_CHECKLIST.md](STILL_NOT_DONE_EXECUTION_CHECKLIST.md) | [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md)

6
docs/00-meta/REMAINING_WORK_BREAKDOWN_AND_ANSWERS.md
View File

@@ -96,7 +96,7 @@
| **Prerequisites** | Host that can reach Blockscout (explorer.d-bis.org or LAN); `smom-dbis-138/.env` loaded. |
| **Who** | Ops or dev from LAN. |
| **Steps to complete** | From repo root: `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh`. If one fails: `.../run-contract-verification-with-proxy.sh --only ContractName`. See [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) and [CONTRACT_DEPLOYMENT_RUNBOOK](../03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md). |
| **Where to update when done** | [CONTRACT_INVENTORY_AND_VERIFICATION](../11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md) — set “Verified” for each; [CONTRACT_NEXT_STEPS_LIST](../11-references/CONTRACT_NEXT_STEPS_LIST.md) — check “Blockscout verification”. |
| **Where to update when done** | [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md) — set “Verified” for each; [CONTRACT_NEXT_STEPS_LIST](../11-references/CONTRACT_NEXT_STEPS_LIST.md) — check “Blockscout verification”. |
**Ref:** [STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS](STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md) §2.
@@ -110,7 +110,7 @@
| **Prerequisites** | Access to explorer (e.g. https://explorer.d-bis.org/address/0x99b3511a2d315a497c8112c1fdd8d508d4b1e506). |
| **Who** | Operator or dev. |
| **Steps to complete** | 1. Open the explorer link; check contract name/source. 2. Document in [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) (and CONTRACT_INVENTORY if needed): “At 0x99b35... the contract is [Multicall | Oracle Aggregator].” Remove or qualify the other. |
| **Where to update when done** | CONTRACT_ADDRESSES_REFERENCE § Pre-Deployed / Newly Deployed; CONTRACT_INVENTORY_AND_VERIFICATION; [REMAINING](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) task 19. |
| **Where to update when done** | CONTRACT_ADDRESSES_REFERENCE § Pre-Deployed / Newly Deployed; ADDRESS_MATRIX_AND_STATUS; [REMAINING](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md) task 19. |
---
@@ -279,7 +279,7 @@
## 5. Optional / when needed
- **Trustless bridge:** Deploy from `script/bridge/trustless/` when you adopt that stack; document addresses. Ref: CONTRACT_NEXT_STEPS § Pending, [OPERATOR_OPTIONAL_CHECKLIST](../11-references/OPERATOR_OPTIONAL_CHECKLIST.md) §2.
- **Mainnet/multichain deploys:** Deploy to other chains with chain-specific scripts; document in CONTRACT_ADDRESSES_REFERENCE and SMART_CONTRACTS_INVENTORY_ALL_CHAINS. Ref: R13, CONTRACT_NEXT_STEPS.
- **Mainnet/multichain deploys:** Deploy to other chains with chain-specific scripts; document in CONTRACT_ADDRESSES_REFERENCE and ADDRESS_MATRIX_AND_STATUS. Ref: R13, CONTRACT_NEXT_STEPS.
- **PaymentChannelManager / GenericStateChannelManager:** Deploy when channel features are needed; use `--with-gas-price 1000000000` on 138. Ref: CONTRACT_NEXT_STEPS_LIST.
- **LINK on mainnet relay bridge:** Follow [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md); then set `relaySupported: true` for LINK in config/token-mapping.json.
- **Chain 138 Snap E2E:** Run full E2E (Playwright + MetaMask Flask) when needed; unit tests already pass. Ref: [chain138-snap/TESTING_INSTRUCTIONS](../../metamask-integration/chain138-snap/TESTING_INSTRUCTIONS.md).

6
docs/00-meta/REMAINING_WORK_DETAILED_STEPS.md
View File

@@ -1,11 +1,13 @@
# Remaining Work — Detailed Steps for Each Task
**Last Updated:** 2026-02-20
**Last Updated:** 2026-02-28
**Purpose:** Single list of all remaining work with step-by-step instructions.
**Sources:** [E2E_COMPLETION_TASKS_DETAILED_LIST.md](E2E_COMPLETION_TASKS_DETAILED_LIST.md), [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md), [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md).
**Copy-paste runbook:** For a single page of ready-to-run commands, see **[NEXT_STEPS_OPERATOR.md](NEXT_STEPS_OPERATOR.md)**.
**Full plan (required / optional / recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) — Wave 0 gates, required phases/codebase/security, optional, recommended (139+ items).
**Execution order:** Wave 0 → Wave 1 → Wave 2 → Wave 3 → Ongoing. Within each wave, run tasks in parallel where possible.
**Infra deployment readiness:** For a single checklist of what is already in place (templates on all hosts, deps, scripts) vs what unblocks completion (LAN, SSH, creds), see **[03-deployment/INFRA_DEPLOYMENT_LOCKED_AND_LOADED.md](../03-deployment/INFRA_DEPLOYMENT_LOCKED_AND_LOADED.md)**.
@@ -40,6 +42,8 @@ These can be done from your current environment (e.g. dev machine, WSL, CI) with
**Completed (2026-02-20):** Doc consolidation continued — NEXT_STEPS_INDEX, DOCUMENTATION_CONSOLIDATION_PLAN; Batch 4+5 → 00-meta-pruned; ALL_TASKS_COMPLETE → root-status-reports; project root cleanup → archive/root-cleanup-20260220; fix-wsl-ip.sh → scripts/. Completable-from-anywhere run: config validation OK, on-chain check 45/45, run-all-validation --skip-genesis OK, reconcile-env --print. ARCHIVE_CANDIDATES "Last reviewed" set.
**Completed (plan implementation):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) added; cross-links from PHASES_AND_TASKS_MASTER, TODO_TASK_LIST_MASTER, RECOMMENDATIONS_OPERATOR_CHECKLIST, REMAINING_WORK_DETAILED_STEPS, OPTIONAL_RECOMMENDATIONS_INDEX, RUNBOOKS_MASTER_INDEX, ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST, OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST, FULL_PARALLEL_EXECUTION_ORDER, NEXT_STEPS_INDEX, MASTER_INDEX. Validation: run-all-validation --skip-genesis OK; run-completable-tasks-from-anywhere.sh OK (config, on-chain 36/36, reconcile-env); phase4-sovereign-tenants.sh --show-steps and schedule-daily-weekly-cron.sh --show run.
---
## Wave 0 — Gates (Do First When Credentials Allow)

4
docs/00-meta/REMAINING_WORK_DETAILED_TASKS.md
View File

@@ -167,7 +167,7 @@ Containers **2506, 2507, 2508** were **removed and destroyed** on all Proxmox ho
| **W2-3** | VLAN enablement | Apply UDM Pro VLAN config; Proxmox VLAN-aware bridge; migrate services to VLANs (by VLAN/host). See NETWORK_ARCHITECTURE.md §3–5. |
| **W2-4** | Phase 3 CCIP | 1) Deploy Ops/Admin (5400, 5401). 2) NAT pools. 3) Expand commit/execute/RMN scripts. Order: Ops first, then NAT, then scripts. See [CCIP_DEPLOYMENT_SPEC.md](../07-ccip/CCIP_DEPLOYMENT_SPEC.md). |
| **W2-5** | Phase 4 sovereign tenants | Sovereign tenant VLANs; isolation; access control (by tenant/VLAN). After W2-3. |
| **W2-6** | Missing containers 2506–2508 | ✅ Created on r630-01 with .202/.203/.204. Remaining: post-create steps above (Besu config, JWT, discovery off, identity). |
| **W2-6** | 2506–2508 | 🗑️ Destroyed 2026-02-08; RPC 2500–2505 only. No action. See MISSING_CONTAINERS_LIST.md. |
| **W2-7** | DBIS services / Hyperledger | Start DBIS services (10100–10151, etc.); additional Hyperledger per deployment runbooks (by host). |
| **W2-8** | NPMplus HA | Optional: Keepalived, secondary 10234. See NPMPLUS_HA_SETUP_GUIDE.md. |
@@ -207,7 +207,7 @@ Containers **2506, 2507, 2508** were **removed and destroyed** on all Proxmox ho
All tasks that can run without LAN, SSH to Proxmox, or live credentials have been executed (config cleanup, validation, cron install, dry-runs, checklists). **What remains** requires you or a host with access:
- **Wave 0:** W0-2 sendCrossChain real (`run-send-cross-chain.sh` without `--dry-run`), W0-3 run backup when NPMplus is up.
- **Post-create 2506–2508:** **Done 2026-02-06.** Besu configure run on r630-01 and ml110: `PROXMOX_HOST=192.168.11.11 bash scripts/run-configure-besu-on-host.sh` and `PROXMOX_HOST=192.168.11.10 bash scripts/run-configure-besu-on-host.sh`. Static-nodes.json and permissioned-nodes.json deployed to all running Besu nodes; discovery disabled for 2500, 2503–2508. RPC enodes (2500–2508) are not in the enode list (extraction skipped); validators + sentries only. Remaining: JWT/nginx for 2506–2508 if required; verify discovery and identity per container.
- **2506–2508:** Containers were **destroyed 2026-02-08** on all hosts. RPC range is 2500–2505 only. No post-create steps. See [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md).
- **Wave 1 apply:** W1-1 `setup-ssh-key-auth.sh --apply`, W1-2 `firewall-proxmox-8006.sh --apply` (per host).
- **Wave 2 & 3:** Deploy monitoring, VLAN, CCIP, Phase 4, DBIS, NPMplus HA; then CCIP Fleet and Phase 4 isolation.

148
docs/00-meta/REPOSITORIES_AND_PRS_CHAIN138.md Normal file
View File

@@ -0,0 +1,148 @@
# Repositories and Pull Requests — Chain 138 (Forms Submitted, Awaiting Feedback)
**Last Updated:** 2026-02-28
**Purpose:** Single reference for all repositories you can add, connect, or submit PRs to for Chain 138 support — including wallets, explorers, on-ramps/off-ramps. **Forms have been submitted where applicable; we are awaiting feedback.** Use this doc to open or connect PRs when partners respond or when you are ready to contribute.
---
## Status: Forms submitted, awaiting feedback
| Integration | Form / submission | Status |
|-------------|-------------------|--------|
| **Ledger Live** | [Tally form](https://tally.so/r/mORpv8) — submitted 2026-02-13 | Awaiting Ledger response; do not start code without signed agreement |
| **Trust Wallet** | PR to wallet-core (materials ready) | Can open PR anytime; [ADD_CHAIN138_TO_TRUST_WALLET](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md) |
| **Consensys / MetaMask** | Outreach (contact form, business@consensys.io) | Awaiting response; no public “add chain” PR repo for Swaps/Bridge |
| **CoinGecko / CMC** | Submission via platform forms (chain/token listing) | Manual submit when ready; [CMC_COINGECKO_SUBMISSION_RUNBOOK](../04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) |
---
## 1. Ledger (form submitted — await response)
**Form:** https://tally.so/r/mORpv8 (submitted 2026-02-13)
**Repositories (for after Ledger confirms):**
| Repo | Purpose | PR / connect |
|------|--------|--------------|
| **LedgerHQ/ledger-live** | Ledger Live desktop/mobile; chain list, RPC, explorer | Add Chain 138 entry per their contribution guide after agreement |
| **LedgerHQ/app-ethereum** | Device app (chain IDs, signing) | Add chain 138 to `network.c` / chain list if they request |
| **LedgerHQ/wallet-api** | Wallet API (Ethereum family, chainId) | Extend for chainId 138 when Ledger specifies |
| **bis-innovations/LedgerLive** | Your public repo for Ledger team review | Push Chain 138 materials (cryptoassets, config, patches); share with Ledger when they ask for code |
**Docs:** [ADD_CHAIN138_TO_LEDGER_LIVE.md](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md), [LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md](../11-references/LEDGER_BLOCKCHAIN_INTEGRATION_COMPLETE.md)
**Do not** open PRs to LedgerHQ repos until Ledger has accepted the request and signed agreement.
---
## 2. Trust Wallet (PR when ready)
**Repository:** https://github.com/trustwallet/wallet-core
| Action | Details |
|--------|---------|
| **Add chain** | Add Chain 138 to `registry.json` (or current registry path); use `id`, `chainId`, `explorer`, `info.rpc` etc. |
| **Codegen** | `./tools/new-evmchain dfiometa` (use registry id; requires Rust) |
| **Tests** | Extend derivation tests for Chain 138 |
| **PR** | Open PR with registry change + generated files + test updates |
**Sample PRs:** [wallet-core #2307](https://github.com/trustwallet/wallet-core/pull/2307), [wallet-core #2157](https://github.com/trustwallet/wallet-core/pull/2157)
**Optional — token/chain logos:** https://github.com/trustwallet/assets — submit via [assets.trustwallet.com](https://assets.trustwallet.com) for Chain 138 native tokens.
**PR-ready file:** [docs/04-configuration/pr-ready/trust-wallet-registry-chain138.json](../04-configuration/pr-ready/trust-wallet-registry-chain138.json) — add to registry in wallet-core. See [pr-ready/README.md](../04-configuration/pr-ready/README.md).
**Doc:** [ADD_CHAIN138_TO_TRUST_WALLET.md](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md)
---
## 3. Chainlist / Ethereum Lists (chain metadata)
**Repository:** https://github.com/ethereum-lists/chains
**PR-ready file:** [docs/04-configuration/pr-ready/eip155-138.json](../04-configuration/pr-ready/eip155-138.json) — copy to `_data/chains/eip155-138.json` in your fork. See [pr-ready/README.md](../04-configuration/pr-ready/README.md).
Chain 138 may already be listed (see chainlist.org/chain/138). If you need to add or update:
| Action | Details |
|--------|--------|
| **Add/update chain** | Add or edit `_data/chains/eip155-138.json` with name, chainId, rpc, explorers, nativeCurrency, etc. |
| **PR** | Fork ethereum-lists/chains, add/update file, open PR; follow their CONTRIBUTING.md |
**Local spec:** `pr-workspace/chains/_data/chains/eip155-138.json` in this repo (use as source for PR content).
---
## 4. Consensys / MetaMask (outreach — no public “add chain” PR)
**Contact:** https://consensys.io/contact/ , business@consensys.io; MetaMask: https://support.metamask.io , https://developers.metamask.io
**Repositories (reference only; Swaps/Bridge/on-ramp are Consensys-controlled):**
| Repo | Purpose |
|------|--------|
| **MetaMask Snaps** | Your Snap can already support Chain 138; no PR to “add chain” to native Swaps/Bridge |
| **Consensys** | Native Swaps, Bridge, Buy/Sell for Chain 138 require partnership/outreach; no public PR repo for “add network” to those products |
**Outreach package:** [metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md) — use for email/contact form. Await response before expecting technical PR steps.
---
## 5. Price Feed — MetaMask and All Wallets
**Master doc:** [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md](../04-configuration/PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md) — single reference for adding Chain 138 USD prices to MetaMask and wallets.
---
## 6. CoinGecko / CoinMarketCap (submission, not PR)
**Submission (not GitHub PR):**
| Platform | URL / process |
|----------|----------------|
| **CoinGecko** | https://www.coingecko.com/en/coins/new — chain and token listing request |
| **CoinMarketCap** | Use CMC listing/submission process (DEX or token form) |
**Runbook:** [CMC_COINGECKO_SUBMISSION_RUNBOOK.md](../04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) — export from report API (`/api/v1/report/coingecko`, `/api/v1/report/cmc`), then submit via platform forms. Chains 138 and 651940 may need to be supported by the platform first.
---
## 7. On-ramps and off-ramps (connect / add network)
Most on-ramp/off-ramp providers do not accept public PRs to “add a chain”; they use partner/API or internal chain lists. Use this list to **request** or **connect** Chain 138.
| Provider | How to add / connect Chain 138 | Repo / link (if any) |
|----------|--------------------------------|----------------------|
| **MoonPay** | Partner/API; request network support | https://www.moonpay.com/contact — no public chain-list PR repo |
| **Ramp Network** | Partner integration; request network | https://ramp.network/ — developer/partner contact |
| **Transak** | Partner; add network via dashboard or partner API | https://transak.com/ — partner/listing request |
| **Onramper** | API; check if they support custom RPC/chainId | https://onramper.com/ |
| **Banxa** | Partner integration | https://banxa.com/ |
| **Coinbase Pay / Onramp** | Partner; add supported networks via Coinbase | https://docs.cdp.coinbase.com/ |
| **MetaMask Buy (Consensys)** | Covered by Consensys outreach above | Same as §4 |
**Current path (no native 138):** Users buy on a supported chain (e.g. mainnet) via ramp → then bridge to Chain 138. Off-ramp: bridge 138→mainnet → sell on mainnet. See [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md), [MAINNET_RAMP_USER_FLOWS.md](../04-configuration/MAINNET_RAMP_USER_FLOWS.md).
**Ramp API in repo:** `metamask-integration/src/ramps/` — `POST /ramps/on-ramp/session`, `POST /ramps/off-ramp/session`; set API keys (MOONPAY_API_KEY, RAMP_NETWORK_API_KEY, etc.) in .env.
---
## 8. Summary — what you can do now
| Item | Action |
|------|--------|
| **Ledger** | Wait for response; then use LedgerHQ repos + bis-innovations/LedgerLive as instructed |
| **Trust Wallet** | Open PR to [trustwallet/wallet-core](https://github.com/trustwallet/wallet-core) with registry + codegen + tests |
| **Chainlist** | If 138 missing or outdated, open PR to [ethereum-lists/chains](https://github.com/ethereum-lists/chains) with `eip155-138.json` |
| **Consensys** | Use [CONSENSYS_OUTREACH_PACKAGE](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md); await response |
| **Price Feed (MetaMask/wallets)** | See [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md](../04-configuration/PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md); CoinGecko, CMC, Consensys |
| **CoinGecko/CMC** | Export from report API; submit via platform forms per runbook |
| **On-ramps/off-ramps** | Contact each provider (MoonPay, Ramp, Transak, etc.) to request Chain 138; no public PR repos |
---
## See also
- [ADD_CHAIN138_TO_LEDGER_LIVE.md](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md)
- [ADD_CHAIN138_TO_TRUST_WALLET.md](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md)
- [WHATS_LEFT_OPERATOR_AND_EXTERNAL.md](WHATS_LEFT_OPERATOR_AND_EXTERNAL.md)
- [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md)

84
docs/00-meta/STILL_NOT_DONE_EXECUTION_CHECKLIST.md Normal file
View File

@@ -0,0 +1,84 @@
# Still Not Done — Execution Checklist
**Purpose:** Single checklist of every remaining item that could not be completed from repo-only (no LAN, no secrets, no external access). Use this when you have **LAN**, **credentials**, or **external accounts** to complete them.
**Source:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md), [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md), [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md).
---
## 1. Operator / LAN (Wave 0 and runbooks)
**Blocker:** Host on LAN (192.168.11.x) and/or `NPM_PASSWORD`, `PRIVATE_KEY` in `.env`.
| # | Task | Command / doc |
|---|------|----------------|
| 1 | **W0-1 NPMplus RPC fix (405)** | From LAN: `bash scripts/run-wave0-from-lan.sh` or `bash scripts/nginx-proxy-manager/update-npmplus-proxy-hosts-api.sh`. Verify: `bash scripts/verify/verify-end-to-end-routing.sh`. |
| 2 | **W0-2 sendCrossChain (real)** | `bash scripts/bridge/run-send-cross-chain.sh <amount> [recipient]` (omit `--dry-run`). Requires PRIVATE_KEY and LINK approved. Bridge: `0x971cD9D156f193df8051E48043C476e53ECd4693`. |
| 3 | **W0-3 NPMplus backup** | `bash scripts/verify/backup-npmplus.sh` or `bash scripts/run-wave0-from-lan.sh` (no `--skip-backup`). Requires NPM_PASSWORD. |
| 4 | **Blockscout verification** | `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh`. Retry one: `--only ContractName`. |
| 5 | **Fix E2E 502s** | `./scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` or `./scripts/maintenance/address-all-remaining-502s.sh --run-besu-fix --e2e`. Runbook: [502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md](502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md). |
| 6 | **Run all operator tasks** | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]`. Use `--dry-run` to print steps. |
| 7 | **Gnosis, Celo, Wemix CCIP bridges** | Per chain: set RPC, CCIP Router, LINK, WETH9/WETH10; run DeployWETHBridges; add destinations; fund LINK. Runbook: [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| 8 | **LINK support on Mainnet relay** | Implement per [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md); set `relaySupported: true` for LINK in token-mapping.json; restart relay on r630-01. |
| 9 | **Wemix token verification** | Confirm WETH, USDT, USDC on [scan.wemix.com/tokens](https://scan.wemix.com/tokens); update `config/token-mapping-multichain.json` and WEMIX_TOKEN_VERIFICATION.md if needed; run `./scripts/validation/validate-config-files.sh`. |
| 10 | **Phase 2–4 deployment** | Phase 2 observability, Phase 3 CCIP fleet, Phase 4 sovereign tenants. Runbooks: [OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md), [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md). |
| 11 | **Proxmox/security (1–9)** | .env chmod 600, validator keys, SSH key-only auth, firewall 8006, VLANs, metrics, backup. See [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md) §1. |
---
## 2. dbis_core TypeScript (~1186 errors, deferred)
**Blocker:** Fixes are in-repo but deferred; require `npx prisma generate` (and possibly `npm install` in dbis_core first) then systematic edits per plan. **Done in-repo:** Priority 1 “missing return” applied in `market-admin.routes.ts`, `peg-admin.routes.ts`, `bridge-admin.routes.ts`.
| # | Task | Command / doc |
|---|------|----------------|
| 1 | **Prisma generate** | In `dbis_core/`: run `npm install` then `npx prisma generate`. If you see "path argument must be of type string. Received undefined", it may be a Prisma bug with the large schema; try Prisma 5.22+ or set `DATABASE_URL` in `.env` and retry. |
| 2 | **Fix by priority** | Follow [DBIS_CORE_TS_FIXES_DETAILED_LIST.md](DBIS_CORE_TS_FIXES_DETAILED_LIST.md): Priority 1 (imports, route returns, assertions) → 2 (JsonValue, unknown) → 3 (Prisma, Request, null) → 4 (schema, Decimal). Verify: `pnpm exec tsc --noEmit` in dbis_core. |
| 3 | **Reference plan** | [dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md](../../dbis_core/TYPESCRIPT_FIXES_PRIORITIZED_PLAN.md), [dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md](../../dbis_core/PROMPT_TYPESCRIPT_FIXES_PHASES_1_4.md). |
---
## 3. Security audits and bridge integrations
**Blocker:** smom backlog / external audits; not automatable from repo.
| # | Task | Owner / doc |
|---|------|-------------|
| 1 | **smom Security audits** | VLT-024, ISO-024. Assign to security/audit owner; see [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) §5. |
| 2 | **Bridge integrations** | BRG-VLT, BRG-ISO. Per smom backlog; see same §5. |
---
## 4. External / third-party (you)
**Blocker:** Your signup, form submission, or PR to external services.
| # | Task | Where / doc |
|---|------|-------------|
| 1 | **Ledger** | Await response to Tally form; sign agreement and follow Ledger integration steps. [ADD_CHAIN138_TO_LEDGER_LIVE.md](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md). |
| 2 | **Trust Wallet** | Open PR to [trustwallet/wallet-core](https://github.com/trustwallet/wallet-core) with Chain 138 registry entry. [ADD_CHAIN138_TO_TRUST_WALLET](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md) (if present). |
| 3 | **Consensys** | Outreach for native Swaps/Bridge for Chain 138. [CONSENSYS_OUTREACH_PACKAGE](../04-configuration/CONSENSYS_OUTREACH_PACKAGE.md) or MetaMask/Consensys channels. |
| 4 | **CoinGecko/CMC** | Submit Chain 138 and tokens for MetaMask USD. [COINGECKO_SUBMISSION.md](../../smom-dbis-138/services/token-aggregation/docs/COINGECKO_SUBMISSION.md), [CMC_COINGECKO_SUBMISSION_RUNBOOK](../04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md). |
---
## 5. Maintenance (ongoing)
| # | Task | Frequency | Command / note |
|---|------|-----------|----------------|
| 1 | Monitor explorer sync | Daily | `scripts/maintenance/daily-weekly-checks.sh daily` |
| 2 | Monitor RPC (e.g. VMID 2201) | Daily | Same script |
| 3 | Config API uptime | Weekly | `daily-weekly-checks.sh weekly` |
| 4 | Review explorer logs | Weekly | Runbook: OPERATIONAL_RUNBOOKS § Maintenance |
| 5 | Update token list | As needed | token-lists; runbook [139] |
| 6 | **Cron install** | Once from LAN | `bash scripts/maintenance/schedule-daily-weekly-cron.sh --install` |
---
## Quick links
- **Breakdown — where the missing info is:** [REMAINING_TASKS_BREAKDOWN_MISSING_INFO.md](REMAINING_TASKS_BREAKDOWN_MISSING_INFO.md) — for each task: what’s needed, what’s missing, where to get it.
- **Copy-paste commands:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md)
- **Operator/external list:** [OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md](OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST.md)
- **Full plan:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md)
- **Step-by-step:** [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md)

142
docs/00-meta/TASKS_RUNBOOKS_REMAINING_AND_RECOMMENDATIONS.md
View File

@@ -1,142 +0,0 @@
# Tasks, Runbooks, Remaining Deployments, and Recommendations
**Purpose:** Single list of (1) runbooks/tasks not yet run, (2) completed items, (3) remaining deployments, and (4) recommendations and suggestions.
**Last updated:** 2026-02-20
**Related:** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) | [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) | [TODO_TASK_LIST_MASTER.md](TODO_TASK_LIST_MASTER.md) | [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md) | [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md)
---
## 1. Runbooks / tasks not yet run (operator or when-ready)
These have runbooks or scripts ready; execution is operator/LAN or when blockers clear.
| # | Task | Runbook / command | Owner / blocker |
|---|------|-------------------|-----------------|
| 1 | **Wemix token verification** | Open [scan.wemix.com/tokens](https://scan.wemix.com/tokens); update `config/token-mapping-multichain.json` and [WEMIX_TOKEN_VERIFICATION.md](../07-ccip/WEMIX_TOKEN_VERIFICATION.md) if needed; run `./scripts/validation/validate-config-files.sh` | Operator |
| 2 | **Gnosis, Celo, Wemix CCIP bridges** | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) — deploy WETH bridges, add destinations, fund LINK | Operator/LAN |
| 3 | **LINK support on Mainnet relay** | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) — Option A or B, implement, deploy, set `relaySupported: true` for LINK | Operator/LAN |
| 4 | **Blockscout verification** | `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh` | Operator/LAN |
| 5 | **Fix E2E 502s** | `./scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` or `./scripts/maintenance/address-all-remaining-502s.sh`; runbook: [502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md](502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md) | Operator/LAN |
| 6 | **Run all operator tasks** | `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]` — backup, verify, optional deploy/VMs; [STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md](STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS.md) | Operator/LAN |
| 7 | **DODO PMM on Chain 138** (create pools if not done) | Set `DODO_VENDING_MACHINE_ADDRESS`, `COMPLIANT_*` in smom-dbis-138/.env; `./scripts/deployment/run-pmm-and-pools.sh` or `scripts/setup-dodo-pools.sh`; [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md) | Operator |
| 8 | **PMM / DODO on L2s (G1)** | Set per-chain RPC + DVM + USDT/USDC; `./smom-dbis-138/scripts/deployment/deploy-pmm-all-l2s.sh`; [OPERATOR_NEXT_STEPS_RUNBOOK](../../smom-dbis-138/docs/deployment/OPERATOR_NEXT_STEPS_RUNBOOK.md) G1 | Operator |
| 9 | **Trustless Inbox + LP on L2s (G2)** | `./smom-dbis-138/scripts/deployment/deploy-trustless-l2s.sh` | Operator |
| 10 | **Lockbox on L2s (G3)** | `TRUSTLESS_DEPLOY_LOCKBOX=1 ./smom-dbis-138/scripts/deployment/deploy-trustless-l2s.sh` | Operator |
| 11 | **Fund mainnet Liquidity Pool (G4)** | `./smom-dbis-138/scripts/deployment/fund-mainnet-lp.sh`; [LIQUIDITY_POOL_CONTROLS_RUNBOOK](../03-deployment/LIQUIDITY_POOL_CONTROLS_RUNBOOK.md) | Operator |
| 12 | **Mainnet trustless stack** | Deploy Lockbox138 (138) + InboxETH, BondManager, LiquidityPoolETH (Mainnet); [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) §7 | Operator |
| 13 | **cUSDT/cUSDC to other chains + Uniswap/Balancer/Curve** | [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md); scripts: `deploy-cusdt-cusdc-all-chains.sh`, `create-uniswap-v3-pool-cusdt-cusdc.sh` | Operator |
| 14 | **CCIPLogger on Mainnet, BSC, Polygon, Gnosis** | `forge script script/DeployCCIPLogger.s.sol --rpc-url <RPC> --broadcast` per chain | Operator |
| 15 | **AddressMapper on other chains** (optional) | DeployAddressMapperOtherChain.s.sol per chain; update `config/smart-contracts-master.json` | Optional |
| 16 | **Paymaster (optional)** | `forge script script/smart-accounts/DeployPaymaster.s.sol --rpc-url $RPC_URL_138 --broadcast` when sources ready | Optional |
---
## 2. Blocked or when-stuck-tx-cleared
| # | Task | Blocker | When unblocked |
|---|------|---------|-----------------|
| 17 | **Chain 138 deployments (Phase 6/8, trustless, vault, etc.)** | Stuck tx / "Replacement transaction underpriced" | Flush mempool from RPC host or use fresh wallet; then `./smom-dbis-138/scripts/deployment/run-all-deployments-parallel.sh chain138` |
| 18 | **eMoney TokenFactory138, bridge, vault, reserve** | Same stuck tx on 138 | [cancel-pending-transactions.sh](../../scripts/cancel-pending-transactions.sh) or resolve from RPC node; [TODO_TASKS_STATUS](../../smom-dbis-138/docs/deployment/TODO_TASKS_STATUS.md) |
| 19 | **Cronos: ISO-4217W, Compliant Fiat, CCIPLogger** | Nonce / insufficient CRO | `./smom-dbis-138/scripts/deployment/fix-nonce-and-retry.sh cronos "script/...";` fund CRO |
---
## 3. Completed (summary)
- **From-anywhere:** `run-completable-tasks-from-anywhere.sh` (config validation, on-chain check, validation, reconcile-env).
- **Token-mapping API:** Bridge UIs/Snap use token-mapping; token-aggregation exposes API; doc hygiene (MAPPER_GAPS, Wemix scan).
- **AddressMapper on Cronos:** Deployed; config updated.
- **Runbooks and indexes:** OPERATIONAL_RUNBOOKS, RUNBOOKS_MASTER_INDEX, CUSDT multichain runbook, LIQUIDITY_POOL_CONTROLS, operator checklist.
- **Chain 138:** Core contracts, CCIP, Oracle, Mock DVM + DODOPMMIntegration (pools can be created); CCIPTxReporter deployed.
- **Canonical tokens (L2):** cUSDT/cUSDC supported in token-aggregation for chains 1, 56, 137, 10, 42161, 8453, 43114, 25, 100 when env set.
---
## 4. Remaining deployments (by area)
| Area | What remains | Runbook / ref |
|------|-------------------------------|----------------|
| **CCIP** | Gnosis, Celo, Wemix WETH9/WETH10 bridges; add destinations; fund LINK | CONFIG_READY_CHAINS_COMPLETION_RUNBOOK |
| **Relay** | LINK support on Mainnet (extend or new receiver); fund; token-mapping `relaySupported: true` | RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK |
| **Trustless** | Mainnet: InboxETH, BondManager, LiquidityPoolETH; optional Lockbox/Inbox on L2s | OPERATOR_READY_CHECKLIST §7; deploy-trustless-l2s.sh |
| **PMM** | Chain 138: create cUSDT/cUSDC pools if not done; L2s: deploy DODOPMMIntegration per chain | CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK; deploy-pmm-all-l2s.sh |
| **Liquidity** | Fund mainnet LiquidityPoolETH (ETH/WETH) | fund-mainnet-lp.sh |
| **cUSDT/cUSDC multichain** | Deploy tokens to BSC, Polygon, Base, etc.; create Uniswap/Balancer/Curve pools | CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK; deploy-cusdt-cusdc-all-chains.sh |
| **Optional** | AddressMapper other chains; CCIPLogger other chains; Paymaster; vault/reserve/Keeper per chain | OPERATOR_OPTIONAL_CHECKLIST; OPTIONAL_DEPLOYMENTS_START_HERE |
---
## 5. External / third-party (not runnable in-repo)
| # | Task | Action | Ref |
|---|------|--------|-----|
| 20 | **Ledger** | Await response to Tally form; sign and follow integration steps | ADD_CHAIN138_TO_LEDGER_LIVE |
| 21 | **Trust Wallet** | Open PR to trustwallet/wallet-core with Chain 138 registry entry | ADD_CHAIN138_TO_TRUST_WALLET |
| 22 | **Consensys** | Outreach for native Swaps/Bridge for Chain 138 | CONSENSYS_OUTREACH_PACKAGE |
| 23 | **CoinGecko/CMC** | Submit Chain 138 and tokens for MetaMask USD | COINGECKO_SUBMISSION_GUIDE; CMC_COINGECKO_SUBMISSION_RUNBOOK |
---
## 6. Tezos / Etherlink (when scoped)
| # | Task | Ref |
|---|------|-----|
| 24 | Verify Etherlink (42793) on CCIP; record selector/Router or "custom relay only" | TEZOS_CCIP_REMAINING_ITEMS |
| 25 | Verify Jumper and LiFi for 138, 651940, 42793; update config/matrix | TEZOS_CCIP_REMAINING_ITEMS |
| 26 | InitializeRegistry, DeployAllAdapters, Etherlink receiver, relay services | TEZOS_CCIP_RUNBOOKS_INDEX |
---
## 7. Recommendations and suggestions (R1–R24 and more)
**Source:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](RECOMMENDATIONS_OPERATOR_CHECKLIST.md) (R1–R24) and [REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md](REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS.md).
| # | Recommendation | When |
|---|-----------------|------|
| R1 | Verify every deployed contract on Blockscout (proxy or BLOCKSCOUT_VERIFICATION_GUIDE) | After each deployment when Blockscout reachable |
| R2 | Keep CONTRACT_ADDRESSES_REFERENCE and SMART_CONTRACTS_INVENTORY updated; reconcile .env | When new contracts deployed or deprecated |
| R3 | Run `./scripts/verify/check-contracts-on-chain-138.sh [RPC]`; fix any MISSING/EMPTY | Periodically or after deploy |
| R4 | Do not use deprecated CCIPWETH9Bridge; use only current and set CCIPWETH9_BRIDGE_CHAIN138 | Always |
| R5 | Never commit .env or private keys; use MASTER_SECRETS_INVENTORY; rotate if exposed | Always |
| R8 | Set RPC_URL_138 (Core); run from LAN/VPN if 192.168.11.x not reachable | Before deploy |
| R9 | Use GAS_PRICE=1000000000 (or current min) on Chain 138 | Every forge script on 138 |
| R10 | Deploy order: 01_DeployCore first, set env, then 02_DeployBridges; alltra: MerchantSettlementRegistry before WithdrawalEscrow | Deploy order |
| R12 | Keep CONTRACT_DEPLOYMENT_RUNBOOK, BLOCKSCOUT_VERIFICATION_GUIDE, BLOCKSCOUT_FIX_RUNBOOK in sync with scripts/URL | After script or URL changes |
| R14 | Run run-contract-verification-with-proxy.sh after deployments when Blockscout reachable | CI after deploy |
| R17 | Monitor bridge/oracle events (TransferInitiated, TransferCompleted, price updates) | Ongoing |
| R18 | Ensure Blockscout (VMID 5000) up and /api reachable | Health checks |
| R19 | Run `forge test` in smom-dbis-138 and alltra-lifi-settlement before deploying | Pre-deploy |
| R21 | When The Order deployed: NPMplus proxy host; document in RPC_ENDPOINTS_MASTER, ALL_VMIDS_ENDPOINTS; replace SANKOFA_CUTOVER_PLAN TBDs | Sankofa/The Order go-live |
| R24 | Keep config/token-mapping.json single source of truth for 138↔Mainnet; update when adding tokens | Adding tokens |
**Additional suggestions:**
- Run `./scripts/run-completable-tasks-from-anywhere.sh` periodically (no LAN).
- Work through [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) as needed; run `bash scripts/verify/run-all-validation.sh [--skip-genesis]`.
- Security: smom audits VLT-024, ISO-024; bridge integrations BRG-VLT, BRG-ISO (TODO_TASK_LIST_MASTER §5).
- dbis_core: ~1186 TS errors (deferred).
- Scripts: add progress indicators; add `--dry-run` where missing (R23).
---
## 8. Quick command reference
| Goal | Command |
|------|---------|
| From anywhere (no LAN) | `./scripts/run-completable-tasks-from-anywhere.sh` |
| Operator backup + verify | `./scripts/run-all-operator-tasks-from-lan.sh` |
| Operator + deploy | `./scripts/run-all-operator-tasks-from-lan.sh --deploy` |
| Blockscout verify | `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh` |
| E2E 502 fix | `./scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` |
| Config validation | `./scripts/validation/validate-config-files.sh` |
| On-chain check 138 | `./scripts/verify/check-contracts-on-chain-138.sh` |
| Full validation | `bash scripts/verify/run-all-validation.sh [--skip-genesis]` |
| Deploy cUSDT/cUSDC all chains | `./smom-dbis-138/scripts/deployment/deploy-cusdt-cusdc-all-chains.sh` |
| PMM on L2s | `./smom-dbis-138/scripts/deployment/deploy-pmm-all-l2s.sh` |
| Fund mainnet LP | `./smom-dbis-138/scripts/deployment/fund-mainnet-lp.sh` |
---
**Single-page operator copy-paste:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
**All runbooks:** [RUNBOOKS_MASTER_INDEX.md](../RUNBOOKS_MASTER_INDEX.md).

160
docs/00-meta/TASKS_TO_INCREASE_ALL_E2E_FLOWS.md Normal file
View File

@@ -0,0 +1,160 @@
# Tasks Required to Increase All End-to-End Flows
**Last Updated:** 2026-02-28
**Purpose:** Single list of all tasks needed to complete and improve every E2E flow (same-chain swap, bridge-only, swap–bridge–swap).
**Flows:** [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md) §6 — Flow A (swap on 138), Flow B (bridge from 138), Flow C (swap → bridge → swap).
---
## Legend
| Type | Meaning |
|------|---------|
| **Op** | Operator (LAN/Proxmox, credentials) |
| **Auto** | Script exists; run or schedule |
| **Code** | Code or config change |
| **Doc** | Documentation / design |
| **Def** | Blocked or deferred |
---
## Flow A: Swap on Chain 138 only (same chain)
**Goal:** User can resolve tokens → get quote → execute swap on 138 (cUSDT↔cUSDC, cUSDT↔USDT, cUSDC↔USDC).
| # | Task | Type | Notes |
|---|------|------|-------|
| A1 | Ensure Core RPC (138) writable and reachable | Op | [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](../03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md). `make-rpc-vmids-writable-via-ssh.sh`, `health-check-rpc-2101.sh`. |
| A2 | Verify or create three PMM pools on 138 | Op/Auto | cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC. `CreateCUSDTCUSDCPool.s.sol`, `CreateCUSDTUSDTPool.s.sol`, `CreateCUSDCUSDCPool.s.sol` or `setup-dodo-pools.sh`. [NEXT_STEPS_PMM_FULL_PARITY](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md). |
| A3 | Register pools with DODOPMMProvider | Op | Set `POOL_CUSDTCUSDC`, `POOL_CUSDTUSDT`, `POOL_CUSDCUSDC` in .env; run `RegisterDODOPools.s.sol`. |
| A4 | Add liquidity to all three PMM pools | Op | `AddLiquidityPMMPoolsChain138.s.sol` with `ADD_LIQUIDITY_BASE_AMOUNT`, `ADD_LIQUIDITY_QUOTE_AMOUNT`; or `run-pmm-full-parity-all-phases.sh` with amounts set. |
| A5 | Ensure token-aggregation indexes DODO on 138 | Op/Code | Set `CHAIN_138_DODO_PMM_INTEGRATION` in env; run indexer so `GET /api/v1/quote` returns DODO quotes. |
| A6 | Expose token-aggregation API for dApps/Snap | Op | Proxy `/api/v1/*` (e.g. from explorer.d-bis.org) to token-aggregation service; or set `GATSBY_SNAP_API_BASE_URL`. |
| A7 | (Optional) Deploy EnhancedSwapRouter on 138 | Op/Def | Only after Uniswap/Balancer pools exist on 138; configure quoter and pool IDs. |
| A8 | (Optional) Add N-hop quote/pathfinding | Code | Token-aggregation today is single-hop only; add graph-based A→B→C pathfinding if needed. |
---
## Flow B: Bridge from Chain 138 (no destination swap)
**Goal:** User can get bridge routes → (optional) resolve token mapping → send bridge tx 138 → destination.
| # | Task | Type | Notes |
|---|------|------|-------|
| B1 | Ensure CCIP bridges on 138 configured and funded | Op | CCIPWETH9Bridge, CCIPWETH10Bridge; destinations set; bridges funded with LINK. [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| B2 | Run bridge destination config (138 ↔ Gnosis/Cronos/Celo/Wemix etc.) | Op | `complete-config-ready-chains.sh`; fund remote bridges with LINK (`fund-ccip-bridges-with-link.sh`, `check-link-balance-config-ready-chains.sh`). |
| B3 | Ensure relay (138→Mainnet) operational if using relay path | Op | Relay service running; Mainnet CCIPRelayBridge funded with WETH. |
| B4 | Token-aggregation: `GET /api/v1/bridge/routes` returns correct Chain 138 bridges | Code/Op | Set `BRIDGE_LIST_JSON_URL` or built-in routes; verify response has `chain138Bridges`. |
| B5 | Token mapping API for 138↔destination | Code/Op | `GET /api/v1/token-mapping`, `token-mapping/resolve`; ensure `token-mapping-multichain.json` or loader includes 138 and target chains. |
| B6 | Frontend/dApp: wire Bridge UI to routes + token mapping | Code | Use `/api/v1/bridge/routes` and `/api/v1/token-mapping/resolve`; show supported tokens and destination addresses. |
| B7 | Test 138→destination and destination→138 with small amounts | Op | Run [T1_2_BRIDGE_RESOLUTION_TASKS](../06-besu/T1_2_BRIDGE_RESOLUTION_TASKS_DETAILED.md) § Task 3.5; document tx hashes. |
---
## Flow C: Swap on 138 → bridge → swap on destination
**Goal:** User gets full quote (source swap + bridge + destination swap), then executes (or coordinator does in one tx).
| # | Task | Type | Notes |
|---|------|------|-------|
| C1 | Complete Flow A (liquidity and quote on 138) | — | Prerequisite: swap on 138 must work. |
| C2 | Complete Flow B (bridge configured and funded) | — | Prerequisite: bridge must work. |
| C3 | Orchestration: `POST /api/bridge/quote` returns sourceSwapQuote and destinationSwapQuote | Code/Op | Set `BRIDGE_REGISTRY_ADDRESS`; optional `ENHANCED_SWAP_ROUTER_ADDRESS` (source), `DESTINATION_RPC_URL`, `DESTINATION_SWAP_ROUTER_ADDRESS`. QuoteService already supports optional swap quotes. |
| C4 | (Optional) Deploy SwapBridgeSwapCoordinator on-chain | Op | One tx: swap (source) → bridge → swap (destination). [DODO_PMM_NEXT_STEPS](../../smom-dbis-138/docs/bridge/DODO_PMM_NEXT_STEPS.md); deploy when full E2E on-chain flow is required. |
| C5 | Destination-chain DEX/aggregator for destinationSwapQuote | Code/Op | Ensure destination chain has DEX or aggregator API; wire QuoteService to it for `destinationSwapQuote`. |
| C6 | Frontend: “Get full path quote” and execute (or submit coordinator tx) | Code | Call `POST /api/bridge/quote`; display minReceived, sourceSwapQuote, destinationSwapQuote; button to execute steps or coordinator. |
| C7 | E2E test: swap on 138 → bridge → swap on destination | Op/Auto | Automated or manual test; document success and tx hashes. |
---
## Cross-cutting (all flows)
### Infrastructure and verification
| # | Task | Type | Notes |
|---|------|------|-------|
| X1 | RPC 2101 (Core) writable and healthy | Op | [RPC_2101_READONLY_FIX](../03-deployment/RPC_2101_READONLY_FIX.md); health-check-rpc-2101.sh. |
| X2 | On-chain contract verification (Blockscout) | Op | `run-contract-verification-with-proxy.sh` from LAN; [DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK](DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK.md) §2. |
| X3 | E2E routing (DNS + HTTPS + RPC) | Auto | `verify-end-to-end-routing.sh`; fix 502s from LAN if needed. [TASKS_TO_COMPLETE_AND_FIX](TASKS_TO_COMPLETE_AND_FIX.md). |
| X4 | Explorer E2E (homepage, API, SPA) | Auto | `explorer-monorepo/scripts/e2e-test-explorer.sh`; [DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK](DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK.md) §5. |
| X5 | Token-aggregation health and DB | Op | PostgreSQL/TimescaleDB; indexer running; `GET /health` and `/api/v1/chains` succeed. |
| X6 | TransactionMirror (if used) deployed and address in .env | Op | Deploy via `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`; set `TRANSACTION_MIRROR_ADDRESS`. |
| X7 | Deployer/admin funded on 138 and on destination chains (for deploy/tests) | Op | Gas tokens; LINK where needed for bridge fees. |
### Token list and discovery
| # | Task | Type | Notes |
|---|------|------|-------|
| X8 | Public token list URL for Chain 138 (MetaMask, dApps) | Op/Code | `GET /api/v1/report/token-list?chainId=138` or static list; point MetaMask/dApp to this URL. [TOKEN_LIST_AUTHORING_GUIDE](../11-references/TOKEN_LIST_AUTHORING_GUIDE.md). |
| X9 | Canonical token addresses in config and .env | Op | [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md); reconcile config/smart-contracts-master.json and .env. |
### Multichain (extend flows to L2s)
| # | Task | Type | Notes |
|---|------|------|-------|
| X10 | Deploy cUSDT/cUSDC on each target L2 | Op | [NEXT_STEPS_PMM_FULL_PARITY](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md) Phase 2; `deploy-cusdt-cusdc-all-chains.sh`. |
| X11 | Deploy DODOPMMIntegration + pools + provider + liquidity on each L2 | Op | `deploy-pmm-all-l2s.sh`; create pools; deploy provider; register; add liquidity. Enables Flow A and C on L2s. |
| X12 | Token-aggregation and bridge quote support for new chains | Code/Op | Add chain IDs and RPCs; token mapping for 138↔L2; bridge routes for new chains. |
### Documentation and runbooks
| # | Task | Type | Notes |
|---|------|------|-------|
| X13 | Update PMM_DEX_ROUTING_STATUS when pools + liquidity are live | Doc | Set “pools created” and “liquidity added”; update CONTRACT_ADDRESSES / ADDRESS_MATRIX if new addresses. |
| X14 | Runbooks for operator: swap, bridge, swap-bridge-swap | Doc | Point operators to [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md), [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md), [NEXT_STEPS_PMM_FULL_PARITY](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md). |
---
## Summary by flow
| Flow | Description | Key tasks |
|------|-------------|-----------|
| **A** | Swap on Chain 138 only | A1–A6 (RPC, pools, liquidity, token-aggregation, API exposure); A7–A8 optional. |
| **B** | Bridge from 138 | B1–B7 (CCIP config, funding, relay, routes API, token mapping, UI, test). |
| **C** | Swap → bridge → swap | C1–C7 (depends on A+B; quote API with swap quotes; optional coordinator; destination DEX; E2E test). |
| **Cross-cutting** | Infra, tokens, multichain, docs | X1–X14. |
---
## Execution order (suggested)
1. **Gates:** X1 (RPC), X6 (TransactionMirror if needed), X7 (fund deployer).
2. **Flow A:** A1 → A2 → A3 → A4 → A5 → A6; then A7–A8 if desired.
3. **Flow B:** B1 → B2 → B3 → B4 → B5; B6 (frontend); B7 (test).
4. **Flow C:** C1, C2 → C3 → C5, C6 → C4 (optional) → C7.
5. **Cross-cutting:** X2–X5, X8–X9 (any time); X10–X12 (multichain when ready); X13–X14 (docs).
**Parallel:** A2–A4 can use `run-pmm-full-parity-all-phases.sh` (Phase 1). B1–B2 and bridge funding can run per chain in parallel where scripts support it.
---
## Full Parallel execution (waves)
Run **all items in a wave in parallel**; then run the next wave. Script: `./scripts/run-e2e-flow-tasks-full-parallel.sh` (from repo root).
| Wave | Tasks (run in parallel) | Notes |
|------|-------------------------|--------|
| **E0 — Gates** | X1, X6, X7; A1 | RPC writable, TransactionMirror, deployer funded; Core RPC reachable. Operator. |
| **E1 — Flow A (Chain 138 DEX)** | A2, A3, A4 | Create pools, register, add liquidity: `run-pmm-full-parity-all-phases.sh` Phase 1 (internal parallel: pool create, then register, then add). |
| **E2 — Flow B (bridge)** | B1, B2 | CCIP config + destinations; fund bridges: `complete-config-ready-chains.sh`, `fund-ccip-bridges-with-link.sh`. Per-chain parallel where supported. |
| **E3 — Code/config (no LAN)** | A5, B4, B5, C3, X8 | Token-aggregation env (`CHAIN_138_DODO_PMM_INTEGRATION`); bridge routes API; token mapping; quote API; token list URL; reconcile .env. |
| **E4 — Infra/verify** | X2, X3, X4, X5 | Blockscout verify; E2E routing; explorer E2E; token-aggregation health. Operator/LAN. |
| **E5 — Multichain** | X10, X11, X12 | Deploy cUSDT/cUSDC + PMM on L2s; token-aggregation + bridge for new chains. `run-pmm-full-parity-all-phases.sh` Phase 2 (parallel per chain). |
| **E6 — Frontend + test** | B6, B7, C5, C6, C7 | Wire Bridge UI; test 138↔dest; destination DEX; full path quote UI; E2E test. |
| **E7 — Docs** | X13, X14 | Update PMM_DEX_ROUTING_STATUS; runbooks. |
**Automated (script):** E1 (Phase 1), E2 (per-chain scripts), E3 (env/config edits), E5 (Phase 2). E0, E4, E6 require operator/LAN where indicated.
---
## References
| Doc | Content |
|-----|---------|
| [DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER](../04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md) | Flows A, B, C and routing |
| [NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS](../03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md) | PMM pools and liquidity |
| [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) | CCIP bridge config and LINK |
| [DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK](DEPLOY_CONFIRM_AND_FULL_E2E_RUNBOOK.md) | Deploy, verify, E2E tests |
| [E2E_COMPLETION_TASKS_DETAILED_LIST](E2E_COMPLETION_TASKS_DETAILED_LIST.md) | Full E2E task breakdown (waves) |
| [PMM_DEX_ROUTING_STATUS](../11-references/PMM_DEX_ROUTING_STATUS.md) | DEX/PMM status |
| `scripts/run-e2e-flow-tasks-full-parallel.sh` | Run E2E flow tasks by wave (full parallel); `--dry-run`, `--wave E1` |

130
docs/00-meta/TASK_CHECK_REPORT.md Normal file
View File

@@ -0,0 +1,130 @@
# Task Check Report — Remaining Tasks Verified Before Completion
**Date:** 2026-03-02
**Purpose:** For each remaining task, verify current state before marking complete or executing. Use this report to decide what still needs to be run by Operator/LAN vs what is already satisfied.
---
## Checks run (2026-03-02)
| Check | Result |
|-------|--------|
| **run-completable-tasks-from-anywhere.sh** | Passed — config OK, 38/38 on-chain (Chain 138), validation OK, reconcile-env printed |
| **preflight-chain138-deploy.sh** | Passed — dotenv exists, RPC Core (chainId 138), nonce consistent, no stuck txs |
---
## Per-task status (after check)
### 1. Full deployment order (Phase 0–6)
| Item | Status | Notes |
|------|--------|-------|
| Phase 0 (prereqs) | Satisfied | Preflight passed; .env and RPC OK |
| Phase 1 (Chain 138 core) | Done | 38/38 contracts present |
| Phase 2 (TransactionMirror + PMM pools) | Done | Mirror deployed; all three pools created (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) |
| Phase 3 (Liquidity + DODOPMMProvider) | Partially done | DODOPMMProvider deployed at `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; pools registered. **Remaining:** add liquidity (optional per doc) via `AddLiquidityPMMPoolsChain138.s.sol` or cast |
| Phase 4–6 | Not run | Optional / other chains; Operator |
**Conclusion:** Phases 0–3 (required) are done except adding liquidity. Full “completion” of Phase 0–6 requires Operator for Phase 4–6 and, if desired, adding liquidity in Phase 3.
---
### 2. Chain 138 PMM: add liquidity, DODOPMMProvider
| Item | Status | Notes |
|------|--------|-------|
| DODOPMMProvider deployed | Done | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; pools registered (2026-02-28) |
| Pools created | Done | 0x9fcB… (cUSDT/cUSDC), 0xa3Ee… (cUSDT/USDT), 0x90bd… (cUSDC/USDC) |
| Add liquidity | Not run | Script: `smom-dbis-138/script/dex/AddLiquidityPMMPoolsChain138.s.sol`; runbook: [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md](../03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md). Requires `ADD_LIQUIDITY_BASE_AMOUNT`, `ADD_LIQUIDITY_QUOTE_AMOUNT` in .env and deployer holding base/quote tokens |
**Conclusion:** Provider and pools are in place. Only “add liquidity” remains; Operator/LAN with token balance and .env amounts.
---
### 3. Operator tasks: Blockscout verify, 502 fix, NPMplus backup, deploy
| Item | Status | Notes |
|------|--------|-------|
| Script exists | Yes | `./scripts/run-all-operator-tasks-from-lan.sh` |
| Dry-run | Run | Would run: run-wave0-from-lan.sh (NPMplus RPC fix + backup), then Blockscout verification |
| Requires | LAN, smom-dbis-138/.env (PRIVATE_KEY, NPM_PASSWORD for backup) | Cannot be run from this host without LAN |
**Conclusion:** Script is present and dry-run succeeds. Execution is Operator/LAN only.
---
### 4. Gnosis, Celo, Wemix CCIP bridges
| Item | Status | Notes |
|------|--------|-------|
| Runbook | Exists | [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md) |
| Scripts | DeployWETHBridges.s.sol; complete-config-ready-chains.sh; fund-ccip-bridges-with-link.sh | Per runbook |
| Requires | Per-chain RPC, CCIP Router, LINK, WETH9/WETH10, deployer gas (xDAI, CELO, WEMIX) | Operator/LAN |
**Conclusion:** Documented and scripted; not run in this check. Operator/LAN.
---
### 5. LINK support on Mainnet relay
| Item | Status | Notes |
|------|--------|-------|
| Runbook | Exists | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md) |
| Requires | Implement option A or B, deploy, fund LINK, set relaySupported for LINK, restart relay | Operator/LAN |
**Conclusion:** Not run. Operator/LAN.
---
### 6. Repos & PRs: Ledger, Trust Wallet, Chainlist, on-ramps
| Item | Status | Notes |
|------|--------|-------|
| Doc | [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md) | External submissions; forms/PRs |
| Action | Submit PRs / forms per doc | External / manual |
**Conclusion:** No automated check; external.
---
### 7. PR-ready files: Chainlist, Trust Wallet
| Item | Status | Notes |
|------|--------|-------|
| Chainlist | Present | `docs/04-configuration/pr-ready/eip155-138.json` |
| Trust Wallet | Present | `docs/04-configuration/pr-ready/trust-wallet-registry-chain138.json` |
| README | Present | [pr-ready/README.md](../04-configuration/pr-ready/README.md) with submission steps |
**Conclusion:** Files exist and are PR-ready; submission is external (fork, PR, forms).
---
### 8. E2E flow waves E1–E7
| Item | Status | Notes |
|------|--------|-------|
| Script | Exists | `./scripts/run-e2e-flow-tasks-full-parallel.sh` |
| Dry-run | Run | Lists waves E0–E7; E3 reports CHAIN_138_DODO_PMM_INTEGRATION set, suggests BRIDGE_REGISTRY_ADDRESS for Flow C |
| Execution | Operator/LAN for E0, E2, E4, E5, E6 | Waves include RPC, backup, Blockscout, routing, L2 PMM, bridge UI |
**Conclusion:** Script and dry-run OK; live execution is Operator/LAN for most waves.
---
## Summary
| Task | Checked | Can complete from here? | Action |
|------|--------|--------------------------|--------|
| 1. Full deployment order Phase 0–6 | Yes | No (Phase 4–6 + liquidity = Operator) | Document: Phases 0–3 done; add liquidity + Phase 4–6 = Operator |
| 2. Chain 138 PMM add liquidity | Yes | No (needs tokens + .env amounts) | Operator runs AddLiquidityPMMPoolsChain138 or cast |
| 3. Operator tasks | Yes | No (LAN required) | Operator runs run-all-operator-tasks-from-lan.sh |
| 4. Gnosis/Celo/Wemix CCIP | Yes | No | Operator per runbook |
| 5. LINK Mainnet relay | Yes | No | Operator per runbook |
| 6. Repos & PRs | Yes | No (external) | Submit per REPOSITORIES_AND_PRS_CHAIN138 |
| 7. PR-ready files | Yes | N/A (files exist) | Submit PRs using pr-ready/ files |
| 8. E2E waves E1–E7 | Yes | No (Operator for most) | Operator runs run-e2e-flow-tasks-full-parallel.sh |
**Completed in this environment:** Preflight and run-completable-tasks-from-anywhere passed; no remaining tasks can be fully “completed” from this host without LAN/Operator or external submission.
**Next step for operator:** Run `./scripts/run-all-operator-tasks-from-lan.sh` (and optionally `--deploy`) from a host on LAN; add liquidity when base/quote amounts and tokens are ready; run E2E waves as needed.

63
docs/00-meta/TASK_LIST_REVIEW_2026_03_01.md Normal file
View File

@@ -0,0 +1,63 @@
# Task List Review — Deprecated and Duplicates Resolved
**Date:** 2026-03-01
**Purpose:** Audit of remaining tasks across master documentation; removal of deprecated items and duplicate wording. Single source for “what was fixed.”
---
## 1. Deprecated tasks corrected
### 2506, 2507, 2508 (Besu RPC containers)
- **Status:** These containers were **destroyed 2026-02-08** on all Proxmox hosts (script: `destroy-vmids-2506-2508.sh`). RPC range is **2500–2505** only; function replaced by new VMID structure (2101, 2201, 2301, 2303–2308, 2400–2403).
- **Issue:** Multiple docs still listed “Missing containers 2506–2508” or “create 2506–2508” as pending/high.
- **Changes:** All references updated to “destroyed 2026-02-08” or “Done (doc)” and W2-6 / optional infra text adjusted. No create action.
**Files updated:**
TODOS_CONSOLIDATED, MASTER_PLAN, COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX, FULL_PARALLEL_EXECUTION_ORDER, PHASES_AND_TASKS_MASTER, WAVE2_WAVE3_OPERATOR_CHECKLIST, REMAINING_ITEMS_FULL_PARALLEL_LIST, REMAINING_WORK_DETAILED_TASKS, NEXT_STEPS_ALL, NEXT_STEPS_MASTER, ALL_IMPROVEMENTS_AND_GAPS_INDEX, ALL_RECOMMENDATIONS_HIGH_PRIORITY.
---
## 2. Deleted document references
### CONTRACT_INVENTORY_AND_VERIFICATION / SMART_CONTRACTS_INVENTORY
- **Status:** CONTRACT_INVENTORY_AND_VERIFICATION.md was removed. **ADDRESS_MATRIX_AND_STATUS.md** is the correlated address and status source.
- **Issue:** Multiple docs and R2/R13 still pointed to CONTRACT_INVENTORY_AND_VERIFICATION or SMART_CONTRACTS_INVENTORY_ALL_CHAINS.
- **Changes:** Replaced with ADDRESS_MATRIX_AND_STATUS (or “update ADDRESS_MATRIX_AND_STATUS”) in task text and Related sections.
**Files updated:**
CONTRACT_ADDRESSES_REFERENCE, RECOMMENDATIONS_OPERATOR_CHECKLIST (R13), ALL_RECOMMENDATIONS_HIGH_PRIORITY (R1–R3), OPERATOR_AND_EXTERNAL_COMPLETION_CHECKLIST, ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST, ALL_RECOMMENDATIONS_OPERATOR_ONLY, REMAINING_COMPONENTS_TASKS_AND_RECOMMENDATIONS, BLITZKRIEG_SOURCE_DOCUMENT_INDEX, REMAINING_WORK_BREAKDOWN_AND_ANSWERS, CONTRACT_DEPLOYMENT_RUNBOOK, CHAIN138_TOKEN_ADDRESSES, LIQUIDITY_POOLS_MASTER_MAP, DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED, MASTER_INDEX, OPERATOR_OPTIONAL_CHECKLIST, QUICK_REFERENCE_CARDS, CCIP_SENDER_CONTRACT_REFERENCE, CCIP_SECURITY_DOCUMENTATION.
**Not updated (optional / archive):**
CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE, SMART_CONTRACTS_INVENTORY_SIMPLE, MASTER_TODO_EXPANDED, BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN, and files under `docs/archive/` — can be updated in a later pass if those docs are still in use.
---
## 3. Duplicate / outdated task wording
### DODO PMM on 138 (TODOS_CONSOLIDATED task 13)
- **Status:** DODOPMMIntegration and the three PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) and DODOPMMProvider were **already deployed 2026-02-28** (see NEXT_STEPS_AND_REMAINING_TODOS completed section).
- **Issue:** Task 13 still said “Deploy DODOPMMIntegration; … create cUSDT/cUSDC pools” as if not done.
- **Change:** Task 13 text updated to “Integration and pools **already deployed**. Remaining: add liquidity (AddLiquidityPMMPoolsChain138 / run-pmm-full-parity); document in LIQUIDITY_POOLS_MASTER_MAP.” Ref set to NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.
---
## 4. Canonical task sources (after review)
- **Single task list:** [TODOS_CONSOLIDATED.md](TODOS_CONSOLIDATED.md)
- **Operator copy-paste:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md)
- **Still not done (LAN/external):** [STILL_NOT_DONE_EXECUTION_CHECKLIST.md](STILL_NOT_DONE_EXECUTION_CHECKLIST.md)
- **E2E flows:** [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md)
- **Full plan:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md)
- **Address/contract status:** [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) (replaces CONTRACT_INVENTORY_AND_VERIFICATION)
- **Containers 2506–2508:** [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md) — destroyed 2026-02-08; RPC 2500–2505 only.
---
## 5. Optional follow-ups
- **config/smart-contracts-master.json:** Referenced in several places; if this file is removed or optional, consider adding “(when present)” or “config and .env” in task text so tasks remain valid.
- **CONTRACT_NEXT_STEPS_AND_RECOMMENDATIONS_COMPLETE, SMART_CONTRACTS_INVENTORY_SIMPLE:** Still reference CONTRACT_INVENTORY_AND_VERIFICATION / SMART_CONTRACTS_INVENTORY; update if those docs stay in use.
- **Archive:** Files under `docs/archive/` were not changed; update only if you reuse them.

84
docs/00-meta/TODOS_CONSOLIDATED.md
View File

@@ -1,16 +1,46 @@
# TODOs — Consolidated Task List
**Last Updated:** 2026-02-20
**Purpose:** Single checklist of all next steps and remaining tasks. Source of truth for the full list: [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md).
**Last Updated:** 2026-03-02
**Purpose:** Single checklist of all next steps and remaining tasks. Source of truth for the full list: [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md). **Token deployments remaining:** [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md).
**Quick run:** From anywhere (no LAN): `./scripts/run-completable-tasks-from-anywhere.sh`. From LAN with secrets: `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]`.
**Quick run:** From anywhere (no LAN): `./scripts/run-completable-tasks-from-anywhere.sh`. Before Chain 138 deploy: `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`. **Chain 138 next steps (all in one):** `./scripts/deployment/run-all-next-steps-chain138.sh [--dry-run] [--skip-mirror] [--skip-register-gru] [--skip-verify]` — preflight → mirror+pool → register c* as GRU → verify. From LAN with secrets: `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]`. **E2E flows (full parallel):** `./scripts/run-e2e-flow-tasks-full-parallel.sh [--dry-run]` — [TASKS_TO_INCREASE_ALL_E2E_FLOWS](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md).
**Last completable run (2026-02-20):** Config validation OK; on-chain 45/45; run-all-validation --skip-genesis OK; reconcile-env --print. Doc consolidation and root cleanup completed (see NEXT_STEPS_FOR_YOU, ARCHIVE_CANDIDATES).
**Full deployment order:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) — Phase 0–6 (prereqs → core → PMM pools → provider → optional → cW* → verify). **Full plan (required/optional/recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
**Last completable run (2026-03-02):** Config validation OK; on-chain 38/38; run-all-validation --skip-genesis OK; reconcile-env. **Preflight** and **run-all-next-steps-chain138.sh** run: preflight passed; mirror/pool present; 12 c* already GRU-registered; verification 38/38. Documentation: MASTER_INDEX, README, RUNBOOKS_MASTER_INDEX created; deprecated list and consolidation plan updated. Progress indicators (Step 1/4–4/4) in run-completable-tasks-from-anywhere.sh. E2E flow tasks script and doc updates (ADDRESS_MATRIX_AND_STATUS, RECOMMENDATIONS R2, NEXT_STEPS_FOR_YOU) completed. **Optional completed (2026-02-27 / 2026-03-01):** DeployCompliantFiatTokens (10 tokens); Blockscout verification; MCP allowlist-138; add-liquidity runbook; token-aggregation fallbacks + ENV_EXAMPLE_CONTENT; E2E routing verification; PMM_DEX_ROUTING_STATUS + REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS updated; cCADT line (commented) in DeployCompliantFiatTokens.s.sol. **Within-scope list (2026-02-27):** CompliantWrappedToken.sol; DeployCompliantFiatTokensForChain.s.sol (c* any chain); DeployCWTokens.s.sol (cWUSDT/cWUSDC); deploy-tokens-and-weth-all-chains-skip-canonical.sh extended with --deploy-c, --deploy-cw, 651940 env validation; TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS §6 implemented; ENV_EXAMPLE_CONTENT c*/cW*/651940 vars. **2026-02-27:** Deployment order doc, preflight script, deployment safety added; todos synced.
**Operator copy-paste commands:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) — one page with exact commands for every pending todo.
---
## First (before any Chain 138 deploy)
| # | Task | Owner | Ref |
|---|------|--------|-----|
| 0a | **Check deployer gas (Chain 138):** Run balance/gas check using **Core RPC only**. | Operator/LAN | `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` or `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh` |
| 0b | **Core Besu RPC (VMID 2101) use IP:port, not FQDN:** Set `RPC_URL_138=http://192.168.11.211:8545` in `smom-dbis-138/.env` for admin/deploy. Do not use `https://rpc-core.d-bis.org` for deployment (DNS/tunnel can fail; IP is direct to node). | Operator | [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md), [VMID_IP_FIXED_REFERENCE](../11-references/VMID_IP_FIXED_REFERENCE.md) |
| 0c | **Test all contracts before deploying:** Run from repo root (see commands below). Full run can take 5–15+ min; use `--no-match` for unit-only. | Anyone | [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8 |
**Test-all-contracts commands (from repo root):**
```bash
# Full build + test (can take 5–15+ minutes)
./scripts/deployment/test-all-contracts-before-deploy.sh
# Quick check: print commands only
./scripts/deployment/test-all-contracts-before-deploy.sh --dry-run
# Faster: unit tests only (skip Fork/Mainnet/Integration/e2e)
./scripts/deployment/test-all-contracts-before-deploy.sh --no-match "Fork|Mainnet|Integration|e2e"
# Include alltra-lifi-settlement
./scripts/deployment/test-all-contracts-before-deploy.sh --alltra
```
| 0 | **Before Chain 138 deploy:** Run preflight (RPC, dotenv, nonce, optional cost). Preflight defaults to `http://192.168.11.211:8545` when `RPC_URL_138` unset. | Anyone | `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`; [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0 |
---
## High priority
| # | Task | Owner | Ref |
@@ -26,7 +56,7 @@
|---|------|--------|-----|
| 3 | **LINK support on Mainnet relay:** Option A or B per runbook; implement, deploy, fund LINK; set `relaySupported: true` for LINK in token-mapping.json; update docs. | Operator/LAN | RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK |
| 4 | **Run "from anywhere" checks periodically:** `./scripts/run-completable-tasks-from-anywhere.sh` | Anyone | NEXT_STEPS_FOR_YOU §2 |
| 5 | **Placeholders (code):** Canonical addresses in token-aggregation (env); AlltraAdapter fee (setBridgeFee); smart accounts kit; quote service Fabric chainId; .bak (BAK_FILES_DEPRECATION). | Dev | REQUIRED_FIXES_UPDATES_GAPS |
| 5 | **Placeholders (code):** All done or documented per [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) §4: canonical addresses (env), AlltraAdapter setBridgeFee, smart accounts kit (env + runbook), quote service FABRIC_CHAIN_ID (default 999), .bak ([BAK_FILES_DEPRECATION.md](../../smom-dbis-138/docs/BAK_FILES_DEPRECATION.md)). | Dev | REQUIRED_FIXES_UPDATES_GAPS |
| 6 | **API keys:** Sign up per reports/API_KEYS_REQUIRED.md; add to `.env`. | Anyone | NEXT_STEPS_FOR_YOU §2 |
---
@@ -40,6 +70,42 @@
| 9 | **Operator tasks script:** `./scripts/run-all-operator-tasks-from-lan.sh [--deploy] [--create-vms]` | Operator/LAN | STEPS_FROM_PROXMOX_OR_LAN_WITH_SECRETS |
| 10 | **sendCrossChain (real):** `bash scripts/bridge/run-send-cross-chain.sh 0.01` (when PRIVATE_KEY and LINK ready) | Operator/LAN | NEXT_STEPS_OPERATOR W0-2 |
| 11 | **NPMplus backup:** `bash scripts/verify/backup-npmplus.sh` | Operator/LAN | NEXT_STEPS_OPERATOR W0-3 |
| 12 | **Mint tokens to deployer for liquidity/bridges:** See [TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER](../11-references/TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER.md) — Chain 138: owner mint (cUSDT, cUSDC, cEURC, …); Cronos: MintController (D-WIN W); other chains: acquire via wrap/bridge/DEX. | Operator/LAN | TOKENS_AND_NETWORKS_MINTABLE_TO_DEPLOYER |
---
## E2E Flows (Full Parallel)
All tasks from [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](TASKS_TO_INCREASE_ALL_E2E_FLOWS.md). Run in waves; within each wave run in **full parallel** when possible. Script: `./scripts/run-e2e-flow-tasks-full-parallel.sh [--dry-run]`.
| Wave | Tasks | Run in parallel |
|------|--------|-----------------|
| E0 | X1, X6, X7, A1 — RPC writable, TransactionMirror, deployer funded, Core RPC | Op |
| E1 | A2, A3, A4 — PMM pools create, register, add liquidity (Chain 138) | run-pmm-full-parity-all-phases.sh Phase 1 |
| E2 | B1, B2 — CCIP config and fund bridges (per chain parallel) | complete-config-ready-chains.sh, fund-ccip-bridges-with-link.sh |
| E3 | A5, B4, B5, C3, X8 — token-aggregation env, bridge routes, token mapping, quote API, token list | Code/Op |
| E4 | X2, X3, X4, X5 — Blockscout verify, E2E routing, explorer E2E, token-aggregation health | Op/LAN |
| E5 | X10, X11, X12 — cUSDT/cUSDC and PMM on L2s; token-aggregation for new chains | run-pmm-full-parity Phase 2 (parallel per chain) |
| E6 | B6, B7, C5, C6, C7 — Bridge UI, test bridge, destination DEX, full path quote UI, E2E test | Code/Op |
| E7 | X13, X14 — Update PMM_DEX_ROUTING_STATUS; runbooks | Doc |
Flow A (swap 138): A1–A6; A7–A8 optional. Flow B (bridge): B1–B7. Flow C (swap-bridge-swap): C1–C7 (depends on A+B).
---
## Token contract deployments (remaining)
Full list: [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md).
| # | Task | Owner | Ref |
|---|------|--------|-----|
| T1 | **DeployCompliantFiatTokens (Chain 138):** cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT. Prereq: CREATE2_FACTORY_ADDRESS. Use Core RPC (IP:port). | ✅ Done 2026-02-27 | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §1 |
| T2 | **Optional cCADT:** Uncomment cCADT line in DeployCompliantFiatTokens.s.sol and re-run script when needed (Tether-style CAD). | Dev/Op | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §1.2 |
| T3 | **cAUSDT:** Deploy or env when Alltra compliant USD token defined; no script in repo. | TBD | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §1.3 |
| T4 | **ACADT (ALL Mainnet 651940):** No script in repo; address TBD when Alltra adds CAD token. | TBD | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §2 |
| T5 | **cW* on public chains:** Deploy/bridge cW* per chain; create PMM edge pools per pool-matrix. | Operator | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §3 |
| T6 | **D-WIN W on 138/651940 (optional):** Extend DeployISO4217WSystem for Chain 138 or 651940 if desired. | Planned | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §4 |
| T7 | **Vault ac*/vdc*/sdc* for new base tokens:** After DeployCompliantFiatTokens, extend DeployAcVdcSdcVaults for each new base. | Operator/LAN | TOKEN_CONTRACT_DEPLOYMENTS_REMAINING §5 |
---
@@ -48,7 +114,7 @@
| # | Task | Owner | Ref |
|---|------|--------|-----|
| 12 | **AddressMapper on other chains:** Deploy via DeployAddressMapperOtherChain; set `mapper` in smart-contracts-master.json. (Cronos done.) | Planned | OPTIONAL_DEPLOYMENTS_START_HERE §A |
| 13 | **DODO PMM on 138:** Deploy DODOPMMIntegration; set env; create cUSDT/cUSDC pools; document in LIQUIDITY_POOLS_MASTER_MAP. | Planned | OPTIONAL_DEPLOYMENTS_START_HERE §B |
| 13 | **DODO PMM on 138:** Integration and pools **already deployed** (2026-02-28). Remaining: add liquidity (AddLiquidityPMMPoolsChain138 / run-pmm-full-parity); document in LIQUIDITY_POOLS_MASTER_MAP. | Planned | NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS |
| 14 | **Mainnet trustless stack:** Deploy Lockbox138 (138) + InboxETH, BondManager, LiquidityPoolETH (Mainnet) per runbook; fund liquidity. | Planned | OPTIONAL_DEPLOYMENTS_START_HERE §C |
---
@@ -82,7 +148,7 @@
| Phase 2 — Observability | Monitoring stack; Grafana via Cloudflare Access; alerts | ⏳ Pending |
| Phase 3 — CCIP fleet | CCIP Ops/Admin; commit/execute/RMN nodes; NAT pools | ⏳ Pending |
| Phase 4 — Sovereign tenants | Sovereign VLANs; tenant isolation; access control | ⏳ Pending |
| Missing containers | 2506, 2507, 2508 (Besu RPC) — see MISSING_CONTAINERS_LIST.md | High |
| ~~Missing~~ containers 2506–2508 | **Destroyed 2026-02-08**; replaced by new RPC structure (2101, 2201, 2301, 2303–2308, 2400–2403). RPC range 2500–2505 only. No create action. See [MISSING_CONTAINERS_LIST.md](../03-deployment/MISSING_CONTAINERS_LIST.md). | Done (doc only) |
---
@@ -115,15 +181,19 @@ Cron: `schedule-daily-weekly-cron.sh --install`; NPMplus backup: `schedule-npmpl
| Check | Command |
|-------|---------|
| Completable from anywhere | `./scripts/run-completable-tasks-from-anywhere.sh` |
| Validate (Proxmox SSH) | `bash scripts/run-via-proxmox-ssh.sh validate [--host IP]` — shellcheck (full) + genesis validation; installs jq/shellcheck on host if missing |
| All validation (CI) | `bash scripts/verify/run-all-validation.sh [--skip-genesis]` |
| Config files | `bash scripts/validation/validate-config-files.sh` |
| On-chain (Chain 138) | `./scripts/verify/check-contracts-on-chain-138.sh` |
| E2E routing | `./scripts/verify/verify-end-to-end-routing.sh` |
| **Test all contracts (before deploy)** | `./scripts/deployment/test-all-contracts-before-deploy.sh` — use `--dry-run` / `--no-match "Fork|Mainnet|Integration|e2e"` / `--alltra` |
---
## References
- [RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md](../03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md) — all recommendations and fixes before deploying smart contracts and PMM pools
- [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) — remaining token deployments by category
- [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md) — copy-paste commands for all operator/LAN tasks
- [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md) — full detail and completed items
- [NEXT_STEPS_MASTER.md](NEXT_STEPS_MASTER.md) — master list and phases

24
docs/00-meta/TODO_TASK_LIST_MASTER.md
View File

@@ -1,17 +1,23 @@
# Master TODO Task List
**Last Updated:** 2026-02-13
**Last Updated:** 2026-03-02
**Purpose:** Consolidated list of all fixes, enhancements, improvements, optimizations, recommendations, and missed steps.
**Full index (1–139):** [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md)
**Full index (1–139):** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md). **Full deployment order:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) (Phase 0–6); before deploy run `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`.
**Fully expanded checklist (everything conceivable):** **[MASTER_TODO_EXPANDED.md](MASTER_TODO_EXPANDED.md)** — Blitzkrieg Steps 0–19, R1–R23, tasks 1–30, Ledger 8–17, DEX/TransactionMirror, Tezos/CCIP, CONTRACT_NEXT_STEPS, GAPS, Supreme Command, Absolute Air Superiority, ALL_REQUIREMENTS, and validation commands.
**Execution mode: Full maximum parallel.** Run all remaining items in parallel by wave. See **[FULL_PARALLEL_EXECUTION_ORDER.md](FULL_PARALLEL_EXECUTION_ORDER.md)** for the ordered wave list (Wave 0 → Wave 1 → Wave 2 → Wave 3). Within each wave, execute every item concurrently; no artificial sequencing. Validation commands at bottom.
**Status:** [FULL_PARALLEL_RUN_LOG.md](../archive/00-meta-pruned/FULL_PARALLEL_RUN_LOG.md) (archived) | [WAVE1_COMPLETION_SUMMARY.md](WAVE1_COMPLETION_SUMMARY.md) | [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md) | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) (step-by-step; 2026-02-05 completion) | **[REMAINING_TASKS_AND_API_FEATURES.md](REMAINING_TASKS_AND_API_FEATURES.md)** (2026-02-10: consolidated remaining tasks + API features inventory).
**Status:** [FULL_PARALLEL_RUN_LOG.md](../archive/00-meta-pruned/FULL_PARALLEL_RUN_LOG.md) (archived) | [WAVE1_COMPLETION_SUMMARY.md](WAVE1_COMPLETION_SUMMARY.md) | [WAVE2_WAVE3_OPERATOR_CHECKLIST.md](WAVE2_WAVE3_OPERATOR_CHECKLIST.md) | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) (step-by-step; 2026-02-05 completion) | **[REMAINING_TASKS_AND_API_FEATURES.md](REMAINING_TASKS_AND_API_FEATURES.md)** (2026-02-10: consolidated remaining tasks + API features inventory). **Single plan (required/optional/recommended):** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
**2026-02-05:** Master documentation updated (MASTER_INDEX v5.8, docs/README, MASTER_PLAN, NEXT_STEPS_MASTER); "Can be accomplished now" list completed; 32 files archived to docs/archive/00-meta-status/.
**2026-02-23:** Placeholders/fixes sync: TODOS_CONSOLIDATED, NEXT_STEPS_AND_REMAINING_TODOS, NEXT_STEPS_FOR_YOU updated to reference REQUIRED_FIXES_UPDATES_GAPS §4 (canonical addresses, AlltraAdapter, smart accounts, quote FABRIC_CHAIN_ID, .bak — all Done or Documented). Remaining in-repo fixes complete; operator/LAN and deferred items unchanged.
**2026-02-28:** Master documentation refresh — MASTER_INDEX 6.6; REPOSITORIES_AND_PRS_CHAIN138; pr-ready (eip155-138 public RPC only, Trust Wallet); set-missing-dotenv-chain138.sh; deploy-bridges-config-ready-chains.sh; ENV_CONFIG_READY_CHAINS (Gnosis/Celo/Wemix); WHATS_LEFT_OPERATOR_AND_EXTERNAL, NEXT_STEPS_INDEX updated.
**2026-02-27:** Deployment order of operations ([DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md)) and preflight script (`preflight-chain138-deploy.sh`) added. Deployment safety: correct RPC (Core only), correct dotenv (smom-dbis-138/.env), gas/cost estimate before deploy, do not deploy when stuck. NEXT_STEPS_AND_REMAINING_TODOS, TODOS_CONSOLIDATED updated with next-steps table and 2026-02-27 completion.
---
## 1. Critical Fixes (Do First)
@@ -42,6 +48,16 @@
- [x] **Real transfer:** Omit `--dry-run` to execute sendCrossChain; documented in [scripts/README.md](../../scripts/README.md) §8. Ensure LINK approved for fee token if needed.
- [ ] **Paymaster (optional):** `forge script script/smart-accounts/DeployPaymaster.s.sol --rpc-url $RPC_URL_138 --broadcast` — requires contract sources; see [SMART_ACCOUNTS_DEPLOYMENT_NOTE.md](../../metamask-integration/docs/SMART_ACCOUNTS_DEPLOYMENT_NOTE.md)
### Undeployed contracts — pre-deployment (test, gas check, gas API, dry-run)
**Full checklist:** [UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md](../03-deployment/UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md)
- [x] **Check deployer wallet for gas** on Chain 138 and all target chains: `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`
- [x] **Use gas API to estimate** all undeployed contract deployment costs: `./scripts/deployment/get-multichain-gas-prices.sh`; optionally `update-gas-estimates.sh`; estimate per-script gas (forge/cast) for PMM pool creation, TransactionMirror, EnhancedSwapRouter, DODOPMMProvider, and any multichain cW*/PMM.
- [x] **Dry-run Chain 138 deployments:** `deploy-contracts-unified.sh --dry-run` (RPC + init fixes applied); DeployDeterministicCore simulated; PMM pool creation: set `DODO_PMM_INTEGRATION_ADDRESS` then `DRY_RUN=true ./scripts/create-all-dodo-pools-from-token-api.sh`; TransactionMirror script (no --broadcast); `deploy-optional-future-all.sh --dry-run`; `fund-ccip-bridges-with-link.sh --dry-run`.
- [ ] **Dry-run mainnet/multichain** (if applicable): `dry-run-mainnet-deployment.sh` (requires ETHEREUM_MAINNET_RPC, PRIVATE_KEY) or per-script `forge script ... --dry-run` for each target chain.
- [x] **Test not-deployed components:** Run `check-contracts-on-chain-138.sh` after any new deploy (36/36 present). Validate PMM pool creation path when pools created; DODOPMMProvider when implemented; TransactionMirror receive path after deploy; EnhancedSwapRouter when pools exist.
---
## 3. Verification Fixes (Applied — Verify)
@@ -131,7 +147,7 @@
- [ ] **Blitzkrieg trail:** Steps 0–19 (env freeze, canonical registry, token lists, GRU M1, CCIP, W-Tokens, wallet ingestion, Blockscout, bridge hardening, CI/CD, monitoring, security, dry-run done; optional Tezos/DODO)
- [ ] **Recommendations R1–R23:** Verification, single source of truth, on-chain check, secrets, RPC/gas/order, runbooks, automation, monitoring, tests, Sankofa/network placeholders
- [ ] **DEX / cross-chain:** TransactionMirror (Mainnet verify, Chain 138 deploy if needed); DODO (DODOPMMIntegration + Provider); EnhancedSwapRouter when pools exist; full trustless stack; Jumper/FABRIC_CHAIN_ID
- [ ] **DEX / cross-chain:** TransactionMirror (Mainnet verify, Chain 138 deploy if needed); DODO (DODOPMMIntegration + Provider); EnhancedSwapRouter when pools exist; full trustless stack; Jumper/FABRIC_CHAIN_ID. **Before any Chain 138 deploy:** run `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`; follow [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) Phase 0–6.
- [ ] **Tezos/CCIP:** External verification (CCIP/Jumper/LiFi); InitializeRegistry/DeployAllAdapters; Etherlink receivers; relay; DON; monitoring; testing
- [ ] **Supreme Command:** Deployment matrix, risk scoreboard, RAG dashboard, reconciliation, prod vs testnet, war-room
- [ ] **Absolute Air Superiority:** Sentinel, canonical anchoring, circuit breaker, stress test, time-to-containment, formal verification, sovereign continuity

2
docs/00-meta/WAVE2_WAVE3_OPERATOR_CHECKLIST.md
View File

@@ -30,7 +30,7 @@
| W2-3 | VLAN enablement: UDM Pro VLAN config; Proxmox bridge; migrate services | By VLAN / host | NETWORK_ARCHITECTURE.md §3–5; UDM_PRO_VLAN_* docs |
| W2-4 | Phase 3 CCIP: Ops/Admin (5400-5401); NAT pools; commit/execute/RMN scripts | Ops first, then NAT, then scripts | CCIP_DEPLOYMENT_SPEC.md |
| W2-5 | Phase 4: Sovereign tenant VLANs; isolation | By tenant/VLAN | After W2-3 |
| W2-6 | Missing containers: 3 VMIDs only (2506, 2507, 2508) — see MISSING_CONTAINERS_LIST.md | By VMID / host | MISSING_CONTAINERS_LIST.md |
| W2-6 | ~~2506–2508~~ Destroyed 2026-02-08; RPC 2500–2505 only. No action. | — | MISSING_CONTAINERS_LIST.md |
| W2-7 | DBIS services (10100–10151); Hyperledger | By host | Per deployment runbooks |
| W2-8 | NPMplus HA (Keepalived, 10234) | Optional | NPMPLUS_HA_SETUP_GUIDE.md |

59
docs/00-meta/WHATS_LEFT_OPERATOR_AND_EXTERNAL.md Normal file
View File

@@ -0,0 +1,59 @@
# What’s Left — Operator and External Only
**Last Updated:** 2026-02-28
**Purpose:** After completing in-repo and on-chain tasks (preflight, PMM pools, DODOPMMProvider, operator script NPMplus/backup/verify, Wemix re-check), these items require **operator (LAN/Proxmox/credentials)** or **you (third-party)**.
---
## Completed in this pass (2026-02-28)
- **Preflight:** Passed (RPC Core, dotenv, nonce consistent).
- **PMM pools:** All three created (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) and addresses documented.
- **DODOPMMProvider:** Deployed at `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; all three pools registered via `RegisterDODOPools.s.sol`.
- **Operator script:** NPMplus RPC fix + backup + Blockscout verify run (see `run-all-operator-tasks-from-lan.sh`).
- **Wemix:** Re-fetched scan.wemix.com/tokens; WWEMIX confirmed; doc updated.
- **Docs:** PRE_DEPLOYMENT_CHECKLIST, LIQUIDITY_POOLS_MASTER_MAP updated with new pool and provider addresses.
- **Dotenv:** `set-missing-dotenv-chain138.sh` run — DODO_PMM_PROVIDER_ADDRESS, POOL_* appended to `smom-dbis-138/.env`.
- **Repositories/PRs:** [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md) — Ledger, Trust, Chainlist, Consensys, CoinGecko/CMC, on-ramps/off-ramps (forms submitted; awaiting feedback).
- **Bridges:** ENV_CONFIG_READY_CHAINS.example filled with Gnosis/Celo/Wemix CCIP router, LINK, and WETH9/WETH10 (WXDAI, WCELO, WWEMIX). **Gnosis deployed 2026-02-28:** CCIPWETH9=0xE37c332a88f112F9e039C5d92D821402A89c7052, CCIPWETH10=0x04B2AE3c3bb3d70Df506FAd8717b0FBFC78ED7E6; destinations 138↔Gnosis configured. **Celo/Wemix:** Fund deployer with CELO (~0.1) and WEMIX (~0.4) then run `deploy-bridges-config-ready-chains.sh celo` and `wemix`, then `complete-config-ready-chains.sh`.
- **PR-ready:** [04-configuration/pr-ready/](../04-configuration/pr-ready/) — eip155-138.json (Chainlist) and trust-wallet-registry-chain138.json (Trust Wallet); see README for submission steps.
- **Maintenance:** `run-all-maintenance-via-proxmox-ssh.sh --e2e` was started via SSH; check `/tmp/proxmox-maintenance-out.log` for progress (steps 0–4 run; E2E runs at step 5).
---
## Operator / LAN only
| # | Task | Command / doc |
|---|------|----------------|
| 1 | **E2E 502 fix** | `./scripts/maintenance/run-all-maintenance-via-proxmox-ssh.sh --e2e` or `./scripts/maintenance/address-all-remaining-502s.sh --run-besu-fix --e2e` (requires SSH to Proxmox). Runbook: [502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md](502_DEEP_DIVE_ROOT_CAUSES_AND_FIXES.md). |
| 2 | **Celo, Wemix CCIP bridges** | Gnosis done. Per chain: fund deployer (CELO ~0.1, WEMIX ~0.4), run `deploy-bridges-config-ready-chains.sh [celo|wemix]`, then `complete-config-ready-chains.sh`, fund LINK. [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| 3 | **LINK support on Mainnet relay** | Option A or B per [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md); implement, deploy, fund; set `relaySupported: true` for LINK; restart relay. |
| 4 | **Set DODO_PMM_PROVIDER_ADDRESS in .env** | Run `./scripts/deployment/set-missing-dotenv-chain138.sh` to append provider and pool addresses (already run 2026-02-28). |
---
## External / third-party (you)
| # | Task | Doc |
|---|------|-----|
| 5 | **Ledger** | Tally form submitted; await response. Repos: LedgerHQ/ledger-live, app-ethereum, wallet-api; review repo: bis-innovations/LedgerLive. [ADD_CHAIN138_TO_LEDGER_LIVE](../04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md). |
| 6 | **Trust Wallet** | Open PR to [trustwallet/wallet-core](https://github.com/trustwallet/wallet-core). [ADD_CHAIN138_TO_TRUST_WALLET](../04-configuration/ADD_CHAIN138_TO_TRUST_WALLET.md). |
| 7 | **Consensys** | Outreach (contact form / business@consensys.io). [CONSENSYS_OUTREACH_PACKAGE](../../metamask-integration/docs/CONSENSYS_OUTREACH_PACKAGE.md). |
| 8 | **CoinGecko/CMC** | Submit via platform forms (not PR). [CMC_COINGECKO_SUBMISSION_RUNBOOK](../04-configuration/coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md). |
| 9 | **On-ramps/off-ramps** | Request Chain 138: MoonPay, Ramp, Transak, etc. (no public PR repos). [REPOSITORIES_AND_PRS_CHAIN138.md](REPOSITORIES_AND_PRS_CHAIN138.md). |
---
## Planned (when scoped)
- **AddressMapper on other chains** (Cronos done); deploy via DeployAddressMapperOtherChain.s.sol.
- **Mainnet trustless stack:** Lockbox138 + InboxETH, BondManager, LiquidityPoolETH (Mainnet).
- **Tezos/Etherlink:** InitializeRegistry, DeployAllAdapters; Etherlink receiver; relay services.
---
## Quick reference
- **Operator copy-paste:** [OPERATOR_READY_CHECKLIST.md](OPERATOR_READY_CHECKLIST.md).
- **Full deployment order:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md).
- **Full next steps:** [NEXT_STEPS_AND_REMAINING_TODOS.md](NEXT_STEPS_AND_REMAINING_TODOS.md).

231
docs/02-architecture/AI_AGENTS_57XX_DEPLOYMENT_TASKS.md Normal file
View File

@@ -0,0 +1,231 @@
# AI / Agents 57xx — Full Deployment Task List
**Last Updated:** 2026-02-26
**Source:** [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](AI_AGENTS_57XX_DEPLOYMENT_PLAN.md), [VMID_ALLOCATION_FINAL.md](VMID_ALLOCATION_FINAL.md)
**VMID band:** 5700–5999
This document is the **single ordered checklist** for deploying the full 57xx stack. Copy-paste commands and paths are ready for operators. Artifacts (compose files, agent script) live in **`scripts/57xx-deploy/`** and can be copied to target VMs.
---
## Prerequisites (all 57xx VMs)
- [ ] **A.1** Ubuntu/Debian with Docker Engine + Compose plugin.
- [ ] **A.2** Create standard dirs and install Docker (once per host):
```bash
sudo apt update
sudo apt install -y ca-certificates curl gnupg ufw
curl -fsSL https://get.docker.com | sudo sh
sudo usermod -aG docker $USER
# Log out/in or: newgrp docker
sudo mkdir -p /opt/ai/{mcp,inference,agent,state}/{config,data,logs}
sudo chown -R $USER:$USER /opt/ai
```
- [ ] **A.3** Network: ensure 5703 → 5701:3000, 5703 → 5702:8000, and 5701/5703 → 5704:5432,6379 are allowed (replace hostnames with your VM hostnames or IPs if needed).
---
## Task 1 — Repo and submodule (once per environment)
- [ ] **1.1** Clone proxmox repo with submodules, or from existing repo root init submodules:
```bash
# Option A: fresh clone
git clone --recurse-submodules <PROXMOX_REPO_URL> /opt/proxmox
# Option B: from repo root
git submodule update --init --recursive
```
- [ ] **1.2** Confirm submodule exists:
```bash
ls -la /opt/proxmox/ai-mcp-pmm-controller/README.md
# or from your workspace: <REPO_ROOT>/ai-mcp-pmm-controller/
```
---
## Task 2 — VM 5701 (MCP Hub) — required
- [ ] **2.1** On the host that will run VMID 5701 (or the machine playing 5701):
```bash
cd /opt/proxmox/ai-mcp-pmm-controller
# or: cd <REPO_ROOT>/ai-mcp-pmm-controller
```
- [ ] **2.2** Create logs dir:
```bash
mkdir -p logs
```
- [ ] **2.3** Create local `.env` (gitignored; do not commit secrets):
```bash
# Minimum:
RPC_URL=https://YOUR_CHAIN_RPC_URL
CHAIN=arbitrum
ALLOW_WRITE=false
EXECUTION_ARMED=false
```
- [ ] **2.4** (Optional) Edit `config/allowlist.json`: replace placeholder pool addresses and base/quote tokens before using pool tools.
- [ ] **2.5** Start the hub:
```bash
docker compose build --no-cache # first time or after Dockerfile change
docker compose --env-file .env up -d
```
- [ ] **2.6** Validate:
```bash
curl -fsS http://127.0.0.1:3000/health
# Expect: {"ok":true,"chain":"arbitrum"} (or your CHAIN value)
```
- [ ] **2.7** (Optional) Interface discovery once you have a pool address:
```bash
curl -sS http://127.0.0.1:3000/mcp/call \
-H 'content-type: application/json' \
-d '{"tool":"dodo.identify_pool_interface","params":{"pool":"0xPOOL"}}' | jq
```
Use `functions_found`, `notes`, and `detected_profile` to choose the right ABI/profile.
---
## Task 3 — VM 5704 (Memory/State) — optional
- [ ] **3.1** On VM 5704 host, create state dirs:
```bash
sudo mkdir -p /opt/ai/state/data/postgres /opt/ai/state/data/redis
sudo chown -R $USER:$USER /opt/ai/state
```
- [ ] **3.2** Copy compose and env from repo (or run `./scripts/57xx-deploy/copy-to-opt-ai.sh` from repo root):
```bash
# Option A: script (from repo root)
./scripts/57xx-deploy/copy-to-opt-ai.sh
# Option B: manual
cp /opt/proxmox/scripts/57xx-deploy/5704-state/docker-compose.yml /opt/ai/state/
cp /opt/proxmox/scripts/57xx-deploy/5704-state/.env.example /opt/ai/state/.env
# Edit .env: set POSTGRES_PASSWORD
```
- [ ] **3.3** Start state stack:
```bash
cd /opt/ai/state
docker compose up -d
docker compose ps
```
- [ ] **3.4** Validate:
```bash
pg_isready -h 127.0.0.1 -U ai -d ai
redis-cli -h 127.0.0.1 ping
```
---
## Task 4 — VM 5702 (Inference) — optional
- [ ] **4.1** On VM 5702 host, create model dir:
```bash
sudo mkdir -p /opt/ai/inference/data/models
sudo chown -R $USER:$USER /opt/ai/inference
```
- [ ] **4.2** Place a GGUF model at `/opt/ai/inference/data/models/model.gguf` (or adjust compose `command` for your filename).
- [ ] **4.3** Copy compose and start:
```bash
cp /opt/proxmox/scripts/57xx-deploy/5702-inference/docker-compose.yml /opt/ai/inference/
cd /opt/ai/inference
docker compose up -d
```
- [ ] **4.4** (Optional) Validate: `curl -sS http://127.0.0.1:8000/` (llama.cpp may not have `/health`).
---
## Task 5 — VM 5703 (Agent Worker) — optional
- [ ] **5.1** On VM 5703 host, copy agent config and compose:
```bash
cp /opt/proxmox/scripts/57xx-deploy/5703-agent/agent.py /opt/ai/agent/config/
cp /opt/proxmox/scripts/57xx-deploy/5703-agent/docker-compose.yml /opt/ai/agent/
cp /opt/proxmox/scripts/57xx-deploy/5703-agent/.env.example /opt/ai/agent/.env
```
- [ ] **5.2** Edit `/opt/ai/agent/.env`: set `MCP_URL` (e.g. `http://5701:3000/mcp/call`), `INF_URL` (e.g. `http://5702:8000`). If using 5704, set `PG_DSN` and/or `REDIS_URL`.
- [ ] **5.3** Edit `/opt/ai/agent/config/agent.py`: replace `POOL_ADDRESS_HERE` with a real allowlisted pool address when using `dodo.get_pool_state`.
- [ ] **5.4** Start agent:
```bash
cd /opt/ai/agent
docker compose up -d
docker logs -f ai-agent-prod
```
---
## Task 6 — Post-deploy validation
- [ ] **6.1** MCP (5701): `curl -fsS http://5701:3000/health` (or from 5701 host: `http://127.0.0.1:3000/health`).
- [ ] **6.2** State (5704): `pg_isready -h 5704 -U ai -d ai` and `redis-cli -h 5704 ping`.
- [ ] **6.3** Inference (5702): `curl -sS http://5702:8000/` if applicable.
- [ ] **6.4** Agent (5703): `docker logs --tail=50 ai-agent-prod` — no repeated errors.
---
## Task 7 — Hardening (before enabling write tools on 5701)
- [ ] **7.1** Pool allowlist populated and reviewed.
- [ ] **7.2** Max slippage, max notional per tx/day, cooldown, and circuit breaker (see [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](AI_AGENTS_57XX_DEPLOYMENT_PLAN.md) § Hardening checklist).
- [ ] **7.3** Only then set `ALLOW_WRITE=true` and `EXECUTION_ARMED=true` in 5701 `.env` and restart MCP.
---
## Artifact locations (in repo)
| VMID | Artifacts |
|------|-----------|
| 5701 | `ai-mcp-pmm-controller/` (submodule): `docker-compose.yml`, `Dockerfile`, `config/`, `.env` (local, gitignored) |
| 5704 | `scripts/57xx-deploy/5704-state/`: `docker-compose.yml`, `.env.example` |
| 5702 | `scripts/57xx-deploy/5702-inference/`: `docker-compose.yml` |
| 5703 | `scripts/57xx-deploy/5703-agent/`: `agent.py`, `docker-compose.yml`, `.env.example` |
**Copy all optional artifacts in one go:** from repo root run `./scripts/57xx-deploy/copy-to-opt-ai.sh` (creates `/opt/ai/*` dirs and copies 5704/5702/5703 files; does not overwrite existing `.env`).
---
## Quick reference — ports and callers
| VMID | Service | Port | Allowed callers |
|------|---------|------|-----------------|
| 5701 | MCP Hub | 3000 | 5702, 5703 |
| 5702 | Inference | 8000 | 5703 |
| 5704 | Postgres | 5432 | 5701, 5703 |
| 5704 | Redis | 6379 | 5701, 5703 |
---
**Owner:** Architecture
**See also:** [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](AI_AGENTS_57XX_DEPLOYMENT_PLAN.md) (Appendices A–F), [ai-mcp-pmm-controller/README.md](../../ai-mcp-pmm-controller/README.md)

90
docs/02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md Normal file
View File

@@ -0,0 +1,90 @@
# Smart Contracts and Blockchains for MCP Token/Pool Addresses
**Purpose:** What smart contracts must exist on which blockchains so the 5701 MCP hub can be given pool and token addresses in its allowlist.
**MCP behavior:** The MCP does **not** deploy contracts. It reads from existing contracts. You configure `config/allowlist.json` with one `chain` (e.g. `arbitrum`) and a list of pools; each pool has `pool_address`, `base_token`, `quote_token`, and `profile`. The MCP calls RPC on that chain to read pool state (getMidPrice, getOraclePrice, reserves, etc.) and token decimals. So **every address in the allowlist must point to an already-deployed contract** on the chosen chain.
---
## 1. What the MCP needs per pool
| Field | Meaning | Must exist on chain |
|-------|---------|---------------------|
| **pool_address** | PMM pool contract (DODO-style: getMidPrice, getOraclePrice, getBaseReserve, getQuoteReserve, _K_, _LP_FEE_RATE_, etc.) | Yes — one contract per pool |
| **base_token** | Base asset (e.g. cWUSDT, cUSDT) — ERC-20 | Yes |
| **quote_token** | Quote asset (e.g. USDC, USDT) — ERC-20 | Yes |
The MCP supports one chain at a time via `CHAIN` and `RPC_URL`. To support multiple chains you run multiple MCP instances (or one allowlist per chain and switch config).
---
## 2. Chain 138 (SMOM-DBIS-138)
| Item | Status | Notes |
|------|--------|--------|
| **DODOPMMIntegration** | Deployed | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` — creates and owns PMM pools |
| **Pools** | Created via integration | Call `createPool` / `createCUSDTCUSDCPool` etc.; pool addresses from creation or `pools(base, quote)` |
| **Base tokens (cUSDT, cUSDC, …)** | Deployed (core) | e.g. cUSDT `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`, cUSDC `0xf22258f57794CC8E06237084b353Ab30fFfa640b` (see [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md)) |
| **Quote tokens (USDT, USDC)** | On-chain | Use addresses from Chain 138 config / token API |
**Contracts you need to have (so the MCP has addresses):**
- **Already deployed:** DODOPMMIntegration; core compliant tokens (cUSDT, cUSDC, etc.).
- **You must do:** Create pools via DODOPMMIntegration (`createCUSDTCUSDCPool`, `createPool(cUSDT, USDT, ...)`, etc.). Then put in the MCP allowlist: each pool’s address, and the base/quote token addresses used for that pool.
No additional smart contracts need to be **deployed** for the MCP beyond what already exists on 138; you only need to **create pools** from the existing integration and then configure the MCP allowlist with those pool and token addresses.
---
## 3. Other blockchains (public chains with cW* design)
The **cross-chain-pmm-lps** design assumes per-chain **cW*** (bridged) tokens and **hub** stables (USDC/USDT), with **single-sided PMM pools** (cW* / hub) on each chain. `config/pool-matrix.json` and `config/deployment-status.json` list the chains and pairs. Today **deployment-status.json** has **no** addresses filled for these chains (1, 56, 137, 10, 100, 25, 42161, 42220, 1111, 43114, 8453).
So that the MCP can have token and pool addresses on a given public chain, the following must **exist** (be deployed or already there):
| What | Who deploys / source | Notes |
|------|----------------------|--------|
| **cW* tokens** (cWUSDT, cWUSDC, …) | Bridge (e.g. CCIP) or custom wrapper | Bridged representation of Chain 138 compliant tokens; address per chain. |
| **Hub stables** (USDC, USDT, …) | Usually already exist | Native Circle/Tether (or chain canonical) deployments; use canonical address per chain. |
| **PMM pool contracts** (one per pair) | You or DODO | DODO-style pool with getMidPrice, getOraclePrice, reserves, k, fee. Either: (a) deploy your own PMM factory + pools (e.g. DODO Vending Machine–compatible or custom), or (b) use existing DODO deployments on that chain if they match the MCP’s `dodo_pmm_v2_like` profile. |
**Blockchains in the design (pool-matrix / deployment-status):**
- **1** — Ethereum Mainnet
- **10** — Optimism
- **25** — Cronos
- **56** — BSC (BNB Chain)
- **100** — Gnosis Chain
- **137** — Polygon
- **1111** — Wemix
- **8453** — Base
- **42161** — Arbitrum One
- **42220** — Celo
- **43114** — Avalanche C-Chain
For **each** chain where you want the MCP to work you need:
1. **Token contracts:** Addresses for the cW* tokens (and any other base tokens) and for the hub quote tokens (USDC/USDT, etc.) on that chain.
2. **Pool contracts:** At least one PMM pool per pair you want to manage (e.g. cWUSDT/USDC, cWUSDC/USDC). Each pool must expose the view functions expected by the MCP’s pool profile (e.g. `dodo_pmm_v2_like`).
So: **no** new chain-specific contracts are “for the MCP” itself; the MCP only needs **addresses** of tokens and pools that already exist. On public chains those tokens and pools either must be **deployed** by you (or your bridge/PMM stack) or come from existing protocols (e.g. DODO) that match the MCP’s interface.
---
## 4. Summary table — “What must be deployed so the MCP has addresses”
| Blockchain | Smart contracts / actions needed so MCP has addresses |
|------------|--------------------------------------------------------|
| **Chain 138** | DODOPMMIntegration already deployed. **Create pools** via it (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC, etc.). Use existing cUSDT/cUSDC and chain USDT/USDC addresses. No extra contract deployment required. |
| **Ethereum (1), BSC (56), Polygon (137), Optimism (10), Gnosis (100), Cronos (25), Arbitrum (42161), Base (8453), Celo (42220), Wemix (1111), Avalanche (43114)** | (1) **cW* token** addresses on that chain (via your bridge or wrapper). (2) **Hub stable** addresses (USDC/USDT — usually exist). (3) **PMM pool** contracts per pair (deploy DODO-style or use existing DODO on that chain). Until these exist and are recorded (e.g. in deployment-status or allowlist), the MCP has nothing to point at on that chain. |
---
## 5. References
- MCP allowlist shape: `ai-mcp-pmm-controller/config/allowlist.json`
- MCP pool profile (view methods): `ai-mcp-pmm-controller/config/pool_profiles.json`
- Chain 138 tokens: `docs/11-references/CHAIN138_TOKEN_ADDRESSES.md`
- Chain 138 DODO: `smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md`, `smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md`
- Per-chain pool design: `cross-chain-pmm-lps/config/pool-matrix.json`, `cross-chain-pmm-lps/config/deployment-status.json`
- DEX/pool gaps: `docs/11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md`

2
docs/02-architecture/PROXMOX_HA_CLUSTER_ROADMAP.md
View File

@@ -121,4 +121,4 @@ So **yes — it should be full HA** if you want automatic failover and no single
- **Current:** Cluster only; no shared storage; no Proxmox HA; manual migration and manual restart after maintenance.
- **Target:** Full HA = shared storage + HA manager + HA resources so that when you power down an R630 (e.g. for DIMM B2 reseat), critical VMs/containers are restarted on another node automatically.
See also: [PROXMOX_CLUSTER_ARCHITECTURE.md](./PROXMOX_CLUSTER_ARCHITECTURE.md) (current cluster and “Future Enhancements”), [NPMPLUS_HA_SETUP_GUIDE.md](../04-configuration/NPMPLUS_HA_SETUP_GUIDE.md) (NPMplus-level HA with Keepalived).
See also: [PROXMOX_CLUSTER_ARCHITECTURE.md](./PROXMOX_CLUSTER_ARCHITECTURE.md) (current cluster and “Future Enhancements”), [NPMPLUS_HA_SETUP_GUIDE.md](../04-configuration/NPMPLUS_HA_SETUP_GUIDE.md) (NPMplus-level HA with Keepalived). For **13× R630 + DoD/MIL-spec** (full HA, Ceph, fencing, RAM/drives, STIG hardening), see **[R630_13_NODE_DOD_HA_MASTER_PLAN.md](./R630_13_NODE_DOD_HA_MASTER_PLAN.md)**.

273
docs/02-architecture/R630_13_NODE_DOD_HA_MASTER_PLAN.md Normal file
View File

@@ -0,0 +1,273 @@
# 13× R630 Proxmox Cluster — DoD/MIL-Spec HA Master Plan
**Last Updated:** 2026-03-02
**Document Version:** 1.0
**Status:** Active — Master plan for 13-node HA, RAM/storage, and DoD/MIL compliance
---
## 1. Executive Summary
This document defines the target architecture for a **13-node Dell PowerEdge R630** Proxmox cluster with:
- **Full HA and failover** (shared storage, HA manager, fencing, automatic recovery).
- **DoD/MIL-spec alignment** (STIG-style hardening, audit, encryption, change control, documentation).
- **RAM and drive specifications** for each R630 to support Ceph, VMs/containers, and growth.
**Scope:** All 13 R630s as Proxmox cluster nodes; optional separate management node (e.g. ml110) or integration of management on a subset of R630s. Design assumes **hyper-converged** (Proxmox + Ceph on same nodes) for shared storage and true HA.
---
## 2. Cluster Design — 13 Nodes
### 2.1 Node roles and quorum
| Item | Requirement |
|------|-------------|
| **Total nodes** | 13 × R630 |
| **Quorum** | Majority = 7. With 13 nodes, up to 6 can be down and cluster still has quorum. |
| **Fencing** | Required for HA: failed node must be fenced (power off/reboot) so Ceph and HA manager can safely restart resources elsewhere. |
| **Qdevice** | Optional: add a quorum device (e.g. small VM or appliance) so quorum survives more node failures; not required with 13 nodes but improves resilience. |
### 2.2 Recommended node layout
| Role | Node count | Purpose |
|------|------------|---------|
| **Proxmox + Ceph MON/MGR/OSD** | 13 | Every R630 runs Proxmox and participates in Ceph (MON, MGR, OSD) for shared storage. |
| **Ceph OSD** | 13 | Each node contributes disk as Ceph OSD; replication (e.g. size=3, min_size=2) across nodes. |
| **Proxmox HA** | 13 | HA manager can restart VMs/containers on any node; VM disks on Ceph. |
| **Optional dedicated** | 0 | No dedicated “monitor-only” nodes required; MON/MGR run on all or a subset (e.g. 3–5 MONs). |
### 2.3 Network and addressing
- **Management:** One subnet (e.g. 192.168.11.0/24) for Proxmox API, SSH, Ceph public/cluster.
- **Ceph:** Separate VLAN or subnet for Ceph cluster network (recommended for DoD: isolate storage traffic).
- **VLANs:** Same VLAN-aware bridge (e.g. vmbr0) on all nodes so VMs/containers keep IPs when failed over.
- **IP plan for 13 R630s:** Reserve 13 consecutive IPs (e.g. 192.168.11.11–192.168.11.23 for r630-01 … r630-13). Document in `config/ip-addresses.conf` and DNS.
---
## 3. RAM Specifications — R630
### 3.1 R630 memory capabilities (reference)
| Spec | Value |
|------|--------|
| **DIMM slots** | 24 (12 per socket in 2-socket) |
| **Max RAM** | Up to 1.5 TB (with compatible LRDIMMs) |
| **Typical configs** | 32 GB, 64 GB, 128 GB, 256 GB, 384 GB, 512 GB (depending on DIMM size and count) |
| **ECC** | Required for DoD/MIL; R630 supports ECC RDIMM/LRDIMM |
### 3.2 Recommended RAM per node (DoD HA + Ceph)
| Tier | RAM per node | Use case |
|------|----------------|---------|
| **Minimum** | 128 GB | Ceph OSD + a few VMs; acceptable for lab or light production. |
| **Recommended** | 256 GB | Production: Ceph (OSD + MON/MGR) + many VMs/containers; headroom for failover and recovery. |
| **High** | 384–512 GB | Heavy workloads, large Ceph OSD count per node, or when consolidating from existing 503 GB nodes. |
**Ceph guidance:** Proxmox/Ceph recommend **≥ 8 GiB per OSD** for OSD memory. With 6–8 OSDs per node (see storage), **48–64 GiB** for Ceph plus Proxmox and guest overhead → **128 GB minimum**, **256 GB recommended**.
**DoD/MIL note:** Prefer **256 GB per node** for 13-node production so that (1) multiple node failures still leave enough capacity for HA migrations and (2) Ceph recovery and rebalancing do not cause OOM or instability.
### 3.3 RAM placement (if mixing sizes)
If not all nodes have the same RAM:
- Put **largest RAM** in nodes that run the most VMs or Ceph MON/MGR.
- Ensure **at least 128 GB** on every node that runs Ceph OSDs.
- Document exact DIMM layout per node (slot, size, speed) for change control and troubleshooting.
---
## 4. Drive Specifications — R630
### 4.1 R630 drive options (reference)
- **Internal bays:** Typically 8 × 2.5" SATA/SAS (or 10-bay with optional kit); some configs support NVMe (e.g. 4 × NVMe via PCIe).
- **Boot:** 2 drives in mirror (ZFS mirror or hardware RAID1) for Proxmox OS — **redundant, DoD-compliant**.
- **Data:** Remaining drives for Ceph OSD and/or local LVM (if hybrid).
### 4.2 Recommended drive layout per R630 (full Ceph)
| Purpose | Drives | Type | Size (example) | Configuration |
|---------|--------|------|----------------|---------------|
| **Boot (OS)** | 2 | SSD | 240–480 GB each | ZFS mirror (preferred) or HW RAID1; Proxmox root only. |
| **Ceph OSD** | 4–6 | SSD (or NVMe) | 480 GB – 1 TB each | One OSD per drive; no RAID (Ceph provides replication). |
**Example per node:** 2 × 480 GB boot (ZFS mirror) + 6 × 960 GB SSD = 6 Ceph OSDs per node.
**Cluster total:** 13 × 6 = 78 OSDs; with replication 3×, usable capacity ≈ (78 × 0.9 TB) / 3 ≈ **~23 TB** (before bluestore overhead; adjust for actual sizes).
### 4.3 DoD/MIL storage requirements
- **Encryption:** At-rest encryption for sensitive data. Options: Ceph encryption (e.g. dm-crypt for OSD), or encrypted VMs (LUKS inside guest). Document which layers are encrypted and key management.
- **Integrity:** ZFS for boot (checksum, scrub). Ceph provides replication and recovery; use **bluestore** with checksums.
- **Sanitization:** Follow DoD 5220.22-M or NIST SP 800-88 for decommissioning/destruction of drives.
- **Spare:** Maintain spare drives and document replacement and wipe procedures.
### 4.4 Sizing for your workload
- **Current (from docs):** ~50+ VMIDs, mix of Besu, Blockscout, DBIS, NPMplus, etc.; growth ~20–50 GB/month.
- **Target:** Size Ceph pool so that **used + 2 years growth** stays &lt; 75% of usable. Example: 15–20 TB usable → ~5–7 TB used now + growth headroom.
---
## 5. Full HA and Failover Architecture
### 5.1 Components
| Component | Role |
|-----------|------|
| **Proxmox cluster** | 13 nodes; same cluster name; corosync for quorum. |
| **Ceph** | Shared storage: MON (3–5 nodes), MGR (2+), OSD on all 13. Replication size=3, min_size=2. |
| **Proxmox HA** | HA manager enabled; VMs/containers on Ceph added as HA resources; start/stop order and groups as needed. |
| **Fencing (STONITH)** | Mandatory: when a node is declared lost, fence device powers it off (or reboots) so Ceph and HA can safely reassign resources. Use Proxmox’s built-in fence agents (e.g. **fence_pve** with Proxmox API or IPMI/IDRAC). |
| **Network** | Redundant links where possible; same VLAN/bridge config on all nodes so failover does not change VM IPs. |
### 5.2 Ceph design (summary)
- **Pools:** At least one pool for VM/container disks (e.g. `ceph-vm`); optionally separate pool for backups or bulk data.
- **Replication:** size=3, min_size=2; tolerate 2 node failures without data loss (with 13 nodes).
- **Network:** Separate cluster network (e.g. 10.x or dedicated VLAN) for Ceph backend traffic; public for client (Proxmox) access.
- **MON/MGR:** 3 or 5 MONs (odd); 2 MGRs minimum. Spread across nodes for availability.
### 5.3 HA resource and failover behavior
- **HA resources:** Add each critical VM/CT as HA resource; define groups (e.g. “database first, then app”) and restart order.
- **Failure:** Node down → fencing → Ceph marks OSDs out → HA manager restarts VMs on other nodes using Ceph disks.
- **Maintenance:** Put node in maintenance → migrate VMs off (or let HA relocate) → fence not triggered; perform RAM/drive work.
### 5.4 What “full HA” gives you (DoD-relevant)
- **No single point of failure:** Storage replicated; compute can run on any node.
- **Automatic failover:** No manual migration for HA-managed guests.
- **Controlled maintenance:** Node can be taken down without losing services; documented procedures for patching and hardware changes.
---
## 6. DoD/MIL-Spec Compliance Framework
### 6.1 Alignment with DISA STIG / DoD requirements
DoD/MIL typically implies (summary; you must map to your exact ATO/contract):
| Area | Requirement | Implementation |
|------|-------------|----------------|
| **Hardening** | DISA STIG or equivalent for OS and applications | Apply STIG/CIS to Debian (Proxmox host) and guests; document exceptions. |
| **Authentication** | Strong auth, no default passwords, MFA where required | SSH key-only on Proxmox; no password SSH; RBAC in Proxmox; MFA for critical UIs if required. |
| **Access control** | Least privilege, RBAC, audit | Proxmox roles and permissions; separate admin vs operator; audit logs. |
| **Encryption** | TLS in transit; encryption at rest for sensitive data | TLS 1.2+ for API and Ceph; at-rest encryption (Ceph or LUKS) as required. |
| **Audit and logging** | Centralized, tamper-resistant, retention | rsyslog/syslog-ng to central log host; retention per policy; integrity (e.g. signed/hash). |
| **Change control** | Documented changes, rollback capability | Change tickets; config in Git; backups before changes; runbooks. |
| **Backup and recovery** | Regular backups, tested restore | Proxmox backups to separate storage; Ceph snapshots; DR runbook and tests. |
| **Physical and environmental** | Physical security, power, cooling | Out of scope for this doc; document in facility plan. |
### 6.2 Hardening checklist (Proxmox + Debian)
Use this as an operational checklist; align with your STIG version.
**Proxmox hosts (Debian base):**
- [ ] **SSH:** Key-only auth; PasswordAuthentication no; PermitRootLogin prohibit-password or key-only; strong ciphers/KexAlgorithms.
- [ ] **Firewall:** Restrict Proxmox API (8006) and SSH to management VLAN/CIDR; default deny.
- [ ] **Services:** Disable unnecessary services; only Proxmox, Ceph, corosync, and required dependencies.
- [ ] **Session timeout:** User session timeout (e.g. 900 s) in shell profile and/or Proxmox UI.
- [ ] **TLS:** TLS 1.2+ only; strong ciphers for pveproxy and Ceph.
- [ ] **Updates:** Security updates applied on a defined schedule; test in non-prod first.
- [ ] **FIPS:** If required by contract, use FIPS-validated crypto (kernel/openssl); document and test.
- [ ] **File permissions:** Sensitive files (keys, tokens) mode 600/400; no world-writable.
- [ ] **Audit:** auditd or equivalent for critical files and commands; logs to central host.
**Ceph:**
- [ ] **Auth:** Cephx enabled; key management per DoD key management policy.
- [ ] **Network:** Cluster network isolated; no Ceph ports exposed to user VLANs.
- [ ] **Encryption:** At-rest encryption for OSD if required; key escrow and rotation documented.
**Guests (VMs/containers):**
- [ ] **Per-guest hardening:** STIG/CIS per OS (e.g. Ubuntu, RHEL); documented baseline.
- [ ] **Secrets:** No secrets in configs in Git; use Vault or Proxmox secrets where applicable.
**Existing automation (this repo):** Use `scripts/security/run-security-on-proxmox-hosts.sh` (SSH key-only + firewall 8006), `scripts/security/setup-ssh-key-auth.sh`, and `scripts/security/firewall-proxmox-8006.sh`; extend to all 13 hosts and run with `--apply` after validating with `--dry-run`. Extend host list in scripts or via env (e.g. all R630 IPs).
### 6.3 Audit and documentation
- **Configuration baseline:** All Proxmox and Ceph configs in version control; changes via PR/ticket.
- **Runbooks:** Install, upgrade, add node, remove node, replace drive, fence test, backup/restore, disaster recovery.
- **Evidence:** Run STIG/CIS scans (e.g. OpenSCAP, Nessus) and retain reports for assessors.
- **Change log:** Document every change (who, when, why, ticket); link to runbook.
---
## 7. Phased Implementation
### Phase 1 — Prepare (no downtime)
1. **IP and DNS:** Assign and document 13 IPs for R630s; update `config/ip-addresses.conf` and DNS.
2. **RAM:** Upgrade all 13 R630s to at least 128 GB (256 GB recommended); document DIMM layout.
3. **Drives:** Install boot mirror (2 × SSD) and data drives (4–6 SSD per node) on each R630; configure ZFS mirror for boot.
4. **Proxmox install:** Install Proxmox VE on all 13; same version; join to one cluster; configure VLAN-aware bridge and management IPs.
5. **Hardening:** Apply SSH key-only, firewall, and STIG/CIS checklist to all nodes; document exceptions.
### Phase 2 — Ceph
1. **Ceph install:** Install Ceph on all 13 nodes (Proxmox Ceph integration); create MON (3 or 5), MGR (2), OSD (all nodes).
2. **Pools:** Create replication pool (size=3, min_size=2) for VM disks; add as Proxmox storage.
3. **Network:** Configure Ceph public and cluster networks; validate connectivity and latency.
4. **Tests:** Fill and drain; kill OSD/node and verify recovery; document procedures.
### Phase 3 — HA and fencing
1. **Fencing:** Configure fence_pve (or IPMI/IDRAC) for each node; test fence from another node.
2. **HA manager:** Enable HA in cluster; add critical VMs/containers as HA resources; set groups and order.
3. **Failover tests:** Power off one node; verify fencing and HA restart on another node; repeat for 2-node failure if desired.
4. **Runbooks:** Document failover test results and operational procedures.
### Phase 4 — Migrate workload
1. **Migrate disks:** Move VM/container disks from local storage to Ceph (live migration or backup/restore).
2. **Decommission local-only:** Once all HA resources are on Ceph, remove or repurpose local LVM for non-HA or cache.
3. **Monitoring and alerting:** Integrate with central monitoring; alerts for quorum loss, Ceph health, fence events, HA failures.
### Phase 5 — DoD/MIL continuous compliance
1. **Scans:** Schedule STIG/CIS scans; remediate and document exceptions.
2. **Backup and DR:** Automate backups; test restore quarterly; update DR runbook.
3. **Change control:** All changes via ticket + runbook; config in Git; periodic review of permissions and audit logs.
---
## 8. References and Related Docs
| Document | Purpose |
|----------|---------|
| [PROXMOX_HA_CLUSTER_ROADMAP.md](./PROXMOX_HA_CLUSTER_ROADMAP.md) | Current HA roadmap (3-node); extend to 13-node. |
| [PROXMOX_CLUSTER_ARCHITECTURE.md](./PROXMOX_CLUSTER_ARCHITECTURE.md) | Cluster and storage overview. |
| [PHYSICAL_DRIVES_AND_CONFIG.md](../04-configuration/PHYSICAL_DRIVES_AND_CONFIG.md) | Current drive layout (existing 2 R630s + ml110). |
| Proxmox Ceph documentation | [Ceph in Proxmox](https://pve.proxmox.com/pve-docs/chapter-pveceph.html). |
| Proxmox HA | [High Availability](https://pve.proxmox.com/pve-docs/chapter-ha-manager.html). |
| DISA STIG | [DISA STIGs](https://public.cyber.mil/stigs/); Debian/Ubuntu and application STIGs. |
| CIS Benchmarks | [CIS Benchmarks](https://www.cisecurity.org/cis-benchmarks); Debian, Proxmox if available. |
---
## 9. Summary Table
| Item | Specification |
|------|----------------|
| **Nodes** | 13 × Dell PowerEdge R630 |
| **Quorum** | Majority 7; up to 6 nodes can fail |
| **RAM per node** | Minimum 128 GB; **recommended 256 GB** (DoD production) |
| **Boot** | 2 × SSD (e.g. 240–480 GB) ZFS mirror per node |
| **Data (Ceph)** | 4–6 × SSD (e.g. 480 GB – 1 TB) per node, one OSD per drive |
| **Shared storage** | Ceph replicated (size=3, min_size=2) |
| **HA** | Proxmox HA manager; fencing (STONITH) required |
| **Hardening** | STIG/CIS alignment; SSH key-only; firewall; TLS; audit; change control |
| **Encryption** | TLS in transit; at-rest per policy (Ceph or LUKS) |
---
**Owner:** Architecture / Infrastructure
**Review:** Quarterly or when adding nodes / changing compliance scope
**Change control:** Update version and “Last Updated” when changing this plan; link change ticket.

81
docs/02-architecture/VMID_ALLOCATION_FINAL.md
View File

@@ -2,12 +2,27 @@
**Navigation:** [Home](/docs/01-getting-started/README.md) > [Architecture](/docs/01-getting-started/README.md) > VMID Allocation
**Last Updated:** 2025-01-20
**Document Version:** 1.0
**Last Updated:** 2026-02-26
**Document Version:** 1.1
**Status:** 🟢 Active Documentation
---
## VMID Quick Reference (Operational)
| Range | Purpose | Notes |
|------:|---------|-------|
| 3000–3003 | Monitor / RPC-adjacent (ml110 / ccip-monitor-1..4) | Within RPC/Gateways (2500–3499). Not CCIP DON. Not AI/Agents. |
| 5400–5599 | CCIP DON (Chainlink CCIP) | 5410–5429 Commit, 5440–5459 Execute, 5470–5476 RMN. |
| 5700–5999 | AI / Agents / Dev | Official band for model serving, MCP, agent runtimes. |
**Naming/Tags (recommended):**
- AI VMs: `ai-<role>-<env>` (e.g. `ai-mcp-prod`, `ai-inf-dev`, `ai-agent-prod`)
- Monitor/RPC-adjacent: `ccip-monitor-<n>`
- Proxmox tags: `AI`, `MCP`, `HF`, `MONITOR`, `PROD`/`DEV`
---
## Complete VMID Allocation Table
| VMID Range | Domain | Total VMIDs | Initial Usage | Available |
@@ -16,7 +31,7 @@
| 5000–5099 | Blockscout | 100 | 1 | 99 |
| 5200–5299 | Cacti | 100 | 1 | 99 |
| 5400–5599 | Chainlink CCIP | 200 | 1+ | 199 |
| 5700–5999 | (available / buffer) | 300 | 0 | 300 |
| 5700–5999 | AI / Agents / Dev (model serving, MCP, agent runtimes) | 300 | 1 | 299 |
| 6000–6099 | Fabric | 100 | 1 | 99 |
| 6200–6299 | FireFly | 100 | 1 | 99 |
| 6400–7399 | Indy | 1,000 | 1 | 999 |
@@ -41,10 +56,14 @@
- **1500-1503**: Initial sentries (4 nodes)
- **1504-2499**: Reserved for sentry expansion (996 VMIDs)
#### RPC / Gateways (2500-3499) - 1,000 VMIDs
- **2500-2502**: Initial RPC nodes (3 nodes)
- **2503-2505**: Besu RPC (HYBX; 3 nodes). **2506-2508 destroyed 2026-02-08** (no longer in use).
- **2509-3499**: Reserved for RPC/Gateway expansion
#### RPC / Gateways (Besu) — 2500–3499
- **2500–2508:** In-use RPC/Gateway nodes (2500–2502 initial; 2503–2505 HYBX; 2506–2508 destroyed 2026-02-08).
- **2509–2999:** Reserved for RPC/Gateway expansion
- **3000–3003:** **ml110 / monitor-style (RPC-adjacent)** — legacy/current usage
- Suggested naming: **ccip-monitor-1..4**
- **Not** the CCIP DON allocation (CCIP DON = **5400–5599**)
- **Not** the AI/Agents allocation (AI/Agents = **5700–5999**)
- **3004–3499:** Reserved for RPC/Gateway expansion
#### Archive / Telemetry (3500-4299) - 800 VMIDs
- **3500+**: Archive / Snapshots / Mirrors / Telemetry
@@ -78,10 +97,16 @@
---
### Available / Buffer (5700-5999) - 300 VMIDs
### AI / Agents / Dev — 5700–5999
- **5700**: Dev VM (shared Cursor dev + private Gitea for four users). See [DEV_VM_GITOPS_PLAN.md](../04-configuration/DEV_VM_GITOPS_PLAN.md).
- **5701-5999**: Reserved for future use / buffer space
This is the **official VMID range** for AI workloads, agent runtimes, MCP servers, and AI/dev experimentation. **Do not** place AI workloads in 3000–3099; that range is within RPC/Gateways expansion and includes legacy monitor/RPC-adjacent nodes (3000–3003).
- **5700:** Dev VM (existing). See [DEV_VM_GITOPS_PLAN.md](../04-configuration/DEV_VM_GITOPS_PLAN.md).
- **5701–5749:** AI platform services (model serving, MCP hub, auth, observability)
- **5750–5899:** AI applications (per-project agents, DODO PMM tooling, policy guardrails)
- **5900–5999:** Experiments / temporary / buffer
**Optional suggested layout:** 5701 = MCP Hub; 5702 = Inference (HF model server); 5703 = Agent Worker (orchestration); 5704 = Memory/State (Postgres/Redis/Vector DB). See [AI_AGENTS_57XX_DEPLOYMENT_PLAN.md](AI_AGENTS_57XX_DEPLOYMENT_PLAN.md) for copy/paste deployment steps (QEMU guest agent, 57xx layout, MCP/DODO PMM, read-only vs execution).
---
@@ -131,16 +156,18 @@ VMID_VALIDATORS_START=1000 # Besu validators: 1000-1499
VMID_SENTRIES_START=1500 # Besu sentries: 1500-2499
VMID_RPC_START=2500 # Besu RPC: 2500-3499
VMID_ARCHIVE_START=3500 # Besu archive/telemetry: 3500-4299
VMID_BESU_RESERVED_START=4300 # Besu reserved: 4300-4999
VMID_EXPLORER_START=5000 # Blockscout: 5000-5099
VMID_CACTI_START=5200 # Cacti: 5200-5299
VMID_CCIP_START=5400 # Chainlink CCIP: 5400-5599
VMID_BUFFER_START=5700 # Buffer: 5700-5999
VMID_FABRIC_START=6000 # Fabric: 6000-6099
VMID_FIREFLY_START=6200 # Firefly: 6200-6299
VMID_INDY_START=6400 # Indy: 6400-7399
VMID_SANKOFA_START=7800 # Sankofa/Phoenix/PanTel: 7800-8999
VMID_SOVEREIGN_CLOUD_START=10000 # Sovereign Cloud: 10000-13999
VMID_BESU_RESERVED_START=4300 # Besu reserved: 4300-4999
VMID_EXPLORER_START=5000 # Blockscout: 5000-5099
VMID_CACTI_START=5200 # Cacti: 5200-5299
VMID_CCIP_START=5400 # Chainlink CCIP: 5400-5599
VMID_AI_AGENTS_START=5700 # AI / Agents / Dev: 5700-5999 (model serving, MCP, agent runtimes)
# Optional alias for backward compatibility (deprecated):
# VMID_BUFFER_START=5700 # deprecated: use VMID_AI_AGENTS_START
VMID_FABRIC_START=6000 # Fabric: 6000-6099
VMID_FIREFLY_START=6200 # Firefly: 6200-6299
VMID_INDY_START=6400 # Indy: 6400-7399
VMID_SANKOFA_START=7800 # Sankofa/Phoenix/PanTel: 7800-8999
VMID_SOVEREIGN_CLOUD_START=10000 # Sovereign Cloud: 10000-13999
```
---
@@ -153,7 +180,7 @@ VMID_SOVEREIGN_CLOUD_START=10000 # Sovereign Cloud: 10000-13999
| Blockscout | 5000 | 5099 | 100 | 1 | 99 | 99.0% |
| Cacti | 5200 | 5299 | 100 | 1 | 99 | 99.0% |
| Chainlink CCIP | 5400 | 5599 | 200 | 1+ | 199 | 99.5% |
| Buffer | 5700 | 5999 | 300 | 0 | 300 | 100% |
| AI/Agents/Dev | 5700 | 5999 | 300 | 1 | 299 | 99.7% |
| Fabric | 6000 | 6099 | 100 | 1 | 99 | 99.0% |
| FireFly | 6200 | 6299 | 100 | 1 | 99 | 99.0% |
| Indy | 6400 | 7399 | 1,000 | 1 | 999 | 99.9% |
@@ -170,11 +197,16 @@ VMID_SOVEREIGN_CLOUD_START=10000 # Sovereign Cloud: 10000-13999
✅ **Future-proof** - Large buffers and reserved ranges
✅ **Modular design** - Each service has dedicated range
✅ **Sovereign Cloud Band** - 4,000 VMIDs for SMOM/ICCC/DBIS/Absolute Realms
✅ **AI/Agents band (5700–5999)** — Dedicated range for model serving, MCP, agent runtimes; 3000–3003 remain RPC/monitor-adjacent
---
## Migration Notes
**New Additions (v1.1):**
- **AI/Agents/Dev (5700–5999)** defined as the official band for AI inference, MCP, agent runtimes, vector DB, and AI platform services (not 3000–3099).
- **3000–3003** explicitly documented as **RPC/monitor-adjacent** (ml110 / ccip-monitor-1..4), not CCIP DON and not AI/Agents.
**Previous Allocations**:
- Validators: 106-110, 1100-1104 → **1000-1004**
- Sentries: 111-114, 1110-1113 → **1500-1503**
@@ -187,8 +219,13 @@ VMID_SOVEREIGN_CLOUD_START=10000 # Sovereign Cloud: 10000-13999
- Indy: 8000, 263 → **6400**
**New Additions**:
- Buffer: 5700-5999 (300 VMIDs)
- AI/Agents/Dev: 5700-5999 (300 VMIDs). **Use this band for AI inference, MCP, agent runtimes, vector DB; not 3000-3099.** Sub-ranges: 5701-5749 platform, 5750-5899 apps, 5900-5999 experiments. 3000-3003 remain RPC/monitor-adjacent (ml110/ccip-monitor-1..4).
- Sankofa/Phoenix/PanTel: 7800-8999 (1,200 VMIDs)
- Sovereign Cloud Band: 10000-13999 (4,000 VMIDs)
- **NPMplus Alltra/HYBX:** VMID 10235 (192.168.11.169). See [04-configuration/NPMPLUS_ALLTRA_HYBX_MASTER_PLAN.md](../04-configuration/NPMPLUS_ALLTRA_HYBX_MASTER_PLAN.md). NPMplus range: 10233 (primary), 10234 (HA secondary), 10235 (Alltra/HYBX).
---
**Owner:** Architecture
**Review cadence:** Quarterly or upon new VMID band creation
**Change control:** PR required; update Version + Last Updated

49
docs/03-deployment/ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md Normal file
View File

@@ -0,0 +1,49 @@
# Add Liquidity to PMM Pools (Chain 138) — Runbook
**Purpose:** Add base/quote liquidity to the three DODO PMM pools on Chain 138 (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
**Prerequisites:**
- Deployer has **cUSDT** and **cUSDC** (and optional official USDT/USDC) balance on Chain 138.
- `smom-dbis-138/.env` has: `PRIVATE_KEY`, `RPC_URL_138`, `DODO_PMM_INTEGRATION_ADDRESS` (or `DODO_PMM_INTEGRATION`), pool addresses and amounts.
---
## 1. Set pool addresses and amounts in .env
Add or set in `smom-dbis-138/.env`:
```bash
# Pool addresses (from PRE_DEPLOYMENT_CHECKLIST / create-all-pmm-pools-chain138.sh)
POOL_CUSDTCUSDC=0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8
POOL_CUSDTUSDT=0xa3Ee6091696B28e5497b6F491fA1e99047250c59
POOL_CUSDCUSDC=0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5
# Amounts (6 decimals; e.g. 1000000 = 1 USDT/USDC)
ADD_LIQUIDITY_BASE_AMOUNT=1000000
ADD_LIQUIDITY_QUOTE_AMOUNT=1000000
```
Optional per-pool overrides: `ADD_LIQUIDITY_CUSDTCUSDC_BASE`, `ADD_LIQUIDITY_CUSDTCUSDC_QUOTE`, etc.
---
## 2. Run the add-liquidity script
From repo root (or from `smom-dbis-138` with `RPC_URL_138` and `DODO_PMM_INTEGRATION` set):
```bash
cd smom-dbis-138
source .env
forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
```
Ensure the deployer has approved (or the script will approve) base/quote tokens to `DODOPMMIntegration` and has sufficient balance for the chosen amounts.
---
## 3. References
- [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) — `addLiquidity(pool, baseAmount, quoteAmount)`
- [PRE_DEPLOYMENT_CHECKLIST](PRE_DEPLOYMENT_CHECKLIST.md) § Step 3
- [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 3.1

45
docs/03-deployment/CONTRACT_DEPLOYMENT_RUNBOOK.md
View File

@@ -2,10 +2,14 @@
**Last Updated:** 2026-02-12
**Full deployment order:** For the canonical sequence (prerequisites → core → PMM/pools → provider → optional → cW* → verification) and remaining recommendations, see [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md).
**Deployment safety:** Use **RPC_URL_138** (Core only, from `smom-dbis-138/.env`) for all deployments; never use Public RPC. All secrets from **`smom-dbis-138/.env`** only. Run a gas/cost estimate before deploy (e.g. `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh`). **Do not deploy when transactions are stuck** — clear tx pool (`./scripts/clear-all-transaction-pools.sh`), wait ~60s, then retry; use scripts that check nonce when available.
## Chain 138 deployment requirements (learned 2026-02-12)
- **Gas price:** Chain 138 enforces a minimum gas price. Always use **`--with-gas-price 1000000000`** (1 gwei) for `forge script` and `forge create` when deploying to Chain 138; otherwise transactions fail with "Gas price below configured minimum gas price".
- **On-chain check:** After deployments, run `./scripts/verify/check-contracts-on-chain-138.sh` (uses `RPC_URL_138`; optional URL arg). Address list comes from `config/smart-contracts-master.json` when available. See [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [CONTRACT_INVENTORY_AND_VERIFICATION](../11-references/CONTRACT_INVENTORY_AND_VERIFICATION.md).
- **On-chain check:** After deployments, run `./scripts/verify/check-contracts-on-chain-138.sh` (uses `RPC_URL_138`; optional URL arg). Address list comes from `config/smart-contracts-master.json` when available. See [CONTRACT_ADDRESSES_REFERENCE](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [ADDRESS_MATRIX_AND_STATUS](../11-references/ADDRESS_MATRIX_AND_STATUS.md).
- **TransactionMirror:** The deploy script can hit a Forge broadcast constructor-args decode error. If so, deploy manually: `forge create contracts/mirror/TransactionMirror.sol:TransactionMirror --constructor-args <ADMIN_ADDRESS> --rpc-url $RPC_URL_138 --private-key $PRIVATE_KEY --gas-price 1000000000`.
## RPC Routing Summary
@@ -19,13 +23,16 @@ Chain 138 uses two standard env vars: **RPC_URL_138** (Core, admin/deploy) and *
## Prerequisites
1. **Network access** to Chain 138 RPC (set `RPC_URL_138` in .env, e.g. http://192.168.11.211:8545 for Core)
1. **.env check (keys only, no secrets printed):** From repo root: `./scripts/deployment/preflight-chain138-deploy.sh` (RPC, dotenv, nonce). Or from smom-dbis-138: `./scripts/deployment/check-env-required.sh` — verifies `PRIVATE_KEY`, `RPC_URL`, `RPC_URL_138` and optional PMM/mainnet/CCIP vars. Use **`smom-dbis-138/.env`** only for deploy secrets.
2. **Network access** to Chain 138 RPC (set `RPC_URL_138` in .env, e.g. http://192.168.11.211:8545 for Core)
- Run from a host on the same LAN as Proxmox, or via VPN
- WSL/remote dev environments may get "No route to host" if not on network
2. **PRIVATE_KEY** in `smom-dbis-138/.env` (deployer wallet with gas; same wallet holds LINK for bridge fees)
3. **PRIVATE_KEY** in `smom-dbis-138/.env` (deployer wallet with gas; same wallet holds LINK for bridge fees)
3. **Foundry** (`forge`) installed
4. **Foundry** (`forge`) installed
5. **Test all contracts before deploy (Phase 0.8):** Run `./scripts/deployment/test-all-contracts-before-deploy.sh` from repo root. This runs `forge build` and `forge test` in smom-dbis-138. Use `--dry-run` to print commands only; `--alltra` to include alltra-lifi-settlement; `--no-match "Fork|Mainnet|Integration|e2e"` for unit tests only. See [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8.
### Deprecated bridge (R4)
@@ -90,7 +97,31 @@ forge script script/smart-accounts/DeploySmartAccountsKit.s.sol --rpc-url $RPC_U
## TransactionMirror (Chain 138)
**Script:** `script/DeployTransactionMirror.s.sol`. If `forge script` fails with "Failed to decode constructor arguments", deploy via `forge create`:
**Script:** `script/DeployTransactionMirror.s.sol`. **Deployed address:** Set in `smom-dbis-138/.env` as `TRANSACTION_MIRROR_ADDRESS` from the script output (e.g. past deploys: `0xE362aa10D3Af1A16880A799b78D18F923403B55a`, `0x4eeF36BBaf706C6da5859cF9B34E9934fEC3E006`).
**Recommended:** Use the combined script; it **always checks nonce**, **validates RPC is active (chainId 138)**, uses **proper gas** (1 gwei min), and loads the **correct dotenv** (`smom-dbis-138/.env` + `config/ip-addresses.conf` for RPC fallbacks).
**Required in `smom-dbis-138/.env`:** `PRIVATE_KEY`, `RPC_URL_138` (Core RPC, 192.168.11.211:8545). No Public fallback for deployments. Optional: `GAS_PRICE` or `GAS_PRICE_138` (default 1000000000). Before deploying: if Core was read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
**If you see "Known transaction" or "Replacement transaction underpriced":** Clear the tx pool then retry: `./scripts/clear-all-transaction-pools.sh` (or RPC-only; see script). Run from a host that can reach `RPC_URL_138` (same LAN/VPN):
```bash
./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
```
This deploys TransactionMirror and creates the DODO cUSDT/cUSDC PMM pool, then runs on-chain verification. **Core RPC only** (no Public fallback). If Core is unreachable, fix read-only and health first (see RPC_2101_READONLY_FIX.md). Options: `--dry-run` (env, RPC, nonce only); `--force` (skip RPC check).
**Skip stuck nonce manually:** Set `NEXT_NONCE` to the next nonce (e.g. `13370`) so the script uses `vm.setNonce` and deploys at a new address; then set `TRANSACTION_MIRROR_ADDRESS` in `.env` to the logged address. The combined script already sets `NEXT_NONCE` from pending nonce.
Or run the two forge commands manually (ensure RPC is Chain 138 and nonce is correct):
```bash
cd smom-dbis-138 && source .env
# Optional: export NEXT_NONCE=<pending nonce> if avoiding a stuck tx
forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
```
If `forge script` fails with "Failed to decode constructor arguments", deploy via `forge create`:
```bash
cd smom-dbis-138
@@ -230,9 +261,9 @@ Deploy the [Stabilizer](../../smom-dbis-138/contracts/bridge/trustless/integrati
## Contract Verification (Blockscout)
Use the **Forge Verification Proxy** for `forge verify-contract` (Blockscout expects `module`/`action` in query; Forge sends JSON only).
Use the **Forge Verification Proxy** for `forge verify-contract` (Blockscout expects `module`/`action` in query; Forge sends JSON only). The verification script uses **canonical addresses** from `smom-dbis-138/.env` and `config/ip-addresses.conf` (ORACLE_PROXY, AGGREGATOR_ADDRESS, CCIP_SENDER, CCIPWETH9_BRIDGE_CHAIN138, etc.); run from a host on LAN that can reach Blockscout (192.168.11.140:4000).
**Preferred: orchestrated script (starts proxy if needed, timeout 600s):**
**Preferred: orchestrated script (starts proxy if needed, timeout 900s default):**
```bash
source smom-dbis-138/.env 2>/dev/null
./scripts/verify/run-contract-verification-with-proxy.sh

194
docs/03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md Normal file
View File

@@ -0,0 +1,194 @@
# Full Deployment Order of Operations
**Last Updated:** 2026-02-28
**Purpose:** Single canonical sequence for deploying and completing the system: prerequisites → Chain 138 core → PMM/pools → provider → optional → cW* → verification. Use this as the master order; other runbooks give per-step detail.
**Related:** [RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md](RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md) (all recommendations & fixes before deploy) | [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) (PMM/pools focus) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) (per-script detail) | [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md) (R1–R24)
---
## Deployment safety (required practices)
Before any Chain 138 deployment, follow these four rules:
| Rule | Requirement |
|------|-------------|
| **Correct RPC** | Use **only** `RPC_URL_138` from `smom-dbis-138/.env` for deployments. It must point to **Core RPC** (VMID 2101, `http://192.168.11.211:8545`). **Never** use `RPC_URL_138_PUBLIC` or Public RPC for deploying — Public is for bridge/monitoring/frontend only. See [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md). |
| **Correct dotenv** | All deployment secrets (`PRIVATE_KEY`, `RPC_URL_138`, `GAS_PRICE_138`, contract addresses) come from **`smom-dbis-138/.env`** only. Do not source a different .env for deploy. Env check: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. From repo root, pre-flight: `./scripts/deployment/preflight-chain138-deploy.sh`. |
| **Gas API / cost estimate** | Before deploying, run a **gas/cost estimation** for accurate deployment costs. **Chain 138:** minimum gas is 1 gwei; use `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md), [GAS_API_INTEGRATION_SUMMARY](../06-besu/GAS_API_INTEGRATION_SUMMARY.md)) to estimate total cost. For **other chains** (e.g. mainnet), use Etherscan/Infura Gas API where available. |
| **Do not deploy when stuck** | Check deployer **nonce** (pending vs latest). If there are pending/stuck transactions, run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that **check nonce** (e.g. `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). If you see "Replacement transaction underpriced" or "Known transaction", do **not** retry until the tx pool is cleared and nonce is consistent. |
---
## Overview
| Phase | Scope | When |
|-------|--------|------|
| **0** | Prerequisites & gates | Before any deploy |
| **1** | Chain 138 core (if not already deployed) | One-time or refresh |
| **2** | TransactionMirror + PMM pools (Chain 138) | Required for PMM routing |
| **3** | Liquidity + DODOPMMProvider | After pools exist |
| **4** | Optional: EnhancedSwapRouter, trustless, CCIP other chains | When dependencies exist |
| **5** | cW* edge pools (11 public chains) | When cW* tokens and infra exist |
| **6** | Post-deploy verification & recommendations | After each phase and ongoing |
---
## Phase 0 — Prerequisites (do first)
Execute in any order where no dependency; all must be satisfied before Phase 1–2.
| # | Item | Action |
|---|------|--------|
| 0.1 | **RPC 2101 (Core) writable** | If read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
| 0.2 | **Deployer wallet funded (Chain 138)** | ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
| 0.3 | **Env configured** | `smom-dbis-138/.env` only: `PRIVATE_KEY`, `RPC_URL_138` (Core); for PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Optional: `GAS_PRICE_138`, `GAS_PRICE`. Run: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Or from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`. |
| 0.4 | **Gas / cost estimate** | Run cost estimate before deploy: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md)). Chain 138 uses min 1 gwei; script gives estimated total cost. |
| 0.5 | **POOL_MANAGER_ROLE** | Deployer must have POOL_MANAGER_ROLE on DODOPMMIntegration for pool creation and provider registration. |
| 0.6 | **No stuck transactions** | If nonce has pending txs or "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait ~60s. Use Core RPC only (no Public fallback). Prefer deploy scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
| 0.7 | **Foundry** | `forge` in PATH; `cd smom-dbis-138 && forge build` succeeds. |
| 0.8 | **Test all contracts** | Run **before** any deploy: `./scripts/deployment/test-all-contracts-before-deploy.sh`. Runs `forge build` and `forge test` in smom-dbis-138 (includes **GRU c* integration tests**: `GRUCompliantTokensRegistryTest`); optionally alltra-lifi-settlement. Use `--dry-run` to print commands only. See [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) § Test before deploy. |
---
## Phase 1 — Chain 138 core (if not already deployed)
If core contracts are already deployed (36/38 present per verification), skip to Phase 2. Otherwise follow this order.
| # | Item | Script / command | Depends on |
|---|------|------------------|------------|
| 1.1 | **Phased core** | `01_DeployCore.s.sol` → set `UNIVERSAL_ASSET_REGISTRY`, `GOVERNANCE_CONTROLLER` in .env → `02_DeployBridges.s.sol` | Phase 0 |
| 1.2 | **Or: unified deploy** | `./scripts/deployment/deploy-contracts-unified.sh --mode ordered` | Phase 0 |
| 1.3 | **CCIP WETH9 bridge** | `GAS_PRICE=1000000000 ./scripts/deploy-and-configure-weth9-bridge-chain138.sh`; set `CCIPWETH9_BRIDGE_CHAIN138` | Phase 0 |
| 1.4 | **Deterministic (CREATE2) core** | `forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` | Phase 0 |
**Gas:** Always use `--with-gas-price 1000000000` (1 gwei) for Chain 138. See [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md).
---
## Phase 2 — TransactionMirror and PMM pools (Chain 138)
Required for PMM routing. Full steps: [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) §3.
**Run Phase 2 (and optional register c* + verify) in one go:** `./scripts/deployment/run-all-next-steps-chain138.sh` — preflight → mirror+pool → register c* as GRU → verify. Use `--skip-mirror` for pool-only (set `TRANSACTION_MIRROR_ADDRESS` in .env first). See [NEXT_STEPS_INDEX](../00-meta/NEXT_STEPS_INDEX.md) §3.
| # | Item | Command / script |
|---|------|------------------|
| 2.1 | **TransactionMirror** | `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` (deploys mirror + cUSDT/cUSDC pool), or run `DeployTransactionMirror.s.sol` only. Set `TRANSACTION_MIRROR_ADDRESS` in .env. If deploy fails with CreateCollision, see [TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md](TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md); use `--skip-mirror` for pool-only. |
| 2.2 | **PMM pools (all three)** | Either: (a) after 2.1 run `CreateCUSDTUSDTPool.s.sol` and `CreateCUSDCUSDCPool.s.sol`, or (b) `./scripts/deployment/create-all-pmm-pools-chain138.sh` (all three). Use Core RPC only. |
| 2.3 | **Record pool addresses** | Note each pool address for Phase 3 (DODOPMMProvider registration). |
| 2.4 | **Register c* as GRU (ERC-2535 integration)** | Set c* and token addresses in .env: `./scripts/deployment/set-dotenv-c-tokens-and-register-gru.sh` (or `--no-register` to only update .env). Then run RegisterGRUCompliantTokens (script runs it unless `--no-register`). **If registration reverts (empty data):** the proxy implementation may be older — upgrade first: `cd smom-dbis-138 && forge script script/deploy/UpgradeUniversalAssetRegistry.s.sol --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` (requires UPGRADER_ROLE). Then grant REGISTRAR_ROLE if needed (see script comment) and re-run set-dotenv script. See [GRU_M00_DIAMOND_FACET_MAP](../04-configuration/GRU_M00_DIAMOND_FACET_MAP.md); [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS](../04-configuration/GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md). |
---
## Phase 3 — Liquidity and DODOPMMProvider
| # | Item | Action |
|---|------|--------|
| 3.1 | **Add liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
| 3.2 | **Deploy DODOPMMProvider** | `forge script script/liquidity/DeployDODOPMMProvider.s.sol:DeployDODOPMMProvider --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. Set `DODO_PMM_PROVIDER_ADDRESS` in .env. |
| 3.3 | **Register pools** | For each pool (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC): call `provider.registerPool(tokenIn, tokenOut, poolAddress)` (via cast or script). |
| 3.4 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where the token-aggregation service runs; ensure indexer runs so API exposes pools. |
| 3.5 | **MCP allowlist (optional)** | Use `ai-mcp-pmm-controller/config/allowlist-138.json` (Chain 138 pools). Run with `ALLOWLIST_PATH=config/allowlist-138.json CHAIN=138`. See [README-allowlist-138.md](../../ai-mcp-pmm-controller/config/README-allowlist-138.md). |
---
## Phase 4 — Optional: EnhancedSwapRouter, trustless, CCIP other chains
Only when dependencies exist (Uniswap/Balancer on 138, or mainnet/other-chain RPC and env).
| # | Item | When / command |
|---|------|----------------|
| 4.1 | **EnhancedSwapRouter (Chain 138)** | When Uniswap V3 / Balancer pools exist on 138: deploy with chain-138–aware script (env quoter/poolId); configure post-deploy. See CONTRACT_DEPLOYMENT_RUNBOOK § EnhancedSwapRouter. |
| 4.2 | **Trustless stack (Lockbox138 + Mainnet)** | When Mainnet RPC and keys available: deploy trustless bridge contracts; set INBOX_ETH, BOND_MANAGER, etc. See [OPTIONAL_DEPLOYMENTS_START_HERE.md](../07-ccip/OPTIONAL_DEPLOYMENTS_START_HERE.md) §2C. |
| 4.3 | **CCIP other chains (Gnosis, Celo, Wemix)** | Deploy WETH bridges per chain; add destinations 138↔chain; fund LINK. See [CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md](../07-ccip/CONFIG_READY_CHAINS_COMPLETION_RUNBOOK.md). |
| 4.4 | **LINK on Mainnet relay** | [RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md](../07-ccip/RELAY_BRIDGE_ADD_LINK_SUPPORT_RUNBOOK.md). |
---
## Phase 5 — cW* edge pools (11 public chains)
Design and pool matrix: [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md). Per chain: deploy cW* tokens (or bridge), then create 6 “poolsFirst” + optional pools per [pool-matrix.json](../../cross-chain-pmm-lps/config/pool-matrix.json) and [06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
| # | Item | Action |
|---|------|--------|
| 5.1 | **Per-chain RPC and env** | Set `CHAIN_*_RPC_URL`, `CHAIN_*_DODO_PMM_INTEGRATION` (or pool source) for each of 1, 10, 25, 56, 100, 137, 42161, 42220, 43114, 8453, 1111 if indexing via token-aggregation. |
| 5.2 | **Deploy and fund** | Per chain: deploy or bridge cW* tokens; create and fund PMM pools per pool-matrix; add to MCP allowlist per chain if using MCP. |
---
## Phase 6 — Post-deploy verification and recommendations
After each deployment phase and periodically.
| # | Item | Command / doc |
|---|------|----------------|
| 6.1 | **On-chain verification (Chain 138)** | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]`. Target 38/38 when TransactionMirror and all three PMM pools exist. |
| 6.2 | **Blockscout verification** | When Blockscout reachable: `./scripts/verify/run-contract-verification-with-proxy.sh`. See [BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md). |
| 6.3 | **Update address docs** | Update [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md), [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md) with new pool and provider addresses. |
| 6.4 | **Recommendations (R1–R24)** | Follow [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md): verify on Blockscout, keep address refs updated, use correct RPC/gas, manage nonce, runbooks in sync, monitoring, testing, token mapping. |
| 6.5 | **Full recommendations list** | Optional and ongoing: [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) (~139 items, 20 sections); [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md) for copy-paste commands. |
---
## Remaining recommendations and suggestions to complete
Beyond the deployment order above, these are the main recommendation buckets. Complete as part of operations or when rolling out new features.
### Operator checklist (R1–R24)
- **Verification & source of truth (R1–R3):** Verify every contract on Blockscout; keep CONTRACT_ADDRESSES_REFERENCE and inventory updated; run check-contracts-on-chain-138.sh.
- **Security and secrets (R4–R7):** Use only canonical CCIPWETH9Bridge; never commit .env/keys; restrict deployer and RPC access.
- **Deployment (R8–R11):** Set RPC_URL_138 (Core); use gas 1 gwei on 138; phased core order (01 → 02); manage nonce if tx stuck.
- **Docs and runbooks (R12–R13):** Keep runbooks in sync with scripts and Blockscout URL; document addresses per chain.
- **Automation and CI (R14–R16):** Run verification after deploy in CI; consider env/config per environment.
- **Monitoring and ops (R17–R18):** Monitor bridge/oracle events; ensure Blockscout and /api are up.
- **Testing and quality (R19–R20):** Run forge test before deploy; NatSpec on public functions.
- **Config and DNS (R21–R22):** The Order/NPMplus proxy when deployed; document blocks #2–#6 if decided.
- **Quick wins (R23):** Progress indicators, --dry-run, config validation.
- **Token mapping (R24):** Keep config/token-mapping.json as single source of truth.
**Doc:** [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md).
### Full recommendations list (~139 items)
- **Proxmox / validated set:** Secure .env and validator keys, SSH key auth, firewall, VLANs, metrics, health, backup, runbooks (items 1–11 high; 12–20 medium; 21–35 low/quick wins).
- **Code quality & scripts:** Shebang, set -euo pipefail, script headers, shellcheck, consolidation, lib, perf (36–43).
- **Documentation:** Quick refs, decision trees, config templates, consolidation, API docs (44–47, 68–74).
- **Security & config:** Audit, validation, scanning, RBAC, config validation, templates, tests, CI (48–57).
- **Monitoring & DX:** Logging, metrics, health, DevContainer, backup review (58–67).
- **Placeholders & codebase:** Canonical addresses env-only, AlltraAdapter fee, smart accounts, quote Fabric chainId, .bak deprecation (87–91).
- **Other:** GRU M00 Diamond spine, CMC/CoinGecko submission, optional naming, Vault System Master Plan.
**Doc:** [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md). **Execution plan:** [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md).
### Copy-paste operator commands
For a single page of exact commands (CCIP bridges, LINK relay, Blockscout verify, 502 fix, DODO PMM, trustless, full operator tasks): [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md).
---
## Quick reference — deployment order summary
1. **Prerequisites:** RPC writable (Core only), deployer funded, **smom-dbis-138/.env** (no other dotenv), gas/cost estimate run, POOL_MANAGER_ROLE, **no stuck txs** (clear pool if needed), forge build.
2. **Chain 138 core:** 01_DeployCore → set env → 02_DeployBridges (or unified script); WETH9 bridge; deterministic if needed.
3. **PMM:** TransactionMirror + create all three PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC).
4. **Provider:** Add liquidity (optional) → deploy DODOPMMProvider → register pools → token-aggregation env → MCP allowlist (optional).
5. **Optional:** EnhancedSwapRouter (when Uniswap/Balancer on 138), trustless stack, CCIP other chains, LINK relay.
6. **cW*:** Per chain: deploy/bridge cW* tokens, create and fund pools per pool-matrix.
7. **Verify & recommendations:** check-contracts-on-chain-138.sh, Blockscout verify, update address docs, R1–R24, full recommendations list.
---
## References
| Doc | Purpose |
|-----|---------|
| [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) | PMM/pools/prerequisites and scripts |
| [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) | Per-script detail, gas, RPC, TransactionMirror |
| [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) | RPC fix, missing contracts, completion steps |
| [RECOMMENDATIONS_OPERATOR_CHECKLIST.md](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md) | R1–R24 |
| [ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md](../00-meta/ALL_RECOMMENDATIONS_AND_IMPROVEMENTS_LIST.md) | ~139 items |
| [OPERATOR_READY_CHECKLIST.md](../00-meta/OPERATOR_READY_CHECKLIST.md) | Copy-paste commands |
| [COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md](../00-meta/COMPLETE_REQUIRED_OPTIONAL_RECOMMENDED_INDEX.md) | Full plan execution order |
| [FULL_PARALLEL_EXECUTION_ORDER.md](../00-meta/FULL_PARALLEL_EXECUTION_ORDER.md) | Waves for parallel execution |

118
docs/03-deployment/NEXT_STEPS_PMM_FULL_PARITY_AND_ALL_POOLS.md Normal file
View File

@@ -0,0 +1,118 @@
# Next Steps: Full Parity and Deploy All PMM Pools
**Last Updated:** 2026-02-28
**Purpose:** Ordered list of steps to achieve full PMM parity and deploy all DODO PMM pools (Chain 138 first, then multichain).
---
## Current state
| Scope | DODOPMMIntegration | Pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | DODOPMMProvider | Liquidity |
|-------|--------------------|-----------------------------------------------|-----------------|-----------|
| **Chain 138** | Deployed (`0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`) | Created (addresses in .env / LIQUIDITY_POOLS_MASTER_MAP) | Deployed (`0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`) | **Zero** (pools empty) |
| **L2s (BSC, Polygon, Base, etc.)** | Script exists (`deploy-pmm-all-l2s.sh`) | Not created | Not deployed | N/A |
| **cW* mesh (11 chains)** | Design only | 111 pools in design | Not deployed | N/A |
**Full parallel runner (Phase 1 + Phase 2):** From `smom-dbis-138/` run `./scripts/deployment/run-pmm-full-parity-all-phases.sh`. Phase 1 creates the three PMM pools in parallel, registers them with DODOPMMProvider, then adds liquidity if `ADD_LIQUIDITY_BASE_AMOUNT` and `ADD_LIQUIDITY_QUOTE_AMOUNT` are set. Phase 2 runs each L2 (BSC, Polygon, Base, etc.) in parallel: deploy cUSDT/cUSDC then DODOPMMIntegration per chain. Use `RUN_PHASE1=0` or `RUN_PHASE2=0` to skip a phase; `DRY_RUN=1` to print only.
**References:** [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md), [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md), [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md), [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
---
## Phase 1: Chain 138 — Verify, add liquidity, and go live
1. **Confirm RPC and deployer**
- Use **Core RPC** only: `RPC_URL_138` (e.g. `http://192.168.11.211:8545`). See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
- If Core was read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`.
- Ensure deployer has gas and `POOL_MANAGER_ROLE` on DODOPMMIntegration.
2. **Verify or create the three PMM pools**
- Pools (from PRE_DEPLOYMENT_CHECKLIST / .env):
- cUSDT/cUSDC: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`
- cUSDT/USDT: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`
- cUSDC/USDC: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`
- If any pool is missing on-chain, create it:
- `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
- `forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
- `forge script script/dex/CreateCUSDCUSDCPool.s.sol:CreateCUSDCUSDCPool --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`
- Or use `./scripts/setup-dodo-pools.sh` (creates cUSDT/USDT and cUSDC/USDC; ensure OFFICIAL_USDT_ADDRESS and OFFICIAL_USDC_ADDRESS are set in .env for Chain 138).
3. **Register pools with DODOPMMProvider** (if not already)
- Set in .env: `POOL_CUSDTCUSDC`, `POOL_CUSDTUSDT`, `POOL_CUSDCUSDC`.
- Run: `forge script script/liquidity/RegisterDODOPools.s.sol:RegisterDODOPools --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"`.
4. **Add liquidity to all three pools**
- Approve base/quote tokens to `DODOPMMIntegration` (`0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`).
- Call `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)` for each pool. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md).
- **Forge script:** `forge script script/dex/AddLiquidityPMMPoolsChain138.s.sol:AddLiquidityPMMPoolsChain138 --rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY"` with env `ADD_LIQUIDITY_BASE_AMOUNT` and `ADD_LIQUIDITY_QUOTE_AMOUNT` (e.g. `1000000e6`). Or use **full-parity runner:** `./scripts/deployment/run-pmm-full-parity-all-phases.sh` (Phase 1 creates pools in parallel, registers, then adds liquidity when amounts are set).
5. **Optional: Deploy EnhancedSwapRouter (Chain 138)**
- Only after Uniswap/Balancer (or other DEX) pools exist on 138; configure quoter and pool IDs. See [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) §5.
6. **Update docs**
- Set [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) to “pools created” and “liquidity added” when done.
- Re-run `./scripts/verify/check-contracts-on-chain-138.sh` and fix any missing addresses (e.g. TransactionMirror, pool addresses in .env).
---
## Phase 2: Multichain — Deploy DODOPMMIntegration and pools on L2s
7. **Deploy cUSDT and cUSDC on each target chain** (if not already)
- Chains: BSC (56), Polygon (137), Base (8453), Optimism (10), Arbitrum (42161), Avalanche (43114), Cronos (25), Gnosis (100). See [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md).
- From `smom-dbis-138/`: `./scripts/deployment/deploy-cusdt-cusdc-all-chains.sh` or run `DeployCompliantUSDT.s.sol` and `DeployCompliantUSDC.s.sol` per chain with that chain’s RPC and chain ID.
- Record addresses in .env (e.g. `CUSDT_ADDRESS_137`, `CUSDC_ADDRESS_137` for Polygon).
8. **Deploy DODOPMMIntegration on each L2**
- From `smom-dbis-138/`: `./scripts/deployment/deploy-pmm-all-l2s.sh` (optionally with `--chain bsc polygon base` or set `DEPLOY_PMM_L2S_FILTER` in .env).
- Requires per-chain: `*_DODO_VENDING_MACHINE_ADDRESS` (or `DODO_VENDING_MACHINE_ADDRESS`), `*_OFFICIAL_USDT_ADDRESS`, `*_OFFICIAL_USDC_ADDRESS`; optional per-chain compliant addresses.
- Save each `DODOPMM_INTEGRATION_<CHAIN>` (or equivalent) in .env.
9. **Create the three PMM pool types on each L2**
- For each chain where DODOPMMIntegration is deployed: call `createCUSDTCUSDCPool`, `createCUSDTUSDTPool`, `createCUSDCUSDCPool` (or equivalent) via Forge script parameterized by that chain’s RPC and integration address.
- No single “create-all-pools-all-chains” script today; either add one or loop over chains and run the same Create* pool scripts with chain-specific env.
10. **Deploy DODOPMMProvider (and register pools) on each L2**
- Deploy provider per chain (e.g. `DeployDODOPMMProvider.s.sol` with that chain’s RPC), then run RegisterDODOPools with that chain’s pool addresses.
11. **Add liquidity on each L2**
- Same as Step 4, per chain: approve tokens to the integration, then `addLiquidity` for each pool.
---
## Phase 3: Chain 138 — Remaining pools (blocked until tokens exist)
12. **XAU and cEURT pools (blocked until tokens exist)**
- Deploy or obtain **XAU** and **cEURT** on Chain 138.
- Create public PMM pools: cUSDT/XAU, cUSDC/XAU, cEURT/XAU via `createPool(baseToken, quoteToken, ...)` on DODOPMMIntegration.
- Create private stabilization pools (PrivatePoolRegistry): cUSDT↔XAU, cUSDC↔XAU, cEURT↔XAU. See [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) and [LIQUIDITY_POOLS_MASTER_MAP.md](../11-references/LIQUIDITY_POOLS_MASTER_MAP.md).
13. **Bridge LP (optional)**
- Deploy full trustless stack including **LiquidityPoolETH** and fund it when swap–bridge–swap is required. See [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md).
---
## Phase 4: Cross-chain cW* PMM mesh (design / recipe only; not deployed)
14. **cW* edge pools on 11 public chains**
- 111 pools (66 first + 45 optional) across Ethereum, BSC, Polygon, Base, Optimism, Arbitrum, Avalanche, Cronos, Gnosis, Celo, Wemix. See [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) and [cross-chain-pmm-lps/docs/06-deployment-recipe.md](../../cross-chain-pmm-lps/docs/06-deployment-recipe.md).
- Prerequisites: cW* tokens and infrastructure on each chain; then deploy and fund per deployment recipe. Not in scope for “all PMM pools” parity until cW* is deployed.
---
## Summary checklist (full parity = Phase 1 + Phase 2)
| # | Step | Script / command |
|---|------|------------------|
| 1 | RPC + deployer ready (138) | `health-check-rpc-2101.sh`, `check-balances-gas-and-deploy.sh` |
| 2 | Verify or create 3 pools (138) | `CreateCUSDTCUSDCPool.s.sol`, `CreateCUSDTUSDTPool.s.sol`, `CreateCUSDCUSDCPool.s.sol` or `setup-dodo-pools.sh` |
| 3 | Register pools with DODOPMMProvider (138) | `RegisterDODOPools.s.sol` |
| 4 | Add liquidity to 3 pools (138) | `addLiquidity(pool, baseAmount, quoteAmount)` via cast or Forge script |
| 5 | Optional: EnhancedSwapRouter (138) | When DEX pools exist on 138 |
| 6 | Update PMM/routing docs | PMM_DEX_ROUTING_STATUS, CONTRACT_ADDRESSES_REFERENCE |
| 7 | Deploy cUSDT/cUSDC on L2s | `deploy-cusdt-cusdc-all-chains.sh` or per-chain Forge scripts |
| 8 | Deploy DODOPMMIntegration on L2s | `deploy-pmm-all-l2s.sh` |
| 9 | Create 3 pool types on each L2 | Per-chain Forge Create* pool scripts |
| 10 | Deploy DODOPMMProvider + register (each L2) | `DeployDODOPMMProvider.s.sol`, `RegisterDODOPools.s.sol` per chain |
| 11 | Add liquidity on each L2 | Same as Step 4, per chain |
**Full parity** for “all PMM pools” in the current design means: **Chain 138** — three pools created, registered, and **funded**; **each target L2** — integration deployed, three pools created, provider deployed and registered, and pools funded. Phase 3 (XAU/cEURT) and Phase 4 (cW* mesh) extend beyond this baseline.

175
docs/03-deployment/PRE_DEPLOYMENT_CHECKLIST.md Normal file
View File

@@ -0,0 +1,175 @@
# Pre-Deployment Checklist — DODO PMM, Pools, Provider, Router & APIs
**Last Updated:** 2026-02-28
**Purpose:** Single source of truth for component status and ordered steps required before deployment (Chain 138).
**See also:** [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) — full deployment order (Phase 0–6) and remaining recommendations.
### Deployment safety (required)
- **Correct RPC:** Use only **Core RPC** (`RPC_URL_138` = VMID 2101, e.g. `http://192.168.11.211:8545`). Never use Public RPC for deployments. Set in `smom-dbis-138/.env`.
- **Correct dotenv:** All secrets from **`smom-dbis-138/.env`** only. Check: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. Pre-flight from repo root: `./scripts/deployment/preflight-chain138-deploy.sh`.
- **Gas / cost estimate:** Run `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (or see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md)) before deploying for accurate cost estimates.
- **Do not deploy when stuck:** If nonce has pending txs or you see "Replacement transaction underpriced", run `./scripts/clear-all-transaction-pools.sh` then wait ~60s before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`).
---
## 1. Component status (current state)
| Component | Status | Address / Notes |
|-----------|--------|-----------------|
| **DODOPMMIntegration** | ✅ Deployed | Chain 138: `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (Mock DVM). |
| **PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC)** | ✅ Created | cUSDT/cUSDC: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8`; cUSDT/USDT: `0xa3Ee6091696B28e5497b6F491fA1e99047250c59`; cUSDC/USDC: `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5`. |
| **DODOPMMProvider** | ✅ Deployed | `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`; all three pools registered via `script/liquidity/RegisterDODOPools.s.sol`. |
| **EnhancedSwapRouter** | ❌ Not deployed | Mainnet-only script today; for Chain 138 deploy when Uniswap/Balancer pools exist; set quoter/poolId. |
| **Token-aggregation API** | ✅ Implemented, runnable | Single-hop quotes; can index DODO once pools exist (set `CHAIN_138_DODO_PMM_INTEGRATION`). |
| **Bridge quote (swap+bridge+swap)** | ✅ Implemented | `POST /api/bridge/quote`; on-chain coordinator optional. |
| **Cross-chain cW* mesh** | Design/tooling only | Edge pools and bots not deployed. |
---
## 2. Prerequisites before running deployment
- [ ] **RPC 2101 (Core) writable**
If Core was read-only: run
`./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then
`./scripts/maintenance/health-check-rpc-2101.sh`.
See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
- [ ] **Deployer wallet funded (Chain 138)**
At least ~0.006 ETH (5M gas × 1 gwei + buffer). Recommended 1–2 ETH.
Check: `./scripts/deployment/check-balances-gas-and-deploy.sh` (from `smom-dbis-138`).
- [ ] **Env set in `smom-dbis-138/.env` only**
Required: `PRIVATE_KEY`, `RPC_URL_138` (must be Core RPC, not Public).
For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`.
Optional: `GAS_PRICE_138` or `GAS_PRICE` (default 1 gwei).
After TransactionMirror deploy: set `TRANSACTION_MIRROR_ADDRESS` from script output.
Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`.
- [ ] **Gas / cost estimate run**
Before deploying: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` for estimated deployment cost (Chain 138 min gas 1 gwei).
- [ ] **Deployer has POOL_MANAGER_ROLE on DODOPMMIntegration**
Pool creation and (if used) DODOPMMProvider registration require this role.
- [ ] **No stuck transactions**
Do not deploy if there are pending/stuck txs. If you see "Replacement transaction underpriced" or stuck nonce: run `./scripts/clear-all-transaction-pools.sh` then wait ~60s before re-running deploy. Use scripts that check nonce when available.
---
## 3. Steps to complete before deployment (in order)
### Step 1: Deploy TransactionMirror (if not already deployed)
```bash
cd smom-dbis-138
export RPC_URL_138="${RPC_URL_138:-http://192.168.11.211:8545}"
forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price 1000000000
```
- Save the logged TransactionMirror address to `smom-dbis-138/.env` as `TRANSACTION_MIRROR_ADDRESS`.
### Step 2: Create PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC)
Use **Core RPC only** (no Public fallback). Either use the combined script (Step 2a) or run each pool script (Step 2b).
**2a) Combined (TransactionMirror + cUSDT/cUSDC pool only):**
```bash
./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
```
This deploys TransactionMirror then creates **only** the cUSDT/cUSDC pool. For the other two pools use 2b.
**2b) Create each pool manually** (e.g. after 2a, or if mirror already deployed):
```bash
cd smom-dbis-138
export DODO_PMM_INTEGRATION="${DODO_PMM_INTEGRATION_ADDRESS:-0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D}"
export RPC_URL_138="${RPC_URL_138:-http://192.168.11.211:8545}"
export GAS_PRICE="${GAS_PRICE_138:-${GAS_PRICE:-1000000000}}"
# cUSDT/cUSDC
forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
# cUSDT/USDT
forge script script/dex/CreateCUSDTUSDTPool.s.sol:CreateCUSDTUSDTPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
# cUSDC/USDC
forge script script/dex/CreateCUSDCUSDCPool.s.sol:CreateCUSDCUSDCPool \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
```
If you see “Replacement transaction underpriced”, wait for the pending tx to be mined or clear the tx pool, then retry (optionally with higher gas). After each creation, note the pool address for Step 4.
### Step 3: Add liquidity to pools (optional but recommended)
Use `DODOPMMIntegration.addLiquidity(pool, baseAmount, quoteAmount)` for each pool. Approve base/quote tokens to the integration contract first. See [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md).
### Step 4: Deploy DODOPMMProvider and register pools
```bash
cd smom-dbis-138
forge script script/liquidity/DeployDODOPMMProvider.s.sol:DeployDODOPMMProvider \
--rpc-url "$RPC_URL_138" --broadcast --private-key "$PRIVATE_KEY" --with-gas-price "$GAS_PRICE"
```
Save the logged address as `DODO_PMM_PROVIDER_ADDRESS` in `.env`. Then, for each pool (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC), call:
```solidity
provider.registerPool(tokenIn, tokenOut, poolAddress);
```
(e.g. via `cast send` or a small script) so that `getQuote` / `executeSwap` work for those pairs.
### Step 5: EnhancedSwapRouter (optional, when Uniswap/Balancer exist on 138)
Current deploy script is mainnet-only (`block.chainid == 1`). For Chain 138:
- When Uniswap V3 / Balancer pools exist on 138, add or use a Chain-138–aware deploy script (env-based quoter/poolId).
- Run with `--rpc-url $RPC_URL_138` and configure quoter and Balancer poolId after deploy.
See [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) § EnhancedSwapRouter.
### Step 6: Token-aggregation API (DODO indexing)
- Ensure `CHAIN_138_DODO_PMM_INTEGRATION=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (or equivalent) is set where the token-aggregation service runs. Optional: `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE` (see token-aggregation `.env.example` and [dex-factories.ts](../../smom-dbis-138/services/token-aggregation/src/config/dex-factories.ts)).
- Once pools exist, the service can index DODO pools from DODOPMMIntegration and expose single-hop quotes.
### Step 7: On-chain verification
After any new deployment:
```bash
./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
```
Target: all expected addresses (e.g. 38/38 when TransactionMirror and DODO cUSDT/cUSDC pool are present). Update [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) and [CONTRACT_ADDRESSES_REFERENCE.md](../11-references/CONTRACT_ADDRESSES_REFERENCE.md) with new pool and provider addresses.
---
## 4. Script reference
| Script | Purpose |
|--------|---------|
| `scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` | Deploy TransactionMirror + create cUSDT/cUSDC pool (Core RPC only). |
| `smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol` | Create cUSDT/cUSDC pool. |
| `smom-dbis-138/script/dex/CreateCUSDTUSDTPool.s.sol` | Create cUSDT/USDT pool. |
| `smom-dbis-138/script/dex/CreateCUSDCUSDCPool.s.sol` | Create cUSDC/USDC pool. |
| `smom-dbis-138/script/liquidity/DeployDODOPMMProvider.s.sol` | Deploy DODOPMMProvider (then register pools). |
| `smom-dbis-138/script/bridge/trustless/DeployEnhancedSwapRouter.s.sol` | Deploy EnhancedSwapRouter (mainnet-only; Chain 138 needs env/config). |
| `scripts/verify/check-contracts-on-chain-138.sh` | Verify expected contract addresses on Chain 138. |
---
## 5. References
- [POOLS_AND_NETWORKS_FULL_DESIGN.md](../11-references/POOLS_AND_NETWORKS_FULL_DESIGN.md) — Every pool and network in the full design (61 pools, 6 networks).
- [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md) — RPC fix, missing contracts, completion steps.
- [UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md](UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md) — Dry-run and validation tasks.
- [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) — Full PMM/DEX routing status.
- [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) — Pool creation, liquidity, swap usage.
- [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) — EnhancedSwapRouter & DODOPMMProvider config.

141
docs/03-deployment/RECOMMENDATIONS_AND_FIXES_BEFORE_DEPLOY.md Normal file
View File

@@ -0,0 +1,141 @@
# Recommendations and Fixes Before Deploying Smart Contracts and PMM Pools
**Last Updated:** 2026-02-27
**Purpose:** Single checklist of all **recommendations** and **required fixes** to complete before deploying smart contracts and PMM pools on Chain 138 (and related chains). Use this with [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) and [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md).
**Related:** [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § First (0a–0c) | [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) | [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md)
**Run all checkable items:** `./scripts/deployment/run-before-deploy-checks.sh` ([§7](#7-run-all-checkable-items-one-script)).
---
## 1. Mandatory fixes and checks (do first)
These must be satisfied before **any** Chain 138 deployment. Run preflight once; repeat if RPC, env, or nonce change.
| # | Item | Action / fix |
|---|------|--------------|
| **1.1** | **Run preflight** | From repo root: `./scripts/deployment/preflight-chain138-deploy.sh [--cost]`. Verifies: dotenv exists, required env keys, RPC returns chainId 0x8a (138), deployer nonce (warns if stuck). Use `--cost` for gas/cost estimate. |
| **1.2** | **Core RPC = IP:port, not FQDN** | In `smom-dbis-138/.env` set `RPC_URL_138=http://192.168.11.211:8545` (Core RPC, VMID 2101). Do **not** use `https://rpc-core.d-bis.org` for deployment (DNS/tunnel can fail). See [RPC_ENDPOINTS_MASTER](../04-configuration/RPC_ENDPOINTS_MASTER.md), [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § 0b. |
| **1.3** | **Deployer gas (Chain 138)** | Ensure deployer has ≥ ~0.006 ETH (recommended 1–2 ETH). Check: `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` or `cd smom-dbis-138 && ./scripts/deployment/check-balances-gas-and-deploy.sh`. |
| **1.4** | **Env from smom-dbis-138/.env only** | All deploy secrets from **`smom-dbis-138/.env`** only. Required: `PRIVATE_KEY`, `RPC_URL_138`. For PMM: `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Optional: `GAS_PRICE_138`, `GAS_PRICE` (default 1 gwei). Verify: `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh`. |
| **1.5** | **No stuck transactions** | If nonce has pending txs or you see "Replacement transaction underpriced": run `./scripts/clear-all-transaction-pools.sh` then wait **~60s** before deploying. Prefer scripts that check nonce (e.g. `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`). |
| **1.6** | **RPC 2101 (Core) writable** | If Core was read-only: `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md). |
| **1.7** | **Test all contracts** | Run **before** any deploy: `./scripts/deployment/test-all-contracts-before-deploy.sh`. Use `--dry-run` to print commands; `--no-match "Fork|Mainnet|Integration|e2e"` for unit-only; `--alltra` to include alltra-lifi-settlement. See [DEPLOYMENT_ORDER_OF_OPERATIONS](DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 0.8. |
| **1.8** | **Gas / cost estimate** | Before deploying: `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` (Chain 138 min gas 1 gwei). See [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md). |
| **1.9** | **POOL_MANAGER_ROLE** | Deployer must have `POOL_MANAGER_ROLE` on DODOPMMIntegration for pool creation and DODOPMMProvider registration. |
| **1.10** | **Foundry** | `forge` in PATH; `cd smom-dbis-138 && forge build` succeeds. |
---
## 2. Deployment safety (four rules)
| Rule | Requirement |
|------|-------------|
| **Correct RPC** | Use **only** `RPC_URL_138` from `smom-dbis-138/.env` for deployments. Must point to **Core RPC** (VMID 2101, `http://192.168.11.211:8545`). Never use Public RPC for deploying. |
| **Correct dotenv** | All deployment secrets from **`smom-dbis-138/.env`** only. Do not source a different .env for deploy. |
| **Gas / cost** | Run gas/cost estimation before deploying (e.g. `calculate-costs-consolidated.sh`). Chain 138 minimum gas 1 gwei. |
| **Do not deploy when stuck** | Clear tx pool, wait ~60s; use scripts that check nonce when available. |
---
## 3. Identified gaps to fix or confirm before deploy
| Gap | Location / scope | Fix / action |
|-----|------------------|--------------|
| **Wemix (1111) token addresses** | config/token-mapping-multichain.json | Confirm WETH, USDT, USDC on [scan.wemix.com/tokens](https://scan.wemix.com/tokens); update config and WEMIX_TOKEN_VERIFICATION.md if different; run `validate-config-files.sh`. |
| **Canonical addresses** | token-aggregation, .env | Canonical token addresses (e.g. CUSDC_ADDRESS_138, CUSDT_ADDRESS_138) in env or smart-contracts-master.json; token-aggregation uses env override. See [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) §3. |
| **AlltraAdapter setBridgeFee** | AlltraAdapter.sol | Fee configurable via `setBridgeFee(uint256)`; operator calls after deploy. Set `ALLTRA_BRIDGE_FEE`, `ALLTRA_ADAPTER_CHAIN138` in .env. |
| **Smart accounts / Paymaster** | DeploySmartAccountsKit | Script reads `ENTRY_POINT`, `SMART_ACCOUNT_FACTORY`, `PAYMASTER` from env. Deploy ERC-4337 contracts separately and set in .env. |
| **Quote service FABRIC_CHAIN_ID** | bridge/quote-service | Uses `FABRIC_CHAIN_ID` from env (default 999). Set when Fabric is live. |
| **CCIPWETH9Bridge** | Env / runbook | Use only canonical bridge (e.g. `0x971c...`); do **not** use deprecated `0x89dd...`. Set `CCIPWETH9_BRIDGE_CHAIN138` in env. See RECOMMENDATIONS_OPERATOR_CHECKLIST R4. |
| **Token mapping** | config/token-mapping.json | Single source of truth for 138↔Mainnet; when adding tokens update token-mapping.json and optionally CHAIN138_TOKEN_ADDRESSES. R24. |
---
## 4. Token deployments remaining (prerequisites for full token/PMM coverage)
If you plan to deploy **additional** tokens or vaults after core + PMM, ensure prerequisites and order. Full list: [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md).
| Category | Prerequisite | Notes |
|----------|-------------|--------|
| **DeployCompliantFiatTokens (cEURC, cEURT, cGBP*, cAUD*, cJPY*, cCHF*, cCADC, cXAU*)** | `CREATE2_FACTORY_ADDRESS` (e.g. from DeployDeterministicCore) | Use Core RPC (IP:port). After deploy: update CHAIN138_TOKEN_ADDRESSES and env. |
| **Optional cCADT** | Add to DeployCompliantFiatTokens.s.sol if needed | Tether-style CAD. |
| **Vault ac* / vdc* / sdc*** | Base tokens deployed (e.g. cUSDC, cUSDT, then extra compliant) | DeployAcVdcSdcVaults; extend for each new base. |
| **cW* on public chains** | Per-chain RPC, bridge, pool-matrix | Design in POOLS_AND_NETWORKS_FULL_DESIGN; pool-matrix in cross-chain-pmm-lps. |
| **ACADT / ALL Mainnet** | Alltra ecosystem | No script in repo; address TBD when Alltra adds CAD token. |
---
## 5. PMM-specific: before adding liquidity and provider
| # | Item | Action |
|---|------|--------|
| 5.1 | **DODOPMMIntegration** | Already deployed: `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`. Ensure `DODO_PMM_INTEGRATION_ADDRESS` set in .env. |
| 5.2 | **PMM pools (all three)** | cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC must be **created** (CreateCUSDTCUSDCPool, CreateCUSDTUSDTPool, CreateCUSDCUSDCPool). Use Core RPC only. |
| 5.3 | **DODOPMMProvider** | Deploy via DeployDODOPMMProvider.s.sol; set `DODO_PMM_PROVIDER_ADDRESS` in .env. Register each pool: `provider.registerPool(tokenIn, tokenOut, poolAddress)`. |
| 5.4 | **Liquidity (optional)** | Per pool: approve base/quote to DODOPMMIntegration, then `addLiquidity(pool, baseAmount, quoteAmount)`. See [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md). |
| 5.5 | **Token-aggregation** | Set `CHAIN_138_DODO_PMM_INTEGRATION` where token-aggregation runs so API indexes DODO pools. |
---
## 6. Operator recommendations (R1–R24) — before and after deploy
**Before deploy:** R8 (RPC Core), R9 (gas 1 gwei), R10 (phased core order), R11 (nonce if stuck), R19 (forge test).
**After deploy:** R1 (verify on Blockscout), R2 (update CONTRACT_ADDRESSES_REFERENCE, ADDRESS_MATRIX_AND_STATUS), R3 (run check-contracts-on-chain-138.sh), R12–R13 (runbooks and per-chain docs).
**Security:** R4 (canonical CCIPWETH9Bridge only), R5 (never commit .env/keys), R7 (restrict deployer and RPC access).
**Ongoing:** R17 (monitor bridge/oracle events), R18 (Blockscout and /api up), R24 (token-mapping.json source of truth).
Full list: [RECOMMENDATIONS_OPERATOR_CHECKLIST](../00-meta/RECOMMENDATIONS_OPERATOR_CHECKLIST.md).
---
## 7. Run all checkable items (one script)
From repo root, run every check that can be automated (preflight, env, forge build, contract tests, config validation). Optionally include gas estimate, alltra e2e, and on-chain verification.
```bash
# All checkable items (unit tests only; ~1–2 min)
./scripts/deployment/run-before-deploy-checks.sh
# With gas/cost estimate
./scripts/deployment/run-before-deploy-checks.sh --cost
# With alltra-lifi-settlement tests (longer)
./scripts/deployment/run-before-deploy-checks.sh --alltra
# With on-chain verification (Chain 138)
./scripts/deployment/run-before-deploy-checks.sh --on-chain
```
The script reports **PASS** or **FAIL** per step and exits 0 only if all steps pass. Remaining items (deployer gas, POOL_MANAGER_ROLE, RPC writable if needed) require operator/LAN; see §1 and §2.
---
## 8. Quick command reference
| Action | Command |
|--------|---------|
| Preflight (RPC, env, nonce, optional cost) | `./scripts/deployment/preflight-chain138-deploy.sh [--cost]` |
| Deployer balance / funding plan (Chain 138) | `RPC_URL_138=http://192.168.11.211:8545 ./scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh` |
| Env check (smom-dbis-138) | `cd smom-dbis-138 && ./scripts/deployment/check-env-required.sh` |
| Test all contracts | `./scripts/deployment/test-all-contracts-before-deploy.sh` (options: `--dry-run`, `--no-match "Fork|Mainnet|Integration|e2e"`, `--alltra`) |
| Gas/cost estimate | `cd smom-dbis-138 && ./scripts/deployment/calculate-costs-consolidated.sh` |
| Clear stuck tx pool | `./scripts/clear-all-transaction-pools.sh` then wait ~60s |
| On-chain verification (Chain 138) | `./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]` |
| Config validation | `bash scripts/validation/validate-config-files.sh` |
---
## 9. References
- [DEPLOYMENT_ORDER_OF_OPERATIONS.md](DEPLOYMENT_ORDER_OF_OPERATIONS.md) — Phase 0–6 full order
- [PRE_DEPLOYMENT_CHECKLIST.md](PRE_DEPLOYMENT_CHECKLIST.md) — PMM/pools steps and script reference
- [CONTRACT_DEPLOYMENT_RUNBOOK.md](CONTRACT_DEPLOYMENT_RUNBOOK.md) — Per-script detail and test-before-deploy
- [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) — First (0a–0c), token deployments (T1–T7), high/medium priority
- [REQUIRED_FIXES_UPDATES_GAPS](../REQUIRED_FIXES_UPDATES_GAPS.md) — Build/code placeholders and gaps (all done or documented)
- [TOKEN_CONTRACT_DEPLOYMENTS_REMAINING](../11-references/TOKEN_CONTRACT_DEPLOYMENTS_REMAINING.md) — Remaining token deployments by category
- [OPERATOR_READY_CHECKLIST](../00-meta/OPERATOR_READY_CHECKLIST.md) — Copy-paste commands for operator/LAN tasks

42
docs/03-deployment/REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md Normal file
View File

@@ -0,0 +1,42 @@
# Required Fixes and Deployments — Status
**Last Updated:** 2026-02-28
## Required fixes
### 1. RPC 2101 (Core) — read-only filesystem
- **Status:** Not fixed (host storage I/O errors).
- **Fix before deploying:** Run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. No Public RPC fallback for contract deployments.
- **Fix:** See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
### 2. Stuck transactions
- **Scripts:** `./scripts/clear-all-transaction-pools.sh` (validators + 2101 + 2201); `./scripts/clear-rpc-2201-txpool.sh`. Deploy script sets `NEXT_NONCE` from pending nonce automatically.
---
## On-chain verification (Chain 138)
**Last run (2026-03-01):** `./scripts/verify/check-contracts-on-chain-138.sh` (use Core RPC URL or run from LAN).
**Result:** **38 present, 0 missing** (38 addresses). TransactionMirror: `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc`. DODO cUSDT/cUSDC pool: `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` (created). **DeployCompliantFiatTokens** was run 2026-02-27 (10 tokens: cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT); see [CHAIN138_TOKEN_ADDRESSES](../11-references/CHAIN138_TOKEN_ADDRESSES.md).
---
## Deployments (Chain 138)
| Item | Address | Status |
|------|---------|--------|
| TransactionMirror | `0x7131F887DBEEb2e44c1Ed267D2A68b5b83285afc` | Deployed 2026-02-27. Set `TRANSACTION_MIRROR_ADDRESS` in smom-dbis-138/.env. |
| DODO cUSDT/cUSDC pool | 0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8 | Created (all three PMM pools exist). Add liquidity via [ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK](ADD_LIQUIDITY_PMM_CHAIN138_RUNBOOK.md). |
| Compliant Fiat (10 tokens) | See CHAIN138_TOKEN_ADDRESSES | Deployed via DeployCompliantFiatTokens 2026-02-27. |
---
## Completion (run from LAN)
0. **If Core RPC was read-only:** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh` (must pass). See [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
1. Optional: `./scripts/clear-all-transaction-pools.sh` then wait 60s if nonce stuck.
2. `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` (Core RPC only; checks nonce, RPC, gas; deploys mirror then pool).
3. Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env` to the logged address.
4. `./scripts/verify/check-contracts-on-chain-138.sh` (pass Core RPC URL or use RPC_URL_138) — target 38 present when both confirmed.

57
docs/03-deployment/RPC_2101_READONLY_FIX.md Normal file
View File

@@ -0,0 +1,57 @@
# RPC 2101 (Core) — Read-only filesystem fix
**VMID 2101** (192.168.11.211, Chain 138 Core RPC) can fail with Besu in a crash loop and **port 8545 connection refused**. Root cause observed: **Read-only file system** on `/data/besu/database/`.
## Cause
- **Kernel I/O errors** on the host (Proxmox 192.168.11.11): `Buffer I/O error on device dm-*`, `EXT4-fs: failed to convert unwritten extents`, `potential data loss`.
- ext4 remounts the filesystem **read-only** to avoid further corruption. Besu then fails with:
`RocksDBException: While appending to file: /data/besu/database/... : Read-only file system`.
- Besu may also crash at startup with **JNA**: `UnsatisfiedLinkError: Failed to create temporary file for ... libjnidispatch.so: Read-only file system` — JNA needs a writable temp dir (e.g. `/tmp` or `java.io.tmpdir`); if the whole root is ro, startup fails before RPC binds.
## Before deploying contracts
Contract deployments use **Core RPC only** (no Public fallback). Fix read-only and verify health first:
1. **Fix read-only:** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh`
2. **Health check:** `./scripts/maintenance/health-check-rpc-2101.sh` (must pass)
3. **Deploy:** `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`
If you get **"Known transaction"** (stuck tx at deployer nonce), clear the Core RPC tx pool: `./scripts/clear-all-transaction-pools.sh` then retry deploy.
## Fixing 2101 (operator)
1. **SSH to Proxmox host:** `ssh root@192.168.11.11`
2. **Check kernel logs for I/O errors:**
`dmesg | grep -E "Buffer I/O|EXT4-fs|dm-"`
Identify which dm-* (LV) is affected; `ls -la /dev/mapper/pve-vm--2101--disk--0` shows 2101’s device (e.g. dm-45).
3. **Storage health:** Check LVM and disks (e.g. `lvs`, `pvs`, `smartctl` on underlying disks). Replace or repair failing hardware.
4. **Remount read-write (only if storage is known good):**
- Stop the container: `pct stop 2101`
- From the host, the container root is mounted by Proxmox; after fixing storage you may need to run `fsck` on the LV or reboot the host. If the filesystem was remounted ro due to transient error, sometimes a container stop/start helps (host remounts the LV).
- Start the container: `pct start 2101`
- Inside container verify: `pct exec 2101 -- touch /data/besu/database/.write_test && rm /data/besu/database/.write_test`
5. **Restart Besu RPC:**
`pct exec 2101 -- systemctl restart besu-rpc.service`
Then: `./scripts/check-network-rpc-138.sh 192.168.11.211 8545`
### If still read-only after make-writable
If `make-rpc-vmids-writable-via-ssh.sh` completes but inside the container **`/tmp`, `/data/besu/database`, or `/data/besu/tmp`** are still read-only (`touch` fails with "Read-only file system"):
- **e2fsck** may have reported `Error writing file system info: Input/output error` — the **underlying storage** (LV or disk on the host) may be failing.
- **Thin pool 100% full:** CT 2101 (and other RPC nodes) use the LVM thin pool **pve/data**. If the pool is 100% full (`lvs pve/data` shows Data% 100.00), writes can fail and the kernel may remount the filesystem read-only. **Fix:** On the Proxmox host, extend the pool if the VG has free space: `lvextend -L +80G pve/data` (adjust size). Then re-run make-writable and restart the container. Alternatively migrate the CT to another pool (e.g. thin1) or free space by removing/moving other LVs.
- On the Proxmox host: check `dmesg | grep -E 'I/O error|dm-|ext4'`, and run `smartctl` / LVM checks on the storage backing the CT. If the LV or disk has persistent I/O errors, fix or replace storage, then re-run `make-rpc-vmids-writable-via-ssh.sh`, or migrate the CT to healthy storage.
## TransactionMirror address
Set `TRANSACTION_MIRROR_ADDRESS` in `smom-dbis-138/.env` from the deploy script output. A previous deploy used **0xE362aa10D3Af1A16880A799b78D18F923403B55a**; use the script output as source of truth.
## Scripts
- **Make Core writable (fix read-only):** `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` — run first when 2101 is read-only.
- **Health check:** `./scripts/maintenance/health-check-rpc-2101.sh` — container, service, port, RPC eth_chainId/eth_blockNumber, and database writability.
- **Fix/restart Besu:** `./scripts/maintenance/fix-core-rpc-2101.sh` [--dry-run] [--restart-only].
- **Check/start RPC service:** `./scripts/check-and-start-rpc-2101.sh` (cannot fix read-only; only restarts the service).
- **Network check:** `./scripts/check-network-rpc-138.sh [HOST] [PORT]` (default 192.168.11.211 8545).
- **Deploy (Core only):** `./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh`. No Public fallback; fix Core first.

62
docs/03-deployment/TRANSACTION_MIRROR_CHAIN138_COLLISION_FIX.md Normal file
View File

@@ -0,0 +1,62 @@
# TransactionMirror Chain 138 — CreateCollision and skip-mirror steps
**Purpose:** If `deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh` fails with **CreateCollision** (contract already at expected address), use this to fix and proceed to pool creation only.
---
## Address from CreateCollision trace
When the deploy fails, the trace shows the address that already has code:
| Address | Role |
|---------|------|
| **0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141** | Expected TransactionMirror address (deployer + nonce 13410). If CreateCollision occurs, a contract is already deployed here. |
**Lookup on Chain 138:**
`cast code 0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141 --rpc-url $RPC_URL_138`
- If code length > 2 (i.e. not `0x`): contract exists; use it as the mirror and skip deploy.
- If code length = 2: no contract at that address on current RPC state; deploy may have failed for another reason, or state differs (e.g. different node).
---
## Exact env + script steps
### Option A — Use existing mirror and run pool-only
1. **Set the mirror address in .env** (if the collision address has code on your RPC):
```bash
# In smom-dbis-138/.env
TRANSACTION_MIRROR_ADDRESS=0xC7f2Cf4845C6db0e1a1e91ED41Bcd0FcC1b0E141
```
2. **Run the script with --skip-mirror** (only creates the cUSDT/cUSDC PMM pool):
```bash
./scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh --skip-mirror
```
3. **Or run without --skip-mirror:**
If `TRANSACTION_MIRROR_ADDRESS` is set and that address has code on chain, the script **skips** the TransactionMirror deploy and proceeds to pool creation.
### Option B — Deploy a new TransactionMirror (different address)
If you need a new mirror (e.g. that address is wrong or empty):
1. Clear any stuck nonce: `./scripts/clear-all-transaction-pools.sh` then wait ~60s.
2. Do **not** set `TRANSACTION_MIRROR_ADDRESS` (or unset it).
3. Run the full script again (no `--skip-mirror`). The next deploy will use the current nonce and a new address.
---
## Script options (reference)
| Option | Effect |
|--------|--------|
| (none) | Deploy TransactionMirror (if not skipped), then create PMM pool. |
| `--skip-mirror` | Skip mirror deploy; only create PMM pool. Requires `TRANSACTION_MIRROR_ADDRESS` in .env. |
| `--dry-run` | Print commands only; no deploy. |
| `--force` | Skip RPC reachability check. |
Skip logic (no flag): if `TRANSACTION_MIRROR_ADDRESS` is set in .env and that address has code on Chain 138, the script skips the mirror deploy and continues to pool creation.

116
docs/03-deployment/UNDEPLOYED_CONTRACTS_PRE_DEPLOYMENT_TASKS.md Normal file
View File

@@ -0,0 +1,116 @@
# Undeployed Contracts — Pre-Deployment Tasks
**Last Updated:** 2026-02-28
**Execution summary (2026-02-27):** On-chain verification **36/38**. Two missing: TransactionMirror (set `TRANSACTION_MIRROR_ADDRESS` in .env from script output) and DODO cUSDT/cUSDC pool (0x9fcB...). **Deploy uses Core RPC only.** Before deploy: if Core was read-only, run `./scripts/maintenance/make-rpc-vmids-writable-via-ssh.sh` then `./scripts/maintenance/health-check-rpc-2101.sh`. See [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md), [RPC_2101_READONLY_FIX.md](RPC_2101_READONLY_FIX.md).
**Execution summary (2026-02-26):** **All runnable tasks executed.** Env check, unified deploy dry-run, PMM pool dry-run, on-chain verification (36/36), deploy-optional-future-all --dry-run, fund-ccip-bridges-with-link --dry-run, check-balances-gas-and-deploy.sh, get-multichain-gas-prices.sh all completed. Mainnet dry-run and TransactionMirror simulate started (mainnet compiles CCIP bridges; run to completion when mainnet RPC is responsive). Previous: 1.x wallet/gas, 2.x gas API and estimates, 3.1 unified deploy dry-run (RPC + init fixes in smom-dbis-138), 3.2 DeployDeterministicCore simulated, 3.3 PMM pool script dry-run, 3.4 TransactionMirror, 3.6 optional-future, 3.7 fund-ccip dry-run, 4.6 on-chain verification (36/36). Optional env vars added to `smom-dbis-138/.env` when missing: `DODO_PMM_INTEGRATION_ADDRESS`, `QUOTE_TOKEN_ADDRESS`, `WETH_ADDRESS_138` (public addresses only). PMM and unified deploy dry-runs now work with .env only (no inline env). Remaining: 3.5 mainnet dry-run (run when mainnet RPC is reachable); 4.1–4.5 post-deploy validation when components are deployed.
**Source:** [AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md](../02-architecture/AI_AGENTS_57XX_MCP_CONTRACTS_AND_CHAINS.md), [DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md](../11-references/DEX_AND_CROSS_CHAIN_CONTRACTS_NEEDED.md), [DEPLOYED_CONTRACTS_OVERVIEW](../../smom-dbis-138/docs/deployment/DEPLOYED_CONTRACTS_OVERVIEW.md), [deployment-status.json](../../cross-chain-pmm-lps/config/deployment-status.json)
This checklist covers: **testing** anything not yet deployed, **checking deployer wallet gas**, **using the gas API to estimate deployment costs**, and **dry-running deployments** before live execution.
**Optional env vars (add/set when needed):** In `smom-dbis-138/.env`, if missing, add (public addresses only): `DODO_PMM_INTEGRATION_ADDRESS=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`, `QUOTE_TOKEN_ADDRESS=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, `WETH_ADDRESS_138=0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` so PMM pool script and dry-runs work with .env only. Check: `./scripts/deployment/check-env-required.sh`.
---
## 1. Check deployer wallet for gas
- [x] **1.1** Resolve deployer address from env:
```bash
cd smom-dbis-138 && cast wallet address $PRIVATE_KEY
```
- [x] **1.2** Run balance check (Chain 138 + all networks the script supports):
```bash
cd smom-dbis-138
./scripts/deployment/check-balances-gas-and-deploy.sh
```
Uses Infura/gas API where available; reports native token balance and estimated cost for 5M gas per chain. See [FUNDING_AND_DEPLOYMENT_CHECKLIST](FUNDING_AND_DEPLOYMENT_CHECKLIST.md).
- [x] **1.3** Chain 138: ensure deployer has at least ~0.006 ETH (5M gas × 1 gwei + buffer). Recommended 1–2 ETH. If balance is 0, fund from genesis alloc or validator (see FUNDING_AND_DEPLOYMENT_CHECKLIST §2).
- [x] **1.4** Mainnet / L2: ensure deployer has sufficient native token per chain for any planned deployments (see [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) for recommended balances).
---
## 2. Use gas API to estimate all deployment costs
- [x] **2.1** Fetch current gas prices (Etherscan for mainnet, defaults/RPC for others):
```bash
cd smom-dbis-138
./scripts/deployment/get-multichain-gas-prices.sh
```
Output can be sourced or used to update cost estimates.
- [x] **2.2** (Optional) Update doc with latest estimates:
```bash
./scripts/deployment/update-gas-estimates.sh
```
Updates [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) (or script’s target doc).
- [x] **2.3** Estimate gas for **undeployed** items (by chain): TransactionMirror simulated via `forge script` (no broadcast); DeployDeterministicCore reported ~10.67M gas. For pool creation use `cast estimate` on DODOPMMIntegration with `createCUSDTCUSDCPool`/`createPool` args when ready. EnhancedSwapRouter/DODOPMMProvider: run script dry-run when implemented.
- [x] **2.4** Sum estimated cost per chain and confirm deployer balance ≥ sum + buffer (e.g. 20–30%): Confirmed via check-balances-gas-and-deploy.sh; Chain 138 sufficient; mainnet/L2 need funding for full deploy.
---
## 3. Dry-run deployments
- [x] **3.1** Chain 138 — unified deploy (no broadcast): Run `./scripts/deployment/deploy-contracts-unified.sh --dry-run --rpc-url $RPC_URL_138`. RPC check uses 10s timeout; init.sh LOG_LEVEL fix applied so script runs with .env loaded.
```bash
cd smom-dbis-138
./scripts/deployment/deploy-contracts-unified.sh --dry-run --rpc-url "http://192.168.11.211:8545"
```
- [x] **3.2** Chain 138 — phased core (dry-run if script supports): Simulated `forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138` (no `--broadcast`); script ran successfully with gas estimate.
```bash
forge script script/deploy/DeployDeterministicCore.s.sol --rpc-url $RPC_URL_138
```
- [x] **3.3** Chain 138 — PMM pool creation (dry-run): Set `DODO_PMM_INTEGRATION_ADDRESS` and `QUOTE_TOKEN_ADDRESS` (e.g. WETH `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`), then run `DRY_RUN=true CHAIN_ID=138 ./scripts/create-all-dodo-pools-from-token-api.sh`. Script accepts `DODO_PMM_INTEGRATION` or `DODO_PMM_INTEGRATION_ADDRESS`. With Token API unavailable it reports "Pools created: 0"; with API running it would list tokens and log `[DRY RUN] Would createPool ...`. Document: [DODO_PMM_INTEGRATION](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md), [DODO_PMM_NEXT_STEPS](../../smom-dbis-138/docs/bridge/DODO_PMM_NEXT_STEPS.md).
- [x] **3.4** Chain 138 — TransactionMirror (optional): Run without `--broadcast` to simulate: `forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url $RPC_URL_138`. See [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) § TransactionMirror.
- [ ] **3.5** Mainnet — dry-run (if deploying anything new): Requires `PRIVATE_KEY`, `ETHEREUM_MAINNET_RPC` in .env. Run from environment with mainnet RPC access. Script validates tools, env, addresses, and compiles CCIP bridges.
```bash
./scripts/deployment/dry-run-mainnet-deployment.sh
```
Or per-script: `forge script script/... --rpc-url $MAINNET_RPC --dry-run`.
- [x] **3.6** Optional/future deployments (dry-run only):
```bash
cd smom-dbis-138
./scripts/deployment/deploy-optional-future-all.sh --dry-run
```
- [x] **3.7** Bridge/LINK funding (dry-run):
```bash
./scripts/deployment/fund-ccip-bridges-with-link.sh --link 10 --dry-run
```
---
## 4. Test anything not deployed (validation / unit / script)
- [ ] **4.1** **PMM pools (Chain 138):** Create cUSDT/cUSDC pool with `forge script script/dex/CreateCUSDTCUSDCPool.s.sol:CreateCUSDTCUSDCPool --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000` (script: `smom-dbis-138/script/dex/CreateCUSDTCUSDCPool.s.sol`). Requires POOL_MANAGER_ROLE on DODOPMMIntegration. If you see "Replacement transaction underpriced", a tx is pending at that nonce; wait for it to be mined or clear mempool, then retry with same or higher gas. After creation, test: `getMidPrice`, `getOraclePrice`, `getBaseReserve`, `getQuoteReserve` on pool address; confirm MCP `dodo.get_pool_state` and `dodo.identify_pool_interface` work with that address in allowlist.
- [ ] **4.2** **DODOPMMProvider:** Not deployed; implementation placeholder. When implemented, add unit tests and a script dry-run for deployment.
- [ ] **4.3** **TransactionMirror (Chain 138):** Deploy with `forge script script/DeployTransactionMirror.s.sol:DeployTransactionMirror --rpc-url $RPC_URL_138 --broadcast --private-key $PRIVATE_KEY --with-gas-price 1000000000`. If you see "Known transaction", the tx may be pending or already mined; check code at the logged address. Then test mirror receive path.
- [ ] **4.4** **EnhancedSwapRouter:** Not deployed. When Uniswap/Balancer pools exist on 138, run deploy script with `--dry-run` and test quote path.
- [ ] **4.5** **cW* tokens and PMM pools on public chains (1, 56, 137, etc.):** No addresses in deployment-status. No deployment from this repo yet. When you have a deployment path (bridge + factory or DODO), run gas estimate and dry-run per chain.
- [x] **4.6** **On-chain verification (38 addresses):** After any new deployment, run:
```bash
./scripts/verify/check-contracts-on-chain-138.sh [RPC_URL]
```
Includes TransactionMirror and DODO cUSDT/cUSDC pool in the list. Last run: 36 present, 2 missing; see [REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS](REQUIRED_FIXES_AND_DEPLOYMENTS_STATUS.md).
---
## 5. Summary — undeployed items (for cost and dry-run scope)
| Chain | Item | Action for estimate / dry-run |
|-------|------|-------------------------------|
| **138** | PMM pools (cUSDT/cUSDC, cUSDT/USDT, cUSDC/USDC) | Estimate: `createPool` / `createCUSDTCUSDCPool` gas. Dry-run: pool-creation script or `cast send --dry-run`. |
| **138** | TransactionMirror | `forge script` or `forge create` with `--dry-run` / `cast estimate`. |
| **138** | DODOPMMProvider | When implemented: script dry-run + unit tests. |
| **138** | EnhancedSwapRouter | When pools exist: script dry-run. |
| **1** | (Trustless stack deployed; no new DODO from repo) | Gas estimate only if adding contracts. |
| **56, 137, 10, 100, 25, 42161, 8453, 42220, 1111, 43114** | cW* tokens, PMM pools | When deployment path exists: per-chain gas estimate + deploy script dry-run. |
---
## 6. References
- [CONTRACT_DEPLOYMENT_RUNBOOK](CONTRACT_DEPLOYMENT_RUNBOOK.md) — Chain 138 gas price, RPC, TransactionMirror.
- [FUNDING_AND_DEPLOYMENT_CHECKLIST](FUNDING_AND_DEPLOYMENT_CHECKLIST.md) — Balance check, funding sources.
- [DEPLOYMENT_GAS_COSTS_REALTIME](../11-references/DEPLOYMENT_GAS_COSTS_REALTIME.md) — Gas API, cost table.
- [check-balances-gas-and-deploy.sh](../../smom-dbis-138/scripts/deployment/check-balances-gas-and-deploy.sh) — Balance + gas report.
- [get-multichain-gas-prices.sh](../../smom-dbis-138/scripts/deployment/get-multichain-gas-prices.sh) — Gas prices for cost estimates.
- [TODO_TASK_LIST_MASTER](../00-meta/TODO_TASK_LIST_MASTER.md) § Undeployed contracts pre-deployment — Master checklist link.

44
docs/03-deployment/sankofa-studio.env.example Normal file
View File

@@ -0,0 +1,44 @@
# Sankofa Studio (FusionAI Creator) — production .env for VMID 7805
# Copy to fusionai-production.env and set values. Use with deploy-sankofa-studio-lxc.sh:
# ENV_FILE=/path/to/fusionai-production.env ./scripts/deployment/deploy-sankofa-studio-lxc.sh
# See: docs/03-deployment/SANKOFA_STUDIO_DEPLOYMENT.md
# Artifact storage (persistent path inside container; ensure volume in compose or host path)
FUSIONAI_ARTIFACT_ROOT=/data/artifacts
# Redis (docker-compose service name)
FUSIONAI_REDIS_URL=redis://redis:6379/0
# API URL (for worker and webhooks; use internal or public)
FUSIONAI_API_URL=http://api:8000
# Service URLs (internal; docker-compose service names)
FUSIONAI_AUDIO_SERVICE_URL=http://audio:8001
FUSIONAI_IMAGE_SERVICE_URL=http://image:8002
FUSIONAI_VIDEO_ASSEMBLY_SERVICE_URL=http://video:8003
FUSIONAI_UE5_EXPORT_SERVICE_URL=http://ue5_export:8004
# Optional: require API key for POST /jobs, run, approve, cancel
# FUSIONAI_API_KEY=your-secret-key
# Optional: TTS backend (stub | piper | elevenlabs)
# FUSIONAI_TTS_BACKEND=stub
# FUSIONAI_ELEVENLABS_API_KEY=...
# FUSIONAI_ELEVENLABS_VOICE_ID=...
# Optional: Image backend (stub | openai | replicate)
# FUSIONAI_IMAGE_BACKEND=stub
# OPENAI_API_KEY=...
# REPLICATE_API_TOKEN=...
# Optional: completion webhook
# FUSIONAI_COMPLETION_WEBHOOK_URL=https://...
# FUSIONAI_WEBHOOK_RETRIES=2
# Optional: rate limit (0 = no limit)
# FUSIONAI_RATE_LIMIT_PER_MINUTE=0
# Runner timeouts (seconds)
# FUSIONAI_STAGE_TIMEOUT_SECONDS=300
# FUSIONAI_JOB_TIMEOUT_SECONDS=3600
# FUSIONAI_SERVICE_RETRIES=3

131
docs/04-configuration/22_TOKENS_13_CHAINS_DEPLOYMENT_RUNBOOK.md Normal file
View File

@@ -0,0 +1,131 @@
# 22 Tokens on All 13 Chains — Deployment Runbook
**Purpose:** Ensure all 22 token types are represented across all 13 chains in DUAL_CHAIN_TOKEN_LIST and DUAL_CHAIN_NETWORKS.
**Status:** Token list expanded; on-chain deployment documented
**Last updated:** 2026-02-28
---
## Overview
| Item | Count |
|------|-------|
| Chains | 13 (138, 1, 651940, 25, 56, 100, 137, 10, 42161, 8453, 43114, 42220, 1111) |
| Token list entries | 52+ (USDC, USDT, WETH on all; custom tokens on 138, 1, 25, 651940) |
| Unique token symbols | 17 (ETH-USD, WETH, WETH10, LINK, cUSDT, cUSDC, USDT, USDC, DAI, WETH9, USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW) |
---
## Token List Coverage (DUAL_CHAIN_TOKEN_LIST)
### Per-chain coverage
| Chain | Name | USDC | USDT | WETH | Custom (cUSDT, cUSDC, WETH10, ISO-4217 W) |
|-------|------|------|------|------|------------------------------------------|
| 138 | DeFi Oracle Meta | ✓ | ✓ | ✓ | ✓ (cUSDT, cUSDC, WETH10, LINK, ETH-USD) |
| 1 | Ethereum | ✓ | ✓ | ✓ | ✓ (DAI, ETH-USD) |
| 651940 | ALL Mainnet | ✓ | ✓ | — | — |
| 25 | Cronos | ✓ | ✓ | ✓ (WETH9) | ✓ (WETH10, LINK, USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW) |
| 56 | BSC | ✓ | ✓ | ✓ | — |
| 100 | Gnosis | ✓ | ✓ | ✓ | — |
| 137 | Polygon | ✓ | ✓ | ✓ | — |
| 10 | Optimism | ✓ | ✓ | ✓ | — |
| 42161 | Arbitrum | ✓ | ✓ | ✓ | — |
| 8453 | Base | ✓ | ✓ | ✓ | — |
| 43114 | Avalanche | ✓ | ✓ | ✓ | — |
| 42220 | Celo | ✓ | ✓ | ✓ | — |
| 1111 | Wemix | ✓ | ✓ | — | — |
**Note:** Wemix uses WEMIX as native; no standard WETH. USDC/USDT use canonical addresses from `canonical-tokens.ts`.
---
## Canonical Addresses (token-aggregation)
`smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts` defines FALLBACK_ADDRESSES for cUSDC and cUSDT on all 13 chains:
- **Chain 138 / 651940:** Custom cUSDT/cUSDC
- **L2s (1, 56, 100, 137, 10, 42161, 8453, 43114, 25, 42220, 1111):** Native USDC/USDT addresses (no custom deployment required for token list)
---
## On-Chain Deployment (Custom Tokens)
### When to deploy
- **cUSDT / cUSDC:** Deploy only if you need *compliant* versions on L2s (e.g. for PMM, CCIP, or regulatory use). Otherwise, use native USDC/USDT.
- **WETH10:** Only on Chain 138 and Cronos (25).
- **ISO-4217 W (USDW, EURW, GBPW, etc.):** Only on Cronos (25) today; expand to other chains if required.
### Deploy cUSDT/cUSDC to all 13 chains
1. **Prerequisites**
- `.env` in `smom-dbis-138/` with `PRIVATE_KEY` and per-chain RPC:
- `ETHEREUM_MAINNET_RPC`, `BSC_RPC_URL`, `POLYGON_MAINNET_RPC`, `BASE_MAINNET_RPC`, `OPTIMISM_MAINNET_RPC`, `ARBITRUM_MAINNET_RPC`, `AVALANCHE_RPC_URL`, `CRONOS_RPC_URL`, `GNOSIS_MAINNET_RPC`, `CELO_MAINNET_RPC`, `WEMIX_MAINNET_RPC`
- Deployer funded with native gas on each chain (ETH, BNB, MATIC, CRO, xDAI, AVAX, CELO, WEMIX, etc.)
2. **Run deploy script**
```bash
cd smom-dbis-138
./scripts/deployment/deploy-cusdt-cusdc-all-chains.sh
```
3. **Record addresses**
- Add `CUSDT_ADDRESS_<chainId>` and `CUSDC_ADDRESS_<chainId>` to `.env` for each chain.
- Update `canonical-tokens.ts` FALLBACK_ADDRESSES if you want to override native USDC/USDT with compliant versions.
4. **Filter by chain (optional)**
```bash
DEPLOY_CUSDT_CUSDC_FILTER="POLYGON BASE" ./scripts/deployment/deploy-cusdt-cusdc-all-chains.sh
```
5. **Dry run**
```bash
DEPLOY_CUSDT_CUSDC_DRY_RUN=1 ./scripts/deployment/deploy-cusdt-cusdc-all-chains.sh
```
---
## Sync and Deploy Token List
After updating `DUAL_CHAIN_TOKEN_LIST.tokenlist.json`:
```bash
# 1. Sync configs to all locations
bash scripts/sync-dual-chain-configs.sh
# 2. Deploy to VMID 5000 (Proxmox)
# From repo root — via Proxmox host (pct):
PROXMOX_HOST=192.168.11.12 # or PROXMOX_HOST_R630_02
scp explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json \
explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_NETWORKS.json \
root@${PROXMOX_HOST}:/tmp/
ssh root@${PROXMOX_HOST} "
pct exec 5000 -- mkdir -p /var/www/html/config
pct push 5000 /tmp/DUAL_CHAIN_TOKEN_LIST.tokenlist.json /var/www/html/config/DUAL_CHAIN_TOKEN_LIST.tokenlist.json
pct push 5000 /tmp/DUAL_CHAIN_NETWORKS.json /var/www/html/config/DUAL_CHAIN_NETWORKS.json
"
# Or use the deploy script (when on Proxmox host with pct):
# ./explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh
```
---
## Verification
| Check | Command / location |
|-------|--------------------|
| Token list JSON | `python3 -c "import json; json.load(open('explorer-monorepo/backend/api/rest/config/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json'))"` |
| Config validation | `./scripts/validation/validate-config-files.sh` |
| Token on chain | `cast call <ADDRESS> "totalSupply()(uint256)" --rpc-url $RPC_URL` |
| Explorer config | `GET https://<explorer>/api/config/DUAL_CHAIN_TOKEN_LIST.tokenlist.json` |
---
## Related Docs
- [CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md](../../smom-dbis-138/docs/deployment/CUSDT_CUSDC_MULTICHAIN_LIQUIDITY_RUNBOOK.md) — PMM, Uniswap, Balancer, Curve
- [canonical-tokens.ts](../../smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts) — Address mapping
- [DEPLOYED_COINS_TOKENS_AND_NETWORKS.md](DEPLOYED_COINS_TOKENS_AND_NETWORKS.md) — Reference addresses

7
docs/04-configuration/ALL_VMIDS_ENDPOINTS.md
View File

@@ -240,6 +240,8 @@ The following VMIDs have been permanently removed:
| 7801 | 192.168.11.51 | sankofa-portal-1 | ✅ Running | Web: 3000 | Sankofa Portal (Company Website) |
| 7802 | 192.168.11.52 | sankofa-keycloak-1 | ✅ Running | Keycloak: 8080, Admin: /admin | Identity and Access Management |
| 7803 | 192.168.11.53 | sankofa-postgres-1 | ✅ Running | PostgreSQL: 5432 | Database Service |
| 7804 | 192.168.11.54 | (Gov Portals dev) | ✅ Running | Web: 80 | Gov Portals — DBIS, ICCC, OMNL, XOM (*.xom-dev.phoenix.sankofa.nexus) |
| 7805 | 192.168.11.72 | sankofa-studio | — | API: 8000 | Sankofa Studio (FusionAI Creator) — studio.sankofa.nexus (IP .72; .55 = VMID 10230 order-vault) |
**Public Domains** (NPMplus routing):
- `sankofa.nexus` → Routes to `http://192.168.11.51:3000` (Sankofa Portal/VMID 7801) ✅
@@ -247,6 +249,7 @@ The following VMIDs have been permanently removed:
- `phoenix.sankofa.nexus` → Routes to `http://192.168.11.50:4000` (Phoenix API/VMID 7800) ✅
- `www.phoenix.sankofa.nexus` → Routes to `http://192.168.11.50:4000` (Phoenix API/VMID 7800) ✅
- `the-order.sankofa.nexus` → ⚠️ **TBD** (not yet configured)
- `studio.sankofa.nexus` → Routes to `http://192.168.11.72:8000` (Sankofa Studio / VMID 7805)
**Service Details:**
- **Host:** r630-01 (192.168.11.11)
@@ -375,6 +378,8 @@ Direct to RPC Nodes:
- VMID 7802 (sankofa-keycloak-1): 192.168.11.52 ✅ **UNIQUE**
- VMID 10232 (CT10232): Reassigned to 192.168.11.56 ✅
4. **192.168.11.55**: ✅ **IN USE** — VMID 10230 (order-vault) only. Sankofa Studio (VMID 7805) uses **192.168.11.72** to avoid conflict.
**Resolution:** All IP conflicts resolved using `scripts/resolve-ip-conflicts.sh`
**Verification:** ✅ All IPs verified unique, all services operational
@@ -477,6 +482,7 @@ This section lists all endpoints that should be configured in NPMplus, extracted
| `phoenix.sankofa.nexus` | `192.168.11.50` | `http` | `4000` | ❌ No | Phoenix API - Cloud Platform Portal (VMID 7800) ✅ **Deployed** |
| `www.phoenix.sankofa.nexus` | `192.168.11.50` | `http` | `4000` | ❌ No | Phoenix API (VMID 7800) ✅ **Deployed** |
| `the-order.sankofa.nexus` | ⚠️ **TBD** | `http` | `TBD` | ❌ No | The Order Portal - ⚠️ **Not yet configured** |
| `studio.sankofa.nexus` | `192.168.11.72` | `http` | `8000` | ❌ No | Sankofa Studio (FusionAI Creator) — VMID 7805 |
### Path-Based Routing Notes
@@ -504,6 +510,7 @@ Some domains use path-based routing in NPM configs:
| `sankofa.nexus`, `www.sankofa.nexus` | 7801, 192.168.11.51:3000 | 192.168.11.140 (Blockscout) |
| `phoenix.sankofa.nexus`, `www.phoenix.sankofa.nexus` | 7800, 192.168.11.50:4000 | 192.168.11.140 (Blockscout) |
| `the-order.sankofa.nexus` | TBD (when The Order portal is deployed) | 192.168.11.140 (Blockscout) |
| `studio.sankofa.nexus` | 7805, 192.168.11.72:8000 | — |
If NPMplus proxy hosts for sankofa.nexus or phoenix.sankofa.nexus currently point to 192.168.11.140, update them to the correct IP:port above. See [RPC_ENDPOINTS_MASTER.md](RPC_ENDPOINTS_MASTER.md) and table "Sankofa Phoenix Services" in this document.

44
docs/04-configuration/CHAIN138_X402_TOKEN_SUPPORT.md Normal file
View File

@@ -0,0 +1,44 @@
# Chain 138 Token Support for x402 Payments
**Purpose:** Record which Chain 138 tokens support ERC-2612 (permit) or ERC-3009, and thus can be used with thirdweb x402 payments.
**References:** [thirdweb x402](https://portal.thirdweb.com/x402), [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md), plan: x402 and Permit Support for Chain 138.
---
## On-chain check results
Run the verification script (from repo root, with Chain 138 RPC reachable):
```bash
./scripts/verify/check-chain138-token-permit-support.sh [RPC_URL]
# Optional: --dry-run to print RPC and token addresses only
```
**Last run:** Script confirms the following for deployed contracts on Chain 138.
| Token | Address | ERC-2612 (permit) | ERC-3009 (transferWithAuthorization) | x402-compatible |
|-------|---------|-------------------|--------------------------------------|-----------------|
| cUSDT | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | Not supported | Not supported | No |
| cUSDC | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | Not supported | Not supported | No |
WETH and WETH10 on Chain 138 (see [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md)) are standard approve/transferFrom implementations and do not expose permit or ERC-3009 in the repo; they are not x402-compatible in their current form.
---
## Implications
- **thirdweb x402** requires the payment token to support either **ERC-2612 permit** or **ERC-3009** (e.g. sign + `transferWithAuthorization` / `receiveWithAuthorization`). See [Chain and token support](https://portal.thirdweb.com/x402#chain-and-token-support).
- **Current state:** No deployed Chain 138 token in the canonical list (cUSDT, cUSDC, WETH, WETH10, LINK) is x402-compatible until one of them implements permit or ERC-3009.
- **Options:**
1. **Use another chain for x402 testing:** e.g. Arbitrum Sepolia with USDC (default in thirdweb x402). The x402 API sketch can be built and tested there, then switched to Chain 138 once a token supports permit.
2. **Add ERC-2612 to compliant tokens:** Implement and deploy new CompliantUSDT/CompliantUSDC contracts that extend OpenZeppelin `ERC20Permit` (see plan: Part 1.2 Option B). This implies new contract addresses and updates to [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md) and env/config.
---
## When a Chain 138 token gains permit
After a token on Chain 138 supports ERC-2612 or ERC-3009:
1. Re-run `./scripts/verify/check-chain138-token-permit-support.sh` and update this doc.
2. In the x402 API, use `network: chain138` (custom chain definition) and set `price` to the token object, e.g. `price: { amount: "<base units>", asset: { address: "<token address>", decimals: 6 } }` for cUSDC/cUSDT.

51
docs/04-configuration/C_TO_CW_MAPPER_MAPPING.md Normal file
View File

@@ -0,0 +1,51 @@
# c* → cW* Mapper Mapping (Multi-Chain)
**Purpose:** Define the mapping of compliant tokens (c*) on Chain 138 to their wrapped representations (cW*) on other chains for bridge/mapper tooling.
## Source of truth
- **Config:** [`config/token-mapping-multichain.json`](../../config/token-mapping-multichain.json)
- **`cToCwSymbolMapping`** — Symbol correspondence: each c* symbol maps to its cW* symbol (e.g. `cUSDT` → `cWUSDT`).
- **Per-pair tokens** — For each `fromChainId: 138` → `toChainId: <chain>` pair, tokens with key `Compliant_*_cW` define: **addressFrom** = c* contract on 138, **addressTo** = cW* contract on the destination chain (or `0x0` placeholder until deployed).
## Symbol mapping (c* → cW*)
| c* (Chain 138) | cW* (other chains) |
|----------------|--------------------|
| cUSDT | cWUSDT |
| cUSDC | cWUSDC |
| cEURC | cWEURC |
| cEURT | cWEURT |
| cGBPC | cWGBPC |
| cGBPT | cWGBPT |
| cAUDC | cWAUDC |
| cJPYC | cWJPYC |
| cCHFC | cWCHFC |
| cCADC | cWCADC |
| cXAUC | cWXAUC |
| cXAUT | cWXAUT |
## Per-chain address mapping
For each destination chain, the mapper (or bridge config) should resolve:
- **Compliant_USDT_cW**: Chain 138 cUSDT address → cWUSDT address on destination
- **Compliant_USDC_cW**: Chain 138 cUSDC address → cWUSDC address on destination
- **Compliant_EURC_cW**: Chain 138 cEURC address → cWEURC address on destination
(Additional c* → cW* pairs can be added to `token-mapping-multichain.json` when those c* and cW* are deployed.)
In `token-mapping-multichain.json`, entries with key suffix `_cW` use `addressTo: "0x0000000000000000000000000000000000000000"` as a placeholder until the cW* contract is deployed on that chain. **Operators:** after deploying cW* (e.g. via `DeployCWTokens.s.sol` or equivalent), update the corresponding `addressTo` in the JSON (or in env-driven config that overrides it). The **receiver/bridge on the destination chain must support minting cW*** (e.g. dedicated cW* receiver such as TwoWayTokenBridgeL2, or an extended bridge that calls `cW*.mint(recipient, amount)` in `ccipReceive`); see [CW_BRIDGE_APPROACH.md](../07-ccip/CW_BRIDGE_APPROACH.md) and [CW_BRIDGE_TASK_LIST.md](../00-meta/CW_BRIDGE_TASK_LIST.md).
## Consumer behavior
- **Mapper / bridge:** When resolving "cUSDT on 138 → token on chain 56", use:
- **Native representation:** key `Compliant_USDT` → `addressTo` = that chain’s native USDT (e.g. BSC USDT).
- **Wrapped representation:** key `Compliant_USDT_cW` → `addressTo` = that chain’s cWUSDT. If `addressTo` is zero, treat as "cW* not deployed" and optionally fall back to native or reject.
- **Loading:** [`config/token-mapping-loader.cjs`](../../config/token-mapping-loader.cjs) builds `addressMapFromTo` / `addressMapToFrom` from `tokens`. Keys `*_cW` are first-class; filter by key suffix or use `cToCwSymbolMapping` for symbol-level logic.
## Related
- [EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md) — All c* on explorer must be GRU-registered.
- [TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md](../11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md) — Deploying cW* via `DeployCWTokens.s.sol` and `--deploy-cw`.

173
docs/04-configuration/DETAILED_GAPS_AND_ISSUES_LIST.md Normal file
View File

@@ -0,0 +1,173 @@
# Detailed Gaps and Issues List
**Date:** 2026-03-02
**Purpose:** Consolidated list of items requiring fixes, deployment, or operator action.
---
## 1. Explorer API (VMID 5000) — ✅ FIXED (2026-02-28)
| Issue | Status | Fix |
|-------|--------|-----|
| `/api/config/token-list` returns Blockscout error (400) | ✅ Fixed | Nginx patched; config files deployed |
| `/api/config/networks` returns Blockscout error | ✅ Fixed |
**Applied:** `scripts/patch-nginx-explorer-config.sh` added locations to HTTP and HTTPS blocks. Config deployed via `pct push`.
**Original cause:** `location = /api/config/token-list` and `location = /api/config/networks` in `fix-nginx-conflicts-vmid5000.sh` are not in the live nginx config. Requests fall through to `location /api/` and get proxied to Blockscout.
**Steps:**
1. SSH to Proxmox host or enter VMID 5000.
2. Run inside VMID 5000:
```bash
# From repo root, copy script into container and run:
pct exec 5000 -- bash -c "cd /tmp && [your-fix-nginx-script-content]"
# Or: scp fix-nginx-conflicts-vmid5000.sh root@<container-ip>:/tmp/ && ssh root@<container-ip> bash /tmp/fix-nginx-conflicts-vmid5000.sh
```
3. Deploy config files:
```bash
# From repo root (with pct or SSH):
./explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh
# Or EXEC_MODE=ssh: EXEC_MODE=ssh EXPLORER_IP=192.168.11.140 ./explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh
```
4. Verify:
```bash
curl -s https://explorer.d-bis.org/api/config/token-list | jq '.tokens | length' # → 22
curl -s https://explorer.d-bis.org/api/config/networks | jq '.chains | length' # → 4
```
---
## 2. Token-Aggregation Service — ✅ FIXED (2026-02-28)
| Issue | Status | Fix |
|-------|--------|-----|
| `/health` returns `{"status":"unhealthy","error":"database \"token_aggregation\" does not exist"}` | ✅ Fixed | DB created; migrations run; service restarted |
**Applied:** Created `token_aggregation` DB; ran migrations; restarted service. Health now returns `"status":"healthy"`.
**Original cause:** The deployed token-aggregation service (port 3001) uses `DATABASE_URL` pointing to a database named `token_aggregation`, but that database does not exist or migrations were not run.
**Steps:**
1. On VMID 5000 (or wherever PostgreSQL runs):
```bash
# Create database if using separate DB:
createdb -U postgres token_aggregation
# Or ensure DATABASE_URL uses explorer_db (migrations create tables there)
```
2. Run migrations:
```bash
cd smom-dbis-138/services/token-aggregation
DATABASE_URL=postgresql://user:pass@host:5432/token_aggregation bash scripts/run-migrations.sh
# Or with explorer_db: DATABASE_URL=postgresql://user:pass@host:5432/explorer_db
```
3. Restart token-aggregation:
```bash
systemctl restart token-aggregation
```
4. Verify:
```bash
curl -s http://192.168.11.140:3001/health | jq .
# Should return "status":"healthy"
```
**Reference:** `docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md`, `smom-dbis-138/services/token-aggregation/scripts/run-migrations.sh`
---
## 3. Nginx Proxy Order — Token-Aggregation vs Blockscout
| Issue | Status | Fix |
|-------|--------|-----|
| `/api/v1/` may proxy to Blockscout instead of token-aggregation | ✅ Addressed | `fix-nginx-conflicts-vmid5000.sh` defines `location /api/v1/` **before** `location /api/` (lines 132–142 before 159). When applying config on VMID 5000, use this script to preserve order. |
**Reference:** `explorer-monorepo/scripts/fix-nginx-conflicts-vmid5000.sh` — correct order is in repo; operator should use this script when (re)applying nginx config.
---
## 4. Explorer Homepage / Wallet Page Tests — Intermittent
| Issue | Status | Fix |
|-------|--------|-----|
| `verify-all-systems.sh` "Explorer homepage" or "Wallet page" may fail | ✅ Improved | Timeout for Explorer homepage and Wallet page increased from 15s to 25s in `scripts/verify-all-systems.sh` to reduce failures on slow networks. |
**Note:** Homepage uses `SolaceScanScout|Blockscout|blockscout|<!DOCTYPE`; wallet uses `Chain 138|ChainID 138|Add Chain`. test_endpoint already captures curl output to a variable before grep.
---
## 5. Wallet Page — Grep Pattern
| Issue | Status | Fix |
|-------|--------|-----|
| Wallet page test looked for "Add Chain 138" | ✅ Fixed | Updated to `Chain 138|ChainID 138|Add Chain` |
---
## 6. Token-Aggregation Health Test — Resilience
| Issue | Status | Fix |
|-------|--------|-----|
| Health test expected `healthy` only; service returns `unhealthy` when DB missing | ✅ Fixed | Test now accepts `healthy`, `"status"`, or `unhealthy` (service reachable) |
---
## 7. Token List Validation — CI
| Issue | Status | Fix |
|-------|--------|-----|
| Token lists not validated in CI | ✅ Fixed | `validate-config-files.sh` now validates dbis-138, cronos, all-mainnet, DUAL_CHAIN |
| Workflow not triggered on token list changes | ✅ Fixed | `validate-config.yml` paths include `token-lists/**` and `explorer-monorepo/backend/api/rest/config/metamask/**` |
---
## 8. DUAL_CHAIN Config Sync
| Issue | Status | Fix |
|-------|--------|-----|
| DUAL_CHAIN files in 3 locations could diverge | ✅ Fixed | `scripts/sync-dual-chain-configs.sh` syncs from `explorer-monorepo/backend/api/rest/config/metamask/` to docs and metamask-integration |
**Usage:** After editing DUAL_CHAIN files, run `./scripts/sync-dual-chain-configs.sh` from repo root.
---
## 9. Optional / Future Improvements
| Item | Priority | Notes |
|------|----------|-------|
| Shellcheck in CI | Low | `run-shellcheck.sh --optional` — install shellcheck if desired |
| Token-aggregation DB naming | Medium | Align DATABASE_URL: use `explorer_db` or create `token_aggregation` and document |
| Explorer homepage test timeout | Done (2026-03-02) | Increased to 25s for Explorer homepage and Wallet page in `verify-all-systems.sh` |
| All-mainnet token logos (HYDX, HYBX, CHT, AUDA) | Done | Placeholder IPFS logo added |
---
## 10. Quick Reference — Scripts
| Script | Purpose |
|--------|---------|
| `scripts/verify-all-systems.sh` | Full system verification (explorer, APIs, RPC, token-aggregation) |
| `scripts/validation/validate-config-files.sh` | Config and token list validation |
| `scripts/sync-dual-chain-configs.sh` | Sync DUAL_CHAIN configs to all locations |
| `explorer-monorepo/scripts/fix-nginx-conflicts-vmid5000.sh` | Fix nginx config (run inside VMID 5000) |
| `explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh` | Deploy token list and networks to VMID 5000 |
| `smom-dbis-138/services/token-aggregation/scripts/run-migrations.sh` | Run token-aggregation DB migrations |
---
## 11. Summary — Fixes Applied in This Session
1. **verify-all-systems.sh:** Wallet page pattern, token-aggregation health test resilience
2. **validate-config-files.sh:** Token list validation (dbis-138, cronos, all-mainnet, DUAL_CHAIN)
3. **validate-config.yml:** Trigger on token list and config changes
4. **sync-dual-chain-configs.sh:** New script to keep DUAL_CHAIN in sync
5. **DUAL_CHAIN configs:** Synced to docs and metamask-integration
---
## 12. Remaining Operator Actions (Requires Proxmox/Server Access)
1. Apply nginx fix and deploy config on VMID 5000 (see §1)
2. Create token_aggregation DB (or align explorer_db) and run migrations (see §2)
3. Restart token-aggregation after DB fix

200
docs/04-configuration/DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md Normal file
View File

@@ -0,0 +1,200 @@
# Using DEX and Aggregators with ChainID 138 Coins/Tokens — Explainer
**Last Updated:** 2026-02-28
**Purpose:** Explain how to use DEXs and aggregators with coins/tokens from ChainID 138 (DeFi Oracle Meta Mainnet), and how routing works for swaps and cross-chain flows.
---
## 1. Chain 138 tokens in DEX flows
### 1.1 Tokens on Chain 138
| Symbol | Address | Role in DEX / aggregator |
|--------|---------|---------------------------|
| **cUSDT** | `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22` | Compliant stablecoin; pair with cUSDC, USDT, WETH in pools |
| **cUSDC** | `0xf22258f57794CC8E06237084b353Ab30fFfa640b` | Compliant stablecoin; pair with cUSDT, USDC, WETH in pools |
| **WETH** | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | Wrapped ETH; bridge asset and quote currency |
| **WETH10** | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | Alternative WETH; used in CCIP bridge flows |
| **LINK** | `0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03` | CCIP fee token; not typically a DEX pair |
**Official reference tokens (for pool pairs):** USDT at `0x15DF1D5BFDD8Aa4b380445D4e3E9B38d34283619`, USDC per deployment. These are used in **cUSDT/USDT** and **cUSDC/USDC** DODO PMM pools so users can swap between compliant and official stablecoins.
When building swap UIs or aggregator integrations, use these addresses for **tokenIn** / **tokenOut** and for resolving symbols (e.g. from token list or `/api/v1/tokens`).
---
## 2. DEX layer on Chain 138
### 2.1 Native DEX: DODO PMM
On Chain 138, the primary DEX layer is **DODO-style PMM** (Proactive Market Maker) via:
- **DODOPMMIntegration** — `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D`
Creates and manages pools; exposes swap functions and pool state.
- **DODOPMMProvider** — `0x8EF6657D2a86c569F6ffc337EE6b4260Bd2e59d0`
Used by routing/aggregation to get quotes and execute swaps for registered pools.
**Pools (created and registered):**
| Pair | Pool address | Use case |
|------|--------------|----------|
| cUSDT / cUSDC | `0x9fcB06Aa1FD5215DC0E91Fd098aeff4B62fEa5C8` | Compliant↔compliant stablecoin |
| cUSDT / USDT | `0xa3Ee6091696B28e5497b6F491fA1e99047250c59` | Compliant↔official USDT |
| cUSDC / USDC | `0x90bd9Bf18Daa26Af3e814ea224032d015db58Ea5` | Compliant↔official USDC |
**How to swap on-chain (direct):**
- **cUSDT ↔ cUSDC:** `DODOPMMIntegration.swapCUSDTForUSDC` / `swapUSDCForCUSDT(pool, amountIn, minAmountOut)`
- **cUSDT ↔ USDT:** `swapCUSDTForUSDT` / `swapUSDTForCUSDT(pool, …)`
- **cUSDC ↔ USDC:** `swapCUSDCForUSDC` / `swapUSDCForCUSDC(pool, …)`
Caller must approve the integration contract for the input token. Use the pool addresses above for the `pool` argument.
**Uniswap V2/V3 on 138:** Not deployed by default. If you deploy Uniswap factories and create pools (e.g. cUSDT/WETH, cUSDC/WETH), the token-aggregation service can index them when `CHAIN_138_UNISWAP_V2_FACTORY` / `CHAIN_138_UNISWAP_V3_FACTORY` are set in env.
---
## 3. Token-aggregation API (quotes and discovery)
The **token-aggregation** service indexes tokens and liquidity pools (UniswapV2, UniswapV3, DODO from `DODOPMMIntegration`) and exposes a REST API. This is the main way to get **quotes** and **pool data** for Chain 138 tokens without calling the chain yourself.
**Base URL:** e.g. `https://explorer.d-bis.org/api/v1` or the URL where the service is proxied (see [REST_API_REFERENCE](../../smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md)).
### 3.1 Single-hop quote (DEX quote)
| Endpoint | Method | Purpose |
|----------|--------|---------|
| **/api/v1/quote** | GET | Best **single-hop** swap quote for a token pair on one chain |
**Query:** `chainId=138`, `tokenIn=<address>`, `tokenOut=<address>`, `amountIn=<raw amount in smallest unit>`.
**Response:** `{ amountOut, poolAddress?, dexType?, error? }` — constant-product style from the first/best indexed pool for that pair. Use for “swap cUSDT → cUSDC” or “cUSDT → WETH” (if a pool exists and is indexed).
**Limitation:** Single-hop only. There is no N-hop path (e.g. cUSDT → WETH → cUSDC) in this API; routing is one direct pool per pair.
### 3.2 Token and pool discovery
| Endpoint | Purpose |
|----------|---------|
| **GET /api/v1/tokens?chainId=138** | List tokens; optional `includeDodoPool`, market data |
| **GET /api/v1/tokens/:address?chainId=138** | Token detail, market data, pools, DODO pool flag |
| **GET /api/v1/tokens/:address/pools?chainId=138** | All pools containing this token |
| **GET /api/v1/report/token-list?chainId=138** | Uniswap-style token list (for MetaMask / dApp) |
Use these to resolve symbol→address, get logos, and see which pools exist for cUSDT, cUSDC, WETH on Chain 138.
### 3.3 Bridge routes and token mapping
| Endpoint | Purpose |
|----------|---------|
| **GET /api/v1/bridge/routes** | CCIP WETH9/WETH10 bridge routes; Chain 138 bridge addresses |
| **GET /api/v1/token-mapping?fromChain=138&toChain=1** | Token address mapping 138↔other chain (for bridge UIs) |
| **GET /api/v1/token-mapping/resolve?fromChain=&toChain=&address=** | Resolve one token address to the other chain |
Use for “bridge WETH from 138 to Mainnet” or “what is cUSDT on 138 in Mainnet terms” (if a wrapped/bridged form exists).
---
## 4. Routing for DEXs — how it works
### 4.1 Single-hop routing (what’s live today)
- **On-chain:** User (or contract) calls `DODOPMMIntegration` swap functions directly with the correct pool address. No on-chain “router” that picks the pool.
- **Off-chain (API):** Client calls `GET /api/v1/quote` with `chainId=138`, `tokenIn`, `tokenOut`, `amountIn`. The service returns the best direct-pool quote from its index (DODO + any configured Uniswap). Client then executes the swap on the integration contract (or via a front-end that submits the tx).
So “routing” today = **choose the right pool** (cUSDT/cUSDC, cUSDT/USDT, or cUSDC/USDC) and call the matching swap function with that pool.
### 4.2 Multi-provider routing (design; not yet deployed)
**EnhancedSwapRouter** (contract) is designed to route **one leg** (e.g. WETH↔stable) across multiple providers:
- **By size:** Small (&lt;$10k) → Uniswap V3 / Dodoex; medium ($10k–$100k) → Dodoex → Balancer → Uniswap V3; large (&gt;$100k) → Dodoex → Curve → Balancer.
- **By slippage / liquidity:** Prefer Dodoex for low slippage; Balancer/Curve for deeper liquidity.
This contract is **not deployed** on Chain 138. When deployed (and when Uniswap/Balancer/Curve pools exist on 138), it would sit in front of multiple DEXs and return `getQuotes(stablecoin, amountIn)` and `swapToStablecoin(...)` so one call gets the best execution. **DODOPMMProvider** would be one of the registered providers.
### 4.3 Swap–bridge–swap (cross-chain routing)
For **cross-chain** flows (e.g. swap on 138 → bridge to Mainnet → swap on Mainnet):
- **Orchestration API:** `POST /api/bridge/quote` — request includes source/destination chain, token, amount, destination address. Response can include:
- **sourceSwapQuote** — optional quote to swap into the bridge asset on source (e.g. 138) when an EnhancedSwapRouter or equivalent is configured.
- **destinationSwapQuote** — optional quote to swap on destination chain after the bridge.
- **On-chain coordinator (optional):** **SwapBridgeSwapCoordinator** can perform “swap (source) → bridge → swap (destination)” in one transaction when deployed and configured.
So “routing for DEXs” in a cross-chain context = **source DEX (138)** + **bridge** + **destination DEX**, with the quote API and optional coordinator tying them together.
---
## 5. Using aggregators with Chain 138 tokens
### 5.1 Internal “aggregation” (token-aggregation service)
The token-aggregation service **aggregates**:
- **Pools:** From DODO (DODOPMMIntegration) and, if configured, UniswapV2/V3.
- **Quote:** Best **single-hop** quote for a given (tokenIn, tokenOut, amountIn) on one chain.
So for Chain 138, it acts as a **single-hop quote aggregator** over the indexed DEX (today: DODO PMM). It does **not** split orders across multiple pools or chains; it picks the best direct pool for the pair.
### 5.2 External DEX aggregators (1inch, 0x, ParaSwap)
- **1inch, 0x, ParaSwap** and similar aggregators support many chains and DEXs. They do **not** support ChainID 138 unless they add it.
- **To use them with Chain 138:** The aggregator would need to add Chain 138 to their config, index or connect to DODO PMM (and any other DEX on 138), and expose 138 in their API/UI. Today you would **contact** them for integration (see [DEX_INTEGRATION_GUIDE](../../metamask-integration/docs/DEX_INTEGRATION_GUIDE.md)).
- **Until then:** Use the **token-aggregation** API for quotes and the **DODOPMMIntegration** contract for execution on 138.
### 5.3 Explorer / bridge aggregator (Go backend)
The **explorer-monorepo** backend has a bridge aggregator that uses Li.Fi, Socket, Squid, Symbiosis, Relay, Stargate. That aggregation is for **bridge routes**, not for on-chain DEX swaps on 138. For **swap + bridge + swap**, the orchestration **POST /api/bridge/quote** and optional SwapBridgeSwapCoordinator are the relevant pieces.
---
## 6. End-to-end flows (summary)
### Flow A: Swap on Chain 138 only (same chain)
1. **Resolve tokens:** `GET /api/v1/tokens?chainId=138` or token list; get addresses for cUSDT, cUSDC, WETH.
2. **Get quote:** `GET /api/v1/quote?chainId=138&tokenIn=<cUSDT>&tokenOut=<cUSDC>&amountIn=...`
3. **Execute:** User signs a tx calling `DODOPMMIntegration.swapCUSDTForUSDC(pool, amountIn, minAmountOut)` (or the matching function for the pair), with approval for the input token.
### Flow B: Bridge from Chain 138 (no destination swap)
1. **Bridge routes:** `GET /api/v1/bridge/routes` for WETH9/WETH10 and Chain 138 bridge addresses.
2. **Token mapping:** If needed, `GET /api/v1/token-mapping/resolve` for 138→destination.
3. User sends a bridge tx (e.g. CCIP) from 138 to the destination chain; no DEX swap on 138 unless they first swap into WETH/WETH10.
### Flow C: Swap on 138 → bridge → swap on destination
1. **Quote:** `POST /api/bridge/quote` with source chain 138, destination chain, token, amount, destination address. Response may include `sourceSwapQuote` and `destinationSwapQuote`.
2. **Source (138):** If user holds cUSDT/cUSDC, optionally swap to WETH via DODOPMMIntegration (or future router) using Flow A.
3. **Bridge:** User (or coordinator) executes bridge transfer.
4. **Destination:** Optional swap using `destinationSwapQuote` or destination-chain DEX.
---
## 7. Config and env (integrators)
| Use case | Env / config |
|----------|---------------|
| **Token-aggregation indexing DODO on 138** | `CHAIN_138_DODO_PMM_INTEGRATION=0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` (and RPC, DB). Optional: `CHAIN_138_DODO_POOL_MANAGER`, `CHAIN_138_DODO_VENDING_MACHINE`. |
| **Uniswap on 138 (if deployed)** | `CHAIN_138_UNISWAP_V2_FACTORY`, `CHAIN_138_UNISWAP_V2_ROUTER`, `CHAIN_138_UNISWAP_V2_START_BLOCK` (and V3 equivalents). |
| **Bridge quote (swap+bridge+swap)** | `RPC_URL`, `BRIDGE_REGISTRY_ADDRESS`; optional `ENHANCED_SWAP_ROUTER_ADDRESS`, `DESTINATION_RPC_URL`, `DESTINATION_SWAP_ROUTER_ADDRESS`. |
| **Token list / MetaMask** | Token-aggregation `GET /api/v1/report/token-list?chainId=138` or static list; point MetaMask/dApp to this URL. |
---
## 8. Reference
| Document | Content |
|----------|---------|
| [PMM_DEX_ROUTING_STATUS.md](../11-references/PMM_DEX_ROUTING_STATUS.md) | DEX/PMM deployment status, what’s live vs not |
| [TASKS_TO_INCREASE_ALL_E2E_FLOWS.md](../00-meta/TASKS_TO_INCREASE_ALL_E2E_FLOWS.md) | **Tasks** required to complete Flow A, B, C and cross-cutting E2E |
| [STATUS_AND_TOKEN_ROUTING.md](../../smom-dbis-138/docs/STATUS_AND_TOKEN_ROUTING.md) | Token-aggregation API summary, routing layers, multihop |
| [REST_API_REFERENCE.md](../../smom-dbis-138/services/token-aggregation/docs/REST_API_REFERENCE.md) | Full token-aggregation API |
| [DODO_PMM_INTEGRATION.md](../../smom-dbis-138/docs/integration/DODO_PMM_INTEGRATION.md) | Pool creation, swap functions, liquidity |
| [ENHANCED_ROUTING.md](../../smom-dbis-138/docs/bridge/trustless/integration/ENHANCED_ROUTING.md) | Multi-provider routing design (EnhancedSwapRouter) |
| [DEX_INTEGRATION_GUIDE.md](../../metamask-integration/docs/DEX_INTEGRATION_GUIDE.md) | Partner DEX/aggregator options (1inch, 0x, ParaSwap) |
| [ADDRESS_MATRIX_AND_STATUS.md](../11-references/ADDRESS_MATRIX_AND_STATUS.md) | All Chain 138 addresses (tokens, pools, contracts) |
**Explorer (Chain 138):** https://explorer.d-bis.org
**RPC (public):** https://rpc-core.d-bis.org (deployment should use Core RPC; see runbooks.)

51
docs/04-configuration/EXPLORER_FUNCTIONALITY_REVIEW.md Normal file
View File

@@ -0,0 +1,51 @@
# Explorer functionality review (routes, API, Snap)
Reference for what works, what the SPA calls, and fixes applied.
## 1. Site routes and navigation
All primary routes return **HTTP 200** and render the same SPA shell (Explore: Home, Blocks, Transactions; Tools: Bridge, WETH, Tokens, Watchlist; MetaMask Snap; language toggle; Connect Wallet):
- `/`, `/home`, `/blocks`, `/transactions`, `/bridge`, `/weth`, `/tokens`, `/watchlist`, `/analytics`, `/operator`
Static routing and nginx serving are OK.
## 2. Exact API URLs the SPA calls
When the page is at `https://explorer.d-bis.org`, the SPA uses **relative** `/api`. In DevTools → Network, filter by `api` and confirm these:
| Widget / feature | URL |
|----------------------------|-----|
| Stats (Total Blocks, etc.) | `GET /api/v2/stats` |
| Gas & Network | `GET /api/v2/blocks?page=1&page_size=20`, `GET /api/v2/stats`, `GET /api/v2/transactions?page=1&page_size=100` |
| Latest Blocks | `GET /api/v2/blocks?page=1&page_size=10` |
| Latest Transactions | `GET /api/v2/transactions?page=1&page_size=10` |
| Tokens (list) | `GET /api/v2/tokens?page=1&page_size=100` |
| Bridge Monitoring | **No API call** — content is static HTML. If it stays "Loading bridge data…", a JS error may prevent the bridge view from running. |
If any of these return non-200 or (failed) CORS, that’s the failing path. If all return 200 but the UI still shows "Loading…", the issue is in the SPA (parsing, DOM update, or an exception after fetch). See [explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md](../../explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md).
## 3. Blockscout stats endpoint
- `https://explorer.d-bis.org/api/v2/stats` returns **200** with `total_blocks`, `total_transactions`, `gas_prices`, `average_block_time`, etc. So the API is up.
## 4. MetaMask Snap section
- **`/snap/`** — Chain 138 Snap page loads; set `GATSBY_SNAP_API_BASE_URL` for market/summary/bridge/swap cards.
- **`/snap/send`** — **Fix applied:** The "Send on Chain 138" link is now built as an **absolute HTTPS** URL when `GATSBY_SNAP_SITE_URL` is set (e.g. `https://explorer.d-bis.org/snap/send`), so the link no longer leads to an HTTP redirect. Rebuild the Snap site with `GATSBY_SNAP_SITE_URL=https://explorer.d-bis.org` (see [chain138-snap/scripts/build-snap-site-for-explorer.sh](../../metamask-integration/chain138-snap/scripts/build-snap-site-for-explorer.sh)) and redeploy to VMID 5000.
## 5. Contract verification
- **Blockscout** supports contract verification (Etherscan-compatible and v2 API). From the explorer: open an **address** → **Contract** tab → **Verify & Publish** (if the instance shows it).
- **Forge (CLI):** Use the **forge-verification-proxy** and then run verification scripts so Forge’s payload is translated to Blockscout v2. See [08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) and [forge-verification-proxy/README.md](../../forge-verification-proxy/README.md). Scripts: `scripts/verify/run-contract-verification-with-proxy.sh`, `scripts/verify-contracts-blockscout.sh`.
- **Gaps and more:** [EXPLORER_GAPS_AND_RECOMMENDATIONS.md](EXPLORER_GAPS_AND_RECOMMENDATIONS.md) § Contract verification.
---
## 6. Conclusions from observed behavior
- **Static routing / nginx:** OK (all pages load).
- **Blockscout stats:** OK (`/api/v2/stats` returns 200).
- **SPA dynamic widgets:** If still "Loading…" after fixes (relative `/api`, no `filter=to`, cache-bust `?v=3`), verify (1) deployed `explorer-spa.js` on VMID 5000 is the latest, (2) hard-refresh (Ctrl+Shift+R), (3) DevTools Console for first error and Network for failing API URL + status.
- **Snap send:** Use absolute HTTPS link (rebuild with `GATSBY_SNAP_SITE_URL`, redeploy Snap site).
- **Full gaps, bridge/lanes, verification, user/API keys:** [EXPLORER_GAPS_AND_RECOMMENDATIONS.md](EXPLORER_GAPS_AND_RECOMMENDATIONS.md).

125
docs/04-configuration/EXPLORER_GAPS_AND_RECOMMENDATIONS.md Normal file
View File

@@ -0,0 +1,125 @@
# Explorer: Gaps, Recommendations, and Additional Items
**Purpose:** Single reference for explorer (https://explorer.d-bis.org): loading, bridge/lanes, **contract verification (Verify & Publish + Forge batch)**, user/API keys, and all other recommendations and gaps.
**Related:** [EXPLORER_FUNCTIONALITY_REVIEW.md](EXPLORER_FUNCTIONALITY_REVIEW.md) | [EXPLORER_METAMASK_TECHNICAL_RESPONSE.md](EXPLORER_METAMASK_TECHNICAL_RESPONSE.md) | [EXPLORER_TROUBLESHOOTING.md](EXPLORER_TROUBLESHOOTING.md) | [BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) | [explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md](../../explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md)
---
## 1. Loading on all pages
### 1.1 Intended behavior
| Page / view | Data loaded | Source |
|-------------|-------------|--------|
| **Home** | Stats, Gas & Network, Latest Blocks, Latest Transactions | `loadStats()`, `loadGasAndNetworkStats()`, `loadLatestBlocks()`, `loadLatestTransactions()` — all use `/api/v2/*` (Blockscout). |
| **Blocks** | Paginated block list | `loadAllBlocks()` → `/api/v2/blocks?page=&page_size=25`. |
| **Transactions** | Paginated transaction list | `loadAllTransactions()` → `/api/v2/transactions?page=&page_size=25`. |
| **Bridge** | Static bridge/lanes content | `refreshBridgeData()` — no API; builds HTML from hardcoded routes. If "Loading bridge data…" persists, a JS error likely prevents this from running. |
| **Tokens** | Token list | `loadTokensList()` → `/api/v2/tokens?page=1&page_size=100`. |
| **WETH** | Static UI + wallet balance (if connected) | No Blockscout list API; wrap/unwrap uses RPC. |
| **Watchlist** | LocalStorage-backed list | `_renderWatchlist()` — no API. |
| **Analytics** | Placeholder (Track 3) | "Coming soon" message; gated by `hasAccess(3)`. |
| **Operator** | Placeholder (Track 4) | "Coming soon" message; gated by `hasAccess(4)`. |
### 1.2 If widgets stay "Loading…" or "—"
- Ensure **all** of these return **200** when opened from the explorer origin: `/api/v2/stats`, `/api/v2/blocks?page=1&page_size=10`, `/api/v2/transactions?page=1&page_size=10`, `/api/v2/tokens?page=1&page_size=100`. See [EXPLORER_LOADING_TROUBLESHOOTING](../../explorer-monorepo/docs/EXPLORER_LOADING_TROUBLESHOOTING.md) for exact URLs and do-now checks.
- Redeploy frontend after SPA changes; use cache-bust `explorer-spa.js?v=3` (or higher) and hard-refresh.
---
## 2. Bridges and lanes / routes to all networks
### 2.1 Current state
- **Bridge Monitoring** view shows:
- Chain 138 WETH9/WETH10 bridge addresses (correct: `0x971cD9…`, `0xe0E932…`).
- **WETH9 routes:** BSC (56), Polygon (137), Avalanche (43114), Base (8453), Arbitrum (42161), Optimism (10), Ethereum Mainnet (1).
- **WETH10 routes:** Same 7 destinations.
- **Ethereum Mainnet bridges:** WETH9 `0x2A0840…`, WETH10 `0xb7721d…` (correct).
- **Source of truth for lanes:** [07-ccip/CHAIN138_COMPLETE_ROUTING_TABLE.md](../07-ccip/CHAIN138_COMPLETE_ROUTING_TABLE.md), [07-ccip/MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md](../07-ccip/MAPPER_GAPS_DEPLOYMENTS_AND_IMPROVEMENTS.md).
### 2.2 Gaps and recommendations
| Item | Status | Recommendation |
|------|--------|----------------|
| **Destination-chain "Bridge Address" in SPA** | Addresses for BSC/Polygon/etc. in the SPA are hardcoded; some may be placeholders (e.g. CCIP Router 138 reused). | Source remote bridge (or router) addresses from config/API (e.g. token-aggregation or `config/smart-contracts-master.json`) when available; or add a "Reference" link to CHAIN138_COMPLETE_ROUTING_TABLE. |
| **Cronos (25), Gnosis (100), Celo (42220), Wemix (1111)** | Routing table lists Cronos as live; 100/42220/1111 as "Config ready". SPA shows only 7 destinations. | Add Cronos (25) to the Bridge Monitoring table when destination bridge address is confirmed; add a short "More chains (Gnosis, Celo, Wemix) when configured" note and link to routing table. |
| **All lanes load** | Bridge view is static HTML; no runtime fetch of lanes. | Optional: call `GET /api/v1/bridge/routes` (or equivalent) if the explorer backend exposes it, and render lanes from response so new chains appear without SPA redeploy. |
---
## 3. Contract verification
### 3.1 What exists
- **Blockscout** on VMID 5000 supports contract verification (Etherscan-compatible + v2 API).
- **Forge verification:** Use the **forge-verification-proxy** so Forge’s payload is translated to Blockscout v2. See [forge-verification-proxy/README.md](../../forge-verification-proxy/README.md) and [08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md).
- **Scripts:** `scripts/verify/run-contract-verification-with-proxy.sh`, `scripts/verify-contracts-blockscout.sh` (and smom-dbis-138 equivalents).
### 3.2 Verify & Publish (Blockscout UI)
To verify a contract from the explorer when automated verification is unavailable or returns 502:
1. Open **https://explorer.d-bis.org/address/<CONTRACT_ADDRESS>**
2. Go to the **Contract** tab → **Verify & Publish**
3. Choose method: **Via Standard JSON Input** (recommended), **Via Sourcify**, or **Via Multi-file**
4. Upload source (or paste) and provide constructor arguments if needed; submit.
See [08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) for Forge/proxy batch verification and troubleshooting (502, HTML response).
### 3.3 Recommendations
| Item | Recommendation |
|------|-----------------|
| **Batch verification (Forge + proxy)** | From a host that can reach Blockscout (LAN): `source smom-dbis-138/.env 2>/dev/null; ./scripts/verify/run-contract-verification-with-proxy.sh`. Uses canonical addresses from .env; see [BLOCKSCOUT_VERIFICATION_GUIDE](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md). |
| **API key for Blockscout** | Self-hosted Blockscout at explorer.d-bis.org does not require an API key for read API. If rate limits or private endpoints are added later, document API key issuance (see §4). |
---
## 4. User profile and dev API key issuance
### 4.1 Gap
- **No user accounts or developer API keys** are implemented in the explorer or Blockscout today. Blockscout (self-hosted) typically does not ship a "developer portal" for API key signup; read API is public or protected at the reverse-proxy/nginx level.
### 4.2 Recommendations
| Option | Effort | Notes |
|--------|--------|--------|
| **A. Blockscout API keys (if enabled)** | Low | If your Blockscout version supports API keys for the read API, enable them and document how operators issue keys (e.g. via Blockscout admin or env). |
| **B. Nginx/API gateway rate limit by key** | Medium | Put an API gateway or nginx in front of `/api` that requires a query param or header (e.g. `?apikey=`) and issue keys out-of-band (e.g. from a simple script or internal form). |
| **C. Separate developer portal** | High | Build a small "developer portal" (e.g. in dbis_core or the-order) that allows signup/login and issues API keys for explorer (and other) APIs; store keys and enforce in gateway. |
**Suggested short-term:** Document that the explorer API is currently public (no key). If you need keys later, start with (A) or (B) and add a one-page "API access" doc with whom to contact for a key and which base URL to use.
---
## 5. Other recommendations and suggestions
### 5.1 From existing docs
- **Snap /send HTTPS:** Ensure "Send on Chain 138" link is absolute HTTPS (`GATSBY_SNAP_SITE_URL` in Snap build). Done in repo; rebuild and redeploy Snap site to apply.
- **CoinGecko / API keys:** Token-aggregation and oracle may use CoinGecko (and optional CMC); see [COINGECKO_API_KEY_SETUP.md](COINGECKO_API_KEY_SETUP.md) and [API_KEYS_REQUIRED.md](../../reports/API_KEYS_REQUIRED.md). Not explorer-specific but affects Snap/market data.
- **RPC TRACE:** Already enabled on public RPC (VMID 2201) for Blockscout indexing; see [explorer-monorepo/docs/RPC_FUNCTIONALITY_AND_BLOCKSCOUT_TRACE.md](../../explorer-monorepo/docs/RPC_FUNCTIONALITY_AND_BLOCKSCOUT_TRACE.md).
### 5.2 Explorer-specific
| # | Recommendation | Priority |
|---|----------------|----------|
| 1 | Ensure all SPA views that call `/api` handle 4xx/5xx and show a clear "Retry" or error message. | High |
| 2 | Add a "Verify contract" link or short instructions on the address/contract page (link to Blockscout verification or BLOCKSCOUT_VERIFICATION_GUIDE). | Medium |
| 3 | Consider serving bridge routes from a small config or API so new chains don’t require an SPA redeploy. | Low |
| 4 | Analytics (Track 3) / Operator (Track 4): when implemented, document access control and any API keys. | Future |
| 5 | Optional: add Blockscout "API" or "Docs" link in footer (e.g. to Blockscout API docs or internal API overview). | Low |
---
## 6. Quick checklist (operator)
- [ ] All explorer pages load; no persistent "Loading…" for stats, blocks, transactions, tokens, bridge (see §1).
- [ ] Bridge Monitoring shows Chain 138 + Mainnet bridges and 7 (or more) destination lanes; add Cronos/config-ready chains if desired (§2).
- [ ] Contract verification: proxy + Forge runbook documented; run batch verification for main contracts (§3).
- [ ] User/API key: decision documented; if keys are introduced, add "API access" doc and issuance process (§4).
- [ ] Snap site: rebuilt with `GATSBY_SNAP_SITE_URL`; `/snap/send` link is HTTPS (§5).

170
docs/04-configuration/EXPLORER_METAMASK_TECHNICAL_RESPONSE.md Normal file
View File

@@ -0,0 +1,170 @@
# Explorer + MetaMask Technical Response — 5 Items for Exact Config
**Purpose:** Reply to the technical review so you get exact “do this / set that” config values for the explorer and MetaMask.
---
## Ready-to-send reply (copy-paste all below)
**5 items (send as-is)**
**1) RPC URL used by MetaMask**
- Public (MetaMask / dApps): `https://rpc-http-pub.d-bis.org`
- WebSocket: `wss://rpc-ws-pub.d-bis.org`
- Internal: `http://192.168.11.221:8545`
**2) ChainId**
- Decimal: `138`
- Hex: `0x8a`
**3) Explorer backend stack**
- Backend: **Blockscout** (Docker container on VMID 5000, API on port 4000)
- Frontend: **SolaceScanScout** SPA served by nginx on VMID 5000; frontend calls `/api` (nginx proxy to `http://127.0.0.1:4000`) and uses the same RPC for wallet/fallback
**4) Intended wrapped-native (WETH9) on chain (Chain 138)**
- WETH9: `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` (same as Ethereum mainnet **by design**; canonical bytecode verified on 138)
- WETH10: `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f`
- Bridges:
- WETH9 Bridge: `0x971cD9D156f193df8051E48043C476e53ECd4693`
- WETH10 Bridge: `0xe0E93247376aa097dB308B92e6Ba36bA015535D0`
**5) EIP-1559**
- Yes — blocks include `baseFeePerGas`
**Summary table (paste-friendly)**
| # | Item | Value |
| - | ---------------------- | -------------------------------------------------------------------------- |
| 1 | RPC URL (MetaMask) | `https://rpc-http-pub.d-bis.org` (WS: `wss://rpc-ws-pub.d-bis.org`) |
| 2 | ChainId | Decimal: **138** — Hex: **0x8a** |
| 3 | Explorer backend stack | **Blockscout** (VMID 5000:4000) + **SolaceScanScout** (nginx on VMID 5000) |
| 4 | Wrapped-native (WETH9) | **`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`** |
| 5 | EIP-1559 | **Yes** — `baseFeePerGas` present |
**Optional: Backend RPC and API wiring (for "Loading…" fixes)**
- Blockscout env (VMID 5000):
- `ETHEREUM_JSONRPC_HTTP_URL=http://192.168.11.221:8545`
- `ETHEREUM_JSONRPC_WS_URL=ws://192.168.11.221:8546`
- `ETHEREUM_JSONRPC_VARIANT=besu`
- `CHAIN_ID=138`
- Frontend: calls `/api` (same origin on `https://explorer.d-bis.org`); nginx proxies `/api` → Blockscout `:4000`
- TRACE API: enabled on public RPC node (VMID 2201) so Blockscout can index internals/block rewards
---
## 1. RPC URL used by MetaMask
- **Public (recommended for MetaMask / dApps):**
- **HTTPS:** `https://rpc-http-pub.d-bis.org`
- **WebSocket:** `wss://rpc-ws-pub.d-bis.org`
- **Internal (same backend, HTTP only):** `http://192.168.11.221:8545` (VMID 2201, besu-rpc-public-1)
MetaMask and the explorer frontend use the **HTTPS** URL when the site is served over `https://explorer.d-bis.org`; otherwise they fall back to the HTTP URL. The explorer **backend** (Blockscout) uses `http://192.168.11.221:8545` (same node).
---
## 2. ChainId (hex and decimal)
- **Decimal:** `138`
- **Hex:** `0x8a` (also written `0x8A` in some UIs)
---
## 3. Explorer backend stack
- **Backend:** **Blockscout** (Docker container on VMID 5000, API on port 4000).
- **Frontend:** Custom SPA **“SolaceScanScout”** (static HTML/JS in `explorer-monorepo/frontend/public/`), served by nginx on VMID 5000. The frontend calls:
- **Blockscout API** at `/api` (proxied by nginx to `http://127.0.0.1:4000`).
- **RPC** (for fallback / wallet) at `https://rpc-http-pub.d-bis.org` or `http://192.168.11.221:8545` as above.
So: **Blockscout** is the indexer/API; **SolaceScanScout** is the custom frontend branding and UI.
**Screenshots (live UI):** See [../images/README.md](../images/README.md) for image list. Reference images (replace with live captures from https://explorer.d-bis.org/ if desired):
| View | Image |
|------|--------|
| Home (stats, Gas & Network, Latest Blocks/Transactions) | ![Explorer home](../images/explorer-home.png) |
| Blocks list | ![Explorer blocks](../images/explorer-blocks.png) |
| Transactions list | ![Explorer transactions](../images/explorer-transactions.png) |
---
## 4. Intended wrapped-native contract addresses (Chain 138)
Chain 138 intentionally uses the **same addresses as Ethereum mainnet** for WETH9/WETH10 (deployed-at-same-address / CREATE2-style setup). They exist on Chain 138 and are the intended wrapped-native contracts.
| Token / Bridge | Address (Chain 138) | Notes |
|-----------------------|---------------------|--------|
| **WETH9** (wrapped-native) | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2` | Same as mainnet; canonical WETH9 bytecode verified on 138 (see `smom-dbis-138/scripts/verify-weth9-canonical.js`). |
| **WETH10** | `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` | Same as mainnet. |
| **WETH9 Bridge** (CCIP) | `0x971cD9D156f193df8051E48043C476e53ECd4693` | In `config/contract-addresses.conf` as `ADDR_CCIPWETH9_BRIDGE`. |
| **WETH10 Bridge** (CCIP) | `0xe0E93247376aa097dB308B92e6Ba36bA015535D0` | In `config/contract-addresses.conf` as `ADDR_CCIPWETH10_BRIDGE`. |
So the **intended wrapped-native (WETH9-equivalent) address** on Chain 138 is **`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`**. The explorer is correct to show it; the chain is not “mainnet” but uses that address by design.
---
## 5. EIP-1559 (baseFeePerGas)
- **Yes.** The chain uses EIP-1559; blocks include **baseFeePerGas**.
- Deployment and gas scripts (e.g. in `scripts/archive/consolidated/deploy/`) use `eth_getBlockByNumber("latest", false)` and read `baseFeePerGas` for gas pricing.
- Docs state EIP-1559 is supported (e.g. `docs/11-references/DEFI_ORACLE_META_MAINNET_PROJECT_DESCRIPTION.md`, `docs/04-configuration/ADD_CHAIN138_TO_LEDGER_LIVE.md`).
---
## Summary table (paste-friendly)
| # | Item | Value |
|---|------|--------|
| 1 | **RPC URL (MetaMask)** | `https://rpc-http-pub.d-bis.org` (WS: `wss://rpc-ws-pub.d-bis.org`) |
| 2 | **ChainId** | Decimal: **138** — Hex: **0x8a** |
| 3 | **Explorer backend stack** | **Blockscout** (API on VMID 5000:4000) + custom frontend **SolaceScanScout** (nginx on VMID 5000) |
| 4 | **Wrapped-native (WETH9) on chain** | **`0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`** (same as mainnet by design) |
| 5 | **EIP-1559** | **Yes** — baseFeePerGas present in blocks |
---
## Optional: Backend RPC and API wiring (for “Loading…” fixes)
- **Blockscout env (VMID 5000):**
- `ETHEREUM_JSONRPC_HTTP_URL=http://192.168.11.221:8545`
- `ETHEREUM_JSONRPC_WS_URL=ws://192.168.11.221:8546`
- `ETHEREUM_JSONRPC_VARIANT=besu`
- `CHAIN_ID=138`
- **Frontend:** Calls `/api` (same origin when on `https://explorer.d-bis.org`); nginx proxies `/api` to Blockscout on port 4000.
- **TRACE API:** Enabled on the public RPC node (VMID 2201) so Blockscout can index internal transactions and block rewards (see `explorer-monorepo/docs/RPC_FUNCTIONALITY_AND_BLOCKSCOUT_TRACE.md`).
You can paste the **Summary table** plus the **Optional** paragraph (if they need backend details) into your reply to get the exact explorer env/config, WETH9/WETH10/bridge wiring, and RPC checklist.
---
## Verification: explorer vs this doc
Verification run: config and live endpoints checked against the values above.
### Codebase (matches doc)
| Item | Source | Status |
|------|--------|--------|
| RPC URL (HTTPS/WS) | `explorer-monorepo/frontend/public/explorer-spa.js` | `RPC_FQDN` = `https://rpc-http-pub.d-bis.org`, `RPC_WS_FQDN` = `wss://rpc-ws-pub.d-bis.org`, `RPC_IP` = `http://192.168.11.221:8545` |
| ChainId | same file | `CHAIN_ID = 138`, MetaMask `chainId: '0x8A'` |
| WETH9 / WETH10 | same file | `0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2`, `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` |
| WETH9/WETH10 bridges | same file | `0x971cD9D156f193df8051E48043C476e53ECd4693`, `0xe0E93247376aa097dB308B92e6Ba36bA015535D0` |
| Blockscout env | `scripts/run-blockscout-config-direct.sh` | `ETHEREUM_JSONRPC_HTTP_URL=http://192.168.11.221:8545`, `CHAIN_ID=138`, `ETHEREUM_JSONRPC_VARIANT=besu` |
| API proxy | `explorer-monorepo/scripts/fix-nginx-serve-custom-frontend.sh` | `location /api/` → `proxy_pass http://127.0.0.1:4000` |
### Live endpoints
| Check | Command / URL | Result |
|-------|----------------|--------|
| Explorer API | `GET https://explorer.d-bis.org/api/v2/stats` | 200; `total_blocks`, `total_transactions`, `gas_prices` present |
| RPC chainId | `POST https://rpc-http-pub.d-bis.org` `eth_chainId` | `"result":"0x8a"` (138) |
| EIP-1559 | `POST https://rpc-http-pub.d-bis.org` `eth_getBlockByNumber("latest", false)` | `baseFeePerGas` present in block (e.g. `"0x7"`) |
**Conclusion:** Explorer config and live behaviour match this doc. Use the “Ready-to-send reply” section to respond to the technical review.

42
docs/04-configuration/EXPLORER_TOKENS_GRU_POLICY.md Normal file
View File

@@ -0,0 +1,42 @@
# Explorer tokens and GRU policy
**Purpose:** All compliant (c*) tokens listed on [https://explorer.d-bis.org/tokens](https://explorer.d-bis.org/tokens) must be part of the GRU (Global Reserve Unit) — i.e. registered in `UniversalAssetRegistry` as `AssetType.GRU`.
## Policy
1. **Token lists**
The canonical Chain 138 token list (`token-lists/lists/dbis-138.tokenlist.json`) and the explorer/MetaMask list (`explorer-monorepo/backend/config/metamask/DUAL_CHAIN_TOKEN_LIST.tokenlist.json`) include only c* tokens that are **registered as GRU** on Chain 138.
2. **When adding a new c* token**
- Deploy the token (or confirm address).
- Register it as GRU: set the token address in `smom-dbis-138/.env` (e.g. `CEURT_ADDRESS_138`, `CGBPC_ADDRESS_138`; see `ENV_EXAMPLE_CONTENT.md`), then run:
```bash
./scripts/deployment/set-dotenv-c-tokens-and-register-gru.sh
```
- Add the token to the token lists (dbis-138 and DUAL_CHAIN for Chain 138) **after** it is registered as GRU.
3. **All c* registered as GRU**
The script `set-dotenv-c-tokens-and-register-gru.sh` sets and registers the following c* (addresses from DeployCompliantFiatTokens / ENV_EXAMPLE_CONTENT):
- **cUSDT** — `0x93E66202A11B1772E55407B32B44e5Cd8eda7f22`
- **cUSDC** — `0xf22258f57794CC8E06237084b353Ab30fFfa640b`
- **cEURC** — `0x8085961F9cF02b4d800A3c6d386D31da4B34266a`
- **cEURT** — `0xdf4b71c61E5912712C1Bdd451416B9aC26949d72`
- **cGBPC** — `0x003960f16D9d34F2e98d62723B6721Fb92074aD2`
- **cGBPT** — `0x350f54e4D23795f86A9c03988c7135357CCaD97c`
- **cAUDC** — `0xD51482e567c03899eecE3CAe8a058161FD56069D`
- **cJPYC** — `0xEe269e1226a334182aace90056EE4ee5Cc8A6770`
- **cCHFC** — `0x873990849DDa5117d7C644f0aF24370797C03885`
- **cCADC** — `0x54dBd40cF05e15906A2C21f600937e96787f5679`
- **cXAUC** — `0x290E52a8819A4fbD0714E517225429aA2B70EC6b`
- **cXAUT** — `0x94e408E26c6FD8F4ee00b54dF19082FDA07dC96E`
Token lists (dbis-138, DUAL_CHAIN for 138) include at least cUSDT, cUSDC, cEURC; add others to lists after they are deployed and verified on explorer.
4. **Explorer /tokens page**
The explorer loads tokens from the Blockscout API (`/v2/tokens`). Curated lists (e.g. for MetaMask or display) must only include c* that are GRU-registered. When adding new c* to any list that can surface on the explorer, register them as GRU first (see step 2).
## References
- [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 2.4 (Register c* as GRU)
- [set-dotenv-c-tokens-and-register-gru.sh](../../scripts/deployment/set-dotenv-c-tokens-and-register-gru.sh)
- [RegisterGRUCompliantTokens.s.sol](../../smom-dbis-138/script/deploy/RegisterGRUCompliantTokens.s.sol)
- [C_TO_CW_MAPPER_MAPPING.md](C_TO_CW_MAPPER_MAPPING.md) — c* to cW* mapping for mapper on other chains

18
docs/04-configuration/EXPLORER_TROUBLESHOOTING.md
View File

@@ -8,6 +8,8 @@
**Last updated:** 2026-02-06
**Reference screenshots:** For expected explorer UI (home, blocks, transactions), see [../images/README.md](../images/README.md) and [EXPLORER_METAMASK_TECHNICAL_RESPONSE.md](EXPLORER_METAMASK_TECHNICAL_RESPONSE.md#3-explorer-backend-stack).
---
## "Your connection isn't private" / net::ERR_CERT_AUTHORITY_INVALID
@@ -116,6 +118,22 @@ When on your LAN, `explorer.d-bis.org` resolves to `76.53.10.36`. If that’s yo
- **Blocks not updating:** Check Blockscout logs:
`ssh root@192.168.11.12 "pct exec 5000 -- docker logs blockscout --tail 50"`
### "Invalid address" when clicking From/To in transaction list
**Symptom:** Clicking the **From** or **To** cell in the transactions table (especially when **To** shows "—" for contract-creation txs) shows an "Invalid address" toast or error.
**Cause:** Those cells were clickable even when the value was empty or "N/A", so the app tried to open an address detail for an invalid value.
**Fix (applied in explorer SPA):** From/To cells are now only clickable when the value is a valid `0x` address. Clicking "—" or "N/A" no longer triggers the address detail; the row still opens the transaction detail when you click elsewhere on the row.
### Contract verification fails (502 / Invalid JSON)
When running `run-contract-verification-with-proxy.sh` or Forge verify, you may see "Blockscout returned HTML" or 502. This usually means Blockscout (VMID 5000) is down or the DB needs migrations.
- **Fix Blockscout:** [03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md](../03-deployment/BLOCKSCOUT_FIX_RUNBOOK.md) — SSL/migrations, thin pool, start stack.
- **Verify from UI:** When https://explorer.d-bis.org is up, use **Address → Contract → Verify & Publish** (no proxy needed). See [08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md).
- **From LAN:** Run verification script from a host that can reach `http://192.168.11.140:4000` so the proxy can forward to Blockscout.
---
## Verify Explorer

146
docs/04-configuration/FULL_PARITY_TOKEN_COVERAGE_RUNBOOK.md Normal file
View File

@@ -0,0 +1,146 @@
# Full Parity Token Coverage — Logos, Pricing, Token Lists, All Networks, All Entry Points
**Last Updated:** 2026-02-28
**Purpose:** Achieve complete coverage for token logos, pricing, and token lists across all networks and all aggregator/wallet entry points.
---
## 1. Coverage Matrix
| Dimension | Target |
|-----------|--------|
| **Networks** | 138, 1, 651940, 56, 137, 100, 10, 42161, 8453, 43114, 25, 42220, 1111 |
| **Token lists** | Uniswap format with logoURI; per-chain and unified |
| **Logos** | 512×512 PNG for CoinGecko/CMC; logoURI for all tokens |
| **Pricing** | CoinGecko, CMC, on-chain oracle; report API |
| **Entry points** | MetaMask, Trust Wallet, Chainlist, CoinGecko, CMC, 1inch, Paraswap, Chain 138 Snap |
---
## 2. Entry Points and Requirements
| Entry Point | Token List | Logos | Pricing | Notes |
|-------------|------------|-------|---------|-------|
| **MetaMask** | CoinGecko (built-in) or custom URL | logoURI per token | CoinGecko API | Chain 138 not in built-in; use Snap token list |
| **Trust Wallet** | Trust Wallet registry | Trust Wallet assets | CoinGecko/CMC | PR to trustwallet/wallet-core |
| **Chainlist** | eip155-138.json | Chain icon | — | [04-configuration/pr-ready/](../pr-ready/) |
| **CoinGecko** | Submit chain + tokens | 512×512 PNG | CoinGecko API | Primary for MetaMask |
| **CoinMarketCap** | Submit chain + tokens | 512×512 PNG | CMC API | Fallback for some wallets |
| **Chain 138 Snap** | token-aggregation API | logoURI from API | Report API | `GET /api/v1/report/token-list` |
| **1inch / Paraswap** | Token list URL | logoURI | Their APIs | Add token list URL when supported |
| **Explorer** | Blockscout / custom | — | — | Token verification |
---
## 3. Single Source of Truth
| Asset | Location | Used By |
|-------|----------|---------|
| **Canonical tokens** | `smom-dbis-138/services/token-aggregation/src/config/canonical-tokens.ts` | Report API, token-list, coingecko, cmc |
| **Token mapping (cross-chain)** | `config/token-mapping-multichain.json` | Bridge tooling, relay |
| **Networks (EIP-3085)** | `smom-dbis-138/services/token-aggregation/src/config/networks.ts` | Snap, wallet_addEthereumChain |
| **Chain configs** | `smom-dbis-138/services/token-aggregation/src/config/chains.ts` | Indexer, report API |
| **Logo URLs** | `canonical-tokens.ts` (getLogoUriForSpec), Trust Wallet assets | Token list, CoinGecko |
| **512×512 logos** | `docs/04-configuration/coingecko/logos/` (prepare-token-logos-512x512.sh) | CoinGecko/CMC submission |
---
## 4. Per-Network Token List Coverage
| Chain ID | Network | Tokens in canonical-tokens | Report API | Token list URL |
|----------|---------|----------------------------|-----------|----------------|
| 138 | Chain 138 | ✅ Full | ✅ | `?chainId=138` |
| 651940 | ALL Mainnet | ✅ cUSDC, cUSDT, WETH | ✅ | `?chainId=651940` |
| 1 | Ethereum | ✅ (L2_CHAIN_IDS) | ✅ | `?chainId=1` |
| 56 | BSC | ✅ | ✅ | `?chainId=56` |
| 137 | Polygon | ✅ | ✅ | `?chainId=137` |
| 100 | Gnosis | ✅ | ✅ | `?chainId=100` |
| 10 | Optimism | ✅ | ✅ | `?chainId=10` |
| 42161 | Arbitrum | Env/fallback | Add to chains.ts | `?chainId=42161` |
| 8453 | Base | Env/fallback | Add to chains.ts | `?chainId=8453` |
| 43114 | Avalanche | Env/fallback | Add to chains.ts | `?chainId=43114` |
| 25 | Cronos | ✅ USDW, etc. | Add to chains.ts | `?chainId=25` |
| 42220 | Celo | Env | Add to chains.ts | `?chainId=42220` |
| 1111 | Wemix | Env | Add to chains.ts | `?chainId=1111` |
---
## 5. Implementation Checklist
### 5.1 Token-Aggregation (All Networks)
- [ ] Add chains 42161, 8453, 43114, 25, 42220, 1111 to `chains.ts`
- [ ] Add WETH9/WETH10 + cUSDT/cUSDC addresses per chain from `token-mapping-multichain.json`
- [ ] Add all networks to `networks.ts` with iconUrls (Trust Wallet fallback)
- [ ] Ensure `getSupportedChainIds()` returns all 13 chains
- [ ] Deploy token-aggregation and proxy `/api/v1/*` before Blockscout
### 5.2 Logos
- [ ] Run `prepare-token-logos-512x512.sh` (requires ImageMagick)
- [ ] Run `upload-token-logos-to-ipfs.sh` — see [IPFS_TOKEN_LOGOS_RUNBOOK](IPFS_TOKEN_LOGOS_RUNBOOK.md)
- [ ] Verify all 23+ tokens have 512×512 PNG in `docs/04-configuration/coingecko/logos/`
- [ ] Ensure `getLogoUriForSpec()` returns valid Trust Wallet URLs for all tokens
- [ ] Add chain logos (138, 651940) for Chainlist/CoinGecko
### 5.3 Token Lists (Unified)
- [ ] Export unified token list: `GET /api/v1/report/token-list` (no chainId = all chains)
- [ ] Publish token list URL for 1inch/Paraswap: `https://explorer.d-bis.org/api/v1/report/token-list`
- [ ] Sync DUAL_CHAIN_TOKEN_LIST, metamask provider tokens.js with canonical-tokens
- [ ] Add Chainlist eip155-138.json to pr-ready (done)
### 5.4 Pricing
- [ ] Submit Chain 138 and 651940 to CoinGecko (chain + tokens)
- [ ] Submit to CoinMarketCap
- [ ] Consensys outreach for MetaMask native support
- [ ] Document on-chain oracle addresses per chain for dApp use
### 5.5 Entry Point Submissions
| Entry Point | Action | Doc |
|-------------|--------|-----|
| CoinGecko | Submit chain + tokens via form | [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) |
| CMC | Submit via listing form | Same |
| Trust Wallet | PR to wallet-core | [ADD_CHAIN138_TO_TRUST_WALLET](ADD_CHAIN138_TO_TRUST_WALLET.md) |
| Chainlist | Submit eip155-138.json | [pr-ready/README](../pr-ready/README.md) |
| 1inch | Token list URL (when chain supported) | — |
| Paraswap | Token list URL (when chain supported) | — |
---
## 6. Commands
```bash
# Prepare logos (requires ImageMagick)
./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh
# Upload logos to IPFS (requires ipfs daemon or PINATA_JWT)
./scripts/upload-token-logos-to-ipfs.sh
# Export report data for submission
API_BASE="https://explorer.d-bis.org"
for chain in 138 651940 1 56 137 100 10 42161 8453 43114 25 42220 1111; do
curl -s "${API_BASE}/api/v1/report/coingecko?chainId=$chain" -o "report-coingecko-${chain}.json"
curl -s "${API_BASE}/api/v1/report/cmc?chainId=$chain" -o "report-cmc-${chain}.json"
done
# Verify token list
curl -s "${API_BASE}/api/v1/report/token-list" | jq '.tokens | length'
curl -s "${API_BASE}/api/v1/report/token-list?chainId=138" | jq '.tokens[] | {symbol, logoURI}'
# Verify Snap API
./metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh "$API_BASE"
```
---
## 7. References
- [PUBLICATION_LOCATIONS_MASTER](PUBLICATION_LOCATIONS_MASTER.md) — **All locations to publish token lists, liquidity pools, chain metadata, pricing**
- [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md)
- [TOKEN_AGGREGATION_REPORT_API_RUNBOOK](TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md)
- [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md)
- [IPFS_TOKEN_LOGOS_RUNBOOK](IPFS_TOKEN_LOGOS_RUNBOOK.md) — IPFS hosting for all logos (explorers, token lists)
- [REPOSITORIES_AND_PRS_CHAIN138](../../00-meta/REPOSITORIES_AND_PRS_CHAIN138.md)

114
docs/04-configuration/GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md Normal file
View File

@@ -0,0 +1,114 @@
# GRU M00 Diamond Docs — Gaps and Inconsistencies Review
**Purpose:** Single review of all GRU M00 Diamond–related documentation for gaps, broken or ambiguous references, and internal inconsistencies. Covers the Facet Map, the Review (Gaps & Recommendations), index/README links, and related references.
**Scope:** [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md), [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md), [README](README.md), [MASTER_INDEX](../MASTER_INDEX.md), [SUBMODULE_RELATIONSHIP_MAP](../11-references/SUBMODULE_RELATIONSHIP_MAP.md), and linked targets.
**Status:** Post–review. All “Still open” items completed: institutional spec created, token model and Pattern A locked, GRU Diamond evolution note added, MASTER_INDEX Review row updated with TOKEN_SCOPE_GRU and VAULT_SYSTEM.
---
## 1. Missing Documents / Broken References
| Item | Where referenced | Issue | Resolution |
|------|------------------|--------|------------|
| **GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md** | Facet Map “Related documents”; Review §2.1, §5.1, §6 checklist, §7 | **Resolved:** File created with full §1–§8; token model A and Pattern A locked; GRC vs M00 evolution note added. |
| **Institutional whitepaper §1–§8** | Facet Map: “or institutional whitepaper §1–§8” | **Resolved:** GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md is the canonical §1–§8 in repo. |
---
## 2. Link and Path Consistency
| Link | From | Target | Status |
|------|------|--------|--------|
| GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md | Facet Map, Review | Same directory (04-configuration) | Target missing; path correct. |
| GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md | Facet Map | Same directory | OK. |
| gru-docs/contracts/README.md | Facet Map, Review | ../../gru-docs/contracts/README.md | OK (submodule at repo root). |
| SUBMODULE_RELATIONSHIP_MAP.md | Facet Map | ../11-references/SUBMODULE_RELATIONSHIP_MAP.md | OK. |
| TOKEN_SCOPE_GRU.md | Facet Map, Review | ../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md | OK. |
| VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md | Facet Map, Review | ../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md (docs root) | OK. |
| SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md | Review §7 | Same directory | OK. |
| REQUIRED_FIXES_UPDATES_GAPS.md | Review §7 | ../REQUIRED_FIXES_UPDATES_GAPS.md | OK. |
| MASTER_INDEX “Related” for Review | MASTER_INDEX | GRU_M00_DIAMOND_FACET_MAP.md, REQUIRED_FIXES_UPDATES_GAPS.md | Paths are doc-relative (no leading docs/); correct from docs/MASTER_INDEX.md. |
**Recommendation:** Add a one-line “Document status” at the top of the Facet Map: “Institutional spec: see GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md (when present) or external whitepaper.” So the missing file is clearly optional.
---
## 3. Terminology and Naming Consistency
| Topic | Facet Map | Review | Inconsistency / resolution |
|-------|-----------|--------|----------------------------|
| **Ownership vs Governance** | “OwnershipFacet (or use GovernanceFacet)” | “GovernanceFacet” in checklist | Intentional: both names valid; M00 may use one. No change. |
| **Gate vs GateFacet** | Diagram: “ComplianceGate”; table: “ComplianceGateFacet (stub)” | “ComplianceGate” / “ComplianceGateFacet” | Logical gate vs implementing facet. Consistent. |
| **Minimum ship list – gates** | §2.1 lists ComplianceGateFacet, AccountingGateFacet only (no Messaging/Reserve as stubs) | §2.6 and §2.7 list all four gates; §2.7 minimum list names only Compliance + Accounting stubs | Facet Map diagram shows 4 gates; minimum list names 2 gate stubs. Align by either (1) adding “MessagingGateFacet (stub), ReserveGateFacet (stub)” to Facet Map §2.1 minimum list, or (2) adding a sentence in Facet Map: “Minimum ship: Compliance and Accounting gate stubs; Messaging and Reserve can be added later.” |
| **TokenFactoryFacet vs MarketFactory + AssetRegistry** | “TokenFactoryFacet” in minimum list with “(or consolidated MarketFactoryFacet + AssetRegistryFacet)” | “TokenFactoryFacet (or unify AssetRegistry + MarketFactory)” | Same intent. OK. |
| **a/d vs ac/vdc/sdc** | §5 uses a\<ISO>, d\<ISO>; §5.5 now maps a↔ac, d↔vdc/sdc | §4.1 recommends adding this mapping | Fixed in Facet Map §5.5. |
---
## 4. Cross-Doc Content Gaps
| Gap | Description | Suggested fix |
|-----|-------------|----------------|
| **Token model not locked** | Facet Map said “[ A \| B \| C ]”; no doc locked a choice. | **Fixed:** Institutional spec §8 locks **Token model A**; Facet Map “Token model” line updated to “A (locked)” with link to spec §8. |
| **Pattern A vs B** | Review recommended documenting “Target: Pattern A.” | **Fixed:** Institutional spec §6 locks **Target: Pattern A**; Facet Map “Target pattern” line added with link to spec §6. |
| **GRC-2535 vs M00 relationship** | Two Diamond designs; migration path undefined. | **Fixed:** Institutional spec now has “GRU Diamond evolution (GRC-2535 vs M00)” at top: GRC = current, M00 = extension/replacement; decision = migrate vs new deploy. |
| **Four gates vs two stubs** | See §3 above. | **Fixed:** Facet Map §2.2 now states that the minimum ship list includes Compliance and Accounting gate stubs and that Messaging/Reserve may follow in a later phase. |
---
## 5. Index and README Consistency
| Location | Content | Issue |
|----------|---------|--------|
| **04-configuration/README.md** | Lists Facet Map and Review under “Smart contracts & ISO-20022.” | No issue. Order: Facet Map then Review. |
| **MASTER_INDEX.md** | “GRU Diamond / Smart contracts” subsection with Facet Map and Review rows. | **Fixed:** Review row “Related Documents” now includes TOKEN_SCOPE_GRU and VAULT_SYSTEM_MASTER_TECHNICAL_PLAN; institutional spec row added. |
| **SUBMODULE_RELATIONSHIP_MAP** | gru-docs row notes same repo as GRU-Official-Docs-Monetary-Policies and standalone path. | Consistent with Facet Map and Review. |
---
## 6. Internal Consistency Within Each Doc
### 6.1 Facet Map
- Section numbering 1–5 and 5.1–5.5 is consistent.
- Governance levels table has 6 rows (0–5); header matches.
- Diagram node IDs (M00, DiamondCut, etc.) match table names; “GovLevel” in diagram = “GovernanceLevelFacet” in table. OK.
- **Fixed:** §5.5 now documents a↔ac, d↔vdc/sdc per Review recommendation.
### 6.2 Review (Gaps and Recommendations)
- Section numbering 1–7 is consistent.
- Checklist in §6 has 12 items; “Institutional spec doc” and “Token model A/B/C locked” appear; both depend on creating/locking in other docs. OK.
- References in §7 to “(To be added)” for institutional spec are consistent with §2.1 and §5.1.
- “smom-dbis-138” in References is a directory path; link to TOKEN_SCOPE_GRU is the specific doc. No conflict.
---
## 7. Summary of Fixes Applied in This Review
1. **Facet Map:** Added §5.5 “Mapping to deployed token names (a/d vs ac/vdc/sdc)” and a link to TOKEN_SCOPE_GRU so the recommended a↔ac, d↔vdc/sdc alignment is documented in the Facet Map.
---
## 8. Recommended Follow-Up — Completed
1. **Done:** Created **GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md** with full §1–§8; linked from Facet Map and Review.
2. **Done:** Locked **token model A** and **Pattern A** in institutional spec (§8 and §6); updated Facet Map “Token model” and “Target pattern” lines.
3. **Done earlier:** Facet Map §2.2 already clarifies minimum ship list (Compliance + Accounting gate stubs; Messaging/Reserve may follow).
4. **Done:** Added **“GRU Diamond evolution (GRC-2535 vs M00)”** at top of institutional spec (migrate vs new deploy).
5. **Done:** Added TOKEN_SCOPE_GRU and VAULT_SYSTEM_MASTER_TECHNICAL_PLAN to MASTER_INDEX “Related” for the Review row.
---
## 9. Related Documents
- [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) — §1–§8 institutional spec (token model A, Pattern A, GRC vs M00 evolution).
- [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md)
- [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md)
- [README.md](README.md) (04-configuration)
- [MASTER_INDEX.md](../MASTER_INDEX.md)
- [SUBMODULE_RELATIONSHIP_MAP.md](../11-references/SUBMODULE_RELATIONSHIP_MAP.md)
- [TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md)
- [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md)

202
docs/04-configuration/GRU_M00_DIAMOND_FACET_MAP.md Normal file
View File

@@ -0,0 +1,202 @@
# GRU M00 Diamond — Facet Map and Module List (Whitepaper)
**Purpose:** Single-page reference for the GRU M00 Diamond (ERC-2535) Token Factory architecture. For Solidity engineers and whitepaper authors. All c/a/d token families are implemented as upgradeable facets; storage and governance placeholders support IPSAS, IFRS/US GAAP, ISO-20022, i18n, and future governance levels.
**Token model:** **A** (locked). Separate ERC-20 contracts deployed by GRU (Aave-like). See [institutional spec §8](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md#8-one-key-design-decision-you-should-lock). **Target pattern:** **A** (one factory, many assets); Pattern B only for flagship USD/EUR if needed. See [institutional spec §6](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md#6-what-upgradeable-facet-per-iso-means-practical).
---
## 1. Facet Map (Mermaid)
```mermaid
flowchart TB
subgraph diamond [GRU M00 Diamond]
M00[M00 Diamond]
end
subgraph core [Core Facets]
DiamondCut[DiamondCutFacet]
DiamondLoupe[DiamondLoupeFacet]
Ownership[OwnershipFacet]
Pause[PauseFacet]
end
subgraph tokenFactory [Token Factory Facets]
AssetRegistry[AssetRegistryFacet]
MarketFactory[MarketFactoryFacet]
MintBurn[MintBurnFacet]
InterestRate[InterestRateFacet]
BridgeWrap[BridgeWrapFacet]
DWIN[DWINFacet]
end
subgraph standards [Standards and Compliance Facets]
IPSAS[IPSASFacet]
IFRS[IFRSUSGAAPFacet]
ISO20022[ISO20022Facet]
i18n[i18nFacet]
GovLevel[GovernanceLevelFacet]
end
subgraph gates [Policy Gates]
PolicyRouter[PolicyRouterFacet]
ComplianceGate[ComplianceGate]
AccountingGate[AccountingGate]
MessagingGate[MessagingGate]
ReserveGate[ReserveGate]
end
M00 --> DiamondCut
M00 --> DiamondLoupe
M00 --> Ownership
M00 --> Pause
M00 --> AssetRegistry
M00 --> MarketFactory
M00 --> MintBurn
M00 --> InterestRate
M00 --> BridgeWrap
M00 --> DWIN
M00 --> IPSAS
M00 --> IFRS
M00 --> ISO20022
M00 --> i18n
M00 --> GovLevel
M00 --> PolicyRouter
PolicyRouter --> ComplianceGate
PolicyRouter --> AccountingGate
PolicyRouter --> MessagingGate
PolicyRouter --> ReserveGate
```
---
## 2. Exact Facet Names
### 2.1 Facets by family
| Facet name | Role | Notes |
|------------|------|--------|
| **Core** | | |
| DiamondCutFacet | Upgrade mechanism | ERC-2535 diamondCut |
| DiamondLoupeFacet | Introspection | facets, facetAddress, selectors |
| OwnershipFacet | Admin / governance | Owner, timelock, upgrade approval (or use GovernanceFacet) |
| PauseFacet | Risk controls | Global and per-selector pause (GuardianFacet alias) |
| **Token Factory** | | |
| AssetRegistryFacet | Asset definitions | ISO code, type, decimals; W positional semantics; assetId hash |
| MarketFactoryFacet | Market creation | Emits c/a/d token contracts per ISO asset |
| MintBurnFacet | Supply controls | Mint/burn rules, reserve gating, supply caps, emergency locks |
| InterestRateFacet | Aave-style indices | Index math for a/d; rate model plug-ins; accrual triggers |
| BridgeWrapFacet | W-before-ISO | Wrapped bridge; escrow proofs; bridge operators |
| DWINFacet | W-after-T/C | D-WIN; denomination logic; optional windowing rules |
| **Standards / Compliance** | | |
| IPSASFacet | Public sector accounting | GRU ledger ↔ IPSAS reporting; fund accounting |
| IFRSUSGAAPFacet | IFRS / US GAAP | Revenue recognition, lease/contract hooks, impairment/reserve reporting |
| ISO20022Facet | Message builders | pacs/camt payloads; dictionary mapping; settlement correlation |
| i18nFacet | Internationalization | Locale packs, translation keys, disclosure templates |
| GovernanceLevelFacet | Policy levels | Reads policy bitmask; routes enforcement per level 0..N |
| **Minimum ship list (stubs)** | | |
| PolicyRouterFacet | Gate orchestration | Calls Compliance, Accounting, Messaging, Reserve gates |
| ComplianceGateFacet | Stub | Allowlist/denylist, jurisdiction tags placeholders |
| AccountingGateFacet | Stub | Journal entry and chart-of-accounts placeholders |
| StandardsRegistryFacet | Module activation | Activate/deactivate modules; enforce required modules per governance level |
### 2.2 Gates (used by PolicyRouter)
| Gate | Purpose |
|------|---------|
| ComplianceGate | checkTransfer (KYC/AML, sanctions, jurisdiction) |
| AccountingGate | postJournal (ledger entries, CoA) |
| MessagingGate | logISO20022 (message logging, correlation IDs) |
| ReserveGate | checkBacking (reserve proofs, attestations) |
Each gate is replaceable via facet upgrade. The **minimum ship list** (§2.1) explicitly includes ComplianceGateFacet and AccountingGateFacet stubs; MessagingGate and ReserveGate may be stubbed or implemented in a later phase.
---
## 3. Storage Namespaces (GRUStorage)
App storage is centralized in **GRUStorage** with namespaced domains so upgrades do not break state.
| Namespace / domain | Contents |
|--------------------|----------|
| Governance & roles | DAO / Council / Guardian roles; emergency pause authorities; upgrade admin; timelock address; policy controllers per module |
| Token Factory Registry | assetId → token addresses (c, a, d); symbol → assetId; per-asset config (decimals, mint rules, chain domain, W positioning) |
| Accounting / Ledger | Journal entries (debits/credits); chart of accounts; cost centers / funds / projects; per-asset reserve attestations; policy metadata hashes |
| Compliance & Identity | KYC/AML allowlists; jurisdiction tags; sanctions flags; travel rule metadata pointers; audit proof roots |
| ISO-20022 Message Vault | Message schemas registry; outbound/inbound message logs; canonicalization hashes; correlation IDs for settlement events |
| i18n Registry | Locale packs (hash pointers); translation keys for UI/clients; multi-jurisdiction disclosure templates |
| Expandable Standards Registry | standardId → moduleConfig: enabled, version, validator contracts, policy-level constraints, data namespace pointers |
---
## 4. Governance Levels (0–5)
GovernanceLevelFacet reads the policy bitmask; PolicyRouter calls the gates according to the active level. **Default at deployment:** level **0** (Free / devnet / sandbox); set via GovernanceLevelFacet after init. See [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md) and institutional spec.
| Level | Name | KYC | Reserves | ISO-20022 | Accounting | Transfer restrictions | Timelock / attestors |
|-------|------|-----|----------|-----------|-------------|----------------------|----------------------|
| 0 | Free / devnet / sandbox | No | No | No | No | None | Minimal |
| 1 | KYC optional + audit | Optional | No | No | Audit logs | None | Standard |
| 2 | KYC required + proofs | Required | Reserve proofs | Logging | Journal optional | Per policy | Standard |
| 3 | IPSAS/IFRS enforced | Required | Reserve proofs | Logging | Journal mandatory | Restricted sets | Extended |
| 4 | Sovereign / regulated | Required | Attestations | Full | Full reporting | Restricted + allowlists | Multi-sig, attestors |
| 5 | Maximum compliance | Required | Full attestations | Full | Full + disclosures | Strict allowlists | Long timelocks, external attestors |
---
## 5. Canonical Symbol Grammar
Enforced in **AssetRegistryFacet** with deterministic parsing.
### 5.1 Market artifacts per ISO-4217
| Prefix | Meaning | Example |
|--------|---------|---------|
| c\<ISO>\<T\|C\> | Base compliant eMoney | cUSDC, cEURCT |
| a\<ISO>\<T\|C\> | Asset token / claim index | aUSDC, aEURCT |
| d\<ISO>\<T\|C\> | Debt token / liability index | dUSDC, dEURCT |
\<T\|C\> = issuer/type suffix (e.g. T = Tether, C = Circle-style).
### 5.2 W rules
- **W before ISO (wrapped bridge):** `W` precedes the ISO code.
Examples: `cWUSDT`, `aWUSDT`, `dWUSDT`.
- **W after T/C (D-WIN):** `W` follows the T or C suffix.
Examples: `cUSDTW`, `aUSDTW`, `dUSDTW`.
### 5.3 BNF-style summary
```
symbol := (c|a|d) iso_suffix | (c|a|d) W iso_suffix | (c|a|d) iso_suffix W
iso_suffix := <ISO4217 code><T|C> e.g. USDC, USDT, EURCT, EURCC
```
### 5.4 Examples
| Symbol | Interpretation |
|--------|----------------|
| cUSDC | Compliant base eMoney, USD (Circle-style) |
| aEURCT | Asset token, EUR (Tether) |
| dWUSDT | Debt token, wrapped USDT (bridge) |
| cUSDTW | Compliant base, USDT D-WIN (denomination/windowing) |
### 5.5 Mapping to deployed token names (a/d vs ac/vdc/sdc)
The canonical grammar uses **a** (asset) and **d** (debt). In the codebase and [TOKEN_SCOPE_GRU](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md), the same roles use Aave-style names: **a** ↔ **ac** (DepositToken, e.g. acUSDC, acUSDT), **d** ↔ **vdc** / **sdc** (DebtToken, e.g. vdcUSDC, sdcUSDC). The registry may store either form (aUSDC or acUSDC); both denote the same asset token type.
### 5.6 ISO-4217 Compliant Token Matrix (native / bridged)
The grammar above aligns with the [ISO4217 Compliant Token Matrix](ISO4217_COMPLIANT_TOKEN_MATRIX.md): native symbols 6-char (`c` + FinChain + ISO + Type), bridged 7-char (`c` + `W` + OriginFinChain + ISO + Type). **ChainID 138 only:** native symbols are v0 (no designator) — `cUSDC`, `cUSDT`; the X is left out. X is used only for origin reference (e.g. bridged `cWXUSDC` on other chains). Registry maps v0 → identity for reporting.
---
## Related documents
- **Full architecture spec:** [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) (§1–§8, token model and Pattern A locked).
- **Detailed review (gaps, wire-ins, recommendations):** [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md).
- **Docs review (gaps and inconsistencies):** [GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md).
- **Existing Diamond (GRC-2535):** [gru-docs/contracts/README.md](../../gru-docs/contracts/README.md). The GRU docs repo is also available as a standalone clone (e.g. **GRU-Official-Docs-Monetary-Policies**); in this repo it is the submodule `gru-docs/`. See [SUBMODULE_RELATIONSHIP_MAP.md](../11-references/SUBMODULE_RELATIONSHIP_MAP.md).
- **Token scope (c/a/d, W):** [smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md).
- **ISO-4217 compliant symbol matrix (native/bridged, v0/v1):** [ISO4217_COMPLIANT_TOKEN_MATRIX.md](ISO4217_COMPLIANT_TOKEN_MATRIX.md).
- **Vault / M00 reference:** [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md).

175
docs/04-configuration/GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md Normal file
View File

@@ -0,0 +1,175 @@
# GRU M00 Diamond — Institutional Architecture Spec
**Purpose:** Buildable blueprint for a single “giant Token Factory” inside the GRU ERC-2535 Diamond. Each currency + a/d token family is implemented as an upgradeable facet set; the GRU Diamond contains governance + storage placeholders for IPSAS, IFRS/US GAAP, ISO-20022, i18n, and future governance levels. Hand-off for whitepaper/tech spec and Solidity engineers.
**Related:** [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md) (single-page facet map, storage namespaces, governance levels, symbol grammar) | [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md) (gaps and wire-ins).
---
## GRU Diamond evolution (GRC-2535 vs M00)
**GRC-2535** (in [gru-docs/contracts](../../gru-docs/contracts/README.md)) is the current GRU Diamond: GrcDiamond + GRCStorage + Monetary, Triangulation, Index, Bond, Audit, Governance, Access, Pause facets. **M00 Diamond** extends or replaces it with the Token Factory, GRUStorage (seven domains), PolicyRouter + gates, and standards placeholders. **Decision:** Either (1) **migrate** GRC → M00 (same contract, add/replace facets and extend storage with reserved GRUStorage namespaces) or (2) **deploy M00 as a new Diamond** and deprecate GRC for token/market flows. Document the chosen path in the deployment runbook.
**Existing registries:** Until M00 is deployed, **UniversalAssetRegistry** (smom-dbis-138) remains the source of truth for bridges and token lists. After M00 is live, migrate or mirror to GRUStorage.TokenFactoryRegistry and document the cutover.
---
## 1) Diamond Topology Overview
### Core Principle
* **GRU = M00 Diamond (ERC-2535)**
* **All c-tokens + a-tokens + d-tokens** are minted/managed by **facets** attached to the GRU Diamond.
* Storage is centralized in **shared app storage** to ensure upgrades don’t break state.
* Governance is **layered and expandable**: policy modules are “plugged in” as facets without changing base state layout.
**Key idea:**
> “Tokens aren’t separate systems; they are *markets* inside the GRU Diamond, emitted as ERC-20 instances or ledgered as internal balance sheets, governed by standards modules.”
---
## 2) Storage Layout (Permanent / Upgrade-Safe)
### A) Diamond App Storage (GRUStorage)
Use **placeholder storage** for many future standards:
* a fixed storage struct (core)
* a **namespaced storage registry** for standards modules
* a **policy bitmask** and **module pointer map**
#### Core Storage Domains
1. **Governance & Roles** — DAO / Council / Guardian roles; emergency pause authorities; upgrade admin / timelock address; policy controllers (per module).
2. **Token Factory Registry** — mapping of `assetId → token addresses` (c, a, d variants); mapping of symbol → assetId (canonical parsing); per-asset configuration (decimals, mint rules, chain domain, W positioning, etc.).
3. **Accounting / Ledger** — Journal entries (debits/credits); chart of accounts; cost centers / funds / projects; per-asset reserve attestations; policy metadata hashes (auditable). Standards-neutral so IFRS/USGAAP/IPSAS can be added without refactoring.
4. **Compliance & Identity** — KYC/AML allowlists; jurisdiction tags; sanctions flags; travel rule metadata pointers; audit proof roots.
5. **ISO-20022 Message Vault** — Message schemas registry; outbound/inbound message logs; message “canonicalization” hashes; correlation IDs for settlement events.
6. **Internationalization (i18n) Registry** — Locale packs (hash pointers); translation keys for UI/client consumption; multi-jurisdiction disclosure templates.
7. **Expandable Standards Registry** — mapping `standardId => moduleConfig` (enabled flags, version, validator contracts, policy-level constraints, data namespace pointers). Enables “turning on” IPSAS or ISO-20022 without migrating storage.
---
## 3) Facet Families (Modular + Upgradeable)
### A) Core Diamond Facets (always present)
* **DiamondCutFacet** (upgrade)
* **DiamondLoupeFacet** (introspection)
* **Ownership/GovernanceFacet** (admin model, timelocks)
* **Pause/GuardianFacet** (risk controls)
### B) Token Factory Facets
1. **AssetRegistryFacet** — create/modify asset definition (ISO code, type, decimals); enforce W positional semantics; generate assetId deterministic hash.
2. **MarketFactoryFacet** — create a “market” for a given ISO asset; emit token contracts for **c** (compliant base), **a** (asset/claim), **d** (debt/liability).
3. **MintBurnFacet** — mint/burn rules; reserve gating; supply caps; emergency locks.
4. **InterestRateFacet (Aave-style)** — index math for a/d behavior; rate model plug-ins (stable/variable); accrual triggers.
5. **BridgeWrapFacet** — **W before ISO** assets (wrapped bridge); escrow proofs; bridge operators / trust model.
6. **DWINFacet** — **W after T/C** (D-WIN); denomination logic; optional “windowing” rules (maturity, buckets, liquidity windows).
### C) Standards / Compliance Facets (placeholders, expandable later)
* **IPSASFacet** — GRU ledger ↔ IPSAS reporting; fund accounting.
* **IFRS/USGAAPFacet** — Revenue recognition; lease/contract classification hooks; impairment / reserve adequacy reporting.
* **ISO20022Facet** — Message builders (pacs/camt); standard dictionary mapping per assetId; settlement event correlation.
* **i18nFacet** — Multi-language disclosure strings by jurisdiction; “legal label packs” versioned and signed.
* **GovernanceLevelFacet** — Policy levels 0..N; each level toggles KYC, transfer restrictions, message logging, accounting journal mandatory, oracle requirements, timelock durations, which standards must be enabled. Reads **policy bitmask** in storage and routes enforcement.
---
## 4) Governance Model (Expandable + Imposed Levels)
* **Level 0:** Free / devnet / sandbox rules.
* **Level 1:** KYC optional + audit logs.
* **Level 2:** KYC required + reserve proofs + ISO-20022 logging.
* **Level 3:** IPSAS/IFRS reporting enforced + restricted transfer sets.
* **Level 4+:** Sovereign/regulated regime enforcement + multi-sig + external attestors + longer timelocks.
**Implementation:** A **PolicyRouter** (facet) calls ComplianceGate.checkTransfer(...), AccountingGate.postJournal(...), MessagingGate.logISO20022(...), ReserveGate.checkBacking(...). Each gate is replaceable via facet upgrade.
---
## 5) How Currency Codes Become “Markets” Inside GRU
For each ISO-4217 code (USD, EUR, JPY, etc.):
* **c\<ISO>\<T|C>** (base compliant eMoney)
* **a\<ISO>\<T|C>** (asset token / claim index)
* **d\<ISO>\<T|C>** (debt token / liability index)
**W rules:** Wrapped bridge = `W` before ISO (e.g. aWUSDT, dWUSDT, cWUSDT). D-WIN = `W` after T/C (e.g. aUSDTW, dUSDTW, cUSDTW). Enforced in **AssetRegistryFacet** with deterministic parsing.
---
## 6) What “Upgradeable Facet per ISO” Means (Practical)
**Pattern A (recommended): One Factory, Many Assets (data-driven)** — One set of facets supports unlimited assets via config records. Safer: fewer upgrades, less surface area.
**Pattern B (if required): “Facet Packs” per asset family** — For major markets (USD/EUR), deploy specialized facets (special rate model, compliance regime, settlement rules). Storage remains standard.
**Target (locked):** **Pattern A** as default. **Pattern B** only for flagship USD/EUR asset families if required.
---
## 7) Minimum Placeholder Checklist (What GRU must include now)
1. **AppStorage skeleton** — module registry; policy bitmask; ledger/journal base structs; ISO-20022 log structs; i18n registry structs.
2. **GovernanceFacet** — role-based access control; timelock hooks; upgrade approval workflow.
3. **PolicyRouterFacet** — empty gates initially, but callable; emits events for auditability.
4. **TokenFactoryFacet** — can register assets; can deploy token instances (or ledgered balances if internal accounting).
5. **ComplianceGateFacet (stub)** — allowlist/denylist placeholder; jurisdiction tags placeholder.
6. **AccountingGateFacet (stub)** — journal entry emission placeholder; chart of accounts placeholder.
7. **StandardsRegistryFacet** — activate/deactivate modules; enforce “required modules for governance level X.”
---
## 8) One Key Design Decision You Should Lock
**Are tokens:**
* **A)** Separate ERC-20 contracts deployed by GRU (Aave-like)
* **B)** Internal ledger balances inside GRU with ERC-20 views
* **C)** Hybrid: ERC-20 external interface, authoritative balances in GRU ledger (tokens as thin proxies)
For DeFi compatibility, **A** is simplest. For sovereign accounting + ISO-20022 tight control, **B** is more “bank-core-like.”
**Locked decision:** **Token model A** (separate ERC-20 contracts deployed by GRU, Aave-like). For DeFi compatibility and simplest integration. B or C may be chosen later if sovereign/accounting requirements dictate.
---
## Deployment target chain and CREATE2
- **Primary chain:** Chain 138 (DeFi Oracle Meta Mainnet) first; then mainnet (1), 651940 (ALL Mainnet), or other EVM chains as needed.
- **CREATE2:** Use CREATE2 when the same M00 Diamond address is required across chains; otherwise CREATE is acceptable for single-chain (e.g. 138-only) deployment.
- **Default governance level at deployment:** **0** (Free / devnet / sandbox). Set via GovernanceLevelFacet after init. For production, set to 1 or 2 (or per policy) in a separate init step.
- **Runbook:** [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md).
---
## Appendix: PolicyRouter and gate event signatures
For auditability and indexers, PolicyRouter and gates SHOULD emit the following events (or equivalent). Implement when building the spine.
| Event | Signature (semantic) | Emitted by |
|-------|----------------------|------------|
| **TransferChecked** | `TransferChecked(address from, address to, address token, uint256 amount, bool allowed, bytes32 reason)` | PolicyRouter after ComplianceGate.checkTransfer |
| **JournalPosted** | `JournalPosted(bytes32 journalId, bytes32 coaRef, uint256 amount, address token)` | PolicyRouter after AccountingGate.postJournal |
| **MessageLogged** | `MessageLogged(bytes32 correlationId, bytes32 payloadHash, string msgType)` | PolicyRouter after MessagingGate.logISO20022 |
| **BackingChecked** | `BackingChecked(bytes32 assetId, uint256 amount, bool sufficient, bytes32 attestationHash)` | PolicyRouter after ReserveGate.checkBacking |
| **GovernanceLevelSet** | `GovernanceLevelSet(uint8 previousLevel, uint8 newLevel)` | GovernanceLevelFacet when level is updated |
Use indexed parameters where appropriate (e.g. `indexed address token`, `indexed bytes32 correlationId`) for efficient filtering. Full ABI and parameter types to be defined in the implementation.
---
## Related documents
- [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md) — Facet map, storage namespaces, governance levels 0–5, canonical symbol grammar.
- [GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md) — Missing components, wire-ins, recommendations.
- [GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md) — Docs review (gaps and inconsistencies).
- [gru-docs/contracts/README.md](../../gru-docs/contracts/README.md) — GRC-2535 Diamond.
- [TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md) — c/a/d and W token lists.
- [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md) — Vault and M00 reference.
- [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md) — Deploy or migrate M00; target chain, CREATE2, default governance level, testing.

263
docs/04-configuration/GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md Normal file
View File

@@ -0,0 +1,263 @@
# GRU M00 Diamond — Detailed Review: Gaps, Wire-Ins, and Recommendations
**Purpose:** Structured review of the GRU M00 Diamond (ERC-2535) Token Factory architecture against the current codebase and docs. Covers missing components, functional wire-ins to complete, naming/alignment gaps, and actionable recommendations.
**References:** [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md), [gru-docs/contracts/README.md](../../gru-docs/contracts/README.md) (GRU docs; same repo as **GRU-Official-Docs-Monetary-Policies** when cloned standalone), [smom-dbis-138](../smom-dbis-138), [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md).
---
## 1. Executive Summary
| Area | Status | Summary |
|------|--------|---------|
| **Spec vs implementation** | Gap | Facet Map describes M00 Diamond + GRUStorage + PolicyRouter + gates; repo has GRC-2535 Diamond (different facets) and standalone UniversalAssetRegistry/TokenFactory/VaultFactory — no single M00 Diamond yet. |
| **Missing components** | Multiple | Institutional spec doc, GRUStorage layout, PolicyRouter + four gates (on-chain), Token Factory facets (AssetRegistry, MarketFactory, MintBurn, InterestRate, BridgeWrap, DWIN), Standards facets (IPSAS, IFRS, ISO20022, i18n, GovernanceLevel), minimum ship stubs. |
| **Wire-ins** | Incomplete | No Diamond → Token Factory wiring; no PolicyRouter → gate calls; no governance level bitmask → enforcement; off-chain ComplianceGate (dbis_core) not mirrored on-chain. |
| **Naming alignment** | Gap | Spec grammar uses **a**\<ISO>, **d**\<ISO>; deployed/specified tokens use **ac***, **vdc***/sdc* — need explicit mapping or doc alignment. |
---
## 2. Missing Components
### 2.1 Documentation
| Item | Description | Recommendation |
|------|-------------|-----------------|
| **GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md** | Full §1–§8 institutional architecture spec (Diamond topology, storage, facets, governance, markets, W rules, Pattern A/B, minimum checklist, token model A/B/C). | **Done:** [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) created; token model A and Pattern A locked; GRC vs M00 evolution note added. |
| **Token model decision** | Facet Map had “[ A \| B \| C ]”; locked choice was missing. | **Done:** Institutional spec §8 locks **Token model A**; Facet Map updated to “A (locked).” |
| **Pattern A vs B** | Target pattern was not stated. | **Done:** Institutional spec §6 locks **Target: Pattern A**; Facet Map “Target pattern” line added. |
### 2.2 Storage (GRUStorage)
| Domain | Facet Map / Spec | Current State | Gap |
|--------|------------------|---------------|-----|
| Governance & roles | DAO/Council/Guardian, upgrade admin, timelock, policy controllers | GRCStorage has Gov (timelock, quorum, proposals), Access (role bits), no DAO/Council/Guardian names. | Add GRUStorage namespace constants and structs for governance; align or migrate from GRCStorage if M00 supersedes GRC. |
| Token Factory Registry | assetId → (c,a,d) addresses; symbol → assetId; per-asset config | UniversalAssetRegistry has token → UniversalAsset (type, compliance, metadata); no assetId, no c/a/d triple per asset. | Define GRUStorage.TokenFactoryRegistry (or equivalent) with assetId, symbol→assetId, and c/a/d address triple; or document migration path from UniversalAssetRegistry. |
| Accounting / Ledger | Journal entries, CoA, cost centers, reserve attestations, policy hashes | Not in Diamond; OMNL/Fineract off-chain. No on-chain journal/CoA structs. | Add GRUStorage.Accounting placeholder structs (journal entry, CoA slot, attestation hashes) for AccountingGateFacet stub. |
| Compliance & Identity | KYC/AML allowlists, jurisdiction, sanctions, travel rule, audit roots | ComplianceGuard (iso4217w) validates mint/reserve only; no allowlist/jurisdiction/sanctions in contracts. dbis_core has ComplianceGateService (sanctions/AML). | Add GRUStorage.Compliance placeholder (allowlist/denylist, jurisdiction tags); wire ComplianceGate to it or to external oracle. |
| ISO-20022 Message Vault | Schema registry, in/out logs, canonicalization hashes, correlation IDs | SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY defines canonical struct; no on-chain vault or log storage. | Add GRUStorage.ISO20022Vault (or event-only + off-chain index); implement MessagingGate.logISO20022. |
| i18n Registry | Locale packs, translation keys, disclosure templates | Not present in any contract. | Add GRUStorage.i18n placeholder (locale keys, hash pointers); i18nFacet stub reads from it. |
| Expandable Standards Registry | standardId → moduleConfig (enabled, version, validators, constraints, pointers) | Not present. | Add GRUStorage.StandardsRegistry; StandardsRegistryFacet activate/deactivate modules and enforce “required modules per governance level.” |
### 2.3 Core Diamond Facets
| Facet | Spec | Current State | Gap |
|-------|------|---------------|-----|
| DiamondCutFacet | Upgrade mechanism | GrcDiamond has diamondCut inline; no separate facet. | OK if M00 keeps cut in core; else extract to DiamondCutFacet. |
| DiamondLoupeFacet | Introspection | GrcDiamond has loupe inline. | Same as above. |
| OwnershipFacet / GovernanceFacet | Owner, timelock, upgrade approval | GrcDiamond has owner; GovernanceFacet has proposeCut/queue/execute. | Alias or merge into single “GovernanceFacet” for M00; ensure timelock and upgrade approval workflow documented. |
| PauseFacet | Global and per-selector pause | PauseFacet exists in gru-docs; GRCStorage has PauseState. | Keep; ensure M00 uses same slot namespace if migrating from GRC. |
### 2.4 Token Factory Facets (all missing as Diamond facets)
| Facet | Spec | Current State | Gap |
|-------|------|---------------|-----|
| AssetRegistryFacet | Asset definitions, W semantics, assetId hash | UniversalAssetRegistry (standalone) has asset types and metadata; iso4217w TokenFactory enforces \<CCC\>W. No deterministic assetId or c/a/d symbol grammar in one place. | Implement as facet (or wrap UniversalAssetRegistry behind facet); add symbol→assetId and W-before/W-after parsing per Facet Map grammar. |
| MarketFactoryFacet | Creates market per ISO; emits c/a/d token contracts | VaultFactory creates vault + DepositToken + DebtToken per asset; TokenFactory138 is stub; CompliantUSDC/USDT and CompliantFiatToken are separate contracts. | Either (1) MarketFactoryFacet deploys proxy/minimal clones for c/a/d, or (2) MarketFactoryFacet registers existing external c/a/d addresses in GRUStorage; document vs VaultFactory/TokenFactory138. |
| MintBurnFacet | Mint/burn rules, reserve gating, supply caps, emergency locks | ComplianceGuard validates mint; individual token contracts have mint/burn. No single MintBurnFacet. | Implement MintBurnFacet calling ReserveGate and token contracts or internal ledger; centralize caps and emergency locks in storage. |
| InterestRateFacet | Aave-style index math, rate models, accrual | Not in gru-docs or smom-dbis-138 as a facet. DepositToken/DebtToken do not implement interest indices. | Add InterestRateFacet (stub or full) with index storage and rate model hooks. |
| BridgeWrapFacet | W-before-ISO (wrapped bridge), escrow, bridge operators | Bridge contracts (GRUCCIPBridge, ISO4217WCCIPBridge, etc.) are standalone; no “BridgeWrapFacet” in Diamond. | Add facet that delegates to bridge contracts or holds bridge operator config in GRUStorage. |
| DWINFacet | W-after-T/C (D-WIN), denomination, windowing | Not present. | Add DWINFacet stub with storage for denomination/windowing rules. |
### 2.5 Standards / Compliance Facets (all missing or stub-only)
| Facet | Spec | Current State | Gap |
|-------|------|---------------|-----|
| IPSASFacet | GRU ledger ↔ IPSAS reporting, fund accounting | OMNL has IPSAS in Fineract/off-chain journal matrix; no on-chain facet. | Add IPSASFacet stub; document mapping from GRUStorage ledger to IPSAS classifications. |
| IFRSUSGAAPFacet | Revenue recognition, lease/contract hooks, impairment | Not present. | Add stub; document future hooks. |
| ISO20022Facet | pacs/camt builders, dictionary, settlement correlation | Methodology doc and runbook exist; no on-chain message builder facet. | Add ISO20022Facet stub; emit or store canonical message hashes/correlation IDs per MessagingGate. |
| i18nFacet | Locale packs, translation keys, disclosure templates | Not present. | Add stub; read from GRUStorage.i18n. |
| GovernanceLevelFacet | Policy levels 0..N, bitmask, routes enforcement | Not present. GRCStorage has no policy level or bitmask. | Add GovernanceLevelFacet; add GRUStorage policy level and bitmask; document “required modules per level.” |
### 2.6 Policy Layer (Router + Gates)
| Component | Spec | Current State | Gap |
|-----------|------|---------------|-----|
| PolicyRouterFacet | Calls ComplianceGate, AccountingGate, MessagingGate, ReserveGate | Not present in contracts. | Implement PolicyRouterFacet: e.g. `checkTransfer` → ComplianceGate, `postJournal` → AccountingGate, `logISO20022` → MessagingGate, `checkBacking` → ReserveGate; gate addresses from storage or facet. |
| ComplianceGate | checkTransfer (KYC/AML, sanctions, jurisdiction) | dbis_core ComplianceGateService (off-chain); ComplianceGuard (on-chain) only validates mint/reserve. | Add ComplianceGateFacet (stub) with allowlist/denylist and jurisdiction placeholders; optionally call off-chain or oracle. |
| AccountingGate | postJournal (ledger, CoA) | No on-chain gate. | Add AccountingGateFacet stub; write to GRUStorage.Accounting or emit events. |
| MessagingGate | logISO20022 (message log, correlation IDs) | No on-chain gate. | Add MessagingGateFacet stub; write to GRUStorage.ISO20022Vault or emit events. |
| ReserveGate | checkBacking (reserve proofs, attestations) | ComplianceGuard validates reserve for mint; no generic “checkBacking” gate. | Add ReserveGateFacet stub; delegate to existing reserve/oracle logic or attestation hashes in storage. |
### 2.7 Minimum Ship List (Stubs)
| Item | Spec | Current State | Gap |
|------|------|---------------|-----|
| AppStorage skeleton | Module registry, policy bitmask, ledger/ISO20022/i18n structs | GRCStorage has different namespaces; no GRUStorage. | Define GRUStorage (or extend GRCStorage with reserved namespaces) with all 7 domains + policy bitmask + module registry. |
| GovernanceFacet | RBAC, timelock, upgrade approval | Exists in gru-docs (GovernanceFacet). | Verify it fits M00; add “policy controllers per module” if required. |
| PolicyRouterFacet | Empty gates callable, events | Missing. | Implement as above. |
| TokenFactoryFacet | Register assets, deploy or ledger tokens | TokenFactory138 is stub; no Diamond facet. | Implement TokenFactoryFacet (or unify AssetRegistry + MarketFactory) to register assets and create/link c/a/d. |
| ComplianceGateFacet (stub) | Allowlist, jurisdiction placeholders | Missing. | Add stub. |
| AccountingGateFacet (stub) | Journal, CoA placeholders | Missing. | Add stub. |
| StandardsRegistryFacet | Activate/deactivate modules, enforce required per level | Missing. | Add; wire to GRUStorage.StandardsRegistry and GovernanceLevelFacet. |
---
## 3. Functional Wire-Ins to Complete
### 3.1 Diamond ↔ Token Factory
- **Current:** No single Diamond owns token creation. VaultFactory, TokenFactory (iso4217w), CompliantFiatToken deployments are independent.
- **Target:** M00 Diamond exposes AssetRegistryFacet + MarketFactoryFacet (or TokenFactoryFacet); all c/a/d registration and creation go through Diamond.
- **Wire-in:** (1) Deploy M00 Diamond with GRUStorage; (2) Add AssetRegistryFacet + MarketFactoryFacet (or TokenFactoryFacet); (3) MarketFactoryFacet either deploys new c/a/d contracts or registers existing ones in GRUStorage; (4) All mint/burn/transfer that must be gated go through Diamond (or token contracts call back into Diamond for gate checks).
**c* GRU integration (implemented):** All c* (compliant) tokens are integrated with the GRU ERC-2535 facet path: (1) **UniversalAssetRegistry** — register each c* via `registerGRUCompliantAsset()` (AssetType.GRU, no timelock); (2) **GRUCCIPBridge** and **PoolManager** read the registry and accept GRU assets; (3) **GRUAssetRegistryFacet** delegates to UniversalAssetRegistry so the M00 Diamond can expose the same registry when the facet is attached. Run **RegisterGRUCompliantTokens.s.sol** after deploying c* tokens; run **GRUCompliantTokensRegistryTest** (integration tests) before deployments. See [DEPLOYMENT_ORDER_OF_OPERATIONS](../03-deployment/DEPLOYMENT_ORDER_OF_OPERATIONS.md) § Phase 2.4.
### 3.2 PolicyRouter → Gates
- **Current:** No PolicyRouter; no on-chain gates except ComplianceGuard (mint-only).
- **Target:** Every transfer (or mint/burn) that is policy-sensitive calls PolicyRouter.checkTransfer (or equivalent); PolicyRouter reads GovernanceLevelFacet level and calls ComplianceGate, AccountingGate, MessagingGate, ReserveGate as required.
- **Wire-in:** (1) Implement PolicyRouterFacet with `checkTransfer`, `postJournal`, `logISO20022`, `checkBacking`; (2) Implement each gate as facet or internal module; (3) Token contracts or Diamond entry points call PolicyRouter before state changes; (4) GovernanceLevelFacet exposes level/bitmask; PolicyRouter reads it and skips or enforces each gate.
### 3.3 Governance Level → Enforcement
- **Current:** No governance level or bitmask in storage; no routing by level.
- **Target:** Governance levels 0–5 (per Facet Map); level stored in GRUStorage; GovernanceLevelFacet and PolicyRouter use it to decide which gates to call and with what strictness.
- **Wire-in:** (1) Add `governanceLevel` (and optional `policyBitmask`) to GRUStorage; (2) GovernanceLevelFacet get/set level (restricted); (3) PolicyRouter and gate stubs branch on level; (4) Document level semantics (0–5) in Facet Map and runbooks.
### 3.4 Off-Chain vs On-Chain Compliance
- **Current:** dbis_core ComplianceGateService does sanctions/AML off-chain; on-chain ComplianceGuard only validates mint/reserve for ISO4217W.
- **Target:** Clear split: which checks are on-chain (allowlist/denylist, jurisdiction tags) vs off-chain (full sanctions/AML); on-chain ComplianceGateFacet calls external adapter or stores results.
- **Wire-in:** (1) Define interface for “compliance result” (allowed/denied + reason); (2) ComplianceGateFacet stub stores allowlist/denylist and jurisdiction in GRUStorage; (3) Optionally add “oracle” or relayer that posts off-chain ComplianceGateService result on-chain for PolicyRouter to read.
### 3.5 ISO-20022 and MessagingGate
- **Current:** Canonical message format and methodology doc exist; no on-chain message log or correlation.
- **Target:** MessagingGate.logISO20022 stores or emits message hash + correlation ID; ISO20022Facet can build/reference pacs/camt payloads.
- **Wire-in:** (1) Add GRUStorage.ISO20022Vault (or event-only design); (2) MessagingGateFacet accepts canonical struct hash + correlationId; (3) Emit event and/or write to storage; (4) Link to SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY and MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.
### 3.6 Reserve and Attestation
- **Current:** ComplianceGuard validates reserve for mint; PoR in GRCStorage (AuditPeriod); no generic “checkBacking” for all operations.
- **Target:** ReserveGate.checkBacking(assetId, amount) used by PolicyRouter before mint/transfer where level requires; attestation hashes in GRUStorage.
- **Wire-in:** (1) ReserveGateFacet stub checks GRUStorage or external oracle for reserve/attestation; (2) MintBurnFacet (or token contracts) call ReserveGate when level ≥ 2; (3) Document attestation format and who posts hashes.
---
## 4. Naming and Alignment Gaps
### 4.1 Symbol Grammar: a/d vs ac/vdc/sdc
- **Facet Map / institutional spec:** Canonical grammar uses **a**\<ISO>\<T|C\> (asset) and **d**\<ISO>\<T|C\> (debt). Examples: aUSDC, dUSDC, aEURCT, dWUSDT.
- **TOKEN_SCOPE_GRU and deployment:** Tokens are named **ac*** (e.g. acUSDC, acUSDT) and **vdc***/sdc* (e.g. vdcUSDC, sdcUSDC). These are Aave-style “deposit” and “debt” tokens.
- **Gap:** “a” and “d” in the spec are logical roles; “ac” and “vdc/sdc” are implementation names. Either (1) document that **a** = **ac** (asset/deposit) and **d** = **vdc/sdc** (debt) and keep both nomenclatures, or (2) rename in spec to ac/d for consistency with deployed tokens.
- **Recommendation:** Add a short subsection in Facet Map or TOKEN_SCOPE_GRU: “Canonical grammar: **a** (asset) ↔ **ac** (DepositToken), **d** (debt) ↔ **vdc** / **sdc** (DebtToken). Symbol in registry may be aUSDC or acUSDC; both refer to same asset token type.”
### 4.2 GRC-2535 vs M00 Diamond
- **GRC-2535 (gru-docs):** GrcDiamond + GRCStorage + Monetary, Triangulation, Index, Bond, Audit, Governance, Access, Pause, ComplianceFacet (stub), OracleAggregatorFacet (stub). No Token Factory, no PolicyRouter, no GRUStorage as in Facet Map.
- **M00 Diamond (Facet Map):** Single Diamond with GRUStorage, Token Factory facets, Standards facets, PolicyRouter + gates.
- **Gap:** Two different “Diamond” designs. Migration path or relationship is undefined.
- **Recommendation:** Document in institutional spec or a “GRU Diamond Evolution” note: “GRC-2535 is the current GRU Diamond (monetary, bond, index, audit). M00 Diamond extends or replaces it with Token Factory + GRUStorage + policy gates. Decision: migrate GRC → M00 (same contract, new facets + storage) vs deploy M00 as new Diamond and deprecate GRC.”
### 4.3 UniversalAssetRegistry vs AssetRegistryFacet
- **UniversalAssetRegistry (smom-dbis-138):** Central registry for asset types (GRU, ISO4217W, Commodity, etc.); used by bridges, PoolManager, GovernanceController, TokenlistGovernanceSync. Not a Diamond facet.
- **AssetRegistryFacet (spec):** Asset definitions, W semantics, assetId, symbol→assetId inside M00 Diamond.
- **Gap:** Duplication or migration path unclear.
- **Recommendation:** (1) If M00 is new deployment: AssetRegistryFacet could wrap or replace UniversalAssetRegistry (Diamond holds registry state or delegates to external registry). (2) Document “UniversalAssetRegistry remains source of truth for bridges until M00 is deployed; then migrate or mirror to GRUStorage.TokenFactoryRegistry.”
---
## 5. Recommendations and Suggestions
### 5.1 High priority
1. **Create GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md** — Paste the full §1–§8 institutional spec; link from Facet Map. This is the single hand-off doc for Solidity engineers.
2. **Lock token model (A/B/C)** — Document in spec or Facet Map which of (A) separate ERC-20, (B) internal ledger, (C) hybrid is the target; update Facet Map “Token model” line accordingly.
3. **Define GRUStorage layout** — One Solidity library or doc with namespaced structs and slots for all 7 domains + policy bitmask + standards registry. Reserve namespaces for future facets to avoid collision.
4. **Implement minimum ship list** — PolicyRouterFacet + four gate stubs (Compliance, Accounting, Messaging, Reserve), StandardsRegistryFacet, GovernanceLevelFacet (level + bitmask), and TokenFactoryFacet (or AssetRegistry + MarketFactory) that register assets and optionally deploy/link c/a/d. Start with stubs that revert or no-op with events.
5. **Wire PolicyRouter to governance level** — PolicyRouter reads level from GovernanceLevelFacet; for each transfer/mint path, call only the gates required for that level; document in runbook.
### 5.2 Medium priority
6. **Align symbol grammar with TOKEN_SCOPE_GRU** — Add a↔ac, d↔vdc/sdc mapping and keep single source of truth for “canonical symbol” (either Facet Map or TOKEN_SCOPE_GRU with cross-link).
7. **Document GRC-2535 → M00 path** — One-page “Diamond evolution” or “M00 migration”: whether M00 is new Diamond or upgrade of GrcDiamond; which facets/storage are reused vs new.
8. **Reserve GRUStorage namespaces** — Even if a domain is stub-only, reserve its slot (keccak256 namespace) so future facets can extend without migration.
9. **ISO-20022 on-chain footprint** — Decide event-only vs storage for message log; implement MessagingGate.logISO20022 and optional ISO20022Facet stub.
10. **Off-chain ComplianceGate integration** — Define how dbis_core ComplianceGateService result is consumed on-chain (relayer, oracle, or keep transfer checks off-chain and only log).
### 5.3 Lower priority / optional
11. **InterestRateFacet and DWINFacet** — Stub with storage for rate indices and D-WIN rules; full implementation when a/d token behavior is finalized.
12. **IPSASFacet / IFRSUSGAAPFacet** — Stub and mapping doc from GRU ledger codes to IPSAS/IFRS; full logic later.
13. **i18nFacet** — Stub reading locale/key hashes from GRUStorage; UI/legal can consume from indexer or API.
14. **Pattern B (facet packs per asset)** — Only if a flagship USD/EUR market needs dedicated rate/compliance/settlement logic; document when and how.
---
## 6. Checklist for “Spine” Completion
Use this as a quick gate for “deployable spine” per institutional spec §7.
| # | Item | Done |
|---|------|------|
| 1 | AppStorage skeleton (module registry, policy bitmask, ledger/ISO20022/i18n structs) | ☐ |
| 2 | GovernanceFacet (RBAC, timelock, upgrade approval) | ☐ (exists in GRC; verify for M00) |
| 3 | PolicyRouterFacet (callable gates, events) | ☐ |
| 4 | TokenFactoryFacet or AssetRegistry + MarketFactory (register assets, deploy or ledger c/a/d) | ☐ |
| 5 | ComplianceGateFacet (stub: allowlist, jurisdiction) | ☐ |
| 6 | AccountingGateFacet (stub: journal, CoA) | ☐ |
| 7 | StandardsRegistryFacet (activate/deactivate, require per level) | ☐ |
| 8 | GovernanceLevelFacet (level 0..N, bitmask) | ☐ |
| 9 | GRUStorage namespaces defined and reserved | ☐ |
| 10 | PolicyRouter wired to level and gates | ☐ |
| 11 | Institutional spec doc created and linked | ☑ (GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) |
| 12 | Token model A/B/C locked and documented | ☑ (Token model A, Pattern A in institutional spec §8, §6) |
| 13 | Testing and verification (post-deploy) | ☐ — Run [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md) §6 (loupe, governance level, PolicyRouter, storage layout, upgrade, events). Add Forge/Hardhat tests when spine is implemented. |
---
## 7. Additional Recommendations, Suggestions, and Gaps
Beyond §2–§6 and the spine checklist, the following are additional recommendations, suggestions, or gaps.
### 7.1 Runbooks and deployment
| Item | Gap | Recommendation |
|------|-----|-----------------|
| **M00 deployment runbook** | Institutional spec said “Document the chosen path in the deployment runbook”; no runbook existed. | **Done:** [GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md](../runbooks/GRU_M00_DIAMOND_DEPLOYMENT_RUNBOOK.md) — Option A (new Diamond), Option B (migrate GRC→M00), target chain, CREATE2, initial facet order, testing §6. |
| **Chain and CREATE2** | M00 Diamond spec did not state target chain(s) or CREATE2. | **Done:** Runbook §1 and institutional spec "Deployment target chain and CREATE2" state: primary chain 138, then mainnet/651940; CREATE2 when same-address parity required. |
### 7.2 Cross-doc and repo alignment
| Item | Gap | Recommendation |
|------|-----|-----------------|
| **TOKEN_SCOPE_GRU ↔ Facet Map** | Facet Map §5.5 links to TOKEN_SCOPE_GRU; TOKEN_SCOPE_GRU did not link back. | **Done:** TOKEN_SCOPE_GRU §8 has “Canonical symbol grammar” note with link to Facet Map §5. |
| **VAULT_SYSTEM_MASTER_TECHNICAL_PLAN** | VAULT_SYSTEM mentioned M00 but did not link to M00 docs. | **Done:** VAULT_SYSTEM §3 (GRU Assets) links to institutional spec and Facet Map. |
| **REQUIRED_FIXES_UPDATES_GAPS** | Repo-wide gaps doc did not list GRU M00 Diamond spine. | **Done:** §9 includes “GRU M00 Diamond spine (optional)” with links to institutional spec §7, Review §6 checklist, deployment runbook. |
### 7.3 Defaults and interfaces
| Item | Gap | Recommendation |
|------|-----|-----------------|
| **Default governance level** | Facet Map defined levels 0–5 but did not state default at deployment. | **Done:** Institutional spec “Deployment target chain and CREATE2” and runbook §2 state default level 0; Facet Map §4 references runbook and spec. |
| **PolicyRouter and gate events** | Spec said gates “emit events” but no standard event names/signatures were defined. | **Done:** Institutional spec **Appendix: PolicyRouter and gate event signatures** defines TransferChecked, JournalPosted, MessageLogged, BackingChecked, GovernanceLevelSet. Runbook §6 references the appendix. |
### 7.4 Testing and verification
| Item | Gap | Recommendation |
|------|-----|-----------------|
| **M00 Diamond tests** | No tests or verification steps were documented for M00 Diamond. | **Done:** Runbook §6 defines post-deploy checks (loupe, governance level, PolicyRouter, storage layout, upgrade, events). Spine checklist item 13 added; add Forge/Hardhat tests when spine is implemented. |
### 7.5 UniversalAssetRegistry migration
| Item | Gap | Recommendation |
|------|-----|-----------------|
| **Explicit migration note** | Review §4.3 recommended documenting UniversalAssetRegistry as source of truth until M00. | **Done:** Institutional spec “GRU Diamond evolution” includes “Existing registries”: UniversalAssetRegistry remains source of truth until M00; after M00, migrate or mirror to GRUStorage.TokenFactoryRegistry and document cutover. |
---
## 8. Related Documents
- [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md) — Facet map, storage namespaces, governance levels, symbol grammar.
- [GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md) — Review of all GRU M00 Diamond docs for gaps and inconsistencies.
- [GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md) — Full §1–§8 institutional spec; token model A and Pattern A locked; GRC vs M00 evolution.
- [gru-docs/contracts/README.md](../../gru-docs/contracts/README.md) — GRC-2535 Diamond.
- [smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md) — c/a/d and W token lists.
- [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md) — Canonical message format.
- [VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md](../VAULT_SYSTEM_MASTER_TECHNICAL_PLAN.md) — Vault and M00 reference.
- [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md) — Repo-wide fixes and gaps.
**See also §7** for additional recommendations (runbooks, cross-docs, defaults, events, testing, UniversalAssetRegistry migration).

2
docs/04-configuration/INGRESS_VERIFICATION_RUNBOOK.md
View File

@@ -20,6 +20,8 @@ This runbook provides step-by-step verification procedures for the complete ingr
## Prerequisites
**Production note:** Example values below (e.g. `your-token`, `your-password`) are placeholders. In production, source real values from your `.env` file only; do not commit secrets.
### Access Credentials
Ensure the following are configured in `.env`:

180
docs/04-configuration/IPFS_TOKEN_LOGOS_RUNBOOK.md Normal file
View File

@@ -0,0 +1,180 @@
# IPFS Token Logos — Full Coverage for All Networks and Explorers
**Last Updated:** 2026-02-28
**Purpose:** Host all token logos on IPFS so they are available for explorer.d-bis.org (Blockscout), token lists, MetaMask, CoinGecko/CMC, and all bridge networks.
---
## 1. Current State
### IPFS in This Repo
| Component | Location | Purpose |
|-----------|----------|---------|
| **Firefly IPFS** | `smom-dbis-138/k8s/firefly/ipfs.yaml`, `smom-dbis-138-proxmox/install/firefly-install.sh` | Firefly shared storage (internal) |
| **Kubo (standalone)** | `ProxmoxVE/install/kubo-install.sh` | General-purpose IPFS node (LXC) |
### Logo Consumers
| Consumer | Where | Format |
|----------|-------|--------|
| **Blockscout (explorer.d-bis.org)** | `tokens.logo_url` in DB, or `/images/tokens/{address}.png` | PNG, any size |
| **Token list (dbis-138.tokenlist.json)** | `logoURI` per token | URL (PNG/SVG) |
| **Token-aggregation API** | `getLogoUriForSpec()` in canonical-tokens.ts | Trust Wallet URLs |
| **MetaMask / Snap** | Fetches token list with logoURI | URL |
| **CoinGecko / CMC** | 512×512 PNG for submission | PNG |
| **Other explorers** | etherscan.io, bscscan.com, polygonscan.com, etc. | Token metadata or external lists |
### Networks and Explorers
| Chain ID | Network | Explorer | Token Logo Source |
|----------|---------|----------|-------------------|
| 138 | Chain 138 | explorer.d-bis.org | Blockscout DB / static / IPFS |
| 651940 | ALL Mainnet | — | Token list |
| 1 | Ethereum | etherscan.io | Contract metadata, token lists |
| 56 | BSC | bscscan.com | Same |
| 137 | Polygon | polygonscan.com | Same |
| 100 | Gnosis | gnosisscan.io | Same |
| 10 | Optimism | optimistic.etherscan.io | Same |
| 42161 | Arbitrum | arbiscan.io | Same |
| 8453 | Base | basescan.org | Same |
| 43114 | Avalanche | snowtrace.io | Same |
| 25 | Cronos | cronoscan.com | Same |
| 42220 | Celo | celoscan.io | Same |
| 1111 | Wemix | scan.wemix.com | Same |
**Key:** Third-party explorers (Etherscan, BSCScan, etc.) resolve logos from contract metadata, token lists, or their own registries. Our token list URL (`https://explorer.d-bis.org/api/v1/report/token-list`) provides logoURI for wallets. For Blockscout (our explorer), we control logo display.
---
## 2. Logo Inventory (All Tokens)
### Chain 138 Tokens (dbis-138.tokenlist.json)
| Symbol | Address (138) | Current logoURI |
|--------|---------------|-----------------|
| ETH-USD | 0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6 | ethereum.org |
| WETH | 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 | ethereum.org |
| WETH10 | 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f | ethereum.org |
| LINK | 0xb7721dD53A8c629d9f1Ba31a5819AFe250002b03 | chainlink-docs |
| cUSDT | 0x93E66202A11B1772E55407B32B44e5Cd8eda7f22 | Trust Wallet |
| cUSDC | 0xf22258f57794CC8E06237084b353Ab30fFfa640b | Trust Wallet |
### Canonical Tokens (All Networks)
From `canonical-tokens.ts`: cUSDC, cUSDT, cEURC, cEURT, cGBPC, cGBPT, cAUDC, cJPYC, cCHFC, cCADC, cXAUC, cXAUT, LiXAU, USDW, EURW, GBPW, AUDW, JPYW, CHFW, CADW, WETH, WETH10, LINK, ETH-USD (oracle).
---
## 3. IPFS Setup Options
### Option A: Use Existing Firefly IPFS
If Firefly IPFS is running and has a public gateway:
```bash
# Gateway typically at http://<ipfs-host>:8080
# Add file: curl -X POST -F file=@logo.png "http://<ipfs-api>:5001/api/v0/add"
```
### Option B: Standalone Kubo (ProxmoxVE Script)
```bash
# Install Kubo on LXC via ProxmoxVE script
# ProxmoxVE/install/kubo-install.sh
# Then: ipfs add logo.png
```
### Option C: Pinata / Infura / Web3.Storage
For production, use a pinning service so logos stay available even when your node is offline:
- **Pinata:** https://pinata.cloud — free tier, pin by upload
- **Web3.Storage:** https://web3.storage — free, IPFS + Filecoin
- **Infura IPFS:** https://infura.io/product/ipfs
### Option D: Public Gateway (ipfs.io)
After `ipfs add`, use `https://ipfs.io/ipfs/<CID>` or `https://<cid>.ipfs.dweb.link`. No pinning service needed if you pin locally and others fetch; for reliability, use a pinning service.
---
## 4. Workflow: Prepare → Upload → Update
### Step 1: Prepare 512×512 PNGs
```bash
./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh
# Output: docs/04-configuration/coingecko/logos/*.png
```
### Step 2: Upload to IPFS
```bash
./scripts/upload-token-logos-to-ipfs.sh
# Uses: ipfs add (local) or Pinata API (if PINATA_JWT set)
# Output: docs/04-configuration/coingecko/logos/ipfs-manifest.json
```
### Step 3: Update Configs
- **Token list:** Replace logoURI with IPFS gateway URL
- **canonical-tokens.ts:** Add `logoUrl` to specs or change LOGO_BASE to IPFS
- **Blockscout:** Update `tokens.logo_url` via migration or admin; or serve from `/images/tokens/{address}.png` (nginx static)
### Step 4: Pin for Persistence
If using local IPFS: `ipfs pin add <CID>`
If using Pinata: upload pins the file automatically.
---
## 5. Blockscout Logo Paths
Blockscout can show token logos from:
1. **`tokens.logo_url`** — Set in DB per token (address). Use IPFS gateway URL.
2. **Static files** — `/images/tokens/{address}.png` (lowercase address). Nginx serves from Blockscout static dir or custom path.
3. **External URL** — If logo_url is an external URL, Blockscout may proxy or hotlink (check Blockscout version).
Recommended: Set `logo_url` in DB to `https://ipfs.io/ipfs/<CID>` or your gateway. Run migration to backfill:
```sql
UPDATE tokens SET logo_url = 'https://ipfs.io/ipfs/Qm...' WHERE address = '0x...';
```
---
## 6. Chainlist Icon (eip155-138.json)
Chainlist requires `_data/icons/defioraclemeta.json` if you use `"icon": "defioraclemeta"`. Format:
```json
[{"url":"ipfs://Qm...","width":1000,"height":1628,"format":"png"}]
```
Upload chain logo (512×512 or larger) to IPFS, then add this file to chains repo. Or omit `icon` (current approach).
---
## 7. Checklist
- [x] Run `prepare-token-logos-512x512.sh` — all 24 tokens
- [x] Run `upload-token-logos-to-ipfs.sh` — CIDs in ipfs-manifest.json
- [ ] Run `upload-token-logos-to-ipfs.sh` — get CIDs
- [ ] Pin CIDs (local or Pinata/Web3.Storage)
- [ ] Update `dbis-138.tokenlist.json` logoURI to IPFS URLs
- [ ] Update `canonical-tokens.ts` LOGO_BASE or per-spec logoUrl
- [ ] Backfill Blockscout `tokens.logo_url` for Chain 138
- [ ] Serve `/images/tokens/{address}.png` from nginx (optional fallback)
- [ ] Add chain icon to Chainlist if desired
- [ ] Verify logos in MetaMask, Blockscout, token list API
---
## See Also
- [FULL_PARITY_TOKEN_COVERAGE_RUNBOOK](FULL_PARITY_TOKEN_COVERAGE_RUNBOOK.md)
- [PUBLICATION_LOCATIONS_MASTER](PUBLICATION_LOCATIONS_MASTER.md)
- [prepare-token-logos-512x512.sh](coingecko/scripts/prepare-token-logos-512x512.sh)
- [scripts/upload-token-logos-to-ipfs.sh](../../scripts/upload-token-logos-to-ipfs.sh)

176
docs/04-configuration/ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md Normal file
View File

@@ -0,0 +1,176 @@
# ISO-20022 Intake / Gateway Contract on Different Blockchain Networks
**Version:** 1.0
**Last Updated:** 2026-02-23
**Status:** Active
**Companion to:** [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md)
---
## 1. Purpose
This document describes **how the intake or gateway contract** that receives ISO-20022 (and Fin) messages **works across different blockchain networks**: same logical contract, same address where possible, two delivery paths (relayer-submitted vs cross-chain), and per-chain configuration without breaking deterministic deployment.
---
## 2. Role of the Intake / Gateway Contract
The **ISO intake contract** is the **single on-chain entry point** that:
1. **Accepts** a **canonical ISO message** (see [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md)) from either:
- an **off-chain relayer** (gateway that parsed MX/MT and submits the canonical payload), or
- a **cross-chain message** (e.g. CCIP) that carries the canonical payload from another chain.
2. **Enforces** idempotency (by `instructionId` / `msgId`), **authorisation** (relayer role or CCIP router), and optional **policy** (ComplianceGuard, allowlists).
3. **Executes** the intended action: mint, transfer, or unlock for bridge, and **emits events** with canonical metadata for audit and ISO-20022 reporting.
The contract does **not** parse raw MX/MT; it only ever sees the **canonical struct**. Parsing and mapping happen off-chain or on the source chain before submission.
---
## 3. Same Address on Every Network
To keep integration simple and avoid per-chain address maps, the intake contract is deployed at the **same address on every supported chain**, following the same pattern as [UniversalCCIPBridge](../runbooks/MULTI_CHAIN_EXECUTION_CROSS_CHAIN_MESSAGE_HANDLING.md) and [MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT](../runbooks/MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md).
### 3.1 Deterministic Deployment (CREATE2)
- **Formula:** `address = keccak256(0xff ++ deployer ++ salt ++ keccak256(bytecode))[12:]`.
- **Identical bytecode** on every chain (same compiler, no chain-specific branches in bytecode).
- **Identical constructor / initializer args** for the core contract; any **chain-specific** config (e.g. CCIP router, relayer list) is set **after** deployment via `initialize()` or setters.
### 3.2 Suggested Salt and Initialization
| Item | Value |
|------|--------|
| **Contract name** | ISO20022IntakeGateway (or equivalent) |
| **Salt** | `keccak256("ISO20022IntakeGateway")` (fixed, documented) |
| **Constructor** | Minimal (e.g. none) or same admin everywhere |
| **initialize(args)** | `admin`, optional `ccipRouter`, optional `relayer`; same `admin` on all chains; `ccipRouter` can be set to 0 and configured per chain later |
This yields **one canonical intake contract address** across all networks (e.g. 138, 1, 56, 10, 137, 42161, 8453, 43114, and 651940 if supported). Integrators and off-chain gateways can use that single address regardless of chain.
---
## 4. Two Ways Messages Reach the Intake Contract
Messages reach the intake contract in two ways: **direct submission by a relayer** (same chain) or **delivery via a cross-chain protocol** (e.g. CCIP) from another chain.
### 4.1 Path A: Relayer-Submitted (Same Chain)
**Flow:**
1. Off-chain **gateway** receives ISO-20022 MX or SWIFT Fin MT.
2. Gateway **parses, validates, and maps** to the **canonical struct** (see methodology doc).
3. Gateway (as a **relayer**) calls the intake contract on the **target chain**:
- `submitInbound(CanonicalMessage calldata m)` for credits (mint / release), or
- `submitOutbound(CanonicalMessage calldata m)` for debits (burn / lock),
with the relayer’s EOA or contract holding **RELAYER_ROLE** (or **INTAKE_RELAYER_ROLE**).
**On-chain:**
- `msg.sender` must have the relayer role.
- Contract checks `processedInstructions[m.instructionId]` (or `processedMessages[m.msgId]`); reverts if already processed.
- Contract optionally checks ComplianceGuard / PolicyManager using `m.debtorId`, `m.creditorId`, `m.purpose`.
- Contract performs the action (mint, transfer, bridge unlock) and sets `processedInstructions[m.instructionId] = true`.
- Contract emits an event with canonical fields for audit and pacs.002/camt.054 mapping.
**Per-chain:** Only the **relayer address(es)** need to be configured per chain (e.g. different gateway EOA or multisig per network). The intake contract bytecode and address stay the same.
### 4.2 Path B: Cross-Chain Delivery (e.g. CCIP)
**Flow:**
1. On the **source chain**, an authorised sender (e.g. the **same intake contract** at the same address, or a dedicated “sender” contract) encodes the **canonical struct** into `bytes data` and sends a **CCIP** (or other cross-chain) message to the **destination chain**, with **receiver** = intake contract address (same canonical address).
2. On the **destination chain**, the **CCIP router** calls the intake contract’s **receive** entry point (e.g. `ccipReceive(Any2EVMMessage calldata message)`).
3. The intake contract:
- Verifies the call is from the **CCIP router** (or a designated receiver adapter) via `msg.sender == ccipRouter` or a **ROUTER_ROLE** check.
- Decodes `message.data` to obtain the **CanonicalMessage**.
- Applies **replay protection** using `message.messageId` and/or the decoded `instructionId` (must not already be in `processedMessages` / `processedInstructions`).
- Optionally validates **source chain** and **sender** from `message.sourceChainSelector` and `message.sender` (allowlist or “same intake contract on source chain”).
- Executes the same logic as Path A (mint / transfer / unlock) and emits the same canonical events.
**Per-chain:** The **CCIP router address** is chain-specific. It is set in `initialize()` or via `setCCIPRouter(address)` after deployment so that the same bytecode is used everywhere. On chains without CCIP (e.g. 651940), the router can be set to `address(0)` and Path B disabled; only Path A (relayer) is used.
---
## 5. Contract Interface (Summary)
The intake contract exposes at least:
| Entry point | Caller | Purpose |
|-------------|--------|---------|
| **submitInbound(CanonicalMessage)** | Relayer (Path A) | Process an inbound credit (mint / release from bridge). |
| **submitOutbound(CanonicalMessage)** | Relayer (Path A) | Process an outbound debit (burn / lock for bridge). |
| **ccipReceive(Any2EVMMessage)** | CCIP router only (Path B) | Decode payload to CanonicalMessage and process as inbound (or outbound if encoded so). |
Optional:
- **setCCIPRouter(address)** – Admin; for deterministic deploy, init with router=0 then set per chain.
- **addRelayer(address)** / **removeRelayer(address)** – Admin; manage who can call submitInbound/submitOutbound.
Idempotency key: **instructionId** (and optionally msgId). Storage: `mapping(bytes32 => bool) public processedInstructions;` and, for CCIP, `mapping(bytes32 => bool) public processedMessages;` keyed by CCIP `messageId` to avoid replay from the transport layer.
---
## 6. How It Works on Different Networks (By Chain Type)
### 6.1 Chains With CCIP (e.g. 138, 1, 56, 10, 137, 42161, 8453, 43114)
- **Deploy** the intake contract via CREATE2 with the same salt and init args (e.g. admin; router=0).
- **Post-deploy:** Call `setCCIPRouter(ccipRouterAddress)` with that chain’s CCIP router.
- **Relayer:** Grant RELAYER_ROLE to the gateway(s) that will submit canonical messages on this chain.
- **Behaviour:** Both Path A (relayer) and Path B (CCIP) are active. Messages can arrive from off-chain (Path A) or from another chain (Path B) with the same canonical format.
### 6.2 Chains Without CCIP (e.g. ALL Mainnet 651940)
- **Deploy** the same contract at the same address via CREATE2 (same salt, same init; no CCIP router).
- Leave **CCIP router** as `address(0)` (or never set it). **Path B is unused.**
- **Relayer:** Only Path A is used; the off-chain gateway submits canonical messages via `submitInbound` / `submitOutbound` from an address with RELAYER_ROLE.
- Optionally, a **custom cross-chain transport** (e.g. AlltraCustomBridge-style) could later call a dedicated function that accepts the same canonical payload, with access control analogous to the CCIP router check.
### 6.3 Same Address, Different Config
- **Address:** Identical across all networks (CREATE2 + same bytecode + same constructor/init args).
- **Config that can differ per chain:**
- CCIP router address (or 0),
- Relayer list (RELAYER_ROLE),
- Optional: ComplianceGuard / PolicyManager / vault addresses if set via setters after deploy.
No per-chain address map is needed in application logic; only the single intake contract address is used, and chain-specific behaviour is controlled by which roles and router are set on that chain.
---
## 7. Security and Replay
- **Path A:** Idempotency by `instructionId` (and optionally `msgId`). Only RELAYER_ROLE can submit; relayer identity is per chain.
- **Path B:** Replay protection by CCIP `messageId` and by decoded `instructionId`; only the CCIP router (or ROUTER_ROLE) can call `ccipReceive`. Validate source chain and sender if required (e.g. only accept from the same intake contract on allowed source chains).
- **Payload integrity:** Optional check of `payloadHash` in the canonical struct against an off-chain attested hash; contract can store or emit it for audit.
---
## 8. Downstream Actions
The intake contract does not hold balances long-term; it **forwards** the intent to:
- **Mint:** Call token factory or mint controller (with reserve/attestation checks as in [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md)).
- **Transfer:** Call token `transfer` or a vault that holds tokens.
- **Bridge unlock:** Call the bridge/vault contract’s release or unlock function with the same canonical metadata so that bridge and e-money runbooks stay aligned.
All such downstream calls should carry or emit the same canonical identifiers (instructionId, msgId, debtorId, creditorId, payloadHash) for audit and ISO-20022 reporting.
---
## 9. Related Documents
| Document | Description |
|----------|-------------|
| [SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md) | Canonical format, mapping, validation, and contract interface for ISO/Fin. |
| [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md) | E-Money and ISO-20022 canonical message semantics. |
| [MULTI_CHAIN_EXECUTION_CROSS_CHAIN_MESSAGE_HANDLING.md](../runbooks/MULTI_CHAIN_EXECUTION_CROSS_CHAIN_MESSAGE_HANDLING.md) | Cross-chain message handling, same address, replay, sender verification. |
| [MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md](../runbooks/MULTI_CHAIN_EXECUTION_DETERMINISTIC_DEPLOYMENT.md) | CREATE2, salts, and deployment order. |
---
**Document Control**
- **Owner:** Configuration / Integration
- **Review:** When intake contract interface or supported chains change

168
docs/04-configuration/ISO4217_COMPLIANT_TOKEN_MATRIX.md Normal file
View File

@@ -0,0 +1,168 @@
# ISO-4217 Compliant Token Matrix (Native + Bridged)
This matrix formalizes the **symbol construction standard** for compliant ISO-4217 coins/tokens across:
- **Financial Chains (Native issuance)** using a **6-character** symbol
- **Public Chains (Bridged/wrapped issuance)** using a **7-character** symbol where **ISO shifts to positions 4–6**
---
## 1. Character-Position Rules
### A) Native Financial-Chain Symbol (6 characters)
**Format:** `c` + `[FinChain]` + `[ISO4217]` + `[Type]`
| Position | Meaning | Allowed Values |
| -------: | -------------------------- | ------------------------------------ |
| 1 | Compliance prefix | `c` |
| 2 | Financial chain designator | See FIN_CHAIN_SET |
| 3–5 | ISO-4217 currency code | See ISO4217_SET |
| 6 | Asset type | `C` (coin), `T` (token), `W` (D‑WIN) |
Example: `cAUSDT` = `c` + `A` + `USD` + `T`
### B) Bridged Public-Chain Symbol (7 characters)
**Format:** `c` + `W` + `[OriginFinChain]` + `[ISO4217]` + `[Type]`
| Position | Meaning | Allowed Values |
| -------: | --------------------------------- | ------------------------------------ |
| 1 | Compliance prefix | `c` |
| 2 | Public wrapper class | `W` |
| 3 | Origin financial chain designator | See FIN_CHAIN_SET |
| 4–6 | ISO-4217 currency code | See ISO4217_SET |
| 7 | Asset type | `C` (coin), `T` (token), `W` (D‑WIN) |
Example: `cWAUSDT` = `c` + `W` + `A` + `USD` + `T`
---
## 2. FIN_CHAIN_SET
| Designator | Chain | Chain ID | Notes |
| ---------- | ------------------------------------ | -------- | --------------------------------------------------------------------- |
| *(none)* | Chain 138 (DeFi Oracle Meta Mainnet) | 138 | **v0 only:** native symbols omit designator (e.g. `cUSDC`, `cUSDT`) |
| `X` | Chain 138 (origin reference only) | 138 | Used only when denoting origin 138 on other chains (e.g. bridged) |
| `A` | Alltra Mainnet | 651940 | ALL Mainnet |
**Chain 138:** On ChainID 138, token symbols are **v0 only** — the chain designator is **left out**. Use `cUSDC`, `cUSDT` (no `X`). The `X` designator is used only for bridged tokens on public chains when the origin is Chain 138 (e.g. `cWXUSDC`). Reserved designators: do not reuse. Add new chains via registry.
---
## 3. ISO4217_SET
Reference: [ISO 4217](https://en.wikipedia.org/wiki/ISO_4217). Supported subset for implementation:
- **Fiat:** USD, EUR, GBP, JPY, AUD, CHF, CAD, CNY
- **Commodity:** XAU (gold)
- **Future:** Add codes via registry; validation enforces **3 uppercase letters only** (no 4-letter codes in v1)
---
## 4. Validation Rules
### Native (len = 6)
- `s[0] == 'c'`
- `s[1] in FIN_CHAIN_SET`
- `s[2:5] in ISO4217_SET` (positions 2, 3, 4)
- `s[5] in {'C','T','W'}`
### Bridged (len = 7)
- `s[0] == 'c'`
- `s[1] == 'W'`
- `s[2] in FIN_CHAIN_SET` (origin chain)
- `s[3:6] in ISO4217_SET` (positions 3, 4, 5)
- `s[6] in {'C','T','W'}`
---
## 5. v0 Symbols (Chain 138 Only)
On **ChainID 138 only**, compliant token symbols use the **v0 form** with **no chain designator** (the X is left out):
| v0 Symbol | Identity | Type | Chain |
| --------- | -------------- | ----- | ------ |
| `cUSDT` | ISO USD, Type T | Token | 138 |
| `cUSDC` | ISO USD, Type C | Coin | 138 |
- These symbols are **maintained only on Chain 138**; they are not used on other chains.
- Registry maps v0 → `{ iso, type, originChain: 'X' }` for reporting and for bridged-origin reference; on-chain on 138 the symbol stays `cUSDC` / `cUSDT`.
---
## 6. Chain 138: No X in Native Symbols
- **On Chain 138:** Native token symbols remain **v0** — `cUSDC`, `cUSDT` (no `X`, no designator). Do not use `cXUSDC` or `cXUSDT` on Chain 138.
- **X** is used only when referring to Chain 138 as **origin** elsewhere (e.g. bridged tokens on public chains: `cWXUSDC`, `cWXUSDT`).
- Registry maps v0 → v1 identity for reporting and validation; the on-chain symbol on 138 does not change.
---
## 7. Case Sensitivity
- Symbols are **case-sensitive**.
- Compliance prefix: **lowercase** `c`.
- FinChain, ISO4217, Type: **uppercase** (e.g. `A`, `USD`, `T`).
---
## 8. Edge Cases
- **ISO codes:** 3 letters only (A–Z); no 4-letter codes in v1.
- **Reserved designators:** `X` (Chain 138), `A` (Alltra); do not reuse.
- **Invalid examples:** `cAUSD` (missing type), `cAUSDCX` (7-char without W at position 2).
---
## 9. Migration Strategy
- **Chain 138:** v0 symbols `cUSDT`, `cUSDC` are **maintained only on ChainID 138**; the X is left out. No on-chain symbol change on 138.
- **v1 registry:** Maps v0 symbol → `{ iso, type, originChain: 'X' }` for reporting; origin `X` denotes Chain 138 when needed (e.g. bridged).
- **New chains:** Use v1 symbols with designator (e.g. `cAUSDT` on Alltra, `cWAUSDT` on public chains).
- **Bridged from Chain 138:** Use 7-char with origin X (e.g. `cWXUSDC`, `cWXUSDT`) on public chains only.
---
## 10. Matrix Examples
### Native on Chain 138 (v0 only — no designator)
| ISO | Coin (`C`) | Token (`T`) |
| --- | ---------- | ----------- |
| USD | `cUSDC` | `cUSDT` |
### Native (6-char) — Other financial chains (e.g. Alltra A)
| ISO | Coin (`C`) | Token (`T`) | D‑WIN (`W`) |
| --- | ---------- | ----------- | ----------- |
| USD | `cAUSDC` | `cAUSDT` | `cAUSDW` |
| EUR | `cAEURC` | `cAEURT` | `cAEURW` |
| GBP | `cAGBPC` | `cAGBPT` | `cAGBPW` |
### Bridged (7-char) — Public networks
| ISO | Coin (`C`) | Token (`T`) | D‑WIN (`W`) |
| --- | ---------- | ----------- | ----------- |
| USD | `cWXUSDC` | `cWXUSDT` | `cWXUSDW` |
| USD | `cWAUSDC` | `cWAUSDT` | `cWAUSDW` |
| EUR | `cWAEURC` | `cWAEURT` | `cWAEURW` |
---
## 11. Chain-Context Mapping
- **Chain 138:** Native symbols are **v0 only** (no X): `cUSDC`, `cUSDT`. No 6-char form with X is used on Chain 138.
- **Other financial chains:** Native symbols use 6-char with designator (e.g. Alltra `cAUSDC`, `cAUSDT`).
- **Bridged symbols** (7-char) live on **Public chains** (Ethereum, Base, Polygon, etc.); use `cWXUSDC` when origin is Chain 138.
- Chain specificity remains defined by **chainId + contract address**; the symbol encodes **class + origin** (except v0 on 138, which encodes class only).
---
## References
- [CHAIN138_TOKEN_ADDRESSES.md](../11-references/CHAIN138_TOKEN_ADDRESSES.md) — v0 symbol mapping
- [TOKEN_SCOPE_GRU.md](../../smom-dbis-138/docs/tokenization/TOKEN_SCOPE_GRU.md) — token scope
- [GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md) — canonical symbol grammar §5

42
docs/04-configuration/MAINNET_RAMP_USER_FLOWS.md Normal file
View File

@@ -0,0 +1,42 @@
# On-Ramp and Off-Ramp User Flows (Mainnet ↔ Chain 138)
**Purpose:** Document the recommended user flows for fiat on-ramp and off-ramp when using mainnet liquidity and third-party bridges. Companion/dApp copy and links should point here.
**Related:** [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY](../00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md) | [METAMASK_BRIDGE_SWAP](../../smom-dbis-138/docs/operations/integrations/METAMASK_BRIDGE_SWAP.md)
---
## On-ramp (Fiat → Crypto on Chain 138)
**Flow:** User buys on a supported chain (e.g. Ethereum Mainnet) via ramp, then bridges to Chain 138.
| Step | User action |
|------|-------------|
| 1 | Open companion/dApp and choose **Buy** (on-ramp). |
| 2 | Select **Ethereum Mainnet** (or another ramp-supported chain). Complete purchase via ramp provider (MoonPay, Ramp, etc.) — funds arrive on mainnet. |
| 3 | Switch to **Bridge** and send assets **Mainnet → Chain 138** using a supported bridge (trustless or third-party). |
| 4 | Receive assets on Chain 138; use for gas, swaps, or dApps. |
**Operator:** Ensure ramp API keys are set and mainnet is funded so bridges can operate. Ramp API: `POST /ramps/on-ramp/session` with `chainId: 1`.
---
## Off-ramp (Crypto on Chain 138 → Fiat)
**Flow:** User bridges from Chain 138 to Mainnet, then sells on mainnet via off-ramp.
| Step | User action |
|------|-------------|
| 1 | On Chain 138, open **Bridge** and send assets **Chain 138 → Ethereum Mainnet**. |
| 2 | Wait for bridge confirmation; assets arrive on user’s mainnet address. |
| 3 | Open companion/dApp and choose **Sell** (off-ramp). Select **Ethereum Mainnet** and complete sale via ramp provider. |
| 4 | Fiat is sent to user’s linked bank/payment method per provider terms. |
**Operator:** Mainnet liquidity (LiquidityPoolETH and/or Relay Bridge) must be funded so 138→mainnet payouts succeed. Ramp API: `POST /ramps/off-ramp/session` with `chainId: 1`.
---
## Where to link in companion/dApp
- **Buy (on-ramp):** Link to this doc or a short in-app guide: “Buy on Ethereum → Bridge to Chain 138.”
- **Sell (off-ramp):** Link to this doc or a short in-app guide: “Bridge to Ethereum → Sell on mainnet.”

140
docs/04-configuration/MIGRATION_PLAN_R630_01_DATA.md Normal file
View File

@@ -0,0 +1,140 @@
# Migration Plan: r630-01 Data Pool (72% → target &lt;70%)
**Last updated:** 2026-02-28
**Phase 1 completed (2026-02-28):** Migrated 8 CTs from data → thin1 on r630-01. **data** now **65.8%** (was 72%); **thin1** 50.6% (was 43.5%). Migrated VMIDs: 10233, 10120, 10100, 10101, 10235, 10236, 7804, 8640.
Goal: Reduce r630-01 **data** pool usage (currently ~65.8%, 280G pool) so it stays below 85% and has headroom. Options: move CTs to **r630-01 thin1** (same host) or to **r630-02 thin5** (cross-host).
---
## 1. Current layout (r630-01)
| Pool | Size | Used% | Free (approx) | Notes |
|-------|-------|-------|----------------|-------|
| **data** | 280G | **65.8%** ✓ | ~100G | After Phase 1 migrations; target &lt;70% met. |
| **thin1** | 208G | 50.6% | ~107G | Now holds migrated CTs from Phase 1. |
**CTs on data (by size, VMID = container):**
| VMID | Allocated | Role / name (typical) | Migration priority |
|-------|-----------|------------------------|--------------------|
| 2500–2505 | 200G each | RPC (alltra etc.) | Low (critical RPC); move only if needed. |
| 2101 | 200G | Core RPC | **Do not move** (deploy/admin). |
| 1000, 1001, 1002 | 100G each | Validators | **Do not move** (consensus). |
| 1500, 1501, 1502 | 100G each | Sentries | Prefer stay; move only if necessary. |
| 10130, 10150, 10151 | 50–100G | Services | Good candidates (Phase 2). |
| 8640, 8642 | 50G each | Services | Good candidates. |
| 7804 | 20G | Gov/portal | Good candidate. |
| 10235, 10236 | 10–20G | Small services | Good candidates. |
| 10232, 10233 | 1–3G | Small | Easy wins. |
| 10100, 10101 | 8G each | Small | Easy wins. |
| 10120 | 4G | Small | Easy win. |
---
## 2. Migration options
### Option A: Same host — data → thin1 (r630-01)
- **Pros:** No node change; no IP/network change; quick (stop → vzdump → destroy → restore to thin1 → start).
- **Cons:** thin1 has ~118G free; cannot move all 200G CTs without exceeding thin1.
- **Best for:** Smaller CTs (total ~50–80G) to free space on data without touching validators/core RPC.
### Option B: Cross host — r630-01 → r630-02 thin5
- **Pros:** thin5 is empty (237G); can move one or two large CTs (e.g. 200G each).
- **Cons:** Node migration (IP may change unless static); service dependency and DNS/load balancer updates.
- **Best for:** One or two 200G RPC CTs (e.g. 2503, 2504, 2505) if you need to free a lot of data in one go.
---
## 3. Recommended phases
### Phase 1 — Same host (data → thin1)
**Goal:** Free ~50–80G on data (get data from 72% to ~55–60%) by moving smaller CTs to thin1.
**Candidates (order by size, smaller first for low risk):**
1. 10232 (1G), 10233 (3G), 10120 (4G)
2. 10100 (8G), 10101 (8G), 10235 (10G)
3. 10236 (20G), 7804 (20G)
4. Optionally one of: 8640 (50G), 8642 (50G), or 10130 (50G)
**Steps per CT (run on r630-01 or via SSH):**
```bash
# On r630-01 (192.168.11.11). Replace VMID with actual (e.g. 10232).
VMID=10232
ssh root@192.168.11.11 bash -s << 'EOF'
set -e
pct stop $VMID
vzdump $VMID --storage local --compress gzip --mode stop --remove 0
BACKUP=$(ls -t /var/lib/vz/dump/vzdump-lxc-$VMID-*.tar.gz | head -1)
pct destroy $VMID --force
pct restore $VMID $BACKUP --storage thin1
rm -f $BACKUP
pct start $VMID
EOF
```
**Automation:** Run for each VMID:
```bash
bash scripts/maintenance/migrate-ct-r630-01-data-to-thin1.sh <VMID> # e.g. 10232
bash scripts/maintenance/migrate-ct-r630-01-data-to-thin1.sh 10232 --dry-run # preview
```
Suggested order: 10232, 10233, 10120, 10100, 10101, 10235, 10236, 7804, then 8640 or 8642.
---
### Phase 2 — If data still &gt;70%: move one large CT to r630-02 thin5
**Goal:** Free ~200G on r630-01 data by migrating one 200G CT to r630-02 and placing it on thin5.
**Candidates:** 2503, 2504, or 2505 (non–core RPC; confirm which can be moved without breaking dependencies).
**Steps:**
1. **Confirm** the CT can run on r630-02 (network, DNS, NPM proxy, etc.).
2. **Migrate** (cross-node):
`pct migrate <VMID> r630-02 --storage thin5`
Or: backup on r630-01, copy backup to r630-02, restore on r630-02 with `--storage thin5`, then destroy on r630-01.
3. **Update** any static IPs, DNS, or proxy config pointing to the old host.
4. **Verify** service and re-run `audit-proxmox-rpc-storage.sh`.
---
## 4. Scripts to use / create
| Action | Script / command |
|--------|-------------------|
| List CTs on data | `ssh root@192.168.11.11 'lvs -o lv_name,lv_size,pool_lv --noheadings pve \| grep " data "'` |
| Same-host migration (data → thin1) | New script or inline: `vzdump` → `pct destroy` → `pct restore --storage thin1` → `pct start` |
| Cross-host migration | `pct migrate <VMID> r630-02 --storage thin5` (or backup/restore to r630-02). |
| Verify after | `bash scripts/audit-proxmox-rpc-storage.sh` and `pvesm status` on both hosts. |
---
## 5. Checklist before migration
- [ ] Backup or snapshot critical CTs before Phase 1.
- [ ] Run prune on r630-01 data CTs again if not done recently: `fix-storage-r630-01-and-thin5.sh`.
- [ ] Ensure no critical operations (deploy, consensus) during the migration window.
- [ ] For Phase 2: document which VMID is moved and update DNS/NPM/load balancer.
---
## 6. Success criteria
- **Phase 1:** r630-01 data pool &lt;70% (ideally 55–65%); thin1 still &lt;75%.
- **Phase 2 (if run):** r630-01 data &lt;65%; r630-02 thin5 used by migrated CT(s); all services verified.
---
## 7. Reference
- **r630-01 data:** 280G, 72% used; LVs: 1000, 1001, 1002, 1500–1502, 2101, 2500–2505, 10100, 10101, 10120, 10130, 10150, 10151, 10232, 10233, 10235, 10236, 7804, 8640, 8642.
- **r630-01 thin1:** 208G, 43.5% used; ~118G free.
- **r630-02 thin5:** 237G, 0% used (empty).
- Storage docs: `STORAGE_RECOMMENDATIONS_BY_FILL_RATE.md`, `PHYSICAL_DRIVES_AND_CONFIG.md`.

69
docs/04-configuration/PHYSICAL_DRIVES_AND_CONFIG.md Normal file
View File

@@ -0,0 +1,69 @@
# Physical Drives and Current Configurations — All Three Proxmox Hosts
**Last updated:** 2026-02-28
---
## ml110 (192.168.11.10)
| Device | Size | Model | Serial | Configuration |
|--------|--------|------------------------|----------|----------------|
| **sda** | 931.5G | ST1000DM003-1ER162 (HDD) | Z4YE0TMR | Partitioned: sda1 (1M), sda2 (1G vfat /boot/efi), sda3 (930.5G LVM2). VG **pve**: swap 8G, root 96G ext4 `/`, **data** thin pool 794G (CTs 1003, 1004, 1503–1508, 2102, 2301, 2304–2308, 2400, 2402, 2403). |
| **sdb** | 931.5G | ST1000DM003-1ER162 (HDD) | Z4YDLPZ3 | **In VG pve** — extended `data` thin pool (data_tdata). Pool now ~1.7 TB total. |
**RAID:** None.
**Summary:** 2× 1TB HDDs. Both in use: sda (OS + original data pool); sdb added to pve and used to extend the data thin pool (~930G added). Data/local-lvm pool now ~1.7 TB.
---
## r630-01 (192.168.11.11)
| Device | Size | Model | Serial | Configuration |
|--------|--------|-------------------|--------------|----------------|
| **sda** | 558.9G | HUC109060CSS600 (SSD) | KSKUZEZF | Partitioned: sda1 (1M), sda2 (1G vfat), sda3 (557G **zfs_member**). ZFS used for Proxmox root (rpool). |
| **sdb** | 558.9G | HUC109060CSS600 (SSD) | KSKM1B4F | Same layout as sda — ZFS mirror partner for root. |
| **sdc** | 232.9G | CT250MX500SSD1 (SSD) | 2203E5FE090E | Member of **md0** (RAID10). |
| **sdd** | 232.9G | CT250MX500SSD1 | 2203E5FE08F8 | Member of **md0** (RAID10). |
| **sde** | 232.9G | CT250MX500SSD1 | 2203E5FE08FA | Member of **md0** (RAID10). |
| **sdf** | 232.9G | CT250MX500SSD1 | 2203E5FE08F1 | Member of **md0** (RAID10). |
| **sdg** | 232.9G | CT250MX500SSD1 | 2203E5FE095E | Member of **md0** (RAID10). |
| **sdh** | 232.9G | CT250MX500SSD1 | 2203E5FE0901 | Member of **md0** (RAID10). |
**RAID:** **md0** = RAID10, 6× 233G SSDs → **~698G** usable. State: **active**, 6/6 devices [UUUUUU].
**LVM on md0:** VG **pve** (single PV `/dev/md0`). Thin pools: **pve-thin1** 208G, **pve-data** 280G. Hosts CTs for validators, RPC 2101, 2500–2505, 1000–1002, 1500–1502, 7800–7804, 10130, 10150–10151, 10200–10236, 3000–3501, 100–105, 130, etc.
**Summary:** 2× 559G SSDs (ZFS root) + 6× 233G SSDs (RAID10 → LVM data/thin1). All drives in use.
---
## r630-02 (192.168.11.12)
| Device | Size | Model | Serial | Configuration |
|--------|--------|-------------------|--------------|----------------|
| **sda** | 232.9G | CT250MX500SSD1 | 2202E5FB4CB9 | Partitioned: sda1 (1M), sda2 (1G vfat), sda3 (231G **zfs_member**). ZFS for Proxmox root. |
| **sdb** | 232.9G | CT250MX500SSD1 | 2203E5FE090D | Same — ZFS mirror for root. |
| **sdc** | 232.9G | CT250MX500SSD1 | 2203E5FE07E1 | sdc3 → LVM VG **thin2** (thin pool → VMIDs 5000, 6000, 6001, 6002). |
| **sdd** | 232.9G | CT250MX500SSD1 | 2202E5FB186E | sdd3 → LVM VG **thin3** (VMIDs 5800, 10237, 8641, 5801). |
| **sde** | 232.9G | CT250MX500SSD1 | 2203E5FE0905 | sde3 → LVM VG **thin4** (VMIDs 7810, 7811). |
| **sdf** | 232.9G | CT250MX500SSD1 | 2203E5FE0964 | sdf3 → LVM VG **thin5** (empty pool after 5000 migrated to thin2). |
| **sdg** | 232.9G | CT250MX500SSD1 | 2203E5FE0928 | sdg3 → LVM VG **thin6** (VMIDs 5700, 6400, 6401, 6402). |
| **sdh** | 232.9G | CT250MX500SSD1 | 2203E5FE0903 | sdh3 → LVM VG **thin1** (thin1-r630-02: 2201, 2303, 2401, 5200–5202, 6200, 10234). |
**RAID:** None (each data disk is a separate LVM PV).
**Summary:** 2× 233G SSDs (ZFS root) + 6× 233G SSDs (each its own VG: thin1–thin6). All 8 drives in use.
---
## Quick reference
| Host | Physical drives | Layout | Unused / notes |
|---------|------------------|--------|-----------------|
| ml110 | 2× 1TB HDD | sda: OS+LVM data; sdb: LVM PV only | **sdb** — 931G not in any VG |
| r630-01 | 2× 559G + 6× 233G SSD | ZFS root + RAID10 md0 → LVM | All in use |
| r630-02 | 2× 233G + 6× 233G SSD | ZFS root + 6× single-disk LVM (thin1–thin6) | All in use |
To re-check:
`ssh root@<host> 'lsblk -o NAME,SIZE,TYPE,FSTYPE,MODEL,SERIAL; echo; pvs; vgs'`

120
docs/04-configuration/PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md Normal file
View File

@@ -0,0 +1,120 @@
# Price Feed for Chain 138 — MetaMask and All Wallets
**Last Updated:** 2026-02-28
**Purpose:** Single reference for adding Chain 138 USD price feeds to MetaMask and other wallets
---
## 1. Current State
| Wallet / Platform | Chain 138 USD Display | Cause |
|-------------------|------------------------|-------|
| **MetaMask** | ❌ $0.00 / "No conversion rate available" | MetaMask uses **CoinGecko API** (primary) and **LavaPack** for prices; Chain 138 is not in their supported chains |
| **Trust Wallet** | ❌ Likely no USD | Trust Wallet also pulls from CoinGecko/CMC |
| **Ledger Live** | ❌ Awaiting integration | Ledger form submitted; awaiting response |
| **Other wallets** | ❌ Most use CoinGecko/CMC | Chain 138 not listed |
**Important:** MetaMask does **not** query on-chain oracle contracts for USD display. Even with a working ETH/USD oracle on Chain 138 (`0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6`), MetaMask will not show native USD until Chain 138 and tokens are listed on CoinGecko (or MetaMask’s provider adds support).
---
## 2. Paths to Add Price Feeds
### 2.1 CoinGecko (Primary — MetaMask and many wallets)
**Why:** MetaMask’s primary price source is CoinGecko. CoinGecko is also used by Trust Wallet, DeFi dashboards, and many other wallets.
**Steps:**
1. **Chain submission (if applicable):** Request Chain 138 (DeFi Oracle Meta Mainnet) be added as a supported blockchain.
2. **Token submission:** Submit each token (cUSDT, cUSDC, WETH, ETH, etc.) with contract address, chain ID 138, decimals, logo.
3. **Form:** https://www.coingecko.com/en/request or https://www.coingecko.com/en/coins/new
**Docs:** [COINGECKO_SUBMISSION_GUIDE](coingecko/COINGECKO_SUBMISSION_GUIDE.md), [COINGECKO_SUBMISSION_PACKAGE](coingecko/COINGECKO_SUBMISSION_PACKAGE.md), [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md)
**Export data:** Use token-aggregation report API:
```bash
curl "https://<your-api>/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
```
---
### 2.2 CoinMarketCap (CMC)
**Why:** Some wallets and aggregators use CMC as a fallback or primary source.
**Steps:** Same process as CoinGecko — submit chain and tokens via CMC’s listing forms.
**Export:** `GET /api/v1/report/cmc?chainId=138`
---
### 2.3 Consensys / MetaMask Direct Outreach
**Why:** MetaMask may add Chain 138 to their native price feed if Consensys approves.
**Steps:**
1. Contact: **business@consensys.io**
2. Request: Add Chain 138 (DeFi Oracle Meta Mainnet) to MetaMask’s price feed provider.
3. Provide: Chain ID 138, RPC URLs, explorer, token list, oracle contract address if relevant.
**Status:** Outreach form submitted; awaiting response. No public PR repo for Swaps/Bridge/price feed.
**Ref:** [REPOSITORIES_AND_PRS_CHAIN138](../../00-meta/REPOSITORIES_AND_PRS_CHAIN138.md)
---
### 2.4 On-Chain Oracle (dApps, not meta-wallet)
**For dApps and custom UIs:** You can query the Chain 138 ETH/USD oracle directly:
| Property | Value |
|----------|-------|
| **Oracle Proxy** | `0x3304b747e565a97ec8ac220b0b6a1f6ffdb837e6` |
| **RPC** | `https://rpc-http-pub.d-bis.org` |
| **Method** | `latestRoundData()` → answer in 8 decimals |
**Docs:** [ORACLE_PRICE_FEED_SETUP](metamask/ORACLE_PRICE_FEED_SETUP.md)
---
### 2.5 Chain 138 Snap (Workaround)
**For MetaMask users:** The Chain 138 Snap provides market data via the token-aggregation API. Users can:
- Open the Snap companion site (e.g. https://explorer.d-bis.org/snap/)
- Use **"Show market data"** or **"Fetch market summary"** to see USD prices
This does **not** change MetaMask’s native balance display; it is a separate UX flow.
---
## 3. Action Checklist
| # | Action | Owner | Doc |
|---|--------|-------|-----|
| 1 | Submit Chain 138 to CoinGecko (chain listing) | You | [COINGECKO_SUBMISSION_PACKAGE](coingecko/COINGECKO_SUBMISSION_PACKAGE.md) |
| 2 | Submit tokens (cUSDT, cUSDC, WETH, etc.) to CoinGecko | You | [COINGECKO_SUBMISSION_GUIDE](coingecko/COINGECKO_SUBMISSION_GUIDE.md) |
| 3 | Submit Chain 138 and tokens to CoinMarketCap | You | [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) |
| 4 | Follow up Consensys outreach | You | [REPOSITORIES_AND_PRS_CHAIN138](../../00-meta/REPOSITORIES_AND_PRS_CHAIN138.md) |
| 5 | Ensure token-aggregation report API is reachable | Ops | [TOKEN_AGGREGATION_REPORT_API_RUNBOOK](TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md) |
| 6 | Prepare 512×512 PNG logos for each token | You | [prepare-token-logos-512x512.sh](coingecko/scripts/prepare-token-logos-512x512.sh) or [COINGECKO_SUBMISSION_GUIDE](coingecko/COINGECKO_SUBMISSION_GUIDE.md) §Step 1 |
---
## 4. Prerequisites
- **Token-aggregation API:** Running and reachable; `GET /api/v1/report/coingecko?chainId=138` and `GET /api/v1/report/cmc?chainId=138` return valid JSON.
- **Token logos:** 512×512 PNG for each token you submit.
- **Chain details:** Chain name, Chain ID 138, RPC URLs, explorer, native currency (see [COINGECKO_SUBMISSION_PACKAGE](coingecko/COINGECKO_SUBMISSION_PACKAGE.md)).
**Note:** CoinGecko and CMC may not list ChainID 138 or 651940 until they add the chain. The report API remains the source of truth; submit when ready and keep the runbook for when platforms add support.
---
## 5. Related Docs
- [TOKEN_AGGREGATION_REPORT_API_RUNBOOK](TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md) — Ensure report API is reachable
- [ORACLE_PRICE_FEED_SETUP](metamask/ORACLE_PRICE_FEED_SETUP.md) — On-chain oracle, MetaMask limitation
- [CHAIN138_SNAP_TROUBLESHOOTING](../../../metamask-integration/chain138-snap/docs/CHAIN138_SNAP_TROUBLESHOOTING.md) — Main balance USD display
- [REPOSITORIES_AND_PRS_CHAIN138](../../00-meta/REPOSITORIES_AND_PRS_CHAIN138.md) — Ledger, Trust, Consensys, CoinGecko/CMC
- [CMC_COINGECKO_REPORTING](../../../smom-dbis-138/services/token-aggregation/docs/CMC_COINGECKO_REPORTING.md) — Report API reference

171
docs/04-configuration/PR_ADDITIONS_VALIDATION_REPORT.md Normal file
View File

@@ -0,0 +1,171 @@
# PR Additions Validation Report — Format and Content Checks
**Last Updated:** 2026-02-28
**Purpose:** Double-check formatting and content for each PR addition before submission.
---
## 1. Token List (dbis-138.tokenlist.json) — tokenlists.org / Uniswap schema
### Schema requirements (from tokenlist.schema.json)
| Field | Requirement | Our value | Status |
|-------|--------------|-----------|--------|
| **name** | string, 1–30 chars, pattern `^[\w ]+$` | "DBIS Chain 138 Token List" (24 chars) | ✅ |
| **timestamp** | date-time format | "2026-02-16T00:00:00.000Z" | ✅ |
| **version** | { major, minor, patch } | { 1, 3, 0 } | ✅ |
| **tokens** | array, 1–10000 items | 6 tokens | ✅ |
| **token.chainId** | integer, min 1 | 138 | ✅ |
| **token.address** | checksummed 0x hex or Solana | Must be EIP-55 | ⚠️ Verify |
| **token.decimals** | 0–255 | 6, 8, 18 | ✅ |
| **token.name** | max 60 chars | All valid | ✅ |
| **token.symbol** | max 20 chars, `^\S+$` | ETH-USD, WETH, etc. | ✅ |
| **tags** (in tokens) | must exist in list-level tags | oracle, pricefeed, defi, wrapped, stablecoin, compliant, ccip | ✅ |
| **logoURI** | format uri | https://... | ✅ |
### Issues to fix
1. **ETH/USD Price Feed** — Oracle contract at `0x3304b747E565a97ec8AC220b0B6A1f6ffDB837e6` is not a standard ERC20; tokenlists.org typically lists ERC20 tokens. Consider removing or confirming it's acceptable.
2. **Address checksums** — Run `cast to-checksum-address` for each address to ensure EIP-55. WETH10: CHAIN138_TOKEN_ADDRESSES has `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f` (lowercase f); token list has `0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9F` (uppercase F). One is wrong.
3. **tokenMap** — Schema allows optional `tokenMap`; our list omits it. Optional, no change needed.
### Validation command
```bash
cd /home/intlc/projects/token-lists && npm install && npx ajv validate -s src/tokenlist.schema.json -d /home/intlc/projects/proxmox/token-lists/lists/dbis-138.tokenlist.json
```
---
## 2. Chainlist (eip155-138.json) — ethereum-lists/chains
### Schema requirements (chainSchema.json)
| Field | Required | Our value | Status |
|-------|----------|-----------|--------|
| **name** | ✅ | "Defi Oracle Meta Mainnet" | ✅ |
| **shortName** | ✅ | "dfio-meta-main" — pattern `^[A-Za-z0-9-_]{1,64}$` | ✅ |
| **chain** | ✅ | "dfiometa" | ✅ |
| **chainId** | ✅ | 138 | ✅ |
| **networkId** | ✅ | 1 | ⚠️ Verify |
| **rpc** | ✅ | array of strings | ✅ |
| **faucets** | ✅ | [] | ✅ |
| **infoURL** | ✅ | "https://d-bis.org" | ✅ |
| **nativeCurrency** | ✅ | { name, symbol, decimals } | ✅ |
| **icon** | ❌ | "defioraclemeta" | ⚠️ Requires icon file |
### Issues to fix
1. **networkId** — Currently `1`. Most EVM mainnets use `networkId === chainId`. Chain 138 may use networkId 138; verify from chain config. If wrong, change to `138`.
2. **icon** — Using `"icon": "defioraclemeta"` requires `_data/icons/defioraclemeta.json` to exist. Format:
```json
[{"url":"ipfs://Qm...","width":1000,"height":1628,"format":"png"}]
```
The URL must be IPFS and retrievable via `ipfs get`. **Option:** Remove `icon` field to avoid needing the icon file (some chains omit it).
3. **explorers[].icon** — We don't use explorer icon; OK.
4. **Prettier** — Run `npx prettier --write _data/chains/eip155-138.json` before PR.
### Validation command
```bash
cd /home/intlc/projects/chains
cp /home/intlc/projects/proxmox/docs/04-configuration/pr-ready/eip155-138.json _data/chains/
./gradlew run
npx prettier --write _data/chains/eip155-138.json
```
---
## 3. Trust Wallet (trust-wallet-registry-chain138.json) — wallet-core
### Registry format (from registry-fields.md)
| Field | Requirement | Our value | Status |
|-------|--------------|-----------|--------|
| **id** | lowercase, never change | "dfiometa" | ✅ |
| **name** | readable | "Defi Oracle Meta Mainnet" | ✅ |
| **coinId** | 10000000 + chainId for EVM clones | 10000138 | ✅ |
| **symbol** | native coin | "ETH" | ✅ |
| **decimals** | 18 | 18 | ✅ |
| **blockchain** | "Ethereum" for EVM | "Ethereum" | ✅ |
| **derivation** | path m/44'/60'/0'/0/0 | ✅ | ✅ |
| **chainId** | string | "138" | ✅ |
| **explorer.sampleTx** | Real tx hash for URL validation | "" | ❌ **MUST FIX** |
| **explorer.sampleAccount** | Real address for URL validation | "" | ❌ **MUST FIX** |
### Issues to fix
1. **sampleTx** — Must be a real transaction hash from Chain 138. Get from https://explorer.d-bis.org (any recent tx).
2. **sampleAccount** — Must be a real address. Use any address that has had activity.
From registry-fields.md: *"Note that the sample values should include existing IDs, so that the resulting full URL is valid."*
### How to get sample values
```bash
# From explorer or RPC
curl -s "https://explorer.d-bis.org/api/v2/transactions" | jq '.items[0].hash'
curl -s "https://explorer.d-bis.org/api/v2/addresses/0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2" | jq '.hash'
# Or use a known address: 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2 (WETH)
```
---
## 4. DefiLlama-Adapters — Protocol TVL
### Not a token list
DefiLlama adapters return TVL (total value locked), not token lists. Each protocol (e.g. DODO) has an `index.js` exporting `tvl(api)` per chain.
### Chain 138 support
- DefiLlama uses chain keys: `ethereum`, `bsc`, `polygon`, `arbitrum`, etc.
- Chain 138 is likely **not** a built-in chain key. Check `DefiLlama-Adapters/helper/chains.js` or similar.
- If adding DODO on Chain 138, you must:
1. Confirm DefiLlama supports chain 138 (may need PR to add chain first)
2. Add config entry and tvl logic for the chain key they use (e.g. `chain138` or `defi-oracle-meta`)
### No PR-ready file
We do not have a DefiLlama adapter file. Create one only after confirming chain support.
---
## Summary — Action Items
| Addition | File | Status |
|----------|------|--------|
| **Token list** | dbis-138.tokenlist.json | ✅ WETH10 address fixed to checksum per CHAIN138_TOKEN_ADDRESSES |
| **Chainlist** | eip155-138.json | ✅ networkId→138; icon removed (avoids needing _data/icons file) |
| **Trust Wallet** | trust-wallet-registry-chain138.json | ✅ sampleTx and sampleAccount added (real tx from explorer) |
| **DefiLlama** | N/A | No PR until chain 138 is supported; adapter structure differs |
---
## Verification commands (run before PR)
```bash
# Token list (from token-lists repo)
cd /home/intlc/projects/token-lists
npm install
# Validate schema (if ajv available)
node -e "
const schema = require('./src/tokenlist.schema.json');
const list = require('/home/intlc/projects/proxmox/token-lists/lists/dbis-138.tokenlist.json');
console.log('name length:', list.name.length, '(max 30)');
console.log('tokens:', list.tokens.length);
list.tokens.forEach(t => console.log(t.symbol, t.address));
"
# Chains
cd /home/intlc/projects/chains
cp ../../proxmox/docs/04-configuration/pr-ready/eip155-138.json _data/chains/
npx prettier --write _data/chains/eip155-138.json
./gradlew run
# Trust Wallet - use registry id, not chainId
# Add entry from pr-ready/trust-wallet-registry-chain138.json to registry.json first
. "$HOME/.cargo/env" # if Rust installed via rustup
cd /home/intlc/projects/wallet-core
./tools/new-evmchain dfiometa # use registry id, NOT 138
```

41
docs/04-configuration/README.md
View File

@@ -46,6 +46,16 @@ This directory contains setup and configuration guides.
- **Fireblocks Web3:** Submodule **[fireblocks-integration/](../fireblocks-integration/)** (Gitea: [d-bis/fireblocks-integration](https://gitea.d-bis.org/d-bis/fireblocks-integration)) — Dedicated RPC (VMID 2301), Console/SDK docs, `.env.example`. In-repo copy: [FIREBLOCKS_WEB3_INTEGRATION.md](FIREBLOCKS_WEB3_INTEGRATION.md) (operator/hosting ref).
**Price feed (MetaMask and all wallets):**
- **[PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md)** ⭐⭐⭐ - **Single reference** for adding Chain 138 USD prices to MetaMask and wallets: CoinGecko, CMC, Consensys outreach, on-chain oracle, Snap workaround.
**Explorer tokens and GRU:**
- **[EXPLORER_TOKENS_GRU_POLICY.md](EXPLORER_TOKENS_GRU_POLICY.md)** ⭐⭐ - Policy: all c* tokens on [explorer.d-bis.org/tokens](https://explorer.d-bis.org/tokens) must be registered as GRU; token list and registration steps.
- **[C_TO_CW_MAPPER_MAPPING.md](C_TO_CW_MAPPER_MAPPING.md)** ⭐⭐ - c* → cW* mapping for mapper: symbol mapping and per-chain address mapping in `config/token-mapping-multichain.json`.
**DEX and aggregators (Chain 138 tokens and routing):**
- **[DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md](DEX_AND_AGGREGATORS_CHAIN138_EXPLAINER.md)** ⭐⭐⭐ - Using DEX and aggregators with Chain 138 coins/tokens; routing for DEXs; token-aggregation API, DODO PMM, swap–bridge–swap flows.
**Chain 138 / Wallets (overview first; all repos in ~/projects/):**
- **[CHAIN138_WALLET_REPOSITORIES.md](CHAIN138_WALLET_REPOSITORIES.md)** ⭐⭐⭐ - **Canonical layout:** metamask-integration, LedgerLive, app-ethereum, TrustWallet-Integration each in `~/projects/`. All items **Yes / Completed.**
- **[CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md](CHAIN138_WALLET_ECOSYSTEM_AND_RATIONALE.md)** ⭐⭐⭐ - **Why** we have the MetaMask Snap, **why** we need Ledger Live when we already use App-Ethereum, Trust Wallet support; links to all wallet docs.
@@ -58,6 +68,37 @@ This directory contains setup and configuration guides.
- **[FIXES_PREPARED.md](FIXES_PREPARED.md)** ⭐⭐⭐ - Single checklist of all fixes (required + optional) with copy-paste commands: UDM Pro Alltra/HYBX port forward, Alltra/HYBX 502 diagnosis, NPMplus certs, Explorer SSL, shellcheck, verification re-run.
- **[FULL_FIXES_PREPARED.md](FULL_FIXES_PREPARED.md)** ⭐⭐⭐ - Consolidated full fixes: validators & block production, stuck tx, Sentries (1503/1504), RPCs (2301, 2402, 2503–2508), UDM Pro, Alltra/HYBX 502, optional (certs, Explorer SSL, shellcheck, verification). Master table + execution order.
**Smart contracts & ISO-20022 / Fin messaging:**
- **[SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md](SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md)** ⭐⭐⭐ - Methodology for smart contracts to accept ISO-20022 and SWIFT Fin messages: canonical format, mapping, validation, and contract interface.
- **[ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md](ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md)** ⭐⭐⭐ - How the intake/gateway contract receives ISO messages on different blockchain networks: relayer vs cross-chain (CCIP), same address (CREATE2), per-chain config.
- **[GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md](GRU_M00_DIAMOND_INSTITUTIONAL_SPEC.md)** ⭐⭐⭐ - GRU M00 Diamond institutional spec (§1–§8): topology, storage, facets, governance, markets, Pattern A/B, minimum checklist; token model A and Pattern A locked.
- **[GRU_M00_DIAMOND_FACET_MAP.md](GRU_M00_DIAMOND_FACET_MAP.md)** ⭐⭐⭐ - GRU M00 Diamond (ERC-2535) Token Factory: facet map, storage namespaces, governance levels 0–5, canonical symbol grammar (c/a/d, W rules). Whitepaper-ready.
- **[GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md](GRU_M00_DIAMOND_REVIEW_GAPS_AND_RECOMMENDATIONS.md)** ⭐⭐⭐ - Detailed review: missing components, functional wire-ins, naming alignment (a/d vs ac/vdc/sdc), checklist and recommendations.
- **[GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md](GRU_M00_DIAMOND_DOCS_REVIEW_GAPS_AND_INCONSISTENCIES.md)** ⭐⭐ - Review of all GRU M00 Diamond docs: missing refs, link consistency, terminology, and follow-up list.
- **[DBIS Rail Technical Spec v1](../dbis-rail/DBIS_RAIL_TECHNICAL_SPEC_V1.md)** ⭐⭐⭐ - Bank-rail settlement and GRU mint orchestration on Chain 138: RootRegistry, ParticipantRegistry, SignerRegistry, SettlementRouter, GRU_MintController, MintAuth lifecycle, EIP-712 signer quorum (3-of-5), replay protection, and audit events.
- **[DBIS Rail Rulebook v1](../dbis-rail/DBIS_RAIL_RULEBOOK_V1.md)** ⭐⭐⭐ - Operational and compliance policy: good funds matrix, finality triggers per rail (wire/ACH/cash/internal), accounting sequence and deterministic accountingRef, MintAuth preconditions, reversal and exception handling, signer revocation timing, incident controls, audit and reporting standards.
- **[DBIS Rail Security Threat Model v1](../dbis-rail/DBIS_RAIL_SECURITY_THREAT_MODEL_V1.md)** ⭐⭐⭐ - Trust boundaries, authorization/ledger/router/mint/validator/off-chain threat categories, severity classification, mitigations, residual risk, versioning and review cycle.
- **[DBIS Rail Regulator-Facing Brief v1](../dbis-rail/DBIS_RAIL_REGULATOR_BRIEF_V1.md)** ⭐⭐⭐ - Institutional narrative for banks, examiners, counsel, risk committees: overview, governance, settlement lifecycle, good funds and finality, controls, risk posture, audit, residual risk disclosure, amendment process.
- **[DBIS Rail Audit Readiness Checklist v1](../dbis-rail/DBIS_RAIL_AUDIT_READINESS_CHECKLIST_V1.md)** ⭐⭐⭐ - Pre-audit control verification: mint path, authorization, signer governance, accounting/evidence, router controls, validator layer, emergency controls, documentation integrity.
- **[DBIS Rail Audit Readiness Results v1](../dbis-rail/DBIS_RAIL_AUDIT_READINESS_RESULTS_V1.md)** ⭐⭐ - Baseline checklist run: status per section, gaps, and prioritized remediation (rail contracts, mint path lock, tests, ops).
- **[DBIS Rail Control Mapping v1](../dbis-rail/DBIS_RAIL_CONTROL_MAPPING_V1.md)** ⭐⭐ - Control IDs mapped to checklist, Spec, Rulebook, and Threat Model for audit and SOC 2 / ISO 27001 alignment.
- **[DBIS Rail and Project Completion Master v1](../dbis-rail/DBIS_RAIL_AND_PROJECT_COMPLETION_MASTER_V1.md)** ⭐⭐ - Project and deployment status; full task list (required and optional) for DBIS Rail and project completion.
- **[Implementation coordination (transcript 540ae663)](../dbis-rail/IMPLEMENTATION_COORDINATION_WITH_TRANSCRIPT_540AE663.md)** ⭐⭐ - Coordinate implementations with PMM/DEX, tokens, GRU, cW*, deployments; maps Completion Master tasks to done/partial/open.
- **[DBIS Rail Ledger Attestation Add-On v1.5](../dbis-rail/DBIS_RAIL_LEDGER_ATTESTATION_ADDON_V1_5.md)** ⭐⭐ - LPA state machine, reversal matrix, signer effectiveFromBlock/revokedAtBlock mandatory.
- **[DBIS Rail Conversion Router Spec v1.5](../dbis-rail/DBIS_RAIL_CONVERSION_ROUTER_SPEC_V1_5.md)** ⭐⭐ - SwapAuth, best execution/MEV, quote provenance, venue allowlist, sanctions/AML for swaps.
- **[DBIS Rail Stablecoin Policy v1.5](../dbis-rail/DBIS_RAIL_STABLECOIN_POLICY_V1_5.md)** ⭐⭐ - Canonical stablecoin definition, registry, routing and monitoring.
- **[DBIS Rail Hash Canonicalization and Test Vectors v1.5](../dbis-rail/DBIS_RAIL_HASH_CANONICALIZATION_AND_TEST_VECTORS_V1_5.md)** ⭐⭐ - LEB/LPA/ISO schemas, canonicalization rules, test vectors.
**Mainnet liquidity & ramps (priority):**
- **[MAINNET_RAMP_USER_FLOWS.md](MAINNET_RAMP_USER_FLOWS.md)** ⭐⭐ - On-ramp (buy on mainnet → bridge to 138) and off-ramp (138→mainnet → sell) user flows. Companion/dApp link target.
- **Priority plan:** [MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md](../00-meta/MAINNET_LIQUIDITY_AND_RAMPS_PRIORITY.md) - Obtain liquid on mainnet (fund LP + relay bridge), then wire off/on-ramps.
**Explorer (explorer.d-bis.org):**
- **[EXPLORER_FUNCTIONALITY_REVIEW.md](EXPLORER_FUNCTIONALITY_REVIEW.md)** - Routes, API URLs, contract verification, Snap send HTTPS.
- **[EXPLORER_GAPS_AND_RECOMMENDATIONS.md](EXPLORER_GAPS_AND_RECOMMENDATIONS.md)** - Loading on all pages, bridge/lanes, **Verify & Publish** (UI) and batch verification (Forge + proxy), user/API key issuance, operator checklist.
- **[EXPLORER_TROUBLESHOOTING.md](EXPLORER_TROUBLESHOOTING.md)** - SSL, NPMplus, 502/verification failures, common errors.
- **Contract verification (Forge + Blockscout):** [../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md](../08-monitoring/BLOCKSCOUT_VERIFICATION_GUIDE.md) — proxy, manual UI, 502/HTML troubleshooting.
## Quick Reference
**Initial Setup:**

3
docs/04-configuration/RPC_ENDPOINTS_MASTER.md
View File

@@ -29,10 +29,11 @@ This is the **authoritative source** for all RPC endpoint configurations. All ot
| **138 Public RPC** | `RPC_URL_138_PUBLIC` | Bridge, monitoring, frontend, browser | `http://192.168.11.221:8545` (VMID 2201); public URL: `https://rpc-http-pub.d-bis.org` |
- Set in `config/ip-addresses.conf` or `smom-dbis-138/.env`. In smom `.env`, **`RPC_URL`** is an accepted alias for **Core** and is normalized to `RPC_URL_138`. `CHAIN138_RPC_URL` / `CHAIN138_RPC` are derived from `RPC_URL_138`. `WS_URL_138_PUBLIC` is the WebSocket for Public (e.g. `ws://192.168.11.221:8546`).
- **Core RPC (VMID 2101) for deploy:** Use **IP and port**, not FQDN. Set `RPC_URL_138=http://192.168.11.211:8545` in `smom-dbis-138/.env` for contract deployment and gas checks. Do not use `https://rpc-core.d-bis.org` for deployment (avoids DNS/tunnel dependency; direct IP is reliable from LAN). See [TODOS_CONSOLIDATED](../00-meta/TODOS_CONSOLIDATED.md) § First (0b).
| Variable / use | Canonical value | Notes |
|----------------|-----------------|--------|
| **RPC_URL_138** (Core) | `http://192.168.11.211:8545` or `https://rpc-core.d-bis.org` | Single standard for Chain 138 admin/deploy |
| **RPC_URL_138** (Core) | `http://192.168.11.211:8545` | **Prefer IP:port for admin/deploy.** Fallback from off-LAN: `https://rpc-core.d-bis.org` |
| **RPC_URL_138_PUBLIC** (Public) | `http://192.168.11.221:8545` or `https://rpc-http-pub.d-bis.org` | Single standard for Chain 138 public; VITE_RPC_URL_138 in frontend |
| **RPC_URL_138_FIREBLOCKS** (Fireblocks) | `http://192.168.11.232:8545` or `https://rpc-fireblocks.d-bis.org` | Dedicated RPC for Fireblocks Web3 (VMID 2301); `WS_URL_138_FIREBLOCKS`: `wss://ws.rpc-fireblocks.d-bis.org` |
| **Ethereum Mainnet** | `https://eth.llamarpc.com` or Infura/Alchemy | `ETHEREUM_MAINNET_RPC` or `RPC_URL_MAINNET` in .env; CCIP relay uses both. Prefer Infura `https://mainnet.infura.io/v3/<PROJECT_ID>` to avoid 429. |

205
docs/04-configuration/SECRETS_CONSOLIDATED_DOWNLOAD.env Normal file
View File

@@ -0,0 +1,205 @@
# =============================================================================
# CONSOLIDATED SECRETS — Single file for download / backup / fill-from-sources
# =============================================================================
# INSTRUCTIONS:
# 1. Download this file (or copy from repo).
# 2. Fill each value from your existing .env files (see comments after each key).
# 3. Save the filled file as secrets-consolidated.env or .env.master in a secure
# location. NEVER commit the filled file. Keep it off cloud/email.
# 4. Use for backup, new machine setup, or feeding into a secrets manager.
# =============================================================================
# Sources: root = proxmox repo root .env; smom = smom-dbis-138/.env;
# dbis = dbis_core/.env; omnis = OMNIS/backend/.env; etc.
# =============================================================================
# --- Proxmox (root) ---
PROXMOX_ML110=
PROXMOX_R630_01=
PROXMOX_R630_02=
PROXMOX_HOST=
PROXMOX_PORT=
PROXMOX_USER=
PROXMOX_TOKEN_NAME=
PROXMOX_TOKEN_VALUE=
PROXMOX_ALLOW_ELEVATED=
# --- Cloudflare (root) ---
CLOUDFLARE_API_TOKEN=
CLOUDFLARE_EMAIL=
CLOUDFLARE_API_KEY=
CLOUDFLARE_ZONE_ID=
CLOUDFLARE_ZONE_ID_D_BIS_ORG=
CLOUDFLARE_ZONE_ID_MIM4U_ORG=
CLOUDFLARE_ZONE_ID_SANKOFA_NEXUS=
CLOUDFLARE_ZONE_ID_DEFI_ORACLE_IO=
CLOUDFLARE_TUNNEL_TOKEN=
CLOUDFLARE_TUNNEL_ID=
CLOUDFLARE_TUNNEL_ID_ALLTRA_HYBX=
CLOUDFLARE_TUNNEL_ID_MIFOS_R630_02=
CLOUDFLARE_TUNNEL_TOKEN_MIFOS_R630_02=
CLOUDFLARE_ORIGIN_CA_KEY=
CLOUDFLARE_ACCOUNT_ID=
# --- ClouDNS (root) ---
CLOUDNS_AUTH_ID=
CLOUDNS_AUTH_PASSWORD=
# --- NPM / NPMplus (root) ---
NPM_URL=
NPM_EMAIL=
NPM_PASSWORD=
NPM_HOST=
NPM_PROXMOX_HOST=
NPMPLUS_HOST=
NPM_VMID=
NPMPLUS_VMID=
NPMPLUS_ALLTRA_HYBX_VMID=
IP_NPMPLUS_ALLTRA_HYBX=
NPM_URL_MIFOS=
# --- Fastly (root) ---
FASTLY_API_TOKEN=
# --- Network / UniFi (root) | Omada (omada-api/.env) ---
PUBLIC_IP=
PROXMOX_HOST_FOR_TEST=
UNIFI_UDM_URL=
UNIFI_API_KEY=
UNIFI_API_MODE=
UNIFI_SITE_ID=
UNIFI_VERIFY_SSL=
OMADA_API_KEY=
OMADA_CLIENT_SECRET=
# --- Gitea (root) ---
GITEA_URL=
GITEA_TOKEN=
GITEA_ORG=
# --- Database & app auth (root, dbis_core, omnis, explorer) ---
DATABASE_URL=
JWT_SECRET=
JWT_REFRESH_SECRET=
JWT_EXPIRES_IN=
JWT_REFRESH_EXPIRES_IN=
SESSION_SECRET=
ADMIN_CENTRAL_API_KEY=
DBIS_CENTRAL_URL=
ADMIN_JWT_SECRET=
# --- Storage AWS/Azure (root, omnis) ---
STORAGE_TYPE=
STORAGE_PATH=
AWS_REGION=
AWS_ACCESS_KEY_ID=
AWS_SECRET_ACCESS_KEY=
AWS_S3_BUCKET=
AZURE_STORAGE_CONNECTION_STRING=
AZURE_STORAGE_CONTAINER=
# --- Blockchain / SMOM-DBIS-138 (smom-dbis-138/.env, root) ---
PRIVATE_KEY=
RPC_URL_138=
RPC_URL_138_PUBLIC=
ETHEREUM_MAINNET_RPC=
CHAIN_651940_RPC_URL=
ETHERLINK_RPC_URL=
TEZOS_RPC_URL=
ETHERSCAN_API_KEY=
ETHERLINK_CCIP_SELECTOR=
TEZOS_BRIDGE_ENABLED=
ETHERLINK_BRIDGE_ENABLED=
TEZOS_RELAY_ORACLE_KEY=
ETHERLINK_RELAY_BRIDGE=
ETHERLINK_RELAY_PRIVATE_KEY=
JUMPER_API_KEY=
ONEINCH_API_KEY=
MOONPAY_API_KEY=
MOONPAY_SECRET_KEY=
RAMP_NETWORK_API_KEY=
ONRAMPER_API_KEY=
# --- Alerts & monitoring (root, dbis_core) ---
SLACK_WEBHOOK_URL=
PAGERDUTY_INTEGRATION_KEY=
EMAIL_ALERT_API_URL=
EMAIL_ALERT_RECIPIENTS=
SENTRY_DSN=
# --- Legal / e-signature (root, the-order/legal-documents) ---
E_SIGNATURE_BASE_URL=
# --- OTC / exchanges (dbis_core/.env) ---
CRYPTO_COM_API_KEY=
CRYPTO_COM_API_SECRET=
CRYPTO_COM_ENVIRONMENT=
BINANCE_API_KEY=
BINANCE_API_SECRET=
KRAKEN_API_KEY=
KRAKEN_PRIVATE_KEY=
OANDA_API_KEY=
OANDA_ACCOUNT_ID=
OANDA_ENVIRONMENT=
FXCM_API_TOKEN=
# --- Price / market data (root, token-aggregation, smom-dbis-138) ---
COINGECKO_API_KEY=
COINDESK_API_KEY=
COINMARKETCAP_API_KEY=
DEXSCREENER_API_KEY=
# --- Mifos / Fineract / OMNL (root, omnl-fineract) ---
MIFOS_BASE_URL=
MIFOS_TENANT=
MIFOS_USER=
MIFOS_PASSWORD=
MIFOS_INSECURE=
OMNL_FINERACT_BASE_URL=
OMNL_FINERACT_TENANT=
OMNL_FINERACT_USER=
OMNL_FINERACT_PASSWORD=
# --- Phoenix / Sankofa / OMNIS backend (OMNIS/backend/.env) ---
SANKOFA_PHOENIX_API_URL=
SANKOFA_PHOENIX_CLIENT_ID=
SANKOFA_PHOENIX_CLIENT_SECRET=
SANKOFA_PHOENIX_TENANT_ID=
# --- Frontend / MetaMask / Explorer (various .env) ---
VITE_WALLETCONNECT_PROJECT_ID=
VITE_THIRDWEB_CLIENT_ID=
VITE_ETHERSCAN_API_KEY=
VITE_SENTRY_DSN=
VITE_API_URL=
VITE_API_BASE_URL=
NEXT_PUBLIC_API_URL=
NEXT_PUBLIC_CHAIN_ID=
METAMASK_API_KEY=
THIRDWEB_SECRET_KEY=
NPM_ACCESS_TOKEN=
# --- DeFi aggregators (alltra-lifi-settlement/.env) ---
PARASWAP_API_KEY=
ZEROX_API_KEY=
# --- ProxmoxVE API (ProxmoxVE/api/.env) ---
MONGO_USER=
MONGO_PASSWORD=
MONGO_IP=
MONGO_PORT=
MONGO_DATABASE=
# --- Chain138 / Fireblocks (root, fireblocks-integration) ---
CHAIN138_RPC_URL=
RPC_URL_138_FIREBLOCKS=
WS_URL_138_FIREBLOCKS=
CHAIN_ID_138=
# --- Phoenix deploy API (phoenix-deploy-api/.env) ---
PORT=
GITEA_TOKEN=
# --- Optional / per-service ---
MARKET_REPORTING_API_KEY=
E_FILING_ENABLED=
NODE_ENV=

262
docs/04-configuration/SMART_CONTRACTS_ISO20022_FIN_METHODOLOGY.md Normal file
View File

@@ -0,0 +1,262 @@
# Methodology: Smart Contracts Accepting ISO-20022 and Fin Messages
**Version:** 1.0
**Last Updated:** 2026-02-23
**Status:** Active
**Scope:** Chain 138 (and multi-chain) e-money and bridge contracts
---
## 1. Purpose and Scope
This document defines the **methodology** for designing and operating smart contracts that **accept** ISO-20022 financial messages (MX/XML) and, where applicable, **SWIFT Fin** (MT) messages, by normalising them to a single **canonical on-chain representation** and processing them through a well-defined contract interface.
### 1.1 Objectives
- **Interoperability:** Enable value transfers and settlement flows that originate from or are traceable to ISO-20022 (and Fin) messaging.
- **Auditability:** Ensure every on-chain transfer, mint, burn, or cross-chain action can be correlated with a standardised message identifier and metadata (e.g. MsgId, UETR, debtor/creditor, purpose).
- **Compliance:** Support regulatory and E-Money requirements (par redeemability, safeguarded reserves, transaction monitoring) while preserving ISO-20022 semantics at the boundary.
### 1.2 Out of Scope
- Off-chain generation or routing of ISO-20022/Fin messages (covered by [ISO 20022 Mapping Table](../../gru-docs/docs/integration/iso20022/Mapping_Table.md) and [dbis_core ISO 20022 integration](../../dbis_core/docs/nostro-vostro/iso20022-mapping.md)).
- Contract deployment or network topology (see deployment runbooks).
---
## 2. Message Sources: ISO-20022 and Fin
### 2.1 ISO-20022 (MX) Messages
| Message Type | Purpose | Typical Use in Smart Contract Context |
|-------------------|----------------------------------|----------------------------------------|
| **pain.001** | Customer credit transfer initiation | Initiation of a payment that may settle on-chain |
| **pacs.008** | FI-to-FI customer credit transfer | Settlement instruction; primary input for on-chain credit |
| **pacs.009** | FI-to-FI direct debit | Debit-side settlement |
| **pacs.002** | Payment status report | Status/correlation off-chain or in events |
| **camt.053** | Bank statement | Off-chain reconciliation |
| **camt.054** | Debit/credit notification | Notifications; optional event mapping |
Messages are **XML** with namespaces per ISO 20022 XSDs (e.g. `urn:iso:std:iso:20022:tech:xsd:pacs.008.001.10`). Parsing and validation are done **off-chain**; only a **canonical payload** is passed to the contract.
### 2.2 SWIFT Fin (MT) Messages
Where legacy flows use **SWIFT Fin** (e.g. MT103, MT202), the methodology treats them as **additional input formats** that must be **mapped into the same canonical structure** as ISO-20022 before being passed to smart contracts.
| MT Type | Purpose | Mapping Notes |
|-----------|----------------------|----------------------------------------------------|
| **MT103** | Single customer transfer | Field 20 → instructionId; 32A → amount/currency; 50/59 → debtor/creditor |
| **MT202** | Bank transfer | Map to pacs.008-like canonical fields |
Fin messages are **normalised to the canonical format** (Section 3) so that contracts do not need separate MT vs MX logic.
---
## 3. Canonical Message Format (On-Chain Contract View)
All accepted messages (ISO-20022 MX or SWIFT Fin) are reduced to a **single canonical struct** used in contract interfaces and events. This aligns with the extended CanonicalMessage described in [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md).
### 3.1 Canonical Struct (Semantic Definition)
| Field | Type | Purpose |
|--------------------|---------|--------|
| `msgType` | string | Message type: `pacs.008`, `pain.001`, `camt.054`, or normalized equivalent (e.g. `MT103`) |
| `instructionId` | bytes32 | InstrId – unique instruction reference (hashed if longer than 32 bytes) |
| `endToEndId` | string | EndToEndId (optional) |
| `msgId` | string | MsgId (optional) |
| `uetr` | string | UETR (optional) |
| `accountRefId` | string | Account reference (debtor account or equivalent) |
| `counterpartyRefId`| string | Counterparty account reference (creditor or equivalent) |
| `debtorId` | string | Debtor identifier (optional) |
| `creditorId` | string | Creditor identifier (optional) |
| `purpose` | string | Purpose / remittance info (optional) |
| `settlementMethod` | string | Settlement method (optional) |
| `categoryPurpose` | string | Category purpose (optional) |
| `token` | address | Token contract address |
| `amount` | uint256 | Amount (in token’s smallest unit) |
| `currencyCode` | string | Currency code (ISO 4217) |
| `payloadHash` | bytes32 | Hash of off-chain payload (full MX/MT or selected elements) for audit |
Strings that exceed on-chain limits (e.g. 32 bytes for a single storage slot) should be **hashed** for storage and the full value emitted in events or stored in an off-chain index keyed by `instructionId` or `msgId`.
### 3.2 Solidity-Oriented Representation
Contracts may use a struct such as:
```solidity
struct CanonicalMessage {
string msgType;
bytes32 instructionId;
string endToEndId;
string msgId;
string uetr;
string accountRefId;
string counterpartyRefId;
string debtorId;
string creditorId;
string purpose;
string settlementMethod;
string categoryPurpose;
address token;
uint256 amount;
string currencyCode;
bytes32 payloadHash;
}
```
Optional fields can be empty strings or zero values where not applicable. Events should expose at least `instructionId`, `msgId` (if present), `token`, `amount`, `debtorId`, `creditorId`, and `payloadHash` so that off-chain systems can map back to ISO-20022.
---
## 4. End-to-End Flow: From Fin/ISO-20022 to Smart Contract
### 4.1 High-Level Pipeline
```
[ISO-20022 MX / SWIFT Fin] → Parse & Validate (off-chain) → Map to Canonical → Submit to Contract → Contract applies policy & executes
```
1. **Ingest:** Receive MX (XML) or Fin (MT) message at an off-chain service (e.g. [dbis_core Iso20022Service](../../dbis_core/src/integration/iso20022/iso20022.service.ts), [Iso20022Adapter](../../dbis_core/src/integration/plugins/iso20022-adapter.ts), or a dedicated gateway).
2. **Parse and validate:** Check schema, mandatory elements, and business rules (amounts, currency, identifiers). Reject invalid messages before any on-chain step.
3. **Map to canonical:** Fill the canonical struct from the message (see Section 5). For MT, use a dedicated MT→canonical mapping (e.g. MT103 field 20 → instructionId, 32A → amount/currencyCode, 50/59 → debtorId/creditorId).
4. **Submit to contract:** Call the contract’s **accept** entry point (e.g. `submitInbound` / `submitOutbound` or equivalent) with the canonical payload. The contract must verify sender (relayer/guardian), idempotency (e.g. by `instructionId` or `msgId`), and policy (ComplianceGuard, PolicyManager, allowlists).
5. **Execute and emit:** Contract performs transfer/mint/burn/cross-chain and emits events that include canonical metadata so that off-chain systems can map to ISO-20022 reports (pacs.002, camt.054, etc.).
### 4.2 Idempotency and Replay Protection
- **Unique key:** Use `instructionId` (and optionally `msgId` or `uetr`) as the idempotency key. Contracts must maintain a mapping (e.g. `processedInstructions[instructionId]`) and **revert or no-op** if the same key is submitted again.
- **Replay:** Ensure the same MX/Fin message cannot be replayed on another chain or at another time by binding the canonical payload to chain and, if needed, to a nonce or timestamp validated off-chain or on-chain.
---
## 5. Mapping Rules: ISO-20022 and Fin → Canonical
### 5.1 ISO-20022 MX → Canonical
Use the same semantic mapping as in the [ISO 20022 Mapping Table](../../gru-docs/docs/integration/iso20022/Mapping_Table.md) and [dbis_core iso20022-mapping](../../dbis_core/docs/nostro-vostro/iso20022-mapping.md), then project onto the canonical struct:
| Canonical Field | ISO-20022 Source (e.g. pacs.008) |
|----------------------|-----------------------------------|
| msgType | Message type (e.g. `pacs.008`) |
| instructionId | `PmtId/InstrId` (hash if needed) |
| endToEndId | `PmtId/EndToEndId` |
| msgId | `GrpHdr/MsgId` |
| uetr | UETR element if present |
| accountRefId | `DbtrAcct/Id` (IBAN or Othr/Id) |
| counterpartyRefId | `CdtrAcct/Id` (IBAN or Othr/Id) |
| debtorId | `Dbtr/Nm` or `Dbtr/Id` |
| creditorId | `Cdtr/Nm` or `Cdtr/Id` |
| purpose | `RmtInf/Ustrd` or `Purp` |
| settlementMethod | Settlement method element |
| categoryPurpose | `CategoryPurp` |
| token | Resolved from currency/account (off-chain config) |
| amount | `IntrBkSttlmAmt` (scaled to token decimals) |
| currencyCode | `IntrBkSttlmAmt/@Ccy` |
| payloadHash | `keccak256(rawMessage)` or hash of selected elements |
### 5.2 SWIFT Fin (MT) → Canonical
Example for **MT103**:
| Canonical Field | MT103 Field | Notes |
|----------------------|-------------|--------|
| msgType | — | Set to `MT103` |
| instructionId | 20 | Hash if &gt; 32 bytes |
| endToEndId | 121 (UETR) or 20 | If present |
| msgId | — | From header or generate |
| uetr | 121 | If present |
| accountRefId | 50a / 52a | Sender account |
| counterpartyRefId | 59a | Beneficiary account |
| debtorId | 50K / 50a | Ordering customer |
| creditorId | 59 / 59a | Beneficiary |
| purpose | 72 | Sender to receiver info |
| token | — | From currency in 32A + config |
| amount | 32A | Parse amount; scale to token decimals |
| currencyCode | 32A | Currency from 32A |
| payloadHash | — | Hash of MT text block or full message |
Contracts only ever see the **canonical** struct; they do not need to know whether the source was MX or MT.
---
## 6. Contract Interface Requirements
### 6.1 Entry Points for “Accepting” Messages
Smart contracts that **accept** ISO-20022/Fin semantics should expose at least one of the following (or equivalent):
- **Inbound (e.g. submitInbound):** For instructions that result in **credit** to the chain (e.g. mint, or release from bridge). Caller must be an authorised relayer/guardian; payload is the canonical struct.
- **Outbound (e.g. submitOutbound):** For instructions that result in **debit** from the chain (e.g. burn, or lock for bridge). Same authorisation and canonical payload.
Naming may vary (e.g. `processInboundMessage`, `acceptCreditTransfer`); the important part is that the **payload is the canonical struct** and that **idempotency** and **policy checks** are enforced.
### 6.2 Authorisation
- Only designated roles (e.g. `ROUTER_ROLE`, `RELAYER_ROLE`, or a guard contract) may call the submit functions. Use AccessControl or equivalent.
- Optionally, require that the **sender** of the transaction is a known **guardian** or **relayer** address list, and that the canonical payload’s `payloadHash` matches an off-chain attested hash.
### 6.3 Events
Emit events that carry enough canonical metadata for off-chain systems to map to ISO-20022 status and reporting (e.g. pacs.002, camt.054):
- At least: `instructionId`, `msgId` (if any), `token`, `amount`, `debtorId`, `creditorId`, `payloadHash`, success/failure.
- Prefer including `msgType`, `endToEndId`, `uetr` where available so that reconciliation and compliance reporting are straightforward.
### 6.4 Integration with E-Money and Compliance
- **ComplianceGuard / PolicyManager / ComplianceRegistry:** Before executing the transfer/mint/burn, contracts should enforce allowlists, KYT, and circuit breakers as described in [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md). The canonical struct supplies `debtorId`, `creditorId`, and `purpose` for policy checks.
- **Reserve and par redeemability:** For base-money mints, ensure reserve attestation and par redeemability rules are applied as in the same runbook; the canonical message does not replace those checks.
---
## 7. Validation and Security
### 7.1 Off-Chain Validation (Before Submit)
- **Schema:** Validate MX against the appropriate ISO 20022 XSD; validate MT format per SWIFT rules.
- **Business rules:** Amount &gt; 0, currency matches token, mandatory identifiers present, no duplicate `instructionId`/`msgId` in the system.
- **Payload hash:** Compute `payloadHash` over the raw or normalized message and attach to the canonical struct so the contract (or a verifier) can optionally check it.
### 7.2 On-Chain Checks
- **Idempotency:** Revert or skip if `instructionId` (or chosen key) already processed.
- **Role:** Only authorised roles can call submit.
- **Token:** Ensure `token` is a known, allowed token (e.g. via TokenRegistry or allowlist).
- **Amount:** Ensure `amount` is within bounds and, for mints, consistent with reserve/attestation logic.
### 7.3 Audit and Non-Repudiation
- Store or log `payloadHash` and `instructionId` on-chain so that auditors can match on-chain execution to off-chain MX/Fin messages.
- Prefer emitting full canonical metadata in events and indexing them off-chain for compliance and reconciliation.
---
## 8. Implementation Checklist
- [ ] **Off-chain:** Parser for ISO-20022 MX (and optionally SWIFT Fin MT) producing the canonical struct.
- [ ] **Off-chain:** Mapping tables and validation rules (amounts, currency, identifiers) aligned with [Mapping_Table.md](../../gru-docs/docs/integration/iso20022/Mapping_Table.md) and [iso20022-mapping.md](../../dbis_core/docs/nostro-vostro/iso20022-mapping.md).
- [ ] **Contract:** Canonical struct and submit interface (e.g. `submitInbound`/`submitOutbound`) with role-based access.
- [ ] **Contract:** Idempotency (e.g. `processedInstructions[instructionId]`) and policy hooks (ComplianceGuard, PolicyManager, ComplianceRegistry).
- [ ] **Contract:** Events that expose canonical metadata for ISO-20022 mapping and reporting.
- [ ] **Integration:** Bridge and e-money entry points (BridgeVault, UniversalCCIPBridge, etc.) carry or reference canonical metadata in events as per [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md).
---
## 9. Related Documents
| Document | Description |
|----------|-------------|
| [ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md](ISO20022_INTAKE_GATEWAY_CONTRACT_MULTI_NETWORK.md) | How the intake/gateway contract receives ISO messages on different blockchain networks (relayer vs cross-chain, same address, per-chain config) |
| [MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md](../runbooks/MULTI_CHAIN_EXECUTION_ISO20022_EMONEY.md) | ISO-20022 canonical message and E-Money requirements for GRU multi-chain |
| [Mapping_Table.md](../../gru-docs/docs/integration/iso20022/Mapping_Table.md) | ISO 20022 (pain.001, pacs.008, etc.) field-level mapping and validation |
| [iso20022-mapping.md](../../dbis_core/docs/nostro-vostro/iso20022-mapping.md) | ISO 20022 to DBIS API mapping and Iso20022Adapter usage |
| [iso20022-message-flow.md](../../dbis_core/docs/flows/iso20022-message-flow.md) | ISO 20022 message processing flow |
| [LEGAL_COMPLIANCE_REQUIREMENTS.md](../../explorer-monorepo/docs/LEGAL_COMPLIANCE_REQUIREMENTS.md) | Legal and ISO 20022 compliance for smart contracts |
---
**Document Control**
- **Owner:** Configuration / Integration
- **Review:** Align with runbook and mapping table changes
- **Next review:** When contract interfaces or ISO-20022 message set change

64
docs/04-configuration/STORAGE_FIX_R630_01_AND_THIN5.md Normal file
View File

@@ -0,0 +1,64 @@
# Storage fix: r630-01 (72%) and r630-02 thin5 (84.6%)
**Last updated:** 2026-02-28
## Situation
- **r630-01** `data` / `local-lvm`: **~72%** used. Many CTs (validators, RPC 2101, 2500–2505, etc.) use this pool.
- **r630-02** `thin5`: **~84.6%** used. **Only VMID 5000 (Blockscout/Explorer)** uses thin5.
## Fix options
### 1. Prune only (recommended first)
Frees space without moving any container:
- **thin5:** Prune inside VMID 5000: journal, Docker logs/images, logrotate, backups.
- **r630-01:** Prune journal and logs in all running CTs on the host.
```bash
# From project root (LAN, SSH to both hosts)
bash scripts/maintenance/fix-storage-r630-01-and-thin5.sh
```
Dry-run:
```bash
bash scripts/maintenance/fix-storage-r630-01-and-thin5.sh --dry-run
```
### 2. Prune + migrate VMID 5000 to an empty pool
To free thin5, migrate Blockscout (5000) to the emptiest pool on r630-02: **thin2** (~4.8% used):
```bash
# Migrate 5000 from thin5 -> thin2 (empty pool)
bash scripts/maintenance/fix-storage-r630-01-and-thin5.sh --migrate-5000 thin2
```
Other options: `thin6` (~14% used), `thin3` (~11% used). This will: stop 5000 → vzdump to local → destroy CT → restore to target pool → start. Expect 15–45 min; Blockscout is down during backup/restore.
### 3. Manual VMID 5000 prune (if script not run from repo)
On r630-02 or from a host that can SSH there:
```bash
bash scripts/maintenance/vmid5000-free-disk-and-logs.sh
```
## Verify after fix
```bash
bash scripts/audit-proxmox-rpc-storage.sh
# or
ssh root@192.168.11.11 'pvesm status'
ssh root@192.168.11.12 'pvesm status'
```
LVM thin reclaim can take a few minutes after deleting data inside CTs; re-run `pvesm status` or `lvs` after a short wait.
## Reference
- thin5 on r630-02: single consumer **VMID 5000**.
- r630-01 data: shared by VMIDs 2101, 1000, 1001, 1002, 10100, 10101, 10120, and others on that host.
- Existing prune script for 5000: `scripts/maintenance/vmid5000-free-disk-and-logs.sh`.

145
docs/04-configuration/STORAGE_RECOMMENDATIONS_BY_FILL_RATE.md Normal file
View File

@@ -0,0 +1,145 @@
# Storage Recommendations by Fill Rate and Growth
**Last updated:** 2026-02-28
Based on current usage, history in `logs/storage-growth/history.csv`, and physical drive layout across ml110, r630-01, and r630-02.
**Completed (2026-02-28):** Storage growth cron verified; prune (VMID 5000 + r630-01 CTs) run; ml110 sdb added to VG `pve` and data thin pool extended to ~1.7 TB (ml110 data now ~11% used). **Phase 1 migration (r630-01 data → thin1):** 8 CTs migrated (10233, 10120, 10100, 10101, 10235, 10236, 7804, 8640); r630-01 data **65.8%** (was 72%), thin1 50.6%.
---
## 1. Thresholds and monitoring
| Level | Use % | Action |
|-------|--------|--------|
| **Healthy** | &lt; 75% | Continue normal collection; review quarterly. |
| **Watch** | 75–84% | Weekly review; plan prune or migration. |
| **WARN** | 85–94% | Prune and/or migrate within 1–2 weeks; do not add new large CTs. |
| **CRIT** | ≥ 95% | Immediate action; LVM thin pools can fail or go read-only. |
Current scripts: `check-disk-all-vmids.sh` uses WARN 85%, CRIT 95% for **container root** usage. These recommendations apply to **host storage (pvesm / LVM)** as well.
---
## 2. Observed fill behavior (from history)
| Host | Storage | Trend (recent) | Implied rate / note |
|------|---------|----------------|----------------------|
| **ml110** | data | ~28.7% → ~25% (Feb 15 → 27) | Slight decrease (prune/dedup). Plenty of free space. |
| **r630-01** | data | 88% → 100% → 72% → **65.8%** (Phase 1 migration) | After Phase 1 (8 CTs data→thin1). Main growth host (validators, RPCs, many CTs). |
| **r630-02** | thin1-r630-02 | ~26.5% stable | Low growth. |
| **r630-02** | thin2 | ~4.8% → ~9% after 5000 migration | Now holds Blockscout (5000); monitor. |
| **r630-02** | thin5 | Was 84.6% → 0% after migration | Empty; available for future moves. |
**Conclusion:** The pool that fills fastest and needs the most attention is **r630-01 data** (72% now; many CTs, Besu/DB growth). **ml110 data** is stable and has headroom. **r630-02** is manageable if you avoid concentrating more large CTs on a single thin pool.
---
## 3. Recommendations by host and pool
### ml110
- **data / local-lvm (~25%)**
- **Rate:** Low/slow.
- **Recommendations:**
- Keep running `collect-storage-growth-data.sh --append` (e.g. cron every 6h).
- Prune logs in CTs periodically (e.g. with `fix-storage-r630-01-and-thin5.sh`-style logic for ml110 or a dedicated prune script).
- No urgency; review again when approaching 70%.
- **Unused sdb (931G)**
- **Recommendation:** Use it before adding new disks elsewhere.
- **Option A:** Add sdb to VG `pve` and extend the `data` thin pool (or create a second thin pool). Frees pressure on sda and doubles effective data capacity.
- **Option B:** Create a separate VG + thin pool on sdb for new or migrated CTs.
- Document the chosen layout and any new Proxmox storage names in `storage.cfg` and in `PHYSICAL_DRIVES_AND_CONFIG.md`.
### r630-01
- **data / local-lvm (~72%)**
- **Rate:** Highest risk; this pool has the most CTs and Besu/DB growth.
- **Recommendations:**
1. **Short term:**
- Run log/journal prune on all r630-01 CTs regularly (e.g. `fix-storage-r630-01-and-thin5.sh` Phase 2, or a cron job).
- Keep storage growth collection (e.g. every 6h) and review weekly when &gt; 70%.
2. **Before 85%:**
- Move one or more large CTs to **thin1** on r630-01 (thin1 ~43% used, has space) if VMIDs allow, or plan migration to r630-02 thin pools.
- Identify biggest CTs: `check-disk-all-vmids.sh` and `lvs` on r630-01 (data pool).
3. **Before 90%:**
- Decide on expansion (e.g. add disks to RAID10 and extend md0/LVM) or permanent migration of several CTs to r630-02.
- **Do not** let this pool sit above 85% for long; it has already hit 100% once.
- **thin1 (~43%)**
- **Rate:** Moderate.
- **Recommendations:** Use as spillover for data pool migrations when possible. Monitor monthly; act if &gt; 75%.
### r630-02
- **thin1-r630-02 (~26%)**
- **Rate:** Low.
- **Recommendation:** Monitor; no change needed unless you add many CTs here.
- **thin2 (~9% after 5000 migration)**
- **Rate:** May grow with Blockscout (5000) and other CTs.
- **Recommendations:**
- Run VMID 5000 prune periodically: `vmid5000-free-disk-and-logs.sh`.
- If thin2 approaches 75%, consider moving one CT to thin5 (now empty) or thin6.
- **thin3, thin4, thin6 (roughly 11–22%)**
- **Rate:** Low to moderate.
- **Recommendation:** Include in weekly pvesm/lvs review; no special action unless one pool trends &gt; 75%.
- **thin5 (0% after migration)**
- **Recommendation:** Keep as reserve for migrations from thin2 or other pools when they approach WARN.
---
## 4. Operational schedule (by fill rate)
| When | Action |
|------|--------|
| **Always** | Cron: `collect-storage-growth-data.sh --append` every 6h; weekly: `prune-storage-snapshots.sh` (e.g. Sun 08:00). |
| **Weekly** | Review `pvesm status` and `lvs` (or run `audit-proxmox-rpc-storage.sh`); check any pool &gt; 70%. |
| **75% ≤ use &lt; 85%** | Plan and run prune; plan migration for largest CTs on that pool; consider using ml110 sdb (if not yet in use). |
| **85% ≤ use &lt; 95%** | Execute prune and migration within 1–2 weeks; do not add new large VMs/CTs to that pool. |
| **≥ 95%** | Immediate prune + migration; consider emergency migration to ml110 (after adding sdb) or r630-02. |
---
## 5. Scripts to support these recommendations
| Script | Purpose |
|--------|--------|
| `scripts/monitoring/collect-storage-growth-data.sh --append` | Record fill over time (for rate). |
| `scripts/maintenance/schedule-storage-growth-cron.sh --install` | Install 6h collect + weekly prune. |
| `scripts/audit-proxmox-rpc-storage.sh` | Current pvesm + RPC rootfs mapping. |
| `scripts/maintenance/check-disk-all-vmids.sh` | Per-CT disk usage (find big consumers). |
| `scripts/maintenance/fix-storage-r630-01-and-thin5.sh` | Prune 5000 + r630-01 CT logs; optional migrate 5000. |
| `scripts/maintenance/migrate-ct-r630-01-data-to-thin1.sh <VMID>` | Migrate one CT from r630-01 data → thin1 (same host). |
| `scripts/maintenance/vmid5000-free-disk-and-logs.sh` | Prune Blockscout (5000) only. |
---
## 6. Adding ml110 sdb to increase capacity (suggested steps)
1. On ml110: `vgextend pve /dev/sdb` (if sdb is already a PV) or `pvcreate /dev/sdb && vgextend pve /dev/sdb`.
2. Extend the data thin pool: `lvextend -L +900G /dev/pve/data` (or use `lvextend -l +100%FREE` and adjust as needed).
3. Re-run `pvesm status` and update documentation.
4. No CT migration required; existing LVs on data can use the new space.
(If sdb is a raw disk with no PV, partition or use full disk as PV per your policy; then add to `pve` and extend the data LV as above.)
---
## 7. Summary table by risk
| Host | Pool | Current (approx) | Risk | Priority recommendation |
|------|------|-------------------|------|--------------------------|
| ml110 | data | ~11% (post-extension) | Low | **Done:** sdb added; pool ~1.7 TB. Monitor as before. |
| ml110 | sdb | In use (extended data) | — | **Done:** sdb added to pve, data thin pool extended (~1.7 TB total). |
| r630-01 | data | ~72% | High | Prune weekly; plan migrations before 85%; consider thin1 spillover. |
| r630-01 | thin1 | ~43% | Medium | Use for migrations from data; monitor monthly. |
| r630-02 | thin1-r630-02 | ~26% | Low | Monitor. |
| r630-02 | thin2 | ~9% | Low | Prune 5000 periodically; watch growth. |
| r630-02 | thin5 | 0% | Low | Keep as reserve for migrations. |
| r630-02 | thin3, thin4, thin6 | ~11–22% | Low | Include in weekly review. |
These recommendations are based on the rate of filling observed in history and current configurations; adjust thresholds or schedule if your growth pattern changes.

41
docs/04-configuration/THIRDWEB_BRIDGE_VS_CCIP.md Normal file
View File

@@ -0,0 +1,41 @@
# Thirdweb Bridge Tab vs Custom CCIP Bridge – Do You Deploy a Contract?
**Short answer:**
**No.** For the **Thirdweb** bridge tab in the Interoperability Bridge app, you do **not** deploy any contract. That tab embeds Thirdweb’s hosted bridge (iframe to `thirdweb.com/bridge`). Thirdweb runs the bridge contracts and supports a fixed set of chains (85+). You only need a **Thirdweb Client ID** (from the [thirdweb dashboard](https://thirdweb.com/dashboard)) and `VITE_THIRDWEB_CLIENT_ID` in the dapp env.
**Custom CCIP bridge (Custom tab):**
For the **Custom** tab (Wrap → Approve → Bridge WETH9 via CCIP), **you do** use your own deployed contracts on Chain 138 and mainnet: WETH9, WETH9 Bridge (CCIP), and LINK for fees. Those are already configured in `config/bridge.ts` and the Custom tab uses them. No extra “Thirdweb bridge contract” is required for the Thirdweb tab.
---
## 1. Thirdweb tab (iframe)
- **What it is:** The “ThirdWeb” tab loads Thirdweb’s **hosted** bridge UI in an iframe:
`https://thirdweb.com/bridge?clientId=...&fromChain=138&toChain=...`
- **Who runs the contracts:** Thirdweb. Their bridge supports a fixed list of chains (85+). Chain 138 may or may not be in that list.
- **What you need:**
- A thirdweb project and **Client ID**.
- `VITE_THIRDWEB_CLIENT_ID` set in the frontend-dapp env (or the fallback in code).
- **Do you deploy a contract?** **No.** You do not deploy any contract for this tab.
If Chain 138 is not supported by Thirdweb’s bridge, the iframe may show an error or “no entry” until Thirdweb adds Chain 138. For Chain 138 → EVM bridging that you control, use the **Custom** tab with your CCIP contracts.
---
## 2. Custom tab (CCIP)
- **What it is:** Your own UI (BridgeButtons, etc.) that talks to your WETH9 and WETH9 Bridge (CCIP) contracts on Chain 138 and LINK on mainnet.
- **Who runs the contracts:** You (addresses in `config/bridge.ts` / env).
- **What you need:** Deployed WETH9, WETH9 Bridge, and LINK (and any allowlists) on Chain 138 and mainnet as per your deployment runbooks.
- **Do you deploy a contract?** **Yes.** This tab uses **your** deployed CCIP/bridge contracts; no Thirdweb bridge contract is involved.
---
## 3. Summary
| Tab | Contract deployment for the bridge? | Who runs bridge contracts? |
|----------|--------------------------------------|-----------------------------|
| ThirdWeb | **No** | Thirdweb (hosted) |
| Custom | **Yes** (WETH9, WETH9 Bridge, LINK) | You (Chain 138 + mainnet) |
So: **there is no separate “Thirdweb bridge contract” for you to deploy.** For the Thirdweb tab you only need a Client ID; for the Custom tab you use your existing CCIP bridge deployment.

124
docs/04-configuration/THIRDWEB_WALLETS_INTEGRATION.md Normal file
View File

@@ -0,0 +1,124 @@
# Thirdweb Wallets – Documentation Review and Integration
**Purpose:** Review [thirdweb Wallets portal](https://portal.thirdweb.com/wallets) and document how we use or can fully integrate user/embedded wallets (email, phone, social, passkey, external) across the repo.
**References:** [thirdweb Wallets – Get Started](https://portal.thirdweb.com/wallets), [User Wallets](https://portal.thirdweb.com/wallets/users), [External Wallets](https://portal.thirdweb.com/wallets/external-wallets), [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart), [Connect SDK v5](https://portal.thirdweb.com/react/v5).
---
## 1. Portal overview
The thirdweb Wallets section covers:
- **User wallets (embedded/in-app):** Email, phone, social OAuth (Google, Apple, Facebook, Discord, X, etc.), passkey, guest, custom JWT.
- **External wallets:** 500+ wallets, EIP-6963; MetaMask, WalletConnect, Coinbase Wallet, etc.
- **Server wallets:** Backend-controlled wallets (send tx, monitor).
- **Gas sponsorship / session keys:** Optional.
For each user, thirdweb can create a **non-custodial wallet** and expose it via SDK or HTTP API.
---
## 2. HTTP API (Wallets)
Relevant for backend or headless flows:
| Endpoint | Purpose |
|----------|--------|
| `POST /v1/auth/initiate` | Start auth (email, phone, passkey, SIWE); get challenge. |
| `POST /v1/auth/complete` | Verify and complete auth; returns `token`, `userId`, `walletAddress`. |
| `GET /v1/auth/social` | Redirect to OAuth provider (`provider`, `redirectUrl`). |
| `GET /v1/wallets/me` | Get authenticated user wallet (use token from complete). |
**Headers:**
- **Frontend:** `x-client-id` (project Client ID).
- **Backend:** `x-secret-key` (Dashboard → Settings → API Keys); never in frontend.
**Auth flow (e.g. email):**
1. `POST /v1/auth/initiate` with `{ "type": "email", "email": "user@example.com" }`.
2. User receives code; then `POST /v1/auth/complete` with `{ "type": "email", "email": "...", "code": "123456" }`.
3. Response includes `token`, `walletAddress`; use `token` for `GET /v1/wallets/me` or other authenticated calls.
**Custom auth:** If you already have an auth system, you can attach thirdweb wallets via [Custom Authentication](https://portal.thirdweb.com/wallets/custom-auth).
---
## 3. Current usage in this repo
| Area | What we use | Notes |
|------|-------------|--------|
| **smom-dbis-138/frontend-dapp** | `ThirdwebProvider` (v4), `useAddress` / `useBalance` / `useContract` from `@thirdweb-dev/react`; bridge UI uses thirdweb v4 hooks. | Connect UI is **wagmi** (MetaMask, WalletConnect, Coinbase) in `WalletConnect.tsx`; no embedded wallet (email/social) yet. |
| **x402-api** | `thirdweb` v5: `createThirdwebClient`, `facilitator`, `settlePayment` from `thirdweb/x402`; custom Chain 138. | Server-side only; no user wallets. |
| **explorer-monorepo** | Raw ethers + MetaMask + custom `/api/v1/auth/nonce` and `/api/v1/auth/wallet`. | No thirdweb SDK. |
**Secrets / env:**
- **frontend-dapp:** `VITE_THIRDWEB_CLIENT_ID`, `VITE_WALLETCONNECT_PROJECT_ID` (see [MASTER_SECRETS.md](MASTER_SECRETS.md), [DAPP_LXC_DEPLOYMENT.md](../03-deployment/DAPP_LXC_DEPLOYMENT.md)).
- **x402-api:** `THIRDWEB_SECRET_KEY` (backend only).
---
## 4. Full integration options
### 4.1 Frontend: one connect experience (embedded + external)
**Goal:** Single “Connect” that supports both **in-app wallets** (email, phone, social) and **external wallets** (MetaMask, WalletConnect, etc.) as in the [portal Get Started](https://portal.thirdweb.com/wallets) and [Quickstart](https://portal.thirdweb.com/wallets/quickstart).
**Recommended path: thirdweb SDK v5**
- Portal and Quickstart use **v5** (`thirdweb` package, `thirdweb/react`).
- v5 provides `ConnectButton` / `ConnectEmbed`, `inAppWallet({ auth: { options: ["email", "google", "passkey", ...] } })`, and 500+ external wallets with smaller bundle and better perf than v4.
- v4 (`@thirdweb-dev/react`) is still in use in the dapp for contract hooks; v5 can run [alongside v4](https://portal.thirdweb.com/react/v5/migrate) for a gradual move.
**Steps:**
1. **Add v5 and a dedicated wallets flow (e.g. demo page)**
- Install: `npm i thirdweb`.
- Use `createThirdwebClient({ clientId })`, `ThirdwebProvider`, `ConnectButton` from `thirdweb/react`.
- Configure `ConnectButton` with `inAppWallet({ auth: { options: ["email", "google", "apple", "passkey"] } })` so users can sign in with email/social or connect MetaMask/WalletConnect.
- **Done:** The frontend-dapp has a **Wallets** page (`/wallets`, `src/pages/WalletsDemoPage.tsx`) that uses only v5: `ConnectButton` with in-app wallet + external wallets, `useActiveAccount`, `useWalletBalance` on Chain 138. Use it to try email/social/external connect without changing the rest of the app.
2. **Unify connect UI (full integration)**
- Replace the current wagmi-only connect modal in `Layout` / `WalletConnect.tsx` with thirdweb v5’s `ConnectButton` (or `ConnectEmbed`) so the same button offers embedded + external.
- Migrate bridge and other features from v4 hooks to v5: e.g. `useAddress` → `useActiveAccount`, `useContract`/`useContractWrite` → v5 contract extensions + `useSendTransaction` (see [v5 migrate](https://portal.thirdweb.com/react/v5/migrate)).
- Keep Chain 138 in v5 (e.g. `defineChain` or use a chain list that includes 138) so the same RPC and chain are used.
3. **Env**
- Use the same `VITE_THIRDWEB_CLIENT_ID` (and optional `VITE_WALLETCONNECT_PROJECT_ID` if needed by v5). No backend secret in frontend.
### 4.2 Backend: optional use of Wallets API
- If you need to **resolve or manage user wallets server-side** (e.g. after a custom auth), call `GET /v1/wallets/me` with the thirdweb token, or use the HTTP auth flow (`/v1/auth/initiate`, `/v1/auth/complete`) with `x-secret-key` from a secure backend.
- **x402-api** already uses `THIRDWEB_SECRET_KEY` for x402; the same key can be used for server-side Wallets API calls if you add them.
### 4.3 Explorer (Blockscout frontend)
- The explorer uses ethers + MetaMask and custom auth endpoints; it does not use thirdweb.
- Full thirdweb Wallets integration there would mean adding the thirdweb SDK and either replacing or complementing the current connect flow with `ConnectButton` + in-app wallet; that’s a separate, optional project.
---
## 5. Checklist for “fully integrated” thirdweb Wallets
- [x] **Documentation:** This file + links to portal (Get Started, Users, Quickstart, v5 migrate).
- [x] **Client ID:** `VITE_THIRDWEB_CLIENT_ID` set in frontend-dapp (and any other app that uses thirdweb).
- [x] **Connect UI (demo):** `/wallets` page with v5 `ConnectButton` + `inAppWallet` (email, google, apple, passkey) + external wallets; Chain 138 balance shown.
- [ ] **Chain 138:** Supported in the thirdweb client/chains config used by the dapp.
- [ ] **Migration (optional):** Bridge and other components moved from v4 hooks to v5 extensions/hooks so one account source is used everywhere.
- [ ] **Backend (optional):** Use of `/v1/wallets/me` or auth endpoints from a secure service when needed.
---
## 6. Quick links
- [Wallets – Get Started](https://portal.thirdweb.com/wallets)
- [User Wallets (auth methods)](https://portal.thirdweb.com/wallets/users)
- [External Wallets](https://portal.thirdweb.com/wallets/external-wallets)
- [Quickstart (TypeScript/React)](https://portal.thirdweb.com/wallets/quickstart)
- [React v5 ConnectButton / ConnectEmbed](https://portal.thirdweb.com/react/v5/components/ConnectButton)
- [In-App Wallet (v5)](https://portal.thirdweb.com/react/v5/in-app-wallet/get-started)
- [Migrate from v4 to v5](https://portal.thirdweb.com/react/v5/migrate)
- [API Reference – Authentication](https://portal.thirdweb.com/reference#tag/authentication)
- [Custom auth](https://portal.thirdweb.com/wallets/custom-auth)

124
docs/04-configuration/TOKEN_AGGREGATION_REPORT_API_RUNBOOK.md Normal file
View File

@@ -0,0 +1,124 @@
# Token-Aggregation Report API — Reachability Runbook
**Purpose:** Ensure `GET /api/v1/report/coingecko`, `GET /api/v1/report/cmc`, and `GET /api/v1/report/token-list` are reachable for CoinGecko/CMC submission and Chain 138 Snap.
---
## 1. Verify current state
```bash
# From repo root
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
```
**Expected when working:** Token list and networks return valid JSON with `.tokens` and `.networks`.
**If you see "no .tokens" or "no .networks":** The `/api/v1/` path is likely proxied to Blockscout (or another backend) instead of token-aggregation. Proceed to §2.
---
## 2. Deploy token-aggregation (if not running)
### 2.1 On explorer VM (VMID 5000) or dedicated host
1. **Deploy the service:**
```bash
cd smom-dbis-138/services/token-aggregation
cp .env.example .env
# Edit .env: DATABASE_URL, CUSDC_ADDRESS_138, CUSDT_ADDRESS_138 (minimum for report)
npm install && npm run build
```
2. **Run via systemd** (or use `deploy-to-proxmox.sh` / `deploy-to-vmid.sh`):
```bash
# Example systemd unit
ExecStart=/usr/bin/node /opt/token-aggregation/dist/index.js
WorkingDirectory=/opt/token-aggregation
```
3. **Verify locally:**
```bash
curl -s "http://localhost:3000/api/v1/report/token-list?chainId=138" | jq '.tokens | length'
curl -s "http://localhost:3000/api/v1/report/coingecko?chainId=138" | jq '.'
curl -s "http://localhost:3000/api/v1/networks" | jq '.networks | length'
```
### 2.2 Minimum env for report API
| Var | Purpose |
|-----|---------|
| `CUSDC_ADDRESS_138` | cUSDC on Chain 138 |
| `CUSDT_ADDRESS_138` | cUSDT on Chain 138 |
| `CHAIN_138_RPC_URL` or `RPC_URL_138` | RPC for indexing |
| `DATABASE_URL` | PostgreSQL (required for full service) |
**Note:** The report endpoints may work with minimal config; full indexing requires DB and RPC.
---
## 3. Proxy /api/v1/ to token-aggregation (explorer.d-bis.org)
If token-aggregation runs on the **explorer VM** (e.g. port 3000):
```bash
# SSH to explorer VM (VMID 5000), then:
TOKEN_AGG_PORT=3000 CONFIG_FILE=/etc/nginx/sites-available/blockscout \
bash /path/to/explorer-monorepo/scripts/apply-nginx-token-aggregation-proxy.sh
```
This inserts `location /api/v1/` proxying to `http://127.0.0.1:3000/api/v1/`. **Important:** The token-aggregation `location` must be defined **before** any Blockscout API `location` that might also match `/api/v1/`, so token-aggregation takes precedence.
### 3.1 If token-aggregation runs elsewhere
- **Option A:** Run token-aggregation on the explorer host (same machine as nginx) and proxy to `127.0.0.1:3000`.
- **Option B:** Run on a different host; proxy to that host, e.g. `proxy_pass http://192.168.11.XXX:3000/api/v1/;`
- **Option C:** Use a separate domain (e.g. `api.d-bis.org`) for the token-aggregation API and set `GATSBY_SNAP_API_BASE_URL` to that URL when building the Snap site.
---
## 4. Re-verify
```bash
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
```
All checks should pass. Then:
```bash
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
```
Use these files for CoinGecko/CMC submission per [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md).
---
## 5. Troubleshooting
| Issue | Cause | Fix |
|-------|-------|-----|
| `curl .../api/v1/report/token-list` returns Blockscout-style JSON (`message`, `result`, `status`) | `/api/v1/` proxied to Blockscout, not token-aggregation | Ensure token-aggregation `location` is first; reload nginx |
| Connection refused to 127.0.0.1:3000 | Token-aggregation not running | Start service; check `systemctl status token-aggregation` |
| Empty `tokens` array | `CUSDC_ADDRESS_138`, `CUSDT_ADDRESS_138` unset or wrong | Set in `.env`; restart service |
| 502 Bad Gateway | Token-aggregation crashed or wrong port | Check logs; verify `TOKEN_AGG_PORT` matches service |
---
## 6. Quick commands summary
```bash
# 1. Verify (from repo root)
bash metamask-integration/chain138-snap/scripts/verify-snap-api-and-icons.sh https://explorer.d-bis.org
# 2. Export for submission (after API is reachable)
curl -s "https://explorer.d-bis.org/api/v1/report/coingecko?chainId=138" -o report-coingecko-138.json
curl -s "https://explorer.d-bis.org/api/v1/report/cmc?chainId=138" -o report-cmc-138.json
```
---
## 7. Related docs
- [PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS](PRICE_FEED_CHAIN138_METAMASK_AND_WALLETS.md) — Price feed checklist
- [CMC_COINGECKO_SUBMISSION_RUNBOOK](coingecko/CMC_COINGECKO_SUBMISSION_RUNBOOK.md) — Export and submit
- [smom-dbis-138/services/token-aggregation/README.md](../../../smom-dbis-138/services/token-aggregation/README.md) — Service setup

94
docs/04-configuration/TOKEN_LISTS_E2E_VERIFICATION.md Normal file
View File

@@ -0,0 +1,94 @@
# Token Lists E2E Verification Report
**Date:** 2026-02-28
**Status:** Verification complete
---
## 1. Token List Validation
| List | Status | Tokens | Notes |
|------|--------|--------|-------|
| dbis-138.tokenlist.json | ✅ Valid | 6 | All IPFS logos, EIP-55 checksummed |
| cronos.tokenlist.json | ✅ Valid | 10 | All IPFS logos, ISO-4217 W tokens |
| all-mainnet.tokenlist.json | ✅ Valid | 9 | All 9 tokens have logoURI (IPFS) |
| DUAL_CHAIN_TOKEN_LIST | ✅ Valid | 22 | Chains 138, 1, 25, 651940 |
---
## 2. Cross-File Consistency
| Check | Result |
|-------|--------|
| Chain 138 addresses (dbis-138 vs DUAL_CHAIN) | ✅ Consistent |
| Cronos addresses (cronos vs DUAL_CHAIN) | ✅ Consistent |
| DUAL_CHAIN synced to backend/config, docs, metamask | ✅ Done |
---
## 3. IPFS Manifest
- **addressToUrl:** 14 of 22 DUAL_CHAIN addresses covered
- **Missing:** Chain 1 (USDT, USDC, DAI, ETH-USD, WETH) and Chain 651940 USDC, Cronos WETH9/LINK — these use external logo URLs in token lists (TrustWallet, ethereum.org)
- **Our tokens (138, 25):** All covered
---
## 4. Explorer API (`/api/config/token-list`)
| Check | Result |
|-------|--------|
| Public URL | ❌ Returns 400 (Blockscout error) |
| Cause | Nginx config not yet applied on VMID 5000 |
| Fix | Run on Proxmox host: |
| | 1. `fix-nginx-conflicts-vmid5000.sh` (inside VMID 5000) |
| | 2. `deploy-explorer-config-to-vmid5000.sh` (from repo root, with pct or EXEC_MODE=ssh) |
---
## 5. Deploy Script
| Check | Result |
|-------|--------|
| Config source path | ✅ Correct |
| pct mode | Requires Proxmox host |
| ssh mode | `EXEC_MODE=ssh EXPLORER_IP=192.168.11.140 ./explorer-monorepo/scripts/deploy-explorer-config-to-vmid5000.sh` |
---
## 6. Nginx Location Order
```
location = /api/config/token-list # Exact match (highest priority)
location = /api/config/networks
location /api/v1/ # Token-aggregation
location /api/ # Blockscout (fallback)
```
✅ Correct — `/api/config/*` takes precedence over `/api/`
---
## 7. Frontend tokenIcons.ts
- Chain 138: 6 addresses ✅
- Cronos WETH9, LINK, ISO-4217 W tokens: 9 addresses ✅
---
## 8. E2E Checklist (Operator)
To achieve full E2E:
1. [ ] SSH to Proxmox host (or VMID 5000)
2. [ ] Run `fix-nginx-conflicts-vmid5000.sh` inside VMID 5000
3. [ ] Run `deploy-explorer-config-to-vmid5000.sh` from repo root (pct or ssh)
4. [ ] Verify: `curl -s https://explorer.d-bis.org/api/config/token-list | jq '.tokens | length'` → 22
5. [ ] Verify: `curl -s https://explorer.d-bis.org/api/config/networks | jq '.chains | length'` → 4
---
## 9. Completed Improvements
- ✅ all-mainnet: logoURI added for HYDX, HYBX, CHT, AUDA
- ✅ tokenIcons.ts: Cronos WETH9, LINK added to TOKEN_ICON_BY_ADDRESS

198
docs/04-configuration/TOKEN_LIST_PR_REVIEW.md Normal file
View File

@@ -0,0 +1,198 @@
# Token List PR Review — How Each Repo Handles Token Lists
**Cloned repos:** `/home/intlc/projects/token-lists`, `chains`, `wallet-core`, `DefiLlama-Adapters`
**Last Updated:** 2026-02-28
---
## 1. Uniswap token-lists (`/home/intlc/projects/token-lists`)
### What it is
- **Schema + TypeScript package**, not a registry of token lists
- Defines the Uniswap token list JSON schema (`src/tokenlist.schema.json`)
- Schema ID: `https://uniswap.org/tokenlist.schema.json`
- Used by tokenlists.org, Uniswap Interface, MetaMask, etc.
### Token list format (from `example.tokenlist.json`)
```json
{
"name": "My Token List",
"logoURI": "ipfs://...",
"keywords": ["audited", "verified"],
"tags": { "stablecoin": { "name": "Stablecoin", "description": "..." } },
"timestamp": "2020-06-12T00:00:00+00:00",
"tokens": [
{
"chainId": 1,
"address": "0xA0b86991c6218b36c1d19D4a2e9Eb0cE3606eB48",
"symbol": "USDC",
"name": "USD Coin",
"decimals": 6,
"logoURI": "ipfs://..."
}
],
"version": { "major": 1, "minor": 0, "patch": 0 }
}
```
### Cross-chain (from `example-crosschain.tokenlist.json`)
- Same structure; tokens can have `extensions.bridgeInfo` mapping chainId → bridged address
- Each chain gets its own token entry with `chainId`
### PR process
- **This repo does NOT host token lists** — it only provides the schema
- To add a list: host it (GitHub Raw, IPFS, ENS) and submit to **tokenlists.org** via https://github.com/Uniswap/tokenlists-org/issues (template: "add list request")
- Or use your own URL (e.g. `explorer.d-bis.org/api/v1/report/token-list`)
### Chain 138 action
- Ensure `proxmox/token-lists/lists/dbis-138.tokenlist.json` validates against schema
- Host at GitHub Raw or explorer API
- Submit URL to tokenlists.org
---
## 2. Chainlist / ethereum-lists/chains (`/home/intlc/projects/chains`)
### What it is
- **Chain metadata** (RPC, explorers, native currency) — not token lists
- Used by chainlist.org, wallets, MESC, etc.
- File: `_data/chains/eip155-{chainId}.json`
### Chain format (from `eip155-1.json`)
```json
{
"name": "Ethereum Mainnet",
"chain": "ETH",
"icon": "ethereum",
"rpc": ["https://mainnet.infura.io/...", "..."],
"features": [{"name": "EIP155"}, {"name": "EIP1559"}],
"faucets": [],
"nativeCurrency": { "name": "Ether", "symbol": "ETH", "decimals": 18 },
"infoURL": "https://ethereum.org",
"shortName": "eth",
"chainId": 1,
"networkId": 1,
"slip44": 60,
"explorers": [{ "name": "etherscan", "url": "https://etherscan.io", "standard": "EIP3091" }]
}
```
### PR process
1. Add `_data/chains/eip155-138.json`
2. If using `icon`, add `_data/icons/defioraclemeta.json` (IPFS URL for logo)
3. Run `./gradlew run` and `npx prettier --write _data/*/*.json`
4. Open PR to https://github.com/ethereum-lists/chains
### Chain 138 status
- **Not present** (no eip155-138.json in chains repo)
- PR-ready: `proxmox/docs/04-configuration/pr-ready/eip155-138.json`
---
## 3. Trust Wallet wallet-core (`/home/intlc/projects/wallet-core`)
### What it is
- **Coin/chain registry** for Trust Wallet app
- `registry.json` — flat array of coins/chains
- EVM chains have: `id`, `name`, `coinId`, `symbol`, `blockchain`, `chainId`, `explorer`, `info.rpc`
### EVM chain format (from registry.json)
```json
{
"id": "ethereum",
"name": "Ethereum",
"coinId": 60,
"symbol": "ETH",
"decimals": 18,
"blockchain": "Ethereum",
"derivation": [{ "path": "m/44'/60'/0'/0/0" }],
"curve": "secp256k1",
"publicKeyType": "secp256k1Extended",
"chainId": "1",
"addressHasher": "keccak256",
"explorer": {
"url": "https://etherscan.io",
"txPath": "/tx/",
"accountPath": "/address/",
"sampleTx": "...",
"sampleAccount": "..."
},
"info": {
"url": "https://ethereum.org",
"source": "https://github.com/ethereum/go-ethereum",
"rpc": "https://mainnet.infura.io",
"documentation": "..."
}
}
```
### PR process
1. Add entry to `registry.json` (EVM: `blockchain: "Ethereum"`, `chainId`, `explorer`, `info.rpc`)
2. Run codegen: `cd codegen-v2 && cargo run -- new-evmchain 138` (or per their CLI)
3. Extend derivation tests
4. Open PR to https://github.com/trustwallet/wallet-core
### Chain 138 status
- **Not present**
- PR-ready: `proxmox/docs/04-configuration/pr-ready/trust-wallet-registry-chain138.json`
---
## 4. DefiLlama-Adapters (`/home/intlc/projects/DefiLlama-Adapters`)
### What it is
- **Protocol TVL adapters** — not token lists
- Each project (e.g. `dodo`, `1inch`) has `index.js` that exports `tvl(api)` per chain
- DefiLlama uses chain keys: `ethereum`, `bsc`, `polygon`, `arbitrum`, `avax`, `optimism`, `base`, etc.
### Adapter format (from `dodo/index.js`)
```javascript
const config = {
ethereum: { dvmFactory: '0x...', fromBlock: 10613640, ... },
arbitrum: { dvmFactory: '0x...', fromBlock: 226578, ... },
// Add new chain: chain138: { ... }
};
Object.keys(config).forEach(chain => {
module.exports[chain] = {
tvl: async (api) => {
// Fetch balances, return { 'ethereum:0xToken': balance }
}
};
});
```
### PR process
1. Add adapter under `projects/{protocol-name}/`
2. Export `tvl` (and optionally `staking`, `borrowed`) per chain
3. Chain 138 would need DefiLlama to add `chain138` as a supported chain key first (see docs.llama.fi)
4. Open PR to https://github.com/DefiLlama/DefiLlama-Adapters
### Chain 138 action
- DefiLlama may not have `chain138` as a chain key yet
- Check `helper/chains.js` or similar for supported chains
- If adding DODO/other protocol on Chain 138, add config entry + tvl logic
---
## Summary: PR Targets by Repo
| Repo | Content | Chain 138 PR |
|------|---------|--------------|
| **token-lists** | Schema only; lists hosted elsewhere | N/A — use tokenlists.org issue to add list URL |
| **chains** | Chain metadata (eip155-138.json) | Add `_data/chains/eip155-138.json` |
| **wallet-core** | Coin/chain registry | Add entry to `registry.json` + codegen |
| **DefiLlama-Adapters** | Protocol TVL adapters | Add adapter for DODO/etc. on Chain 138 (if chain supported) |
---
## References
- [PUBLICATION_LOCATIONS_MASTER](PUBLICATION_LOCATIONS_MASTER.md)
- [pr-ready/eip155-138.json](pr-ready/eip155-138.json)
- [pr-ready/trust-wallet-registry-chain138.json](pr-ready/trust-wallet-registry-chain138.json)
- [ADD_CHAIN138_TO_TRUST_WALLET](ADD_CHAIN138_TO_TRUST_WALLET.md)

6
docs/04-configuration/VERIFICATION_GAPS_AND_TODOS.md
View File

@@ -1,6 +1,6 @@
# Verification Scripts and Documentation - Gaps and TODOs
**Last Updated:** 2026-01-31
**Last Updated:** 2026-03-02
**Document Version:** 1.0
**Status:** Active Documentation
@@ -10,6 +10,8 @@
**Status**: Gap Analysis Complete
**Purpose**: Identify all placeholders, missing components, and incomplete implementations
**Documentation note (2026-03-02):** Runbook placeholders (e.g. `your-token`, `your-password`) are intentional examples. In production, use values from `.env` only; do not commit secrets. [INGRESS_VERIFICATION_RUNBOOK.md](INGRESS_VERIFICATION_RUNBOOK.md) updated with a production note in Prerequisites. Other runbooks (NPMPLUS_BACKUP_RESTORE, SANKOFA_CUTOVER_PLAN) keep example placeholders; operators should source from .env when running commands.
---
## Critical Missing Components
@@ -106,7 +108,7 @@
- Line 125: `NPM_PASSWORD="your-password"` → Example placeholder (acceptable)
- Line 178: `NPM_PASSWORD="your-password"` → Example placeholder (acceptable)
**Action Required**: Add clear notes that these are examples and should use `.env` file in production.
**Status (2026-03-02):** Addressed. INGRESS_VERIFICATION_RUNBOOK.md now includes a production note in Prerequisites. VERIFICATION_GAPS_AND_TODOS documents that runbooks use example placeholders and production should source from .env.
---

10
docs/04-configuration/coingecko/COINGECKO_SUBMISSION_GUIDE.md
View File

@@ -67,10 +67,18 @@ This guide provides step-by-step instructions for submitting cUSDT and cUSDC tok
**Requirements:**
- Format: PNG
- Size: 512x512 pixels
- Size: 512×512 pixels
- Background: Transparent preferred
- Quality: High resolution
**Quick prepare (script):**
```bash
# From repo root. Requires ImageMagick (convert) or Pillow for 512×512 resize.
# Install: apt install imagemagick OR pip install Pillow
./docs/04-configuration/coingecko/scripts/prepare-token-logos-512x512.sh
# Output: docs/04-configuration/coingecko/logos/*-512x512.png
```
**Where to get logos:**
- Use USDT/USDC logos as reference
- Create distinct versions for cUSDT/cUSDC

1
docs/04-configuration/coingecko/exports/report-cmc-1.json Normal file
View File

@@ -0,0 +1 @@
{"message":"Params 'module' and 'action' are required parameters","result":null,"status":"0"}

1
docs/04-configuration/coingecko/exports/report-cmc-10.json Normal file
View File

@@ -0,0 +1 @@
{"message":"Params 'module' and 'action' are required parameters","result":null,"status":"0"}

1
docs/04-configuration/coingecko/exports/report-cmc-100.json Normal file
View File

@@ -0,0 +1 @@
{"message":"Params 'module' and 'action' are required parameters","result":null,"status":"0"}

Some files were not shown because too many files have changed in this diff Show More