proxmox/docs/GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md

# Gaps, Placeholders, and Recommendations — Consolidated

**Last Updated:** 2026-02-05  
**Purpose:** Single reference for all identified gaps, placeholders, and actionable recommendations across the repository.

**Related:** [REQUIRED_FIXES_UPDATES_GAPS.md](REQUIRED_FIXES_UPDATES_GAPS.md) | [PLACEHOLDERS_AND_TBD.md](PLACEHOLDERS_AND_TBD.md) | [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) | [04-configuration/VERIFICATION_GAPS_AND_TODOS.md](04-configuration/VERIFICATION_GAPS_AND_TODOS.md)

**Updates (2026-02-05):** API keys in token-aggregation and root `.env.example` replaced with placeholders. `docs/TODO.md` and `smom-dbis-138/docs/TODO.md` created; smom-dbis-138 status-report links to `../tasks/TODO.md` fixed. RPC_ENDPOINTS_MASTER Sankofa section updated (sankofa.nexus → 7801/.51:3000, phoenix → 7800/.50:4000; the-order TBD). dbis_core nostro-vostro emergency hotline and example URLs set to "To be configured".

---

## 1. Security and secrets

### 1.1 API keys and secrets in `.env.example` (high)

| Location | Issue | Recommendation |
|----------|--------|-----------------|
| `smom-dbis-138/services/token-aggregation/.env.example` | `COINGECKO_API_KEY=CG-LxMsQ7jp3Jd6he3VFzP1uUXA` and `COINMARKETCAP_API_KEY=5fb006b25c3f44f394dc59e3d867f330` look like real keys | Replace with placeholders (e.g. `your-coingecko-api-key`, `your-cmc-api-key`). Rotate the keys if they were ever committed or shared. |
| `.env.example` (root) | `COINGECKO_API_KEY=CG-LxMsQ7jp3Jd6he3VFzP1uUXA` | Same as above; use a placeholder and document where to obtain keys. |

### 1.2 Other secret placeholders

- **Root `.env.example`:** Documents `PRIVATE_KEY`, `JWT_SECRET`, `NPM_PASSWORD`, Cloudflare, AWS, etc. with `your-*` placeholders — good. Ensure no real values are committed.
- **OMNIS/backend, dbis_core, the-order:** Use `your-*` or empty; keep examples placeholder-only and document in [MASTER_SECRETS_INVENTORY.md](04-configuration/MASTER_SECRETS_INVENTORY.md) or [API_KEYS_REQUIRED.md](../reports/API_KEYS_REQUIRED.md).

---

## 2. Configuration and DNS placeholders

### 2.1 Sankofa / The Order (TBD)

| Item | Location | Recommendation |
|------|----------|----------------|
| `the-order.sankofa.nexus` | [ALL_VMIDS_ENDPOINTS.md](04-configuration/ALL_VMIDS_ENDPOINTS.md), [RPC_ENDPOINTS_MASTER.md](04-configuration/RPC_ENDPOINTS_MASTER.md) | Marked TBD / not yet configured. Once The Order portal is deployed, add NPMplus proxy host and document IP:port in RPC_ENDPOINTS_MASTER and ALL_VMIDS_ENDPOINTS. |
| Sankofa cutover plan | [SANKOFA_CUTOVER_PLAN.md](04-configuration/SANKOFA_CUTOVER_PLAN.md) | Replace `<TARGET_IP>`, `<TARGET_PORT>`, and table TBDs with actual Sankofa service IPs/ports when deployed. |

### 2.2 sankofa.nexus placeholder routes

- **RPC_ENDPOINTS_MASTER:** `sankofa.nexus`, `phoenix.sankofa.nexus`, `the-order.sankofa.nexus` are documented as placeholders routing to Blockscout (192.168.11.140). ALL_VMIDS_ENDPOINTS shows sankofa/phoenix now point to 192.168.11.51 and 192.168.11.50. Keep RPC_ENDPOINTS_MASTER in sync with actual NPMplus routes and remove “placeholder (routes to Blockscout)” for sankofa.nexus / phoenix.sankofa.nexus if they now point to Sankofa/Phoenix.

### 2.3 Network / architecture placeholders

| Item | Location | Recommendation |
|------|----------|----------------|
| Public blocks #2–#6 | [NETWORK_ARCHITECTURE.md](02-architecture/NETWORK_ARCHITECTURE.md) | “Placeholders - To Be Configured”. Document when blocks are assigned or mark as reserved. |
| Blocks #2–#6 | [NETWORK_CONFIGURATION_MASTER.md](11-references/NETWORK_CONFIGURATION_MASTER.md) | “To be configured”. Same as above. |

---

## 3. Code placeholders and TODOs

### 3.1 smom-dbis-138

| Item | Location | Priority | Recommendation |
|------|----------|----------|----------------|
| AlltraAdapter fee | `contracts/bridge/adapters/evm/AlltraAdapter.sol` | Medium | `getBridgeFee()`: use configurable value (e.g. `setBridgeFee`); document in [PLACEHOLDERS_AND_TBD.md](PLACEHOLDERS_AND_TBD.md). Update with actual ALL Mainnet fee when known. |
| Smart accounts kit | `script/smart-accounts/DeploySmartAccountsKit.s.sol` | Medium | EntryPoint, AccountFactory, Paymaster from env; document required env in .env.example and deploy runbook. Deploy contracts and set env before production. |
| EnhancedSwapRouter | `contracts/bridge/trustless/EnhancedSwapRouter.sol` | Low | Uniswap quoter / Balancer: document when pools exist; keep “return 0” placeholder until integrated. |
| DODOPMMProvider | `contracts/liquidity/providers/DODOPMMProvider.sol` | Low | “For now, placeholder” — document oracle-driven flow and complete when DODO is integrated. |
| Quote service Fabric | `orchestration/bridge/quote-service.ts` | Low | `FABRIC_CHAIN_ID` env (default 999). Set real chain ID when Fabric is integrated. |
| register-all-mainnet avgBlockTime | [TEZOS_CCIP_REMAINING_ITEMS.md](07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md) | Low | Verify actual block time and set in script. |
| TezosRelayService | `services/tezos-relay/src/TezosRelayService.js` | Medium | “TODO: Perform actual Tezos mint/transfer”. Implement via Taquito or Tezos RPC; remove mock for production. |

### 3.2 dbis_core

| Item | Location | Recommendation |
|------|----------|----------------|
| as4-settlement | `src/core/settlement/as4-settlement/liquidity-limits.service.ts` | Implement “Check intraday/daily usage”, “Implement liquidity reservation”, “Implement liquidity release” or document as future work. |
| arbitrage monitoring | `src/core/defi/arbitrage/services/monitoring/metrics.service.ts` | “TODO: Integrate with Prometheus/StatsD” — add when monitoring stack is deployed. |
| risk-monitor | `src/core/defi/arbitrage/services/risk-monitor.service.ts` | “TODO: Integrate with real-time risk checks” — same as above. |
| cache.service | `src/core/defi/arbitrage/services/cache/cache.service.ts` | “TODO: Initialize Redis client”, “Implement pattern-based deletion” — implement or stub for tests. |
| alert.service | `src/core/defi/arbitrage/services/alert.service.ts` | “TODO: Implement actual PagerDuty API call” — implement or document workaround. |
| deal-execution integration tests | `__tests__/integration/deal-execution.integration.test.ts` | TODOs: DB persistence, metrics, risk monitoring, alerting, Redis, cache invalidation — implement or mark as skipped with ticket. |

### 3.3 OMNIS

| Item | Location | Recommendation |
|------|----------|----------------|
| Sankofa Phoenix SDK | `src/identity/sankofa-phoenix.ts`, `src/identity/authProvider.tsx`, `backend/src/controllers/authController.ts` | Multiple “TODO: Replace with actual Sankofa Phoenix SDK”. Integrate real SDK or document dependency and timeline. |
| authController | `backend/src/controllers/authController.ts` | “Implement token blacklisting if needed” — decide and implement or document. |
| BudgetForm, MilestoneForm, AccountForm | `src/components/*.tsx` | “Implement actual … API call” — wire to backend APIs. |
| DocumentUpload | `src/components/DocumentUpload.tsx` | “Implement actual file upload to backend” — implement upload endpoint and client. |
| ProfileEditForm | `src/components/ProfileEditForm.tsx` | “Call backend API to persist profile changes” — implement. |
| CI/CD and deploy | `.github/workflows/*.yml`, `scripts/deploy.sh` | “TODO: Replace with actual Sankofa Phoenix deployment” / “Add database migration” / “Add health check” — add real deployment and health steps. |

### 3.4 the-order (legal-documents)

| Item | Location | Recommendation |
|------|----------|----------------|
| court-efiling | `services/legal-documents/src/services/court-efiling.ts` | “TODO: Integrate with actual court e-filing system” and status/config queries — implement or document vendor. |
| e-signature | `services/legal-documents/src/services/e-signature.ts` | “TODO: Integrate with e-signature provider” and status/webhook — implement or document provider. |
| document-security | `services/legal-documents/src/services/document-security.ts` | “TODO: Fetch PDF, apply watermark/redactions, re-upload” — implement or document. |

### 3.5 Other code TODOs

| Item | Location | Recommendation |
|------|----------|----------------|
| NPMplus HA alert | `scripts/npmplus/monitor-ha-status.sh` | “TODO: Send alert (email, webhook)” — add notification (e.g. mail or webhook). |
| Storage monitor | `scripts/storage-monitor.sh` | “TODO: Add email/Slack/webhook notifications” — add alerting. |
| CCIPLogger | [CONTRACTS_TO_DEPLOY.md](11-references/CONTRACTS_TO_DEPLOY.md) | “Placeholder (not implemented in script)” — implement or remove from list. |

---

## 4. Documentation and link gaps

### 4.1 Broken or missing TODO links

| Issue | Location / report | Recommendation |
|-------|-------------------|----------------|
| ~~Broken link to `docs/TODO.md`~~ | Fixed | **Done:** [docs/TODO.md](TODO.md) created (points to 00-meta/TODO_TASK_LIST_MASTER + smom-dbis-138). [smom-dbis-138/docs/TODO.md](../smom-dbis-138/docs/TODO.md) created; status-reports links updated to `../tasks/TODO.md`. |
| the-order `REMAINING_TODOS.md` | Same report | Create or archive and fix links. |

### 4.2 Example / contact placeholders

| Item | Location | Recommendation |
|------|----------|----------------|
| ~~Emergency hotline~~ | [dbis_core/docs/nostro-vostro/api-reference.md](../dbis_core/docs/nostro-vostro/api-reference.md), [cb-implementation-guide.md](../dbis_core/docs/nostro-vostro/cb-implementation-guide.md) | Replace `+1-XXX-XXX-XXXX` with real emergency contact or “To be configured”. |
| API base URLs | dbis_core nostro-vostro docs | `https://api.scb.example.com`, `https://api.example.com` — replace with real base URL or document as template. |
| Proxmox/smom-dbis-138-proxmox | [smom-dbis-138-proxmox/README.md](../smom-dbis-138-proxmox/README.md) | `PROXMOX_HOST="proxmox.example.com"`, `PROXMOX_TOKEN_SECRET="your-token-secret"` — keep as placeholder; document in deployment guide. |

---

## 5. Token aggregation and canonical data

| Item | Location | Recommendation |
|------|----------|----------------|
| Canonical addresses env-only | [REQUIRED_FIXES_UPDATES_GAPS.md](REQUIRED_FIXES_UPDATES_GAPS.md) §3 | All token addresses from env; unset tokens omitted. Document required env vars in token-aggregation README and .env.example (e.g. which `*_ADDRESS_138` / `*_ADDRESS_651940` are required for report). |
| CoinGecko/CMC chain support | token-aggregation adapters | ChainId 138 and 651940 not supported by CoinGecko/CMC; external price/volume empty. Document in report API; consider alternative price source or CMC/CoinGecko submission for custom chains. |

---

## 6. Tezos / Etherlink / CCIP

| Item | Location | Recommendation |
|------|----------|----------------|
| Etherlink finality | [TEZOS_CCIP_REMAINING_ITEMS.md](07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md) | Set confirmation blocks in relay/DON config when decided; document in TEZOS_CROSS_CHAIN_FINALITY. |
| Route planner TBD | [TEZOS_USDTZ_IMPLEMENTATION_ROADMAP.md](11-references/TEZOS_USDTZ_IMPLEMENTATION_ROADMAP.md) | Replace “TBD” bridge provider in route-routes and route-planner with `eth2tz[0]?.provider ?? 'TBD'` or real provider. |
| Placeholder wallet / tx hashes | Same doc | Do not use placeholder wallet or tx hashes in production; use real signer and `adapter.sendTransaction` results. |

---

## 7. Operational and runbook gaps

| Item | Location | Recommendation |
|------|----------|----------------|
| NPMplus HA (Keepalived / secondary) | [PHASES_AND_TASKS_MASTER.md](00-meta/PHASES_AND_TASKS_MASTER.md), [NPMPLUS_HA_SETUP_GUIDE.md](04-configuration/NPMPLUS_HA_SETUP_GUIDE.md) | Optional, pending. Implement Keepalived or HAProxy and document failover; update OPERATIONAL_RUNBOOKS with NPMplus HA failover steps. |
| UDM Pro VLAN / VLAN-aware bridge | NEXT_STEPS_MASTER, PHASES_AND_TASKS_MASTER | Optional. Document when VLAN migration is planned; update NETWORK_ARCHITECTURE when done. |
| Automated backups | TODO_TASK_LIST_MASTER | NPMplus backup (NPM_PASSWORD); ensure backup-npmplus.sh is scheduled and verified. |
| verify-backend-vms TBD paths | VERIFICATION_GAPS_AND_TODOS | Marked resolved (10130, 2400); if new VMIDs need nginx checks, add paths to script. |

---

## 8. Summary of recommendations by priority

### High (security and correctness)

1. **Replace real-looking API keys** in `smom-dbis-138/services/token-aggregation/.env.example` and root `.env.example` with placeholders; rotate any exposed keys.
2. **Sankofa cutover:** Replace `<TARGET_IP>`, `<TARGET_PORT>`, and TBDs in SANKOFA_CUTOVER_PLAN when services are deployed.
3. **the-order.sankofa.nexus:** Configure in NPMplus and docs when The Order portal is deployed.
4. **TezosRelayService:** Implement real Tezos mint/transfer or clearly document mock and timeline.

### Medium (product and ops)

5. **Smart accounts:** Deploy EntryPoint, AccountFactory, Paymaster; set env; document in runbook and .env.example.
6. **AlltraAdapter fee:** Confirm ALL Mainnet fee and set via `setBridgeFee` (or config); document.
7. **OMNIS Sankofa Phoenix:** Integrate SDK or document dependency and roadmap.
8. **dbis_core:** Redis cache, PagerDuty alert, as4 liquidity reservation/release — implement or document.
9. ~~**Broken TODO links**~~ **Done:** docs/TODO.md and smom-dbis-138/docs/TODO.md added; status-report links fixed.
10. **NPMplus HA:** Implement and document failover; add alerting in monitor-ha-status.sh and storage-monitor.sh.

### Low (polish and future work)

11. **EnhancedSwapRouter / DODOPMMProvider / quote-service Fabric:** Document placeholders; complete when pools/Fabric are available.
12. **Network blocks #2–#6:** Document when assigned or keep as “reserved”.
13. **Canonical token env:** Document required token address env vars for token-aggregation report.
14. ~~**Example URLs and emergency contact**~~ **Done:** Emergency hotline and support URLs set to "To be configured" in dbis_core nostro-vostro docs.
15. **the-order legal-documents:** Court e-filing, e-signature, document-security — implement or document vendor/roadmap.

---

## 9. Where to track and update

- **Fixes and code placeholders:** [REQUIRED_FIXES_UPDATES_GAPS.md](REQUIRED_FIXES_UPDATES_GAPS.md), [PLACEHOLDERS_AND_TBD.md](PLACEHOLDERS_AND_TBD.md)
- **Verification and config gaps:** [04-configuration/VERIFICATION_GAPS_AND_TODOS.md](04-configuration/VERIFICATION_GAPS_AND_TODOS.md)
- **Improvements and optional work:** [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](ALL_IMPROVEMENTS_AND_GAPS_INDEX.md), [00-meta/NEXT_STEPS_MASTER.md](00-meta/NEXT_STEPS_MASTER.md), [00-meta/TODO_TASK_LIST_MASTER.md](00-meta/TODO_TASK_LIST_MASTER.md)
- **Optional index:** [OPTIONAL_RECOMMENDATIONS_INDEX.md](OPTIONAL_RECOMMENDATIONS_INDEX.md)

Update this document when closing gaps or when new placeholders are introduced.