proxmox/docs/00-meta/DOTENV_AND_MARKDOWN_AUDIT_GAPS_AND_RECOMMENDATIONS.md

# Dotenv & Markdown Audit — Required Info, Gaps, and Recommendations

**Last Updated:** 2026-03-06  
**Purpose:** Single audit of (1) required information in dotenv and markdown files, (2) next steps completed in this run, (3) gaps found, (4) additional recommendations.

**Sources:** DOTENV_FILES_REFERENCE.md, ENV_EXAMPLE_CONTENT.md, REMAINING_ITEMS_DOTENV_AND_ACTIONS.md, OPERATOR_CREDENTIALS_CHECKLIST.md, PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST.md, NEXT_STEPS_LIST.md, EXECUTION_CHECKLIST_MULTIPLE_ROUTES_AND_LIQUIDITY.md, .env.master.example, smom-dbis-138/env.additions.example.

---

## 1. Required information — dotenv

### 1.1 Repo root `.env` (from .env.master.example / DOTENV_FILES_REFERENCE)

| Variable / group | Required for | Notes |
|------------------|--------------|--------|
| **NPM_*** (NPM_URL, NPM_EMAIL, NPM_PASSWORD) | NPMplus backup, 502 fix, operator scripts | Operator scripts load via load-project-env.sh |
| **PROXMOX_*** | Proxmox API, VM/CT creation | ML110, R630-01, R630-02 hosts |
| **RPC_URL_138** | Chain 138 scripts when run from root | Prefer `http://192.168.11.211:8545` for deploy |
| **CLOUDFLARE_*** | Tunnels, DNS | Optional for many flows |
| **GITEA_TOKEN** | push-to-gitea, gitea-create-orgs-and-repos | When using Gitea automation |
| **COINGECKO_API_KEY**, **ETHERSCAN_API_KEY** | Token aggregation, verification | Optional; improves price/verify |

### 1.2 smom-dbis-138 `.env` (single source for deploy, relay, token-aggregation, frontend)

| Variable / group | Required for | Notes |
|------------------|--------------|--------|
| **PRIVATE_KEY** | Deploy, bridge send, forge script | 64-char hex; same wallet holds LINK for CCIP fees |
| **RPC_URL_138** | Deploy, verify, on-chain checks | Use IP:port for deploy: `http://192.168.11.211:8545` |
| **ETH_MAINNET_RPC_URL** / **ETHEREUM_MAINNET_RPC** | Mainnet verify, CCIP, relay | Infura/Alchemy |
| **CCIPWETH9_BRIDGE_CHAIN138**, **CCIPWETH10_BRIDGE_CHAIN138** | Bridge scripts, token-aggregation, routing | Canonical: WETH9 `0x9cba0D04Ae5f6f16e3C599025aB97a05c4A593d5`; WETH10 see §3 gap |
| **CHAIN_138_DODO_PMM_INTEGRATION** | Token-aggregation indexer, quotes | `0x79cdbaFBaA0FdF9F55D26F360F54cddE5c743F7D` |
| **CUSDT_ADDRESS_138**, **CUSDC_ADDRESS_138** | Scripts, token-aggregation | Canonical in EXPLORER_TOKEN_LIST_CROSSCHECK §5 |
| **DATABASE_URL** | Token-aggregation DB, migrations | When using PostgreSQL (e.g. VMID 5000) |
| **CRONOS_RPC**, **CELO_RPC**, **WEMIX_RPC**, **GNOSIS_RPC** | complete-config-ready-chains, deployer-gas | Celo: CELO_RPC; Wemix: WEMIX_RPC; etc. |
| **CCIPWETH9_BRIDGE_CELO**, **CCIPWETH10_BRIDGE_CELO**, etc. | complete-config-ready-chains (inbound) | Set after deploying bridges on each chain |
| **BRIDGE_REGISTRY_ADDRESS** | QuoteService, POST /api/bridge/quote | Deploy BridgeRegistry then set |
| **LINK_TOKEN** / **CCIP_FEE_TOKEN** | CCIP fees | Deployer must hold LINK and approve bridge |

### 1.3 Markdown docs that specify required env

| Doc | Key requirement |
|-----|------------------|
| OPERATOR_CREDENTIALS_CHECKLIST | PRIVATE_KEY, RPC_URL_138, NPM_PASSWORD, LAN; per-task table |
| REMAINING_ITEMS_DOTENV_AND_ACTIONS | GITEA_TOKEN; PRIVATE_KEY + RPC + CCIP/LINK in smom-dbis-138/.env |
| CONFIG_READY_CHAINS_COMPLETION_RUNBOOK | CCIPWETH9/10 per chain; CHAIN138_SELECTOR; PRIVATE_KEY |
| DEPLOYER_GAS_AUTO_ROUTE_RUNBOOK | deployer-gas-routes.json; Protocolink/manual per chain |
| ENV_EXAMPLE_CONTENT | Full list RPCs, API keys, C* addresses, bridge addresses |

---

## 2. Required information — markdown (next steps, checklists)

### 2.1 Next-step docs and their “required info”

| Doc | Required info / gates |
|-----|------------------------|
| **NEXT_STEPS_LIST** | B.1/B.2: CRO, WEMIX; B.3: LINK/gas; A2: CHAIN_138_DODO_PMM_INTEGRATION; C3: BRIDGE_REGISTRY_ADDRESS |
| **EXECUTION_CHECKLIST_MULTIPLE_ROUTES_AND_LIQUIDITY** | Prereqs 1.1–1.4; Phase A–C; SBS.1: BRIDGE_REGISTRY_ADDRESS; Phase B: per-chain RPC + gas |
| **TODOS_CONSOLIDATED** | 0a/0b/0c: RPC_URL_138, PRIVATE_KEY; V4: Wemix/Cronos/Celo bridge env; V5: LINK |
| **OPERATOR_READY_CHECKLIST** | NPM_PASSWORD (backup); RPC_URL_138 (verify); PRIVATE_KEY (deploy); per-chain RPC for config-ready |
| **STILL_NOT_DONE_EXECUTION_CHECKLIST** | Same as above; external/third-party items (Ledger, CMC, etc.) |

### 2.2 Docs that reference .env but do not list every variable

- MASTER_INDEX, ADDITIONAL_PATHS_AND_EXTENSIONS, PHASE_C runbook, FUNDING_AND_DEPLOYMENT_CHECKLIST — refer to DOTENV_FILES_REFERENCE or env.additions.example for full lists.

---

## 3. Run completed (2026-03-06)

| Task | Result |
|------|--------|
| **validate-config-files.sh** | ✅ Passed |
| **run-completable-tasks-from-anywhere.sh** | ✅ Passed (config, on-chain 59/59, validation --skip-genesis, reconcile output printed) |
| **check-pmm-pool-balances-chain138.sh** | ✅ Pool 1: 2M cUSDT / 2M cUSDC; Pools 2–3 empty (expected) |
| **deployer-gas-auto-route.sh --dry-run** | ✅ Ran; 6 chains need gas (1, 56, 10, 42161, 8453, 25); Celo/Wemix/651940/42793 “no RPC configured” if RPC not in env |

---

## 4. Gaps found

### 4.1 Address / config consistency

| Gap | Location | Recommendation |
|-----|----------|----------------|
| **CCIPWETH10 on Chain 138** | CONTRACT_ADDRESSES_REFERENCE.md: `0xe0E93247376aa097dB308B92e6Ba36bA015535D0`. Reconcile script / some code may output `0xF5a87528cEb72312979DB0C51509489caF940721`. routing-registry.json and cross-chain-bridges use `0xe0E932...`. | Verify on Blockscout which contract is the active CCIP WETH10 bridge; align reconcile script and env.additions.example to that address. |
| **CCIPWETH9 on Chain 138** | Docs mention both `0x971cD9...` and `0x9cba0D04...`. On-chain check and routing-registry use `0x9cba0D04...`. | Treat `0x9cba0D04Ae5f6f16e3C599025aB97a05c4A593d5` as canonical for “working” WETH9 bridge; document the other in CONTRACT_ADDRESSES_REFERENCE as alternate/deploy if applicable. |

### 4.2 Missing or placeholder env

| Gap | Recommendation |
|-----|----------------|
| **Inbound routing-registry** | Inbound routes (dest→138) use bridge address `0x0` with a note. Populate from .env per chain (e.g. MAINNET_CCIP_WETH9_BRIDGE) when available, or document in DEPLOYMENT_DATA_SOURCES_INDEX. |
| **BRIDGE_REGISTRY_ADDRESS** | Not set; SBS and QuoteService require it. Deploy BridgeRegistry (script/bridge/interop/DeployBridgeRegistry or deploy-bridge-contracts.sh) and set in smom-dbis-138/.env. |
| **Celo/Wemix/651940/42793 RPC** | deployer-gas-auto-route reports “no RPC configured” when CELO_RPC, WEMIX_RPC, etc. are unset. Add to smom-dbis-138/.env or deployer-gas script env when using those chains. |

### 4.3 Documentation

| Gap | Recommendation |
|-----|----------------|
| **REMAINING_ITEMS_DOTENV_AND_ACTIONS** | Dated 2026-02-08; references archived CONTINUE_AND_COMPLETE. Update “Run order” to point to EXECUTION_CHECKLIST_MULTIPLE_ROUTES_AND_LIQUIDITY and NEXT_STEPS_LIST. |
| **PLACEHOLDERS_AND_REQUIRED_ADDITIONS_LIST** | Dated 2026-02-05. Refresh “Required additions — operator / environment” to align with OPERATOR_READY_CHECKLIST and NEXT_STEPS_LIST (e.g. B.1/B.2/B.3, C3). |
| **Single “required secrets” list** | OPERATOR_CREDENTIALS_CHECKLIST, REMAINING_ITEMS_DOTENV_AND_ACTIONS, and DOTENV_FILES_REFERENCE overlap. Add a single “Required secrets for operator” section in OPERATOR_CREDENTIALS_CHECKLIST that links to DOTENV_FILES_REFERENCE for full lists. |

### 4.4 Blocked / external

| Gap | Notes |
|-----|--------|
| **B.1 Cronos** | Needs ~15 CRO; use acquire-cro-and-wemix-gas.sh for aggregator links. |
| **B.2 Wemix** | Needs ~0.4 WEMIX; see WEMIX_ACQUISITION_TABLED. |
| **B.3 Fund CCIP LINK** | fund-ccip-bridges-with-link.sh; blocked by LINK/gas per lane. |
| **SBS.1** | Blocked by BRIDGE_REGISTRY_ADDRESS (deploy BridgeRegistry). |

---

## 5. Additional recommendations

### 5.1 Dotenv and config

1. **Single .env.example for smom-dbis-138:** ENV_EXAMPLE_CONTENT.md is the canonical content; ensure smom-dbis-138 has a single .env.example (or symlink) that matches it and env.additions.example so operators have one place to copy.
2. **ROUTING_REGISTRY_JSON_PATH:** Document in DOTENV_FILES_REFERENCE (token-aggregation) that optional ROUTING_REGISTRY_JSON_PATH overrides path to config/routing-registry.json.
3. **LIFI_* / JUMPER_*:** Already in env.additions.example; add to ENV_EXAMPLE_CONTENT or DOTENV_FILES_REFERENCE if QuoteService is the primary bridge-quote entry point.

### 5.2 Markdown and runbooks

4. **Execution order:** In EXECUTION_CHECKLIST and NEXT_STEPS_LIST, add one-line “Blocked by” for each blocked step (e.g. B.1: “Blocked by: CRO”; SBS.1: “Blocked by: BRIDGE_REGISTRY_ADDRESS”).
5. **Reconcile script output:** Script that prints “canonical Chain 138 addresses” should take CONTRACT_ADDRESSES_REFERENCE (or a single JSON) as source of truth so CCIPWETH9/10 and others stay in sync.
6. **Deployer-gas RPC:** Document in DEPLOYER_GAS_AUTO_ROUTE_RUNBOOK that CELO_RPC, WEMIX_RPC, RPC_URL_651940, and RPC_URL_42793 (or equivalent) are read when present for balance/route display.

### 5.3 Operational

7. **NPMplus backup:** Run when NPM_PASSWORD is set: `./scripts/run-all-operator-tasks-from-lan.sh` (optionally `--skip-backup` if not needed).
8. **Periodic checks:** Schedule validate-config-files.sh and check-pmm-pool-balances-chain138.sh (e.g. weekly) to catch config drift and pool balance changes.
9. **Phase C deployment-status:** When cW* or edge pools are deployed, update cross-chain-pmm-lps/config/deployment-status.json and env so QuoteService and runbooks stay accurate.

### 5.4 Code/configuration

10. **Token-aggregation registry path:** cross-chain-bridges.ts tries several paths for routing-registry.json; document in token-aggregation README that when run from monorepo root, config/ is resolved from cwd.
11. **Inbound bridge addresses:** Add a small table or JSON snippet in DEPLOYED_TOKENS_BRIDGES_LPS_AND_ROUTING_STATUS or CONTRACT_ADDRESSES_REFERENCE listing “Inbound bridge (source chain)” per chain (1, 56, 137, …) so operators know which env var fills routing-registry inbound.

---

## 6. Quick reference — where to set what

| Goal | Where to set | Doc |
|------|--------------|-----|
| Operator (LAN) tasks | Root .env: NPM_*; smom-dbis-138/.env: PRIVATE_KEY, RPC_URL_138 | OPERATOR_CREDENTIALS_CHECKLIST |
| Deploy / bridge (138) | smom-dbis-138/.env: PRIVATE_KEY, RPC_URL_138, CCIP*, LINK | ENV_EXAMPLE_CONTENT, REMAINING_ITEMS_DOTENV_AND_ACTIONS |
| Token-aggregation | smom-dbis-138/.env: CHAIN_138_DODO_PMM_INTEGRATION, RPC, DATABASE_URL | DOTENV_FILES_REFERENCE |
| Config-ready chains (Celo, Cronos, Wemix, Gnosis) | smom-dbis-138/.env: *_RPC, CCIPWETH9_BRIDGE_*, CCIPWETH10_BRIDGE_* | CONFIG_READY_CHAINS_COMPLETION_RUNBOOK |
| Bridge quote API (SBS) | smom-dbis-138/.env: BRIDGE_REGISTRY_ADDRESS | EXECUTION_CHECKLIST SBS.1, env.additions.example |
| Full env template | .env.master.example (root); smom-dbis-138/env.additions.example | MASTER_SECRETS, DOTENV_FILES_REFERENCE |

---

## 7. Summary

- **Required info:** Concentrated in root `.env` (NPM, Proxmox, RPC_URL_138) and **smom-dbis-138/.env** (PRIVATE_KEY, RPC_URL_138, CCIP bridges, DODO PMM, optional DATABASE_URL, per-chain RPC/bridges). Markdown checklists reference these; DOTENV_FILES_REFERENCE and ENV_EXAMPLE_CONTENT are the most complete.
- **Completed this run:** Config validation ✅, completable tasks ✅, PMM pool check ✅ (Pool 1 at 2M/2M), deployer-gas dry-run ✅.
- **Completed (2026-03-06):** Reconcile script CCIPWETH10 aligned; deployer-gas RPC doc; token-aggregation README registry path; DEPLOYED_TOKENS inbound env table; OPERATOR_CREDENTIALS "Required secrets" link; PLACEHOLDERS refreshed; REMAINING_ITEMS run order; smom-dbis-138 README .env source; Blocked-by in EXECUTION_CHECKLIST.
- **Gaps remaining:** Inbound routing-registry 0x0 placeholders; BRIDGE_REGISTRY_ADDRESS unset; B.1/B.2/B.3/SBS.1 blocked by CRO/WEMIX/LINK/registry.
- **Recommendations done:** reconcile aligned; deployer-gas RPC; token-aggregation path; inbound table; smom-dbis-138 .env ref; PLACEHOLDERS/OPERATOR_CREDENTIALS updated. Pending: schedule periodic validation/pool checks; deployment-status.json when Phase C deploys. (Was: Single .env.example reference, reconcile script sourcing CONTRACT_ADDRESSES_REFERENCE, “Blocked by” in checklists, deployer-gas RPC docs, periodic validation and pool checks, deployment-status.json updates for Phase C.