fix(stellar): unify agent secret env var and correct futurenet passphrase

.env.example

@@ -5,7 +5,7 @@ NODE_ENV=development
 # Stellar
 STELLAR_NETWORK=testnet
 STELLAR_RPC_URL=https://soroban-testnet.stellar.org
-AGENT_SECRET_KEY=your_agent_stellar_secret_key_here
+STELLAR_AGENT_SECRET_KEY=your_agent_stellar_secret_key_here
 VAULT_CONTRACT_ID=your_deployed_contract_id_here
 USDC_TOKEN_ADDRESS=testnet_usdc_contract_address_here
 

src/agent/README.md

@@ -305,7 +305,7 @@ MAX_GAS_PERCENT=0.1                  # Max gas as % of amount
 # Stellar Network
 STELLAR_NETWORK=testnet              # testnet | mainnet | futurenet
 STELLAR_RPC_URL=https://soroban-testnet.stellar.org
-STELLAR_AGENT_SECRET=SBXXXXXX        # Agent keypair
+STELLAR_AGENT_SECRET_KEY=SBXXXXXX     # Agent keypair
 VAULT_CONTRACT_ID=CXXXXXX            # Vault smart contract
 USDC_TOKEN_ADDRESS=GXXXXXX           # USDC token address
 
@@ -339,7 +339,7 @@ DATABASE_URL=postgresql://...
 grep "Agent Loop" logs/combined.log
 
 # Verify environment variables
-echo $STELLAR_AGENT_SECRET
+echo $STELLAR_AGENT_SECRET_KEY
 ```
 
 **Protocol scan failing:**

src/stellar/README.md

@@ -30,7 +30,7 @@ import {
 ```bash
 STELLAR_NETWORK=testnet
 STELLAR_RPC_URL=https://soroban-testnet.stellar.org
-STELLAR_AGENT_SECRET=SXXX...
+STELLAR_AGENT_SECRET_KEY=SXXX...
 VAULT_CONTRACT_ID=CXXX...
 WALLET_ENCRYPTION_KEY=<64_hex_chars>
 ```

src/stellar/client.ts

@@ -8,9 +8,22 @@ import {
 import { TransactionResult } from './types';
 
 const RPC_URL = process.env.STELLAR_RPC_URL || 'https://soroban-testnet.stellar.org';
-const NETWORK_PASSPHRASE = process.env.STELLAR_NETWORK === 'mainnet' 
-  ? Networks.PUBLIC 
-  : Networks.TESTNET;
+export function resolveNetworkPassphrase(network: string | undefined): string {
+  switch (network?.toLowerCase()) {
+    case 'mainnet':
+      return Networks.PUBLIC;
+    case 'testnet':
+      return Networks.TESTNET;
+    case 'futurenet':
+      return Networks.FUTURENET;
+    default:
+      throw new Error(
+        `Unknown STELLAR_NETWORK: "${network}". Expected "mainnet", "testnet", or "futurenet".`
+      );
+  }
+}
+
+const NETWORK_PASSPHRASE = resolveNetworkPassphrase(process.env.STELLAR_NETWORK);
 
 let agentKeypair: Keypair | null = null;
 let rpcServer: rpc.Server | null = null;
@@ -37,9 +50,9 @@ export function getNetworkPassphrase(): string {
  */
 export function getAgentKeypair(): Keypair {
   if (!agentKeypair) {
-    const secret = process.env.STELLAR_AGENT_SECRET;
+    const secret = process.env.STELLAR_AGENT_SECRET_KEY;
     if (!secret) {
-      throw new Error('STELLAR_AGENT_SECRET not configured');
+      throw new Error('STELLAR_AGENT_SECRET_KEY not configured');
     }
     agentKeypair = Keypair.fromSecret(secret);
   }

tests/unit/stellar/client.test.ts

@@ -26,6 +26,7 @@ jest.mock('@stellar/stellar-sdk', () => ({
   Networks: {
     PUBLIC: 'Public Global Stellar Network ; September 2015',
     TESTNET: 'Test SDF Network ; September 2015',
+    FUTURENET: 'Test SDF Future Network ; October 2022',
   },
   Transaction: jest.fn(),
   TransactionBuilder: jest.fn(),
@@ -38,6 +39,7 @@ import {
   getAgentKeypair,
   submitTransaction,
   waitForConfirmation,
+  resolveNetworkPassphrase,
 } from '../../../src/stellar/client';
 
 describe('Stellar Client', () => {
@@ -73,16 +75,50 @@ describe('Stellar Client', () => {
     });
   });
 
+  // ── resolveNetworkPassphrase ───────────────────────────────────────────────
+
+  describe('resolveNetworkPassphrase()', () => {
+    it('returns PUBLIC passphrase for mainnet', () => {
+      expect(resolveNetworkPassphrase('mainnet')).toBe(
+        'Public Global Stellar Network ; September 2015',
+      );
+    });
+
+    it('returns TESTNET passphrase for testnet', () => {
+      expect(resolveNetworkPassphrase('testnet')).toBe(
+        'Test SDF Network ; September 2015',
+      );
+    });
+
+    it('returns FUTURENET passphrase for futurenet', () => {
+      expect(resolveNetworkPassphrase('futurenet')).toBe(
+        'Test SDF Future Network ; October 2022',
+      );
+    });
+
+    it('throws for unknown network value', () => {
+      expect(() => resolveNetworkPassphrase('badnet')).toThrow(
+        'Unknown STELLAR_NETWORK: "badnet"',
+      );
+    });
+
+    it('throws for undefined network value', () => {
+      expect(() => resolveNetworkPassphrase(undefined)).toThrow(
+        'Unknown STELLAR_NETWORK',
+      );
+    });
+  });
+
   // ── getAgentKeypair ───────────────────────────────────────────────────────
 
   describe('getAgentKeypair()', () => {
-    it('returns a keypair when STELLAR_AGENT_SECRET is configured', () => {
-      process.env.STELLAR_AGENT_SECRET = 'SMOCK_SECRET_KEY_FOR_TESTS_ONLY';
+    it('returns a keypair when STELLAR_AGENT_SECRET_KEY is configured', () => {
+      process.env.STELLAR_AGENT_SECRET_KEY = 'SMOCK_SECRET_KEY_FOR_TESTS_ONLY';
       expect(() => getAgentKeypair()).not.toThrow();
     });
 
     it('the returned keypair exposes publicKey()', () => {
-      process.env.STELLAR_AGENT_SECRET = 'SMOCK_SECRET_KEY_FOR_TESTS_ONLY';
+      process.env.STELLAR_AGENT_SECRET_KEY = 'SMOCK_SECRET_KEY_FOR_TESTS_ONLY';
       const keypair = getAgentKeypair();
       expect(typeof keypair.publicKey()).toBe('string');
     });