From eae9101f2f1d718e35d1549a7b57a16f8d2221a0 Mon Sep 17 00:00:00 2001
From: ZAINAB <zainabjane@outlook.com>
Date: Fri, 26 Jun 2026 13:16:46 +0000
Subject: [PATCH] docs: clarify contract ID placeholders and env vars in
 deployments.md

Closes #522

- Replace ambiguous '_(set after first deploy)_' text with explicit
  <PLACEHOLDER> tokens so maintainers know what to fill in.
- Add required env var blocks for both testnet and mainnet.
- Add placeholder convention note at the top of the file.
- Link update steps to DEPLOYMENT.md for the full deploy guide.
---
 docs/deployments.md | 48 +++++++++++++++++++++++++++++++++++++++++----
 1 file changed, 44 insertions(+), 4 deletions(-)

diff --git a/docs/deployments.md b/docs/deployments.md
index 5699022..281105f 100644
--- a/docs/deployments.md
+++ b/docs/deployments.md
@@ -2,18 +2,38 @@
 
 Deployed contract addresses for each environment. Update this file after every deployment.
 
+> **Placeholder convention:** Values shown as `<PLACEHOLDER>` have not been filled in yet
+> and must be replaced with the real 56-character Stellar contract ID (starting with `C`)
+> before the environment is functional.  Values shown as `_(not yet deployed)_` mean the
+> contract has never been deployed to that network.
+
 ---
 
 ## Testnet
 
 | Contract | Contract ID | Deployed At | Deployed By |
 |---|---|---|---|
-| `energy_token` | _(set after first deploy)_ | — | — |
-| `audit_registry` | _(set after first deploy)_ | — | — |
-| `community_governance` | _(set after first deploy)_ | — | — |
+| `energy_token` | `<TESTNET_ENERGY_TOKEN_ID>` | — | — |
+| `audit_registry` | `<TESTNET_AUDIT_REGISTRY_ID>` | — | — |
+| `community_governance` | `<TESTNET_COMMUNITY_GOVERNANCE_ID>` | — | — |
 
 Explorer: `https://stellar.expert/explorer/testnet/contract/<CONTRACT_ID>`
 
+### Required environment variables (testnet)
+
+After deploying, set the following in your `.env.local` (see `.env.example`):
+
+```env
+NEXT_PUBLIC_STELLAR_NETWORK=testnet
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-testnet.stellar.org
+NEXT_PUBLIC_ENERGY_TOKEN_ID=<TESTNET_ENERGY_TOKEN_ID>
+NEXT_PUBLIC_AUDIT_REGISTRY_ID=<TESTNET_AUDIT_REGISTRY_ID>
+NEXT_PUBLIC_COMMUNITY_GOVERNANCE_ID=<TESTNET_COMMUNITY_GOVERNANCE_ID>
+MINTER_SECRET_KEY=<your-testnet-deployer-secret>
+```
+
+---
+
 ## Mainnet
 
 | Contract | Contract ID | Deployed At | Deployed By |
@@ -24,6 +44,26 @@ Explorer: `https://stellar.expert/explorer/testnet/contract/<CONTRACT_ID>`
 
 Explorer: `https://stellar.expert/explorer/public/contract/<CONTRACT_ID>`
 
+### Required environment variables (mainnet)
+
+```env
+NEXT_PUBLIC_STELLAR_NETWORK=mainnet
+NEXT_PUBLIC_STELLAR_RPC_URL=https://soroban-rpc.stellar.org
+NEXT_PUBLIC_ENERGY_TOKEN_ID=<MAINNET_ENERGY_TOKEN_ID>
+NEXT_PUBLIC_AUDIT_REGISTRY_ID=<MAINNET_AUDIT_REGISTRY_ID>
+NEXT_PUBLIC_COMMUNITY_GOVERNANCE_ID=<MAINNET_COMMUNITY_GOVERNANCE_ID>
+MINTER_SECRET_KEY=<your-mainnet-deployer-secret>
+```
+
+> ⚠️ Mainnet deployments are irreversible. Use a hardware wallet or HSM-backed key.
+> Never commit real secret keys — use GitHub Actions secrets in CI/CD.
+
 ---
 
-> **How to update this file:** After running the deploy workflow (or manual deploy steps below), paste the contract IDs returned by `stellar contract deploy` into the table above and commit the change.
+## How to update this file
+
+1. Run the deploy workflow (`GitHub → Actions → Deploy Contracts → Run workflow`) or follow the manual steps in [docs/DEPLOYMENT.md](DEPLOYMENT.md).
+2. The `stellar contract deploy` command prints a contract ID for each contract.
+3. Replace the corresponding `<PLACEHOLDER>` value in the table above with the real contract ID.
+4. Set the same IDs in the matching environment variables listed above (`.env.local` for local dev, GitHub / Vercel secrets for CI/CD).
+5. Commit the updated file.