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.