Harden deployment env flows and surface external blockers

2026-04-22 14:47:52 -07:00
parent dc123ff647
commit d9a3053a58
19 changed files with 318 additions and 51 deletions
--- a/.env.master.example
+++ b/.env.master.example
@@ -20,6 +20,8 @@ PROXMOX_ALLOW_ELEVATED=
 # Prefer CLOUDFLARE_API_TOKEN scoped to Zone:DNS:Edit on the zones you use (avoid global Account API key when possible).
 # Bulk DNS script: scripts/update-all-dns-to-public-ip.sh — use --dry-run and --zone-only=sankofa.nexus (etc.) before wide updates.
 CLOUDFLARE_API_TOKEN=
+# Set to 1 if token has no DNS:Edit and you need Global API key for scripts/cloudflare/provision-d-bis-mail-dns-and-npmplus.sh etc.
+CLOUDFLARE_DNS_PREFER_GLOBAL_KEY=
 CLOUDFLARE_EMAIL=
 CLOUDFLARE_API_KEY=
 CLOUDFLARE_ZONE_ID=
@@ -42,6 +44,8 @@ CLOUDNS_AUTH_PASSWORD=
 # --- NPM / NPMplus ---
 # For scripts/verify/backup-npmplus.sh: NPM_EMAIL and NPM_PASSWORD are both required
 # (no in-script defaults); see AGENTS.md operator / backup row.
+# PMG (LXC 100) web UI — optional: run scripts/operator/sync-pmg-webui-password-to-dotenv.sh to pull from /root/PMG_WEBUI_password.txt
+PMG_WEBUI_PASSWORD=
 NPM_URL=
 NPM_EMAIL=
 NPM_PASSWORD=
@@ -96,9 +100,20 @@ AZURE_STORAGE_CONTAINER=

 # --- Blockchain / SMOM-DBIS-138 (use smom-dbis-138/.env for PRIVATE_KEY) ---
 PRIVATE_KEY=
+DEPLOYER_ADDRESS=
 RPC_URL_138=
 RPC_URL_138_PUBLIC=
 ETHEREUM_MAINNET_RPC=
+DBIS_CORE_URL=
+CC_PAYMENT_ADAPTERS_URL=
+CC_AUDIT_LEDGER_URL=
+CC_SHARED_EVENTS_URL=
+CC_SHARED_SCHEMAS_URL=
+FIN_GATEWAY_URL=
+ALLIANCE_ACCESS_URL=
+CHAIN138_CI_RPC_URL=
+ALL_MAINNET_RPC=
+CHAIN_651940_RPC_URL=
 CHAIN_1_UNISWAP_V2_FACTORY=0x5C69bEe701ef814a2B6a3EDD4B1652CB9cc5aA6f
 CHAIN_1_UNISWAP_V2_ROUTER=0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D
 CHAIN_1_UNISWAP_V2_START_BLOCK=0
@@ -129,7 +144,10 @@ CHAIN_8453_UNISWAP_V2_START_BLOCK=0
 CHAIN_42161_UNISWAP_V2_FACTORY=0x02a84c1b3BBD7401a5f7fa98a384EBC70bB5749E
 CHAIN_42161_UNISWAP_V2_ROUTER=0x8cFe327CEc66d1C090Dd72bd0FF11d690C33a2Eb
 CHAIN_42161_UNISWAP_V2_START_BLOCK=0
-CHAIN_651940_RPC_URL=
+# Optional / scaffold-only until Wemix UniV2 routing is promoted
+CHAIN_1111_UNISWAP_V2_FACTORY=
+CHAIN_1111_UNISWAP_V2_ROUTER=
+CHAIN_1111_UNISWAP_V2_START_BLOCK=0
 ETHERLINK_RPC_URL=
 TEZOS_RPC_URL=
 ETHERSCAN_API_KEY=
--- a/docs/03-deployment/EXTERNAL_DEPENDENCY_BLOCKERS.md
+++ b/docs/03-deployment/EXTERNAL_DEPENDENCY_BLOCKERS.md
@@ -0,0 +1,35 @@
+# External Dependency Blockers
+
+**Purpose:** Canonical list of delivery items that cannot be resolved by repo-only changes and must be satisfied by external implementation, deployment, or infrastructure provisioning.
+
+## Current blockers
+
+| Blocker ID | External dependency | Pass condition | Repo-side signal |
+|---|---|---|---|
+| `EXT-DBIS-CORE` | `dbis_core` deployment | `DBIS_CORE_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-CC-PAYMENT-ADAPTERS` | `cc-payment-adapters` implementation and hosting | `CC_PAYMENT_ADAPTERS_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-CC-AUDIT-LEDGER` | `cc-audit-ledger` implementation and hosting | `CC_AUDIT_LEDGER_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-CC-SHARED-EVENTS` | `cc-shared-events` implementation and hosting | `CC_SHARED_EVENTS_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-CC-SHARED-SCHEMAS` | `cc-shared-schemas` implementation and hosting | `CC_SHARED_SCHEMAS_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-FIN-GATEWAY` | FIN / Alliance Access gateway | `FIN_GATEWAY_URL` or `ALLIANCE_ACCESS_URL` is set and reachable | `scripts/verify/check-external-dependencies.sh` |
+| `EXT-CHAIN138-CI-RPC` | Chain 138 node reachable from CI runners | `CHAIN138_CI_RPC_URL` or `RPC_URL_138_PUBLIC` returns a block number | `scripts/verify/check-external-dependencies.sh` |
+
+## How to check
+
+Strict mode:
+
+```bash
+bash scripts/verify/check-external-dependencies.sh
+```
+
+Advisory mode:
+
+```bash
+bash scripts/verify/check-external-dependencies.sh --advisory
+```
+
+## Notes
+
+- These blockers are expected to remain unresolved until external systems are deployed or pointed at live instances.
+- Repo-side readiness scripts now surface these blockers explicitly instead of failing with generic env or connectivity errors.
+- `dbis_core` source exists in this workspace, but that does not satisfy `EXT-DBIS-CORE`; the blocker closes only when a live reachable instance exists.
--- a/docs/11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md
+++ b/docs/11-references/DEPLOYMENT_DATA_SOURCES_INDEX.md
@@ -1,9 +1,10 @@
 # Deployment Data Sources Index — Dotenv and Config Files

-**Last Updated:** 2026-02-27  
+**Last Updated:** 2026-04-22  
 **Purpose:** Index of files that contain or reference smart contract deployment addresses, RPC endpoints, or deployment configuration.

-**Deployer:** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`  
+**Primary deployer (smom / core scripts):** `0x4A666F96fC8764181194447A7dFdb7d471b301C8`  
+**Thirdweb / CREATE2 deploys:** `0xB2dEA0e264ddfFf91057A3415112e57A1a5Eac14` — contract txs submitted to **RPC VMID 2103** (`http://192.168.11.217:8545`); on-chain path is **CREATE2** via the singleton at `0x4e59b44847b379578588920ca78fbf26c0b4956c` (see [RPC_ENDPOINTS_MASTER.md](../04-configuration/RPC_ENDPOINTS_MASTER.md) § Active RPC nodes).  
 **Canonical contract list:** [DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md](DEPLOYER_CONTRACTS_INVENTORY_AND_VERIFICATION_STATUS.md) | [CONTRACT_ADDRESSES_REFERENCE.md](CONTRACT_ADDRESSES_REFERENCE.md)

 ---
@@ -13,7 +14,7 @@
 | File | Contains addresses? | Notes |
 |------|--------------------|--------|
 | **smom-dbis-138/.env** | Yes | Canonical for Chain 138: PRIVATE_KEY, RPC_URL_138, cUSDT/cUSDC/…, CCIP, DODO PMM, pools, TRANSACTION_MIRROR, vaults. Do not commit. |
-| **.env** (repo root) | Partial | RPC_URL_138, PRIVATE_KEY, ETHEREUM_MAINNET_RPC, CHAIN_651940_RPC_URL, API keys. |
+| **.env** (repo root) | Partial | RPC_URL_138, optional PRIVATE_KEY / DEPLOYER_ADDRESS, ETHEREUM_MAINNET_RPC, ALL_MAINNET_RPC, CHAIN_651940_RPC_URL, API keys. |

 ---

@@ -44,7 +45,8 @@

 ## 4. Script load order

- **scripts/lib/load-project-env.sh** — loads root .env, ip-addresses.conf, smom-dbis-138/.env.
+- **scripts/lib/load-project-env.sh** — loads root `.env`, `ip-addresses.conf`, `smom-dbis-138/.env`, derives `DEPLOYER_ADDRESS` from `PRIVATE_KEY`, and aliases `CHAIN_651940_RPC_URL <- ALL_MAINNET_RPC` when needed.
+- **smom-dbis-138/scripts/lib/deployment/dotenv.sh** — now mirrors the same deployer/all-mainnet fallbacks when `ENV_FILE` is not overriding the default load path.
 - **scripts/lib/load-contract-addresses.sh** — reads config/smart-contracts-master.json and contract-addresses.conf; .env overrides.

 ---
--- a/docs/11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md
+++ b/docs/11-references/TOKENS_DEPLOYER_DEPLOYED_ON_OTHER_CHAINS.md
@@ -136,8 +136,8 @@ The following items have been **brought within scope** and are implemented.

 ### 6.3 AUSDT and ALL Mainnet (651940) — **Implemented (env validation only)**

- **All-chains script:** Chain **651940** is in the chain list. The script does **not** deploy tokens on 651940; it only runs **env validation**: if `CHAIN_651940_RPC` is set, it checks/reminds to set `AUSDT_ADDRESS_651940` (ecosystem token; not deployed by this repo).
- **Env:** `CHAIN_651940_RPC` (or `ALL_MAINNET_RPC`), `AUSDT_ADDRESS_651940`.
+- **All-chains script:** Chain **651940** is in the chain list. The script does **not** deploy tokens on 651940; it only runs **env validation**: if `CHAIN_651940_RPC` or `CHAIN_651940_RPC_URL` is set, it checks/reminds to set `AUSDT_ADDRESS_651940` (ecosystem token; not deployed by this repo).
+- **Env:** `CHAIN_651940_RPC`, `CHAIN_651940_RPC_URL`, or `ALL_MAINNET_RPC`, plus `AUSDT_ADDRESS_651940`.

 ---

--- a/docs/MASTER_INDEX.md
+++ b/docs/MASTER_INDEX.md
@@ -26,6 +26,7 @@
 | **Source to CEX execution plan** | [03-deployment/SOURCE_TO_CEX_EXECUTION_PLAN.md](03-deployment/SOURCE_TO_CEX_EXECUTION_PLAN.md) — operator bridge, normalization, and exchange-handoff plan |
 | **Source to CEX production readiness** | [03-deployment/SOURCE_TO_CEX_PRODUCTION_READINESS.md](03-deployment/SOURCE_TO_CEX_PRODUCTION_READINESS.md) — repo-native readiness gate for immediate production |
 | **Immediate live production task list: source to CEX** | [03-deployment/IMMEDIATE_LIVE_PRODUCTION_TASK_LIST_SOURCE_TO_CEX.md](03-deployment/IMMEDIATE_LIVE_PRODUCTION_TASK_LIST_SOURCE_TO_CEX.md) — task list with remaining live blockers called out |
+| **External dependency blockers** | [03-deployment/EXTERNAL_DEPENDENCY_BLOCKERS.md](03-deployment/EXTERNAL_DEPENDENCY_BLOCKERS.md) — explicit list of items that cannot be closed by repo-only changes, with readiness checks and env knobs |
 | **Crypto.com OTC before vs after matrix** | [03-deployment/CRYPTO_COM_OTC_BEFORE_AFTER_OPERATOR_MATRIX.md](03-deployment/CRYPTO_COM_OTC_BEFORE_AFTER_OPERATOR_MATRIX.md) — strict operator comparison of the current ecosystem versus the state after a real Crypto.com OTC sink is connected |
 | **Provider-facing source to CEX package** | [03-deployment/PROVIDER_FACING_PACKAGE_SOURCE_TO_CEX.md](03-deployment/PROVIDER_FACING_PACKAGE_SOURCE_TO_CEX.md) — strict provider-facing package covering expectations, flow presentation, questions, and a first 30-day ramp plan |
 | **Mr. Promod Uniswap V2 liquidity program** | [03-deployment/PROMOD_UNISWAP_V2_LIQUIDITY_PROGRAM.md](03-deployment/PROMOD_UNISWAP_V2_LIQUIDITY_PROGRAM.md) — wrapped-depth-first Uniswap V2 rollout for cW* and cWAUSDT on bridged public networks |
--- a/scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh
+++ b/scripts/deployment/check-deployer-balance-chain138-and-funding-plan.sh
@@ -11,7 +11,20 @@

 set -euo pipefail

-DEPLOYER="${DEPLOYER_ADDRESS:-0x4A666F96fC8764181194447A7dFdb7d471b301C8}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT"
+
+if [[ -f "$PROJECT_ROOT/scripts/lib/load-project-env.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "$PROJECT_ROOT/scripts/lib/load-project-env.sh" >/dev/null 2>&1 || true
+fi
+
+DEPLOYER="${DEPLOYER_ADDRESS:-}"
+if [[ -z "$DEPLOYER" && -n "${PRIVATE_KEY:-}" ]]; then
+  DEPLOYER="$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || true)"
+fi
+DEPLOYER="${DEPLOYER:-0x4A666F96fC8764181194447A7dFdb7d471b301C8}"
 CHAIN138_PUBLIC_RPC_DEFAULT="https://rpc-http-pub.d-bis.org"
 RPC="${RPC_URL_138:-${CHAIN138_PUBLIC_RPC_URL:-$CHAIN138_PUBLIC_RPC_DEFAULT}}"

--- a/scripts/deployment/check-deployer-lp-balances.py
+++ b/scripts/deployment/check-deployer-lp-balances.py
@@ -135,8 +135,10 @@ def deployer_address(env: dict[str, str], override: str | None) -> str:
        v = (os.environ.get(k) or "").strip()
        if v:
            return v
-    pk = env.get("PRIVATE_KEY", "") or (os.environ.get("PRIVATE_KEY") or "").strip()
-    if pk:
+    for key in ("PRIVATE_KEY", "DEPLOYER_PRIVATE_KEY"):
+        pk = (os.environ.get(key) or env.get(key) or "").strip()
+        if not pk or "${" in pk:
+            continue
        r = subprocess.run(
            ["cast", "wallet", "address", pk],
            capture_output=True,
@@ -145,7 +147,7 @@ def deployer_address(env: dict[str, str], override: str | None) -> str:
        )
        if r.returncode == 0 and r.stdout.strip():
            return r.stdout.strip()
-    return (env.get("DEPLOYER_ADDRESS") or "").strip()
+    return (env.get("DEPLOYER_ADDRESS") or env.get("DEPLOYER") or "").strip()


 def parse_uint(s: str) -> int:
--- a/scripts/deployment/check-deployer-nonce-and-balance.sh
+++ b/scripts/deployment/check-deployer-nonce-and-balance.sh
@@ -18,12 +18,12 @@ PUBLIC_ETHEREUM_RPC="${ETHEREUM_MAINNET_PUBLIC_RPC:-https://ethereum-rpc.publicn
 PUBLIC_CRONOS_RPC="${CRONOS_MAINNET_PUBLIC_RPC:-https://evm.cronos.org}"
 PUBLIC_ARBITRUM_RPC="${ARBITRUM_MAINNET_PUBLIC_RPC:-https://arbitrum-one-rpc.publicnode.com}"

-DEPLOYER=""
-if [[ -n "${PRIVATE_KEY:-}" ]]; then
+DEPLOYER="${DEPLOYER_ADDRESS:-}"
+if [[ -z "$DEPLOYER" && -n "${PRIVATE_KEY:-}" ]]; then
  DEPLOYER=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || true)
 fi
 [[ -z "$DEPLOYER" ]] && {
-  echo "Could not derive deployer address. Set PRIVATE_KEY in ${PROJECT_ROOT}/.env, smom-dbis-138/.env, or ~/.secure-secrets/private-keys.env" >&2
+  echo "Could not derive deployer address. Set PRIVATE_KEY or DEPLOYER_ADDRESS in repo .env, smom-dbis-138/.env, or ~/.secure-secrets/private-keys.env" >&2
  exit 1
 }
 echo "Deployer address: $DEPLOYER"
--- a/scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
+++ b/scripts/deployment/deploy-transaction-mirror-and-pmm-pool-after-txpool-clear.sh
@@ -40,10 +40,15 @@ fi
 set -a
 source "$SMOM/.env"
 set +a
+if [[ -f "$SMOM/scripts/lib/deployment/dotenv.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "$SMOM/scripts/lib/deployment/dotenv.sh"
+  load_deployment_env --repo-root "$PROJECT_ROOT"
+fi

 # 2) RPC: Core (2101) only — no Public fallback for deployments
 RPC="${RPC_URL_138:-http://192.168.11.211:8545}"
-[[ -z "${PRIVATE_KEY:-}" ]] && echo "PRIVATE_KEY not set in $SMOM/.env. Abort." >&2 && exit 1
+require_private_key_env "Set PRIVATE_KEY in $SMOM/.env, repo .env, or ~/.secure-secrets/private-keys.env." || exit 1
 # Chain 138 gas: min 1 gwei; use GAS_PRICE from .env or default
 GAS_PRICE="${GAS_PRICE_138:-${GAS_PRICE:-1000000000}}"

@@ -73,7 +78,7 @@ else
 fi

 # 4) Always check deployer nonce (pending) and set NEXT_NONCE for scripts
-DEPLOYER=$(cast wallet address --private-key "$PRIVATE_KEY" 2>/dev/null) || { echo "cast wallet address failed. Check PRIVATE_KEY in .env." >&2; exit 1; }
+DEPLOYER="$(derive_deployer_address)" || { echo "Could not derive deployer address from PRIVATE_KEY." >&2; exit 1; }
 NONCE_PENDING=$(cast nonce "$DEPLOYER" --rpc-url "$RPC" --block pending 2>/dev/null) || true
 NONCE_LATEST=$(cast nonce "$DEPLOYER" --rpc-url "$RPC" --block latest 2>/dev/null) || true
 # Normalize: empty or non-numeric -> use latest, then 0; ensure decimal for export
--- a/scripts/deployment/deploy-transaction-mirror-chain138-nonce-fix.sh
+++ b/scripts/deployment/deploy-transaction-mirror-chain138-nonce-fix.sh
@@ -10,11 +10,17 @@ PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
 SMOM="${PROJECT_ROOT}/smom-dbis-138"
 NONCE="${1:-13370}"

-[[ -f "${SMOM}/.env" ]] && set -a && source "${SMOM}/.env" 2>/dev/null && set +a
+if [[ -f "${SMOM}/scripts/lib/deployment/dotenv.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "${SMOM}/scripts/lib/deployment/dotenv.sh"
+  load_deployment_env --repo-root "$PROJECT_ROOT"
+elif [[ -f "${SMOM}/.env" ]]; then
+  set -a && source "${SMOM}/.env" 2>/dev/null && set +a
+fi
 RPC="${RPC_URL_138:-${RPC_URL_138_PUBLIC:-http://192.168.11.221:8545}}"
-[[ -z "${PRIVATE_KEY:-}" ]] && echo "PRIVATE_KEY not set." >&2 && exit 1
-[[ "${PRIVATE_KEY#0x}" == "$PRIVATE_KEY" ]] && export PRIVATE_KEY="0x$PRIVATE_KEY"
-ADMIN="${MIRROR_ADMIN:-$(cast wallet address --private-key "$PRIVATE_KEY" 2>/dev/null)}"
+require_private_key_env "Set PRIVATE_KEY in smom-dbis-138/.env, repo .env, or ~/.secure-secrets/private-keys.env." || exit 1
+ADMIN="${MIRROR_ADMIN:-$(derive_deployer_address 2>/dev/null || true)}"
+[[ -n "$ADMIN" ]] || { echo "ERROR: Could not derive deployer address from PRIVATE_KEY." >&2; exit 1; }

 echo "Deploying TransactionMirror (nonce=$NONCE) to $RPC"
 cd "$SMOM"
--- a/scripts/deployment/deploy-transaction-mirror-chain138.sh
+++ b/scripts/deployment/deploy-transaction-mirror-chain138.sh
@@ -17,6 +17,11 @@ for a in "$@"; do [[ "$a" == "--dry-run" ]] && DRY_RUN=true && break; done

 [[ -f "${SCRIPT_DIR}/../lib/load-project-env.sh" ]] && source "${SCRIPT_DIR}/../lib/load-project-env.sh" 2>/dev/null || true
 [[ -f "${SMOM}/.env" ]] && set -a && source "${SMOM}/.env" 2>/dev/null && set +a || true
+if [[ -f "${SMOM}/scripts/lib/deployment/dotenv.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "${SMOM}/scripts/lib/deployment/dotenv.sh"
+  load_deployment_env --repo-root "$PROJECT_ROOT"
+fi

 # RPC_URL_138 or RPC_URL (alias)
 RPC="${RPC_URL_138:-${RPC_URL:-http://192.168.11.211:8545}}"
@@ -24,13 +29,8 @@ export RPC_URL_138="$RPC"
 export ETH_RPC_URL="$RPC"
 GAS_PRICE="${GAS_PRICE:-1000000000}"

-if ! $DRY_RUN && [[ -z "${PRIVATE_KEY:-}" ]]; then
-  echo "ERROR: PRIVATE_KEY not set. Set in smom-dbis-138/.env"
-  exit 1
-fi
-
-if [[ "${PRIVATE_KEY#0x}" == "$PRIVATE_KEY" ]]; then
-  export PRIVATE_KEY="0x$PRIVATE_KEY"
+if ! $DRY_RUN; then
+  require_private_key_env "Set PRIVATE_KEY in smom-dbis-138/.env, repo .env, or ~/.secure-secrets/private-keys.env." || exit 1
 fi
 export PRIVATE_KEY  # Ensure subshells/forge inherit it

@@ -38,7 +38,11 @@ export PRIVATE_KEY  # Ensure subshells/forge inherit it
 if [[ -n "${MIRROR_ADMIN:-}" ]]; then
  ADMIN="$MIRROR_ADMIN"
 else
-  if $DRY_RUN; then ADMIN="<DEPLOYER_ADDRESS>"; else ADMIN=$(cast wallet address --private-key "$PRIVATE_KEY" 2>/dev/null) || { echo "ERROR: cast not found or PRIVATE_KEY invalid"; exit 1; }; fi
+  if $DRY_RUN; then
+    ADMIN="<DEPLOYER_ADDRESS>"
+  else
+    ADMIN="$(derive_deployer_address)" || { echo "ERROR: Could not derive deployer address from PRIVATE_KEY." >&2; exit 1; }
+  fi
 fi

 if $DRY_RUN; then
--- a/scripts/deployment/preflight-chain138-deploy.sh
+++ b/scripts/deployment/preflight-chain138-deploy.sh
@@ -35,16 +35,19 @@ else
 fi

 # 3) Load env for RPC and nonce checks (no secrets printed)
-[[ -f "${PROJECT_ROOT}/config/ip-addresses.conf" ]] && source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
-set -a
-source "$SMOM/.env"
-set +a
+if [[ -f "$SMOM/scripts/lib/deployment/dotenv.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "$SMOM/scripts/lib/deployment/dotenv.sh"
+  load_deployment_env --repo-root "$PROJECT_ROOT"
+else
+  [[ -f "${PROJECT_ROOT}/config/ip-addresses.conf" ]] && source "${PROJECT_ROOT}/config/ip-addresses.conf" 2>/dev/null || true
+  set -a
+  source "$SMOM/.env"
+  set +a
+fi

 RPC="${RPC_URL_138:-http://192.168.11.211:8545}"
-if [[ -z "${PRIVATE_KEY:-}" ]]; then
-  echo "FAIL: PRIVATE_KEY not set in $SMOM/.env." >&2
-  exit 1
-fi
+require_private_key_env "Set PRIVATE_KEY in $SMOM/.env, repo .env, or ~/.secure-secrets/private-keys.env." || exit 1

 # 4) RPC: must be Core (chainId 138 = 0x8a)
 echo ""
@@ -62,7 +65,7 @@ fi
 echo "OK   RPC (Core): $RPC (chainId 138)."

 # 5) Nonce: warn if pending > latest (stuck txs)
-DEPLOYER=$(cast wallet address --private-key "$PRIVATE_KEY" 2>/dev/null) || { echo "FAIL: cast wallet address failed. Check PRIVATE_KEY in .env." >&2; exit 1; }
+DEPLOYER="$(derive_deployer_address)" || { echo "FAIL: Could not derive deployer address from PRIVATE_KEY." >&2; exit 1; }
 NONCE_PENDING=$(cast nonce "$DEPLOYER" --rpc-url "$RPC" --block pending 2>/dev/null) || true
 NONCE_LATEST=$(cast nonce "$DEPLOYER" --rpc-url "$RPC" --block latest 2>/dev/null) || true
 # Normalize to decimal (cast may return hex 0xN or decimal N)
--- a/scripts/lib/load-project-env.sh
+++ b/scripts/lib/load-project-env.sh
@@ -46,6 +46,16 @@ _lpr_dotenv_source() {
  fi
 }

+_lpr_export_from_private_key() {
+  [[ -n "${DEPLOYER_ADDRESS:-}" || -z "${PRIVATE_KEY:-}" ]] && return 0
+  command -v cast >/dev/null 2>&1 || return 0
+  local _lpr_addr
+  _lpr_addr="$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || true)"
+  [[ -n "$_lpr_addr" ]] || return 0
+  export DEPLOYER_ADDRESS="$_lpr_addr"
+  export DEPLOYER="${DEPLOYER:-$_lpr_addr}"
+}
+
 # Path validation
 [[ -d "$PROJECT_ROOT" ]] || err_exit "PROJECT_ROOT not a directory: $PROJECT_ROOT"
 [[ -f "${PROJECT_ROOT}/config/ip-addresses.conf" ]] || echo "WARN: config/ip-addresses.conf not found; using defaults" >&2
@@ -66,6 +76,9 @@ _lpr_dotenv_source "${PROJECT_ROOT}/smom-dbis-138/.env"
 KEEPER_SECRET_FILE="${KEEPER_SECRET_FILE:-${HOME}/.secure-secrets/chain138-keeper.env}"
 [[ -z "${KEEPER_PRIVATE_KEY:-}" ]] && [[ -f "${KEEPER_SECRET_FILE}" ]] && _lpr_dotenv_source "${KEEPER_SECRET_FILE}"

+# 3d. Normalize a deployer address for scripts that need a read-only owner identity.
+_lpr_export_from_private_key
+
 # 4. dbis_core config if present
 [[ -f "${PROJECT_ROOT}/dbis_core/config/dbis-core-proxmox.conf" ]] && _lpr_source_relaxed "${PROJECT_ROOT}/dbis_core/config/dbis-core-proxmox.conf" || true

@@ -124,6 +137,9 @@ export CHAIN138_RPC="$RPC_URL_138"
 export ETH_RPC_URL="${ETH_RPC_URL:-$RPC_URL_138}"
 export RPC_URL_138_PUBLIC="${RPC_URL_138_PUBLIC:-http://${RPC_PUBLIC_1}:8545}"
 export WS_URL_138_PUBLIC="${WS_URL_138_PUBLIC:-ws://${RPC_PUBLIC_1}:8546}"
+export CHAIN_651940_RPC_URL="${CHAIN_651940_RPC_URL:-${ALL_MAINNET_RPC:-}}"
+export CHAIN_651940_RPC="${CHAIN_651940_RPC:-${CHAIN_651940_RPC_URL:-${ALL_MAINNET_RPC:-}}}"
+export ALLTRA_MAINNET_RPC="${ALLTRA_MAINNET_RPC:-${ALL_MAINNET_RPC:-${CHAIN_651940_RPC_URL:-${CHAIN_651940_RPC:-}}}}"
 export SMOM_DIR="${SMOM_DBIS_138_DIR:-${PROJECT_ROOT}/smom-dbis-138}"
 export DBIS_CORE_DIR="${DBIS_CORE_DIR:-${PROJECT_ROOT}/dbis_core}"

--- a/scripts/mint-tokens-for-deployer.sh
+++ b/scripts/mint-tokens-for-deployer.sh
@@ -16,8 +16,11 @@ SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 cd "$PROJECT_ROOT"

-# Load smom-dbis-138 .env
-if [[ -f smom-dbis-138/.env ]]; then
+# Load normalized project env when available.
+if [[ -f scripts/lib/load-project-env.sh ]]; then
+    # shellcheck disable=SC1091
+    source scripts/lib/load-project-env.sh >/dev/null 2>&1 || true
+elif [[ -f smom-dbis-138/.env ]]; then
    set -a
    source smom-dbis-138/.env
    set +a
@@ -50,11 +53,13 @@ for a in "$@"; do
 done

 DEPLOYER=""
-if [[ -n "${PRIVATE_KEY:-}" ]]; then
+if [[ -n "${DEPLOYER_ADDRESS:-}" ]]; then
+    DEPLOYER="${DEPLOYER_ADDRESS}"
+elif [[ -n "${PRIVATE_KEY:-}" ]]; then
    DEPLOYER=$(cast wallet address --private-key "$PRIVATE_KEY" 2>/dev/null || true)
 fi
 if [[ -z "$DEPLOYER" ]]; then
-    DEPLOYER="${DEPLOYER_ADDRESS:-0x4A666F96fC8764181194447A7dFdb7d471b301C8}"
+    DEPLOYER="0x4A666F96fC8764181194447A7dFdb7d471b301C8"
 fi

 LINK_RAW="${AMOUNT_LINK}000000000000000000"   # 18 decimals
--- a/scripts/verify/build-liquidity-pools-master-map.py
+++ b/scripts/verify/build-liquidity-pools-master-map.py
@@ -38,6 +38,7 @@ RPC_DEFAULTS = {
    or "https://rpc-core.d-bis.org",
    "651940": os.environ.get("CHAIN_651940_RPC")
    or os.environ.get("CHAIN_651940_RPC_URL")
+    or os.environ.get("ALL_MAINNET_RPC")
    or os.environ.get("ALLTRA_MAINNET_RPC")
    or "https://mainnet-rpc.alltra.global",
    "1": os.environ.get("ETHEREUM_MAINNET_RPC") or "https://eth.llamarpc.com",
@@ -335,13 +336,15 @@ class PoolBuilder:
        quote_symbol = venue.get("quote")
        notes = list(venue.get("notes", []))
        if any(note in PLACEHOLDER_NOTES for note in notes):
-            status = "planned_reference_placeholder"
+            status = "documented_reference_surface"
        elif venue.get("live"):
            status = "live"
+        elif venue.get("protocol") == "1inch" and venue.get("supported"):
+            status = "documented_aggregator_surface"
        elif venue.get("supported"):
-            status = "supported_not_live"
+            status = "documented_reference_surface"
        else:
-            status = "unsupported"
+            status = "documented_unsupported_surface"
        return {
            "chainId": int(chain_id),
            "network": chain_data["name"],
--- a/scripts/verify/check-deployer-balance-blockscout-vs-rpc.sh
+++ b/scripts/verify/check-deployer-balance-blockscout-vs-rpc.sh
@@ -8,7 +8,20 @@

 set -euo pipefail

-DEPLOYER="${DEPLOYER_ADDRESS:-0x4A666F96fC8764181194447A7dFdb7d471b301C8}"
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+cd "$PROJECT_ROOT"
+
+if [[ -f "$PROJECT_ROOT/scripts/lib/load-project-env.sh" ]]; then
+  # shellcheck disable=SC1090
+  source "$PROJECT_ROOT/scripts/lib/load-project-env.sh" >/dev/null 2>&1 || true
+fi
+
+DEPLOYER="${DEPLOYER_ADDRESS:-}"
+if [[ -z "$DEPLOYER" && -n "${PRIVATE_KEY:-}" ]]; then
+  DEPLOYER="$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || true)"
+fi
+DEPLOYER="${DEPLOYER:-0x4A666F96fC8764181194447A7dFdb7d471b301C8}"
 RPC="${1:-${RPC_URL_138:-https://rpc-core.d-bis.org}}"
 EXPLORER_API="${2:-https://explorer.d-bis.org/api/v2}"

@@ -67,11 +80,13 @@ fi
 # --- 3. Compare ---
 echo ""
 if [ -n "$RPC_WEI" ] && [ -n "$BLOCKSCOUT_WEI" ]; then
-  if [ "$RPC_WEI" -ge "$BLOCKSCOUT_WEI" ]; then
-    DIFF=$((RPC_WEI - BLOCKSCOUT_WEI))
-  else
-    DIFF=$((BLOCKSCOUT_WEI - RPC_WEI))
-  fi
+  DIFF="$(python3 - "$RPC_WEI" "$BLOCKSCOUT_WEI" <<'PY'
+import sys
+rpc = int(sys.argv[1])
+blockscout = int(sys.argv[2])
+print(abs(rpc - blockscout))
+PY
+)"
  if [ "$DIFF" -le 1 ]; then
    echo "Match: RPC and Blockscout balances match (diff <= 1 wei)."
  else
--- a/scripts/verify/check-external-dependencies.sh
+++ b/scripts/verify/check-external-dependencies.sh
@@ -0,0 +1,130 @@
+#!/usr/bin/env bash
+# Check external dependencies that cannot be satisfied by repo-only changes.
+# Default: fail when any external blocker is unresolved.
+# Use --advisory to always exit 0 while still printing blocker status.
+
+set -euo pipefail
+
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+if [[ -f "$PROJECT_ROOT/scripts/lib/load-project-env.sh" ]]; then
+  # shellcheck disable=SC1091
+  source "$PROJECT_ROOT/scripts/lib/load-project-env.sh"
+fi
+
+ADVISORY=0
+[[ "${1:-}" == "--advisory" ]] && ADVISORY=1
+
+PASS_COUNT=0
+FAIL_COUNT=0
+
+log_ok() { printf '[OK] %s\n' "$1"; }
+log_block() { printf '[BLOCKED] %s\n' "$1"; }
+
+record_pass() {
+  PASS_COUNT=$((PASS_COUNT + 1))
+  log_ok "$1"
+}
+
+record_fail() {
+  FAIL_COUNT=$((FAIL_COUNT + 1))
+  log_block "$1"
+}
+
+http_ok() {
+  local url="$1"
+  curl -fsS -m 8 -o /dev/null "$url"
+}
+
+check_url_blocker() {
+  local blocker_id="$1"
+  local label="$2"
+  local url="${3:-}"
+  local hint="$4"
+
+  if [[ -z "$url" ]]; then
+    record_fail "$blocker_id $label: unresolved. $hint"
+    return 0
+  fi
+
+  if http_ok "$url"; then
+    record_pass "$blocker_id $label: reachable at $url"
+  else
+    record_fail "$blocker_id $label: configured but unreachable at $url"
+  fi
+}
+
+check_chain138_ci_rpc() {
+  local blocker_id="EXT-CHAIN138-CI-RPC"
+  local rpc="${CHAIN138_CI_RPC_URL:-${RPC_URL_138_PUBLIC:-${CHAIN138_PUBLIC_RPC_URL:-}}}"
+
+  if [[ -z "$rpc" ]]; then
+    record_fail "$blocker_id Chain 138 CI RPC: unresolved. Set CHAIN138_CI_RPC_URL (preferred) or RPC_URL_138_PUBLIC to a runner-reachable endpoint."
+    return 0
+  fi
+
+  if ! command -v cast >/dev/null 2>&1; then
+    record_fail "$blocker_id Chain 138 CI RPC: cast not available to verify $rpc"
+    return 0
+  fi
+
+  local block_number
+  block_number="$(cast block-number --rpc-url "$rpc" 2>/dev/null || true)"
+  if [[ -n "$block_number" ]]; then
+    record_pass "$blocker_id Chain 138 CI RPC: reachable at $rpc (block $block_number)"
+  else
+    record_fail "$blocker_id Chain 138 CI RPC: configured but unreachable at $rpc"
+  fi
+}
+
+echo "=== External Dependency Check ==="
+echo ""
+
+check_url_blocker \
+  "EXT-DBIS-CORE" \
+  "dbis_core deployment" \
+  "${DBIS_CORE_URL:-}" \
+  "Deploy dbis_core or set DBIS_CORE_URL to an existing reachable instance."
+
+check_url_blocker \
+  "EXT-CC-PAYMENT-ADAPTERS" \
+  "cc-payment-adapters implementation" \
+  "${CC_PAYMENT_ADAPTERS_URL:-}" \
+  "Implement/host cc-payment-adapters and set CC_PAYMENT_ADAPTERS_URL."
+
+check_url_blocker \
+  "EXT-CC-AUDIT-LEDGER" \
+  "cc-audit-ledger implementation" \
+  "${CC_AUDIT_LEDGER_URL:-}" \
+  "Implement/host cc-audit-ledger and set CC_AUDIT_LEDGER_URL."
+
+check_url_blocker \
+  "EXT-CC-SHARED-EVENTS" \
+  "cc-shared-events implementation" \
+  "${CC_SHARED_EVENTS_URL:-}" \
+  "Implement/host cc-shared-events and set CC_SHARED_EVENTS_URL."
+
+check_url_blocker \
+  "EXT-CC-SHARED-SCHEMAS" \
+  "cc-shared-schemas implementation" \
+  "${CC_SHARED_SCHEMAS_URL:-}" \
+  "Implement/host cc-shared-schemas and set CC_SHARED_SCHEMAS_URL."
+
+check_url_blocker \
+  "EXT-FIN-GATEWAY" \
+  "FIN / Alliance Access gateway" \
+  "${FIN_GATEWAY_URL:-${ALLIANCE_ACCESS_URL:-}}" \
+  "Provision a real FIN / Alliance Access gateway and set FIN_GATEWAY_URL or ALLIANCE_ACCESS_URL."
+
+check_chain138_ci_rpc
+
+echo ""
+echo "Resolved: $PASS_COUNT"
+echo "Blocked:  $FAIL_COUNT"
+
+if (( FAIL_COUNT > 0 )) && (( ADVISORY == 0 )); then
+  exit 1
+fi
+
+exit 0
--- a/scripts/verify/run-all-validation.sh
+++ b/scripts/verify/run-all-validation.sh
@@ -60,6 +60,15 @@ else
 fi
 echo ""

+echo "3c. External dependency blockers..."
+EXT_CHECK="$SCRIPT_DIR/check-external-dependencies.sh"
+if [[ -x "$EXT_CHECK" ]]; then
+  bash "$EXT_CHECK" --advisory || true
+else
+  echo "   (skip: $EXT_CHECK missing)"
+fi
+echo ""
+
 if [[ "$SKIP_GENESIS" == true ]]; then
  echo "4. Genesis — skipped (--skip-genesis)"
 else
--- a/2
+++ b/2