**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.
This document does not duplicate the full 139-item tables or every recommendation. It links to existing indexes by ID range and section and adds the protection-layer and admin-panel strategy.
---
## 1. Document and Index Consolidation
**Current state:** Tasks and recommendations are spread across many files. This Master Plan is the single entry point.
| 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) |
| **Remaining work (step-by-step)** | [REMAINING_WORK_DETAILED_STEPS.md](REMAINING_WORK_DETAILED_STEPS.md) | Wave 0–3, cron, API keys; "Can be accomplished now" list; 2026-02-05 completion note |
| Best practices checklist | [10-best-practices/IMPLEMENTATION_CHECKLIST.md](../10-best-practices/IMPLEMENTATION_CHECKLIST.md) | High / medium / low / quick wins |
| Placeholders and TBD | [PLACEHOLDERS_AND_TBD.md](../PLACEHOLDERS_AND_TBD.md), [PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md](PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md) | Per-component placeholders; required env, API keys, waves |
---
## 2. Protection Layer and Granular Admin Control Panels
**Goal:** Protect all tooling and infrastructure across every project and expose a full protection layer in granular admin control panels at all levels (human context, audit, trust boundaries).
### 2.1 Current state
| Component | Auth / protection | Gap |
|-----------|-------------------|-----|
| **dbis_core** | JWT + request signing, [admin-permission.middleware.ts](../../dbis_core/src/integration/api-gateway/middleware/admin-permission.middleware.ts), [AdminPermissionsService](../../dbis_core/src/core/admin/shared/admin-permissions.service.ts), SCB-scoped access | Strong; use as reference for central policy. |
| **smom-dbis-138/frontend-dapp** | [AdminPanel.tsx](../../smom-dbis-138/frontend-dapp/src/pages/AdminPanel.tsx) — RBAC, FunctionPermissions, AuditLogViewer, EmergencyControls; wallet/mainnet gating | Good; ensure it uses central permission and audit when Layer 1 exists. |
| **smom-dbis-138/orchestration/portal** | [auth.ts](../../smom-dbis-138/orchestration/portal/src/middleware/auth.ts) — `x-admin-token`, in-memory sessions | Weak; no central audit. Target: JWT + central permission + audit. |
| **multi-chain-execution** | [admin-routes.ts](../../multi-chain-execution/src/api/admin-routes.ts) — `ADMIN_API_KEY` / `x-admin-key` only | API key only. Target: JWT or client-credentials + audit. |
| **token-aggregation** | Token auth for admin routes | No user-level audit (ALL_IMPROVEMENTS #105). Target: JWT or federated + audit. |
| **OMNIS** | [AdminDashboard](../../OMNIS/src/pages/AdminDashboard.tsx), RoleManagement, role-based auth | Align with central permission when Layer 1 exists. |
| **explorer-monorepo** | Wallet auth + RequireTrack | Align with central permission when Layer 1 exists. |
| **Org** | New or extend DBIS global console | No single "who has what role across all projects" or global audit view | Add "Security and audit" section to [admin-console-frontend-plan.md](../../dbis_core/docs/admin-console-frontend-plan.md) Phase 4/6: global identity list, role matrix, central audit viewer (filter by project, service, user, action). |
| **Project** | smom-dbis-138 AdminPanel, DBIS/SCB consoles | dApp has RBAC and audit; DBIS console not yet built | Keep dApp as reference; ensure DBIS console (when built) uses same permission model and writes to same audit store. |
| **Service** | Orchestration portal, token-aggregation, multi-chain-execution | Portal: weak auth. Token-aggregation: auth for admin endpoints. Multi-chain: API key only. | (1) Replace portal auth with JWT + central permission + audit. (2) Add token-aggregation admin auth and audit. (3) Add multi-chain admin auth and audit. |
| **Infra** | Proxmox, MCP, scripts, configs | No identity or audit for script/MCP runs | Introduce "admin runner" or gateway: scripts and MCP calls go through it; identity + permission check; log to central audit. Document in this plan and [OPERATIONAL_RUNBOOKS.md](../03-deployment/OPERATIONAL_RUNBOOKS.md). |
### 2.5 Placeholders to resolve (protection context)
- **"Who asked what agent/tool to do what, when, outcome"** — Define schema and storage (e.g. in dbis_core or shared service) and document in this MASTER_PLAN and admin-console-frontend-plan.
- **Admin surfaces above** — All listed in table 2.2 with target "Use central JWT + permission + audit."
---
## 3. Gaps and Placeholders — Full List (Resolved into Actions)
Consolidated from [GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md](../GAPS_AND_RECOMMENDATIONS_CONSOLIDATED.md), [REQUIRED_FIXES_UPDATES_GAPS.md](../REQUIRED_FIXES_UPDATES_GAPS.md), [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md), and [NEXT_STEPS_MASTER.md](NEXT_STEPS_MASTER.md). Detailed tables stay in those docs; below are the resolution rules.
- **Secrets and API keys:** No real keys in `.env.example` (token-aggregation, root); use placeholders; document in [MASTER_SECRETS_INVENTORY.md](../04-configuration/MASTER_SECRETS_INVENTORY.md). Rotate any exposed keys.
- **Config/DNS TBDs:** the-order.sankofa.nexus, Sankofa cutover plan `<TARGET_IP>`, RPC_ENDPOINTS_MASTER placeholders — **When The Order / Sankofa deployed, update NPMplus and docs; remove TBD.**
- **Network placeholders:** Public blocks #2–#6 in [NETWORK_ARCHITECTURE.md](../02-architecture/NETWORK_ARCHITECTURE.md) — **Document when assigned or mark reserved.**
- **Code placeholders:** See Section 3.1 below (one-line resolution table).
- **Documentation placeholders:** Emergency hotline and example URLs in dbis_core nostro-vostro — Done ("To be configured"). the-order REMAINING_TODOS.md — **Create or archive and fix links.**
- **Token aggregation:** Canonical addresses env-only — **Document required env in README and .env.example.** CoinGecko/CMC chain support — **Document in report API.**
- **Tezos/Etherlink:** Per [TEZOS_CCIP_REMAINING_ITEMS.md](../07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md); add to execution as "External/contract/off-chain checklist."
### 3.1 Placeholders and TBDs — One-line resolution
| Item | Location | Resolution |
|------|----------|------------|
| API keys in .env.example | token-aggregation, root | Replace with placeholders; document in MASTER_SECRETS_INVENTORY; rotate if exposed. |
| the-order.sankofa.nexus | RPC_ENDPOINTS_MASTER, ALL_VMIDS_ENDPOINTS | When The Order portal deployed: add NPMplus proxy host and document IP:port. |
| Sankofa cutover plan TBDs | SANKOFA_CUTOVER_PLAN | Replace `<TARGET_IP>`, `<TARGET_PORT>` when Sankofa deployed. |
| sankofa.nexus / phoenix routes | RPC_ENDPOINTS_MASTER | Keep in sync with NPMplus; remove "placeholder (routes to Blockscout)" when pointing to Sankofa/Phoenix. |
| Public blocks #2–#6 | NETWORK_ARCHITECTURE, NETWORK_CONFIGURATION_MASTER | Document when assigned or mark reserved. |
| AlltraAdapter fee | AlltraAdapter.sol | Implement configurable setBridgeFee; document in PLACEHOLDERS_AND_TBD. Update when ALL Mainnet fee known. |
| Smart accounts kit | DeploySmartAccountsKit.s.sol | Deploy EntryPoint, AccountFactory, Paymaster; set env; document in runbook and .env.example. |
| TezosRelayService | TezosRelayService.js | Implement real Tezos mint/transfer via Taquito/RPC or document mock and timeline. |
| EnhancedSwapRouter / DODOPMMProvider | EnhancedSwapRouter.sol, DODOPMMProvider.sol | Document until integrated; complete when pools/DODO available. |
| quote-service Fabric chainId | quote-service.ts | Set FABRIC_CHAIN_ID env when Fabric integrated; document. |
| dbis_core TODOs | metrics, risk-monitor, cache, alert, as4 liquidity | Implement or document (Prometheus, Redis, PagerDuty, liquidity reservation/release). |
| OMNIS Sankofa Phoenix SDK | identity, authProvider, authController | Integrate real SDK or document dependency and timeline. |
| CCIPLogger | CONTRACTS_TO_DEPLOY | Implement or remove from list. |
| Canonical token env | token-aggregation | Document required token address env vars in README and .env.example. |
| CoinGecko/CMC chain support | token-aggregation adapters | Document in report API; consider alternative source or CMC/CoinGecko submission. |
| Etherlink finality, route TBD, placeholder wallet/tx | TEZOS_CCIP_REMAINING_ITEMS, TEZOS_USDTZ_IMPLEMENTATION_ROADMAP | Set confirmation blocks when decided; replace TBD provider; no placeholder wallet/tx in production. |
| NPMplus HA, UDM Pro VLAN | PHASES_AND_TASKS_MASTER, runbooks | Optional: implement and document failover; document VLAN when planned. |
| Emergency hotline, example URLs | dbis_core nostro-vostro docs | Done: set to "To be configured." |
---
## 4. Recommendations and Suggestions — Integrated into Phases
All recommendations from [ALL_IMPROVEMENTS_AND_GAPS_INDEX.md](../ALL_IMPROVEMENTS_AND_GAPS_INDEX.md) (items 1–139), [10-best-practices/IMPLEMENTATION_CHECKLIST.md](../10-best-practices/IMPLEMENTATION_CHECKLIST.md), [RECOMMENDATIONS_AND_SUGGESTIONS.md](../10-best-practices/RECOMMENDATIONS_AND_SUGGESTIONS.md), [DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md](DOCUMENTATION_ENHANCEMENTS_RECOMMENDATIONS.md), [ADDITIONAL_OPTIMIZATION_RECOMMENDATIONS.md](../../smom-dbis-138/docs/ADDITIONAL_OPTIMIZATION_RECOMMENDATIONS.md), [TEZOS_CCIP_REMAINING_ITEMS.md](../07-ccip/TEZOS_CCIP_REMAINING_ITEMS.md), [rpc-translator-138/ALL_RECOMMENDATIONS.md](../../rpc-translator-138/ALL_RECOMMENDATIONS.md), orchestration portal RECOMMENDATIONS_SUMMARY, and [06-besu/COMPLETE_RECOMMENDATIONS_SUMMARY.md](../06-besu/COMPLETE_RECOMMENDATIONS_SUMMARY.md) are mapped into the phased execution below. Reference by phase and item range (e.g. Proxmox high 1–11 → IMPLEMENTATION_CHECKLIST + ALL_IMPROVEMENTS §1).
---
## 5. Phased Execution Summary
**Phase 0 — Foundation (done):** Per [PHASES_AND_TASKS_MASTER.md](PHASES_AND_TASKS_MASTER.md) Phase 0.
### Phase 1 — Critical fixes and protection-layer foundation
| Step | Action | Doc reference |
|------|--------|----------------|
| 1.1 | Secrets and config: Replace real-looking API keys in .env.example with placeholders; rotate if exposed. Document in MASTER_SECRETS_INVENTORY. | GAPS_AND_RECOMMENDATIONS §1 |
| 1.2 | Central policy and audit: Define identity/permission model and audit schema (who, what, when, resource, outcome). Implement or extend in dbis_core (or dedicated service): permission check API, audit append API. Document here and in admin-console-frontend-plan. | This plan §2 |
| 1.3 | Admin auth alignment: Portal → JWT + central permission + audit. Token-aggregation → auth and audit for admin endpoints. Multi-chain-execution → JWT or client-credentials + audit. | ALL_IMPROVEMENTS #105; this plan §2.2 |
| 1.4 | Code placeholders (high/medium): AlltraAdapter fee (configurable); Smart accounts deploy and env; TezosRelayService real path or documented mock. | REQUIRED_FIXES; GAPS_AND_RECOMMENDATIONS §3 |
### Phase 4 — Granular admin panels and infra protection
| Step | Action | Doc reference |
|------|--------|----------------|
| 4.1 | Org-level panel: Global identity, role matrix, central audit viewer (filter by project/service/user/action). Add to admin-console-frontend-plan; implement when DBIS console is built. | admin-console-frontend-plan Phase 4/6 |
| 4.2 | Project-level panels: Ensure smom-dbis-138 AdminPanel and future DBIS/SCB consoles use central permission and audit. | This plan §2.4 |
| 4.3 | Service-level panels: Complete portal, token-aggregation, multi-chain auth and audit (from Phase 1.3); expose minimal "admin" or "security" view per service linking to central audit. | This plan §2.2, §2.4 |
| 4.4 | Infra-level panel: Design and document "admin runner" for scripts and MCP; who can run which script/MCP tool; all runs logged. Add infra admin view. Update OPERATIONAL_RUNBOOKS and this plan. | This plan §2.4; OPERATIONAL_RUNBOOKS |
### Phase 5 — Code quality, docs, and optional work
Use [PARALLEL_TASK_STRUCTURE.md](PARALLEL_TASK_STRUCTURE.md) for cohorts. Within Phase 1: 1.1 and 1.4 can run in parallel; 1.2 then 1.3 (auth depends on central policy). Phase 2 can be parallelized by team (observability vs security vs backups). Phase 4.1–4.4 can run in parallel after Phase 1.2–1.3 are done.
---
## 7. Success Criteria and Maintenance
- **Master Plan success:** (1) This MASTER_PLAN.md exists and is linked from MASTER_INDEX. (2) Every placeholder/TBD has a one-line resolution (Section 3.1). (3) Protection layer and admin panel levels are described and assigned to phases. (4) All 139 improvement items and all recommendation docs are referenced by phase/section without duplication.
- **Ongoing:** Update this plan when new gaps or recommendations are added; keep NEXT_STEPS_MASTER and ALL_IMPROVEMENTS as the detailed checklists; this plan remains the single entry point and strategy (protection layer + panels).
---
## 8. File and Reference Summary
| Purpose | Document |
|---------|----------|
| Single Master Plan | This file: [MASTER_PLAN.md](MASTER_PLAN.md) |
| **Blitzkrieg Super Pro Max** (token-and-bridge rollout, marching ants, all recommendations) | [BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md](BLITZKRIEG_SUPER_PRO_MAX_MASTER_PLAN.md) |
- **Orchestration portal:** JWT support in [auth.ts](../../smom-dbis-138/orchestration/portal/src/middleware/auth.ts) (Bearer + `ADMIN_JWT_SECRET` or `JWT_SECRET`). [central-audit.ts](../../smom-dbis-138/orchestration/portal/src/services/central-audit.ts) sends audit when `DBIS_CENTRAL_URL` and `ADMIN_CENTRAL_API_KEY` are set.
- **Token-aggregation:** [central-audit.ts](../../smom-dbis-138/services/token-aggregation/src/api/central-audit.ts) and calls in [admin.ts](../../smom-dbis-138/services/token-aggregation/src/api/routes/admin.ts) after each admin mutation.
- **Multi-chain-execution:** [central-audit.ts](../../multi-chain-execution/src/api/central-audit.ts) and audit calls in [admin-routes.ts](../../multi-chain-execution/src/api/admin-routes.ts). Optional `X-Admin-Subject` header for audit identity.
**Env vars:**
| Var | Where | Purpose |
|-----|--------|--------|
| `ADMIN_CENTRAL_API_KEY` | dbis_core, orchestration portal, token-aggregation, multi-chain-execution | Secret for service-to-service auth to Admin Central API |
| `DBIS_CENTRAL_URL` | orchestration portal, token-aggregation, multi-chain-execution | Base URL of dbis_core API (e.g. `https://dbis-api.d-bis.org`) |
| `ADMIN_JWT_SECRET` or `JWT_SECRET` | orchestration portal | Optional; when set, login issues JWT and Bearer is accepted |
Document in [MASTER_SECRETS_INVENTORY.md](../04-configuration/MASTER_SECRETS_INVENTORY.md) and keep values out of repo.
---
**Document Status:** Active
**Maintained By:** Infrastructure Team
**Review:** Update when new gaps or recommendations are added or items are completed.