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 0xcacfd227A040002e49e2e01626363071324f820a; WETH10 0xe0E93247376aa097dB308B92e6Ba36bA015535D0
CHAIN_138_DODO_PMM_INTEGRATION	Token-aggregation indexer, quotes	0x5BDc62f1ae7D630c37A8B363a1d49845356Ee72d
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. Older bootstrap defaults may still mention 0xF5a87528cEb72312979DB0C51509489caF940721, but the active routing registry and env-backed defaults now use 0xe0E932....	Keep 0xe0E93247376aa097dB308B92e6Ba36bA015535D0 as the canonical WETH10 bridge and update any remaining legacy bootstrap references if they resurface.
CCIPWETH9 on Chain 138	Docs mention both 0x971cD9... and 0xcacfd227.... On-chain check and routing-registry use 0xcacfd227....	Treat 0xcacfd227A040002e49e2e01626363071324f820a 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.