feat(scripts): resolve CCIP/LINK addresses via config inventory

- Add scripts/lib/address-inventory.sh (jq + JSON inventory fallback)
- Wire deployment helper scripts to load_explorer_runtime_env + resolve_address_value
- Persist new LINK to address-inventory.json via persist_inventory_value
- Document config/*.json in config/README.md

Made-with: Cursor

config/README.md

@@ -0,0 +1,8 @@
+# config — reference JSON (non-secret)
+
+Files such as `address-inventory.json` and `runtime-env.json` are **reference snapshots** of address and runtime surface fields that were previously carried only in `.env`. They must **not** contain API keys or other secrets.
+
+- Keep **real secrets** in `.env` (gitignored) or your secret store.
+- After changing explorer-related env or CCIP addresses, update these JSON files if scripts or docs depend on them.
+
+See proxmox parent `docs/00-meta/SUBMODULE_HYGIENE.md` for Gitea/GitHub remotes and submodule push order.

scripts/complete-all-prerequisites.sh

@@ -6,12 +6,13 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || source "$PROJECT_ROOT/../.env" 2>/dev/null || true
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
-LINK_TOKEN="${LINK_TOKEN:-}"
+LINK_TOKEN="$(resolve_address_value LINK_TOKEN LINK_TOKEN "")"
-WETH9_BRIDGE="0x971cD9D156f193df8051E48043C476e53ECd4693"
+WETH9_BRIDGE="$(resolve_address_value CCIPWETH9_BRIDGE CCIPWETH9_BRIDGE 0x971cD9D156f193df8051E48043C476e53ECd4693)"
-WETH10_BRIDGE="0xe0E93247376aa097dB308B92e6Ba36bA015535D0"
+WETH10_BRIDGE="$(resolve_address_value CCIPWETH10_BRIDGE CCIPWETH10_BRIDGE 0xe0E93247376aa097dB308B92e6Ba36bA015535D0)"
 ACCOUNT=$(cast wallet address "$PRIVATE_KEY")
 
 echo "╔══════════════════════════════════════════════════════════════╗"
@@ -53,9 +54,9 @@ if [ "${LINK_CONFIRMED:-false}" != "true" ]; then
         echo "Waiting 60 seconds for network confirmation..."
         sleep 60
         
-        # Update .env
+        # Keep address inventory as the script-facing source of truth for addresses.
-        sed -i "s|^LINK_TOKEN=.*|LINK_TOKEN=$NEW_LINK|" "$PROJECT_ROOT/.env" 2>/dev/null || \
+        persist_inventory_value "LINK_TOKEN" "$NEW_LINK" || true
-            echo "LINK_TOKEN=$NEW_LINK" >> "$PROJECT_ROOT/.env"
+        persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$NEW_LINK" || true
         export LINK_TOKEN="$NEW_LINK"
         
         # Verify
@@ -139,4 +140,3 @@ if [ "${LINK_CONFIRMED:-false}" = "true" ]; then
 fi
 
 echo ""
-

scripts/complete-link-token-setup.sh

@@ -6,13 +6,14 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || true
+load_explorer_runtime_env
 
-LINK_TOKEN="0x514910771AF9Ca656af840dff83E8264EcF986CA"
+LINK_TOKEN="$(resolve_address_value LINK_TOKEN LINK_TOKEN_138 0x514910771AF9Ca656af840dff83E8264EcF986CA)"
 CHAIN_ID=138
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
-CCIP_ROUTER="0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e"
+CCIP_ROUTER="$(resolve_address_value CCIP_ROUTER_ADDRESS CCIP_ROUTER_ADDRESS 0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e)"
 
 echo "╔══════════════════════════════════════════════════════════════╗"
 echo "║     COMPLETE LINK TOKEN SETUP                                ║"
@@ -125,8 +126,8 @@ echo ""
 # Step 4: Check bridge balances (if token exists)
 if [ "${TOKEN_EXISTS:-false}" = "true" ]; then
     echo "=== Step 4: Checking Bridge LINK Balances ==="
-    WETH9_BRIDGE="0x971cD9D156f193df8051E48043C476e53ECd4693"
+    WETH9_BRIDGE="$(resolve_address_value CCIPWETH9_BRIDGE CCIPWETH9_BRIDGE 0x971cD9D156f193df8051E48043C476e53ECd4693)"
-    WETH10_BRIDGE="0xe0E93247376aa097dB308B92e6Ba36bA015535D0"
+    WETH10_BRIDGE="$(resolve_address_value CCIPWETH10_BRIDGE CCIPWETH10_BRIDGE 0xe0E93247376aa097dB308B92e6Ba36bA015535D0)"
     
     WETH9_LINK=$(cast call "$LINK_TOKEN" "balanceOf(address)" "$WETH9_BRIDGE" --rpc-url "$RPC_URL" 2>/dev/null || echo "0")
     WETH9_LINK_ETH=$(cast --from-wei "$WETH9_LINK" ether 2>/dev/null || echo "0")
@@ -172,7 +173,7 @@ echo "║     SETUP SUMMARY                                            ║"
 echo "╚══════════════════════════════════════════════════════════════╝"
 echo ""
 echo "Configuration:"
-echo "  ✓ .env updated with LINK_TOKEN"
+echo "  ✓ Address inventory available for LINK_TOKEN"
 echo "  ✓ Token lists updated"
 echo "  ✓ CCIP configuration documented"
 echo ""
@@ -207,4 +208,3 @@ fi
 echo ""
 echo "✅ Setup script completed!"
 echo ""
-

scripts/comprehensive-link-deployment.sh

@@ -5,9 +5,11 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR/.."
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
+cd "$PROJECT_ROOT"
 
-source .env 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
 ACCOUNT=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || echo "")
@@ -45,8 +47,8 @@ echo "╚═══════════════════════
 echo ""
 if ./scripts/diagnose-link-deployment.sh 2>&1 | grep -q "Using Existing LINK Token"; then
     echo "✓✓✓ Found existing LINK token!"
-    source .env 2>/dev/null || true
+    load_explorer_runtime_env
-    LINK_TOKEN="${LINK_TOKEN:-}"
+    LINK_TOKEN="$(resolve_address_value LINK_TOKEN LINK_TOKEN "")"
     if [ -n "$LINK_TOKEN" ] && [ ${#LINK_TOKEN} -eq 42 ]; then
         CODE=$(cast code "$LINK_TOKEN" --rpc-url "$RPC_URL" 2>/dev/null || echo "")
         if [ -n "$CODE" ] && [ "$CODE" != "0x" ] && [ ${#CODE} -gt 100 ]; then
@@ -86,8 +88,8 @@ echo ""
 echo "Waiting 45 seconds for network confirmation..."
 sleep 45
 
-source .env 2>/dev/null || true
+load_explorer_runtime_env
-LINK_TOKEN="${LINK_TOKEN:-}"
+LINK_TOKEN="$(resolve_address_value LINK_TOKEN LINK_TOKEN "")"
 if [ -n "$LINK_TOKEN" ] && [ ${#LINK_TOKEN} -eq 42 ]; then
     CODE=$(cast code "$LINK_TOKEN" --rpc-url "$RPC_URL" 2>/dev/null || echo "")
     if [ -n "$CODE" ] && [ "$CODE" != "0x" ] && [ ${#CODE} -gt 100 ]; then
@@ -128,4 +130,3 @@ echo "  1. Wait additional time (5-10 minutes)"
 echo "  2. Use Remix IDE (instructions above)"
 echo "  3. Check block explorer: https://explorer.d-bis.org/address/$ACCOUNT"
 echo ""
-

scripts/configure-link-token-chain138.sh

@@ -7,9 +7,12 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
+load_explorer_runtime_env
 
 # Ethereum Mainnet canonical LINK token address
 LINK_TOKEN_MAINNET="0x514910771AF9Ca656af840dff83E8264EcF986CA"
+CCIP_ROUTER="$(resolve_address_value CCIP_ROUTER_ADDRESS CCIP_ROUTER_ADDRESS 0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e)"
 CHAIN_ID=138
 
 echo "╔══════════════════════════════════════════════════════════════╗"
@@ -20,26 +23,16 @@ echo "LINK Token Address: $LINK_TOKEN_MAINNET"
 echo "Chain ID: $CHAIN_ID"
 echo ""
 
-# Step 1: Update .env file
+# Step 1: Update address inventory
-echo "=== Step 1: Updating .env file ==="
+echo "=== Step 1: Updating address inventory ==="
-ENV_FILE="$PROJECT_ROOT/.env"
+if [ -f "$EXPLORER_ADDRESS_INVENTORY_FILE" ]; then
-if [ -f "$ENV_FILE" ]; then
+    persist_inventory_value "LINK_TOKEN" "$LINK_TOKEN_MAINNET"
-    # Update or add LINK_TOKEN
+    persist_inventory_value "LINK_TOKEN_138" "$LINK_TOKEN_MAINNET"
-    if grep -q "^LINK_TOKEN=" "$ENV_FILE"; then
+    persist_inventory_value "LINK_TOKEN_MAINNET" "$LINK_TOKEN_MAINNET"
-        sed -i "s|^LINK_TOKEN=.*|LINK_TOKEN=$LINK_TOKEN_MAINNET|" "$ENV_FILE"
+    persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$LINK_TOKEN_MAINNET"
-        echo "✓ Updated LINK_TOKEN in .env"
+    echo "✓ Updated config/address-inventory.json"
-    else
-        echo "LINK_TOKEN=$LINK_TOKEN_MAINNET" >> "$ENV_FILE"
-        echo "✓ Added LINK_TOKEN to .env"
-    fi
-    
-    # Update CCIP fee token if exists
-    if grep -q "^CCIP_CHAIN138_FEE_TOKEN=" "$ENV_FILE"; then
-        sed -i "s|^CCIP_CHAIN138_FEE_TOKEN=.*|CCIP_CHAIN138_FEE_TOKEN=$LINK_TOKEN_MAINNET|" "$ENV_FILE"
-        echo "✓ Updated CCIP_CHAIN138_FEE_TOKEN in .env"
-    fi
 else
-    echo "⚠ .env file not found at $ENV_FILE"
+    echo "⚠ Address inventory not found at $EXPLORER_ADDRESS_INVENTORY_FILE"
 fi
 echo ""
 
@@ -105,7 +98,6 @@ echo ""
 
 # Step 3: Add to database
 echo "=== Step 3: Adding LINK token to database ==="
-source "$ENV_FILE" 2>/dev/null || true
 
 DB_HOST="${DB_HOST:-localhost}"
 DB_PORT="${DB_PORT:-5432}"
@@ -158,7 +150,7 @@ echo ""
 echo "LINK Token Address: $LINK_TOKEN_MAINNET"
 echo ""
 echo "Updated:"
-echo "  ✓ .env file (LINK_TOKEN and CCIP_CHAIN138_FEE_TOKEN)"
+echo "  ✓ Address inventory (LINK_TOKEN and CCIP_CHAIN138_FEE_TOKEN)"
 echo "  ✓ Token list files (dbis-138.tokenlist.json, token-list.json)"
 echo "  ✓ Database tokens table (if accessible)"
 echo "  ✓ CCIP documentation"
@@ -168,9 +160,8 @@ echo "  1. Verify LINK token on ChainID 138:"
 echo "     cast code $LINK_TOKEN_MAINNET --rpc-url <RPC_URL>"
 echo ""
 echo "  2. Check CCIP Router fee token:"
-echo "     cast call <CCIP_ROUTER> \"getFeeToken()\" --rpc-url <RPC_URL>"
+echo "     cast call $CCIP_ROUTER \"getFeeToken()\" --rpc-url <RPC_URL>"
 echo ""
 echo "  3. Fund bridge contracts with LINK if needed:"
 echo "     ./scripts/fund-bridge-contracts.sh 10"
 echo ""
-

scripts/deploy-all-contracts.sh

@@ -7,8 +7,9 @@ set -euo pipefail
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
 SOURCE_PROJECT="/home/intlc/projects/smom-dbis-138"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || source "$PROJECT_ROOT/../.env" 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="http://192.168.11.250:8545"
 CHAIN_ID=138
@@ -26,7 +27,7 @@ echo ""
 
 # Check prerequisites
 if [ -z "${PRIVATE_KEY:-}" ]; then
-    echo "❌ Error: PRIVATE_KEY not set in .env"
+    echo "❌ Error: PRIVATE_KEY not available in effective environment"
     exit 1
 fi
 
@@ -189,14 +190,13 @@ echo "Deploying LINK Token (required for CCIP)..."
 echo ""
 deploy_contract "script/DeployMockLinkToken.s.sol:DeployMockLinkToken" "MockLinkToken"
 
-# Update .env with LINK token address if found
+# Update address inventory with LINK token address if found
 if [ -n "${DEPLOYED_ADDRESS:-}" ]; then
     echo ""
-    echo "Updating .env with LINK_TOKEN=$DEPLOYED_ADDRESS"
+    echo "Updating address inventory with LINK_TOKEN=$DEPLOYED_ADDRESS"
-    if [ -f "$PROJECT_ROOT/.env" ]; then
+    persist_inventory_value "LINK_TOKEN" "$DEPLOYED_ADDRESS" || true
-        sed -i "s/^LINK_TOKEN=.*/LINK_TOKEN=$DEPLOYED_ADDRESS/" "$PROJECT_ROOT/.env" || true
+    persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$DEPLOYED_ADDRESS" || true
-        echo "✅ .env updated"
+    echo "✅ Address inventory updated"
-    fi
     DEPLOYED_ADDRESS=""  # Reset for next deployment
 fi
 
@@ -220,4 +220,3 @@ echo "  Deployer: $DEPLOYER"
 echo ""
 echo "📄 Deployment logs saved in /tmp/deploy-*.log"
 echo ""
-

scripts/deploy-and-verify-link.sh

@@ -5,8 +5,9 @@ set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || source "$PROJECT_ROOT/../.env" 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
 GAS_PRICE="${1:-$(cast --to-wei 20 gwei)}"
@@ -158,10 +159,10 @@ if [ "$CONFIRMED" != "true" ]; then
 fi
 
 echo ""
-echo "=== Updating .env ==="
+echo "=== Updating address inventory ==="
-sed -i "s|^LINK_TOKEN=.*|LINK_TOKEN=$LINK_ADDRESS|" "$PROJECT_ROOT/.env" 2>/dev/null || \
+persist_inventory_value "LINK_TOKEN" "$LINK_ADDRESS"
-    echo "LINK_TOKEN=$LINK_ADDRESS" >> "$PROJECT_ROOT/.env"
+persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$LINK_ADDRESS"
-echo "✓ Updated .env"
+echo "✓ Updated config/address-inventory.json"
 echo ""
 
 echo "=== Verifying Token Functions ==="
@@ -197,4 +198,3 @@ fi
 echo "✅✅✅ LINK TOKEN DEPLOYMENT COMPLETE!"
 echo "Address: $LINK_ADDRESS"
 echo ""
-

scripts/diagnose-link-deployment.sh

@@ -4,12 +4,15 @@
 set -euo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
-cd "$SCRIPT_DIR/.."
+PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
+cd "$PROJECT_ROOT"
 
-source .env 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
 ACCOUNT=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || echo "")
+FOUND_LINK=""
 
 if [ -z "$ACCOUNT" ]; then
     echo "Error: PRIVATE_KEY not set or invalid"
@@ -43,7 +46,7 @@ echo ""
 
 # Check CCIP Router for fee token
 echo "=== Checking CCIP Router for Fee Token ==="
-CCIP_ROUTER="0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e"
+CCIP_ROUTER="$(resolve_address_value CCIP_ROUTER_ADDRESS CCIP_ROUTER_ADDRESS 0x8078A09637e47Fa5Ed34F626046Ea2094a5CDE5e)"
 ROUTER_CODE=$(cast code "$CCIP_ROUTER" --rpc-url "$RPC_URL" 2>/dev/null || echo "")
 if [ -n "$ROUTER_CODE" ] && [ "$ROUTER_CODE" != "0x" ]; then
     echo "✓ CCIP Router exists"
@@ -65,6 +68,7 @@ echo ""
 # Check if LINK token exists at any known address
 echo "=== Checking Known LINK Addresses ==="
 KNOWN_LINKS=(
+    "$(resolve_address_value LINK_TOKEN LINK_TOKEN 0x514910771AF9Ca656af840dff83E8264EcF986CA)"
     "0x0cb0192C056aa425C557BdeAD8E56C7eEabf7acF"
     "0x07dE1f489E1bfCE2c326066a9DFc10e731CBA0CB"
     "0x514910771AF9Ca656af840dff83E8264EcF986CA"
@@ -92,8 +96,9 @@ echo ""
 if [ -n "$FOUND_LINK" ]; then
     echo "=== Using Existing LINK Token ==="
     echo "LINK Token: $FOUND_LINK"
-    sed -i "s|^LINK_TOKEN=.*|LINK_TOKEN=$FOUND_LINK|" .env 2>/dev/null || echo "LINK_TOKEN=$FOUND_LINK" >> .env
+    persist_inventory_value "LINK_TOKEN" "$FOUND_LINK" || true
-    echo "✓ Updated .env"
+    persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$FOUND_LINK" || true
+    echo "✓ Updated address inventory"
     
     # Check balance
     BALANCE=$(cast call "$FOUND_LINK" "balanceOf(address)" "$ACCOUNT" --rpc-url "$RPC_URL" 2>/dev/null || echo "0")
@@ -246,9 +251,10 @@ if [ -n "$NEW_LINK" ] && [ ${#NEW_LINK} -eq 42 ]; then
     echo "$NEW_LINK" > /tmp/link_address.txt
     
     # Update .env
-    cd "$SCRIPT_DIR/.."
+    cd "$PROJECT_ROOT"
-    sed -i "s|^LINK_TOKEN=.*|LINK_TOKEN=$NEW_LINK|" .env 2>/dev/null || echo "LINK_TOKEN=$NEW_LINK" >> .env
+    persist_inventory_value "LINK_TOKEN" "$NEW_LINK" || true
-    echo "✓ Updated .env"
+    persist_inventory_value "CCIP_CHAIN138_FEE_TOKEN" "$NEW_LINK" || true
+    echo "✓ Updated address inventory"
     
     # Wait and verify
     echo ""
@@ -294,4 +300,3 @@ fi
 
 # Cleanup
 rm -rf "$TEMP_DIR"
-

scripts/full-readiness-check.sh

@@ -5,6 +5,7 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
 # Colors
 RED='\033[0;31m'
@@ -20,15 +21,15 @@ log_warn() { echo -e "${YELLOW}[⚠]${NC} $1"; }
 log_error() { echo -e "${RED}[✗]${NC} $1"; }
 log_header() { echo -e "${CYAN}[CHECK]${NC} $1"; }
 
-# Load environment
+# Load runtime env plus address inventory.
-source "$PROJECT_ROOT/.env" 2>/dev/null || source "$PROJECT_ROOT/../.env" 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
-LINK_TOKEN="${LINK_TOKEN:-0x73ADaF7dBa95221c080db5631466d2bC54f6a76B}"
+LINK_TOKEN="$(resolve_address_value LINK_TOKEN LINK_TOKEN 0x73ADaF7dBa95221c080db5631466d2bC54f6a76B)"
-WETH9="0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2"
+WETH9="$(resolve_address_value WETH9_ADDRESS WETH9_ADDRESS 0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2)"
-WETH10="0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f"
+WETH10="$(resolve_address_value WETH10_ADDRESS WETH10_ADDRESS 0xf4BB2e28688e89fCcE3c0580D37d36A7672E8A9f)"
-WETH9_BRIDGE="0x971cD9D156f193df8051E48043C476e53ECd4693"
+WETH9_BRIDGE="$(resolve_address_value CCIPWETH9_BRIDGE CCIPWETH9_BRIDGE 0x971cD9D156f193df8051E48043C476e53ECd4693)"
-WETH10_BRIDGE="0xe0E93247376aa097dB308B92e6Ba36bA015535D0"
+WETH10_BRIDGE="$(resolve_address_value CCIPWETH10_BRIDGE CCIPWETH10_BRIDGE 0xe0E93247376aa097dB308B92e6Ba36bA015535D0)"
 
 PASSED=0
 FAILED=0
@@ -63,7 +64,7 @@ echo ""
 # 2. Account Status
 log_header "2. Account Status"
 if [ -z "${PRIVATE_KEY:-}" ]; then
-    check_fail "PRIVATE_KEY not set in .env"
+    check_fail "PRIVATE_KEY not available in effective environment"
     ACCOUNT=""
 else
     ACCOUNT=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || echo "")
@@ -211,18 +212,18 @@ echo ""
 log_header "8. Configuration Files"
 if [ -f "$PROJECT_ROOT/.env" ]; then
     check_pass ".env file exists"
-    if grep -q "^PRIVATE_KEY=" "$PROJECT_ROOT/.env"; then
-        check_pass "PRIVATE_KEY configured"
-    else
-        check_fail "PRIVATE_KEY not in .env"
-    fi
-    if grep -q "^LINK_TOKEN=" "$PROJECT_ROOT/.env"; then
-        check_pass "LINK_TOKEN configured"
-    else
-        check_warn "LINK_TOKEN not in .env"
-    fi
 else
-    check_fail ".env file not found"
+    check_warn ".env file not found"
+fi
+if [ -n "${PRIVATE_KEY:-}" ]; then
+    check_pass "PRIVATE_KEY available in effective environment"
+else
+    check_fail "PRIVATE_KEY not available in effective environment"
+fi
+if [ -f "$EXPLORER_ADDRESS_INVENTORY_FILE" ] && [ -n "$(inventory_get LINK_TOKEN 2>/dev/null || true)" ]; then
+    check_pass "LINK_TOKEN configured in address inventory"
+else
+    check_warn "LINK_TOKEN not in address inventory"
 fi
 echo ""
 
@@ -264,4 +265,3 @@ else
     log_error "✗ SYSTEM NOT READY - $FAILED critical issues found"
     exit 1
 fi
-

scripts/lib/address-inventory.sh

@@ -0,0 +1,67 @@
+#!/usr/bin/env bash
+
+# Shared helpers for explorer-monorepo address inventory access.
+
+_inventory_helper_dir="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+EXPLORER_PROJECT_ROOT="${EXPLORER_PROJECT_ROOT:-$(cd "$_inventory_helper_dir/../.." && pwd)}"
+EXPLORER_RUNTIME_ENV_FILE="${EXPLORER_RUNTIME_ENV_FILE:-$EXPLORER_PROJECT_ROOT/.env}"
+EXPLORER_PARENT_ENV_FILE="${EXPLORER_PARENT_ENV_FILE:-$EXPLORER_PROJECT_ROOT/../.env}"
+EXPLORER_ADDRESS_INVENTORY_FILE="${EXPLORER_ADDRESS_INVENTORY_FILE:-$EXPLORER_PROJECT_ROOT/config/address-inventory.json}"
+
+load_explorer_runtime_env() {
+    source "$EXPLORER_RUNTIME_ENV_FILE" 2>/dev/null || true
+    source "$EXPLORER_PARENT_ENV_FILE" 2>/dev/null || true
+}
+
+inventory_get() {
+    local key="${1:-}"
+    if [ -z "$key" ] || [ ! -f "$EXPLORER_ADDRESS_INVENTORY_FILE" ] || ! command -v jq >/dev/null 2>&1; then
+        return 1
+    fi
+    jq -r --arg key "$key" '.inventory[$key] // empty' "$EXPLORER_ADDRESS_INVENTORY_FILE"
+}
+
+resolve_address_value() {
+    local env_name="${1:-}"
+    local inventory_key="${2:-$env_name}"
+    local fallback="${3:-}"
+    local current="${!env_name:-}"
+
+    if [ -n "$current" ]; then
+        printf '%s\n' "$current"
+        return 0
+    fi
+
+    current="$(inventory_get "$inventory_key" 2>/dev/null || true)"
+    if [ -n "$current" ]; then
+        printf '%s\n' "$current"
+        return 0
+    fi
+
+    if [ -n "$fallback" ]; then
+        printf '%s\n' "$fallback"
+        return 0
+    fi
+
+    return 1
+}
+
+persist_inventory_value() {
+    local key="${1:-}"
+    local value="${2:-}"
+    local tmp_file
+
+    if [ -z "$key" ] || [ -z "$value" ] || [ ! -f "$EXPLORER_ADDRESS_INVENTORY_FILE" ]; then
+        return 1
+    fi
+    if ! command -v jq >/dev/null 2>&1; then
+        echo "jq is required to update $EXPLORER_ADDRESS_INVENTORY_FILE" >&2
+        return 1
+    fi
+
+    tmp_file="$(mktemp)"
+    jq --arg key "$key" --arg value "$value" --arg updated "$(date -I)" \
+        '.updated = $updated | .inventory[$key] = $value' \
+        "$EXPLORER_ADDRESS_INVENTORY_FILE" > "$tmp_file"
+    mv "$tmp_file" "$EXPLORER_ADDRESS_INVENTORY_FILE"
+}

scripts/test-link-deployment-simple.sh

@@ -5,11 +5,13 @@ set -uo pipefail
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
 CHAIN_ID=138
+LINK_TOKEN="${LINK_TOKEN:-$(resolve_address_value LINK_TOKEN LINK_TOKEN "")}"
 
 echo "╔══════════════════════════════════════════════════════════════╗"
 echo "║     LINK TOKEN DEPLOYMENT TEST                               ║"
@@ -19,7 +21,7 @@ echo ""
 # Test 1: Environment
 echo "1. Environment Variables:"
 if [ -z "${PRIVATE_KEY:-}" ]; then
-    echo "   ❌ PRIVATE_KEY not set"
+    echo "   ❌ PRIVATE_KEY not available in effective environment"
     exit 1
 else
     DEPLOYER=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || echo "")
@@ -138,7 +140,7 @@ if [ -n "${LINK_TOKEN:-}" ] && [ "$LINK_TOKEN" != "" ]; then
         echo "   ⚠️  LINK_TOKEN configured but not found on-chain: $LINK_TOKEN"
     fi
 else
-    echo "   ⚠️  LINK_TOKEN not configured"
+    echo "   ⚠️  LINK_TOKEN not configured in address inventory"
 fi
 echo ""
 
@@ -153,4 +155,3 @@ echo "    --broadcast \\"
 echo "    --legacy \\"
 echo "    --gas-price 20000000000"
 echo ""
-

scripts/test-link-deployment.sh

@@ -6,11 +6,13 @@ set -uo pipefail  # Remove -e to allow error handling
 
 SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
 PROJECT_ROOT="$(cd "$SCRIPT_DIR/.." && pwd)"
+source "$PROJECT_ROOT/scripts/lib/address-inventory.sh"
 
-source "$PROJECT_ROOT/.env" 2>/dev/null || source "$PROJECT_ROOT/../.env" 2>/dev/null || true
+load_explorer_runtime_env
 
 RPC_URL="${RPC_URL_138:-http://192.168.11.250:8545}"
 CHAIN_ID=138
+LINK_TOKEN="${LINK_TOKEN:-$(resolve_address_value LINK_TOKEN LINK_TOKEN "")}"
 
 echo "╔══════════════════════════════════════════════════════════════╗"
 echo "║     LINK TOKEN DEPLOYMENT TEST SUITE                         ║"
@@ -51,7 +53,7 @@ echo "════════════════════════
 echo ""
 
 if [ -z "${PRIVATE_KEY:-}" ]; then
-    test_fail "PRIVATE_KEY not set in .env"
+    test_fail "PRIVATE_KEY not available in effective environment"
 else
     test_pass "PRIVATE_KEY is set"
     DEPLOYER=$(cast wallet address "$PRIVATE_KEY" 2>/dev/null || echo "")
@@ -243,7 +245,7 @@ if [ -n "${LINK_TOKEN:-}" ] && [ "$LINK_TOKEN" != "" ]; then
         test_warn "LINK token address configured but contract not found on-chain"
     fi
 else
-    test_warn "LINK_TOKEN not configured in .env"
+    test_warn "LINK_TOKEN not configured in address inventory"
 fi
 
 echo ""
@@ -320,4 +322,3 @@ else
     echo -e "${RED}❌ Some critical tests failed. Please fix issues before deploying.${NC}"
     exit 1
 fi
-