fix(contracts): unify contract ID env var naming across deploy paths

.env.example

@@ -54,8 +54,11 @@ STELLAR_SECRET_KEY=SXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 # Public key corresponding to STELLAR_SECRET_KEY.
 STELLAR_PUBLIC_KEY=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
-# Deployed contract IDs (fill in after deploying contracts).
-STELLAR_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+# Deployed contract IDs (fill in after deploying contracts; these are the same
+# keys written to contract-ids.env by the deploy scripts).
+STELLAR_CONTRACT_VAULT_REGISTRY=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+STELLAR_CONTRACT_ACCESS_LEASE=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
+STELLAR_CONTRACT_SUBSCRIPTION=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 
 
 # -----------------------------------------------------------------------------

docs/DEPLOY-BACKEND-GUIDE.md

@@ -140,8 +140,9 @@ Add each variable below. Click **+ New Variable** for each one.
 | `PAY_TO` | `GCK7ALS7EP5DQG4UZMON3XTNUE7SSIW27XW24UOLXDHBOHWEWIGZVPZF` | Your BACKEND wallet public key |
 | `AGENT_SECRET_KEY` | `<your-stellar-secret-key>` | Your BACKEND wallet secret key |
 | `REGISTRY_SECRET_KEY` | `<your-stellar-secret-key>` | Same as AGENT_SECRET_KEY |
-| `VAULT_REGISTRY_CONTRACT_ID` | `CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H` | Deployed contract |
-| `REGISTRY_CONTRACT_ID` | `CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H` | Same as above |
+| `STELLAR_CONTRACT_VAULT_REGISTRY` | `CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H` | Deployed contract (from `contract-ids.env`) |
+| `STELLAR_CONTRACT_ACCESS_LEASE` | `CDQZBCEPN6RCJAQLEKB3ZRNLUZXDCCFMVIS6STZNAOEAQLXD3FUBNQGX` | Deployed contract (from `contract-ids.env`) |
+| `STELLAR_CONTRACT_SUBSCRIPTION` | `CCCE6Q6WHDICGMQWXXXMM6X7YDGK3BXU4JNQJNSIA6XQRC52MQL42CD6` | Deployed contract (from `contract-ids.env`) |
 | `OPENROUTER_API_KEY` | Get a free key at [openrouter.ai](https://openrouter.ai) | Free tier available |
 | `ADMIN_API_KEY` | `<your-admin-api-key>` | Keep this secret |
 
@@ -173,8 +174,9 @@ USDC_CONTRACT_ID=CBIELTK6YBZJU5UP2WWQEUCYKLPU6AUNZ2BQ4WWFEIE3USCIHMXQDAMA
 PAY_TO=GCK7ALS7EP5DQG4UZMON3XTNUE7SSIW27XW24UOLXDHBOHWEWIGZVPZF
 AGENT_SECRET_KEY=<your-stellar-secret-key>
 REGISTRY_SECRET_KEY=<your-stellar-secret-key>
-VAULT_REGISTRY_CONTRACT_ID=CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H
-REGISTRY_CONTRACT_ID=CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H
+STELLAR_CONTRACT_VAULT_REGISTRY=CBQEIMSRPSRKJJHGOELZTP3CISZVHZ6WPKZTWJMYZXHFXPGHHWFQBD4H
+STELLAR_CONTRACT_ACCESS_LEASE=CDQZBCEPN6RCJAQLEKB3ZRNLUZXDCCFMVIS6STZNAOEAQLXD3FUBNQGX
+STELLAR_CONTRACT_SUBSCRIPTION=CCCE6Q6WHDICGMQWXXXMM6X7YDGK3BXU4JNQJNSIA6XQRC52MQL42CD6
 OPENROUTER_API_KEY=sk-or-...   ← FILL IN (get free at openrouter.ai)
 ADMIN_API_KEY=<your-admin-api-key>
 NODE_ENV=production

docs/ENVIRONMENT-VARIABLES.md

@@ -39,9 +39,9 @@ This document is the single source of truth for every environment variable used
 | `PAY_TO` | Yes | — | Backend |
 | `AGENT_SECRET_KEY` | Yes | — | Backend |
 | `REGISTRY_SECRET_KEY` | Yes | — | Backend |
-| `VAULT_REGISTRY_CONTRACT_ID` | Yes | — | Backend |
-| `REGISTRY_CONTRACT_ID` | Yes | — | Backend |
 | `STELLAR_CONTRACT_VAULT_REGISTRY` | Yes | — | Backend |
+| `VAULT_REGISTRY_CONTRACT_ID` | No | — | Backend (deprecated alias) |
+| `REGISTRY_CONTRACT_ID` | No | — | Backend (deprecated alias) |
 | `STELLAR_CONTRACT_ACCESS_LEASE` | Yes | — | Backend |
 | `STELLAR_CONTRACT_SUBSCRIPTION` | Yes | — | Backend |
 | `STELLAR_SECRET_KEY` | Yes | — | Backend / Scripts |
@@ -140,21 +140,11 @@ This document is the single source of truth for every environment variable used
 - **Default:** none
 - **Format:** `G...` (56-character Stellar public key)
 
-### `VAULT_REGISTRY_CONTRACT_ID`
-- **Purpose:** Contract ID of the vault registry contract.
-- **Required:** Yes
-- **Default:** none
-
-### `REGISTRY_CONTRACT_ID`
-- **Purpose:** Contract ID of the primary registry contract.
-- **Required:** Yes
-- **Default:** none
-
 ### `STELLAR_CONTRACT_VAULT_REGISTRY`
 - **Purpose:** Contract ID for the vault registry (used by deployment scripts and backend).
 - **Required:** Yes
 - **Default:** none
-- **Notes:** May be identical to `VAULT_REGISTRY_CONTRACT_ID`; keep both for backward compatibility with existing scripts.
+- **Notes:** Canonical name; written to `contract-ids.env` by both deploy paths. The legacy aliases below are normalised to this key by `rollback-contracts.cjs`.
 
 ### `STELLAR_CONTRACT_ACCESS_LEASE`
 - **Purpose:** Contract ID for the access-lease contract.
@@ -166,6 +156,18 @@ This document is the single source of truth for every environment variable used
 - **Required:** Yes
 - **Default:** none
 
+### `VAULT_REGISTRY_CONTRACT_ID` *(deprecated alias)*
+- **Purpose:** Legacy alias of `STELLAR_CONTRACT_VAULT_REGISTRY`.
+- **Required:** No
+- **Default:** none
+- **Notes:** Retained only for backward compatibility with older scripts; new deployments should use `STELLAR_CONTRACT_VAULT_REGISTRY`.
+
+### `REGISTRY_CONTRACT_ID` *(deprecated alias)*
+- **Purpose:** Legacy alias of `STELLAR_CONTRACT_VAULT_REGISTRY`.
+- **Required:** No
+- **Default:** none
+- **Notes:** Retained only for backward compatibility with older scripts; new deployments should use `STELLAR_CONTRACT_VAULT_REGISTRY`.
+
 ---
 
 ## Secrets & API Keys
@@ -348,8 +350,6 @@ These variables are consumed by the deployment manifests rather than by the appl
 | `PAY_TO` | Dev `G...` account | Staging `G...` account | Prod `G...` account |
 | `AGENT_SECRET_KEY` | Dev `S...` key | Staging `S...` key | Prod `S...` key (secret manager) |
 | `REGISTRY_SECRET_KEY` | Dev `S...` key | Staging `S...` key | Prod `S...` key (secret manager) |
-| `VAULT_REGISTRY_CONTRACT_ID` | Dev contract ID | Staging contract ID | Prod contract ID |
-| `REGISTRY_CONTRACT_ID` | Dev contract ID | Staging contract ID | Prod contract ID |
 | `STELLAR_CONTRACT_VAULT_REGISTRY` | Dev contract ID | Staging contract ID | Prod contract ID |
 | `STELLAR_CONTRACT_ACCESS_LEASE` | Dev contract ID | Staging contract ID | Prod contract ID |
 | `STELLAR_CONTRACT_SUBSCRIPTION` | Dev contract ID | Staging contract ID | Prod contract ID |
@@ -401,8 +401,6 @@ USDC_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 # Contracts
 # ---------------------------------------------------------------------------
 PAY_TO=GXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-VAULT_REGISTRY_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
-REGISTRY_CONTRACT_ID=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 STELLAR_CONTRACT_VAULT_REGISTRY=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 STELLAR_CONTRACT_ACCESS_LEASE=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX
 STELLAR_CONTRACT_SUBSCRIPTION=CXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXXX

docs/contract-deploy-guide.md

@@ -192,20 +192,20 @@ Then redeploy the backend (Railway redeploys automatically on env change).
 ```bash
 # Read vault-registry count
 soroban contract invoke \
-  --id $vault_registry --source deployer --network testnet \
+  --id $STELLAR_CONTRACT_VAULT_REGISTRY --source deployer --network testnet \
   -- count
 
 # Grant a test lease (30 days = 518400 ledgers)
 soroban contract invoke \
-  --id $access_lease --source deployer --network testnet \
+  --id $STELLAR_CONTRACT_ACCESS_LEASE --source deployer --network testnet \
   -- grant_lease \
   --resource_id "test-resource-1" \
   --buyer GBUYER1_PUBLIC_KEY \
   --duration_ledgers 518400
 
 # Check if valid
 soroban contract invoke \
-  --id $access_lease --source deployer --network testnet \
+  --id $STELLAR_CONTRACT_ACCESS_LEASE --source deployer --network testnet \
   -- is_valid \
   --resource_id "test-resource-1" \
   --buyer GBUYER1_PUBLIC_KEY

scripts/03-deploy-contracts.sh

@@ -13,7 +13,8 @@
 #   export CONTRACTS_DIR=../contracts   # optional; defaults to ../contracts
 #   bash scripts/03-deploy-contracts.sh
 #
-# Output: contract-ids.env  (source this before running 04-init-contracts.sh)
+# Output: contract-ids.env  (canonical STELLAR_CONTRACT_* keys; source this
+#         before running 04-init-contracts.sh)
 
 set -euo pipefail
 
@@ -60,9 +61,10 @@ WASM_DIR="$CONTRACTS_DIR/target/wasm32-unknown-unknown/release"
 
 # ── Helper: deploy one contract ───────────────────────────────────────────────
 deploy_contract() {
-  local name="$1"
+  local env_name="$1"
+  local name="$2"
   local wasm="$WASM_DIR/${name}.wasm"
-  # Progress goes to stderr; only `name=id` goes to stdout (and the env file).
+  # Progress goes to stderr; only `ENV_NAME=id` goes to stdout (and the env file).
   echo "" >&2
   echo "▸ Deploying $name…" >&2
   local id
@@ -71,14 +73,14 @@ deploy_contract() {
     --source   deployer \
     --network  testnet)
   echo "  Contract ID: $id" >&2
-  echo "$name=$id"
+  echo "$env_name=$id"
 }
 
 # ── Deploy ────────────────────────────────────────────────────────────────────
 {
-  deploy_contract "vault_registry"
-  deploy_contract "access_lease"
-  deploy_contract "subscription"
+  deploy_contract "STELLAR_CONTRACT_VAULT_REGISTRY" "vault_registry"
+  deploy_contract "STELLAR_CONTRACT_ACCESS_LEASE"   "access_lease"
+  deploy_contract "STELLAR_CONTRACT_SUBSCRIPTION"   "subscription"
 } > "$OUT_FILE"
 
 echo ""

scripts/04-init-contracts.sh

@@ -2,17 +2,18 @@
 # SynapsVault — Step 4: Initialise all deployed contracts
 #
 # Prerequisites:
-#   source contract-ids.env      (sets vault_registry, access_lease, subscription)
+#   source contract-ids.env      (sets STELLAR_CONTRACT_VAULT_REGISTRY,
+#                                 STELLAR_CONTRACT_ACCESS_LEASE, STELLAR_CONTRACT_SUBSCRIPTION)
 #   export DEPLOYER_SECRET=S...
 #   export BACKEND_PUBLIC=G...   (the backend platform wallet public key)
 #
 # All three contracts expose init(admin); admin = BACKEND_PUBLIC.
 
 set -euo pipefail
 
-: "${vault_registry:?  source contract-ids.env first}"
-: "${access_lease:?    source contract-ids.env first}"
-: "${subscription:?    source contract-ids.env first}"
+: "${STELLAR_CONTRACT_VAULT_REGISTRY:?  source contract-ids.env first}"
+: "${STELLAR_CONTRACT_ACCESS_LEASE:?    source contract-ids.env first}"
+: "${STELLAR_CONTRACT_SUBSCRIPTION:?    source contract-ids.env first}"
 : "${DEPLOYER_SECRET:? export DEPLOYER_SECRET}"
 : "${BACKEND_PUBLIC:?  export BACKEND_PUBLIC}"
 
@@ -31,7 +32,7 @@ printf '%s\n' "$DEPLOYER_SECRET" | $CLI keys add deployer --secret-key 2>/dev/nu
 echo ""
 echo "▸ Initialising vault-registry (admin = BACKEND_PUBLIC)…"
 $CLI contract invoke \
-  --id      "$vault_registry" \
+  --id      "$STELLAR_CONTRACT_VAULT_REGISTRY" \
   --source  deployer \
   --network testnet \
   -- init \
@@ -42,7 +43,7 @@ echo "✅ vault-registry initialised"
 echo ""
 echo "▸ Initialising access-lease (admin = BACKEND_PUBLIC)…"
 $CLI contract invoke \
-  --id      "$access_lease" \
+  --id      "$STELLAR_CONTRACT_ACCESS_LEASE" \
   --source  deployer \
   --network testnet \
   -- init \
@@ -53,7 +54,7 @@ echo "✅ access-lease initialised"
 echo ""
 echo "▸ Initialising subscription manager (admin = BACKEND_PUBLIC)…"
 $CLI contract invoke \
-  --id      "$subscription" \
+  --id      "$STELLAR_CONTRACT_SUBSCRIPTION" \
   --source  deployer \
   --network testnet \
   -- init \
@@ -64,7 +65,7 @@ echo "✅ subscription initialised"
 echo ""
 echo "▸ Verifying vault-registry…"
 COUNT=$($CLI contract invoke \
-  --id      "$vault_registry" \
+  --id      "$STELLAR_CONTRACT_VAULT_REGISTRY" \
   --source  deployer \
   --network testnet \
   -- count 2>/dev/null || echo "0")
@@ -78,9 +79,9 @@ echo "╚═══════════════════════
 echo ""
 echo "Copy these into your backend .env:"
 echo ""
-echo "  STELLAR_CONTRACT_VAULT_REGISTRY=$vault_registry"
-echo "  STELLAR_CONTRACT_ACCESS_LEASE=$access_lease"
-echo "  STELLAR_CONTRACT_SUBSCRIPTION=$subscription"
+echo "  STELLAR_CONTRACT_VAULT_REGISTRY=$STELLAR_CONTRACT_VAULT_REGISTRY"
+echo "  STELLAR_CONTRACT_ACCESS_LEASE=$STELLAR_CONTRACT_ACCESS_LEASE"
+echo "  STELLAR_CONTRACT_SUBSCRIPTION=$STELLAR_CONTRACT_SUBSCRIPTION"
 echo "  STELLAR_NETWORK=testnet"
 echo "  STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org"
 echo ""

scripts/deploy-contracts.cjs

@@ -67,6 +67,14 @@ const CONTRACTS = [
   { name: 'subscription', wasmFile: 'subscription.wasm' },
 ];
 
+// Canonical env var prefix for the deployed contract IDs (the names the backend
+// reads), e.g. `vault-registry` -> `STELLAR_CONTRACT_VAULT_REGISTRY`.
+const CONTRACT_ENV_PREFIX = 'STELLAR_CONTRACT_';
+
+function contractEnvName(contractName) {
+  return `${CONTRACT_ENV_PREFIX}${contractName.toUpperCase().replace(/-/g, '_')}`;
+}
+
 // Minimum account balance (in stroops) required to proceed with deployment.
 const MIN_BALANCE_STROOPS = 10_000_000n; // 1 XLM
 
@@ -490,7 +498,7 @@ function writeContractIds(contractIds, network, dryRun) {
   ];
 
   for (const [name, id] of Object.entries(contractIds)) {
-    const envName = `${name.toUpperCase().replace(/-/g, '_')}_CONTRACT_ID`;
+    const envName = contractEnvName(name);
     lines.push(`${envName}=${id}`);
   }
 
@@ -592,4 +600,4 @@ if (require.main === module) {
   });
 }
 
-module.exports = { parseArgs, validateEnv, CONTRACTS };
+module.exports = { parseArgs, validateEnv, CONTRACTS, contractEnvName };