feat(sdk-coin-stx): accept a configured PoX-5 staking contract pair

The Stacks Foundation PoX-5 test contract uses the standard name `pox-5`
at a non-canonical boot address. `isValidContractAddress` is address-only,
so a register targeting it is rejected on every parse unless the caller
supplies an allowlist.

Accept it as a PAIR instead: add `allowedStakingContracts` (name, address
and optional expiry) to the StacksNetwork statics, seeded on mainnet with
the test pair, and consult it in `isContractPairValid` and
`Pox5Builder.isValidContractCall`. `isValidContractAddress` stays
address-only, so pox-4 and send-many-memo at that address are still
rejected.

The entry is pair-scoped and self-expiring, so the trust cannot outlive the
test or leak to other contract names. The caller-supplied allowlist remains
a working override.

SI-2089

TICKET: SI-2089

Author: Doddanna17

modules/sdk-coin-stx/src/lib/contractBuilder.ts

@@ -15,7 +15,7 @@ import {
 } from '@stacks/transactions';
 import { InvalidParameterValueError } from '@bitgo/sdk-core';
 import { Transaction } from './transaction';
-import { contractPrincipalCVFromString, isValidAddress, standardPrincipalCVFromString } from './utils';
+import { contractPrincipalCVFromString, isExpired, isValidAddress, standardPrincipalCVFromString } from './utils';
 import { ClarityValueJson } from './iface';
 import { Utils } from '.';
 import { CONTRACT_NAME_SENDMANY, VALID_POX5_CONTRACT_FUNCTION_NAMES, VALID_STAKING_CONTRACT_NAMES } from './constants';
@@ -61,6 +61,15 @@ export class ContractBuilder extends AbstractContractBuilder {
     return this;
   }
 
+  /**
+   * Caller-supplied pairs plus this network's active (non-expired) pairs. Network pairs are
+   * pair-scoped (name + address), so a canonical name never binds to a foreign address.
+   */
+  private getAllowedStakingContracts(): ReadonlyArray<{ name: string; address: string }> {
+    const networkPairs = (this._coinConfig.network as BitgoStacksNetwork).allowedStakingContracts ?? [];
+    return [...this._allowedStakingContracts, ...networkPairs.filter((pair) => !isExpired(pair.expiresAt))];
+  }
+
   /** True when the current (name, address) is a canonical pair or an explicitly allowlisted pair. */
   private isContractPairValid(): boolean {
     const isCanonicalName =
@@ -72,7 +81,7 @@ export class ContractBuilder extends AbstractContractBuilder {
     if (isCanonicalName && isCanonicalAddress) {
       return true;
     }
-    return this._allowedStakingContracts.some(
+    return this.getAllowedStakingContracts().some(
       (contract) => contract.name === this._contractName && contract.address === this._contractAddress
     );
   }
@@ -106,7 +115,7 @@ export class ContractBuilder extends AbstractContractBuilder {
       throw new InvalidParameterValueError('Invalid address');
     }
     const isCanonicalAddress = Utils.isValidContractAddress(address, this._coinConfig.network as BitgoStacksNetwork);
-    const isAllowedAddress = this._allowedStakingContracts.some((contract) => contract.address === address);
+    const isAllowedAddress = this.getAllowedStakingContracts().some((contract) => contract.address === address);
     if (!isCanonicalAddress && !isAllowedAddress) {
       throw new InvalidParameterValueError('Invalid contract address');
     }

modules/sdk-coin-stx/src/lib/pox5Builder.ts

@@ -26,7 +26,7 @@ import {
   FUNCTION_NAME_UNSTAKE,
   FUNCTION_NAME_UPDATE_BOND_REGISTRATION,
 } from './constants';
-import { contractPrincipalCVFromString, standardPrincipalCVFromString } from './utils';
+import { contractPrincipalCVFromString, isExpired, standardPrincipalCVFromString } from './utils';
 
 type Integer = bigint | number | string;
 type ByteValue = Buffer | Uint8Array | string;
@@ -167,10 +167,14 @@ export class Pox5Builder extends ContractBuilder {
   }
 
   public static isValidContractCall(coinConfig: Readonly<CoinConfig>, payload: ContractCallPayload): boolean {
-    return (
-      (coinConfig.network as BitgoStacksNetwork).stakingContractAddress === addressToString(payload.contractAddress) &&
-      payload.contractName.content === CONTRACT_NAME_POX5
+    const network = coinConfig.network as BitgoStacksNetwork;
+    const address = addressToString(payload.contractAddress);
+    const isCanonical = network.stakingContractAddress === address;
+    // A configured (non-expired) network pair may point pox-5 at a different deployer.
+    const isConfiguredPair = (network.allowedStakingContracts ?? []).some(
+      (pair) => pair.name === CONTRACT_NAME_POX5 && pair.address === address && !isExpired(pair.expiresAt)
     );
+    return (isCanonical || isConfiguredPair) && payload.contractName.content === CONTRACT_NAME_POX5;
   }
 
   registerForBond(params: Pox5RegisterForBondParams): this {

modules/sdk-coin-stx/src/lib/utils.ts

@@ -292,6 +292,24 @@ export function isValidContractAddress(addr: string, network: BitgoStacksNetwork
   );
 }
 
+/**
+ * Whether a configured staking-contract allowance has expired.
+ *
+ * @param {string} [expiresAt] - ISO-8601 date (e.g. `2027-03-31`). Undefined ⇒ never expires.
+ * @returns {boolean} - true when the entry is in the past and must no longer be honoured; an
+ *   unparseable expiry fails closed (treated as expired)
+ */
+export function isExpired(expiresAt?: string): boolean {
+  if (!expiresAt) {
+    return false;
+  }
+  const expiry = Date.parse(expiresAt);
+  if (Number.isNaN(expiry)) {
+    return true;
+  }
+  return Date.now() > expiry;
+}
+
 /**
  * Check if the name is one of valid contract names
  *

modules/sdk-coin-stx/test/unit/transactionBuilder/contractBuilder.ts

@@ -171,17 +171,15 @@ describe('Stacks: Contract Builder', function () {
       it('an unsigned caller-allowlisted non-canonical pox-5 (dummy) contract call transaction', async () => {
         // The caller supplies the staking contract it is configured for — no SDK change needed.
         const builder = factoryProd.getContractBuilder();
-        builder.allowedStakingContracts([
-          { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-        ]);
+        builder.allowedStakingContracts([{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }]);
         builder.fee({ fee: '180' });
         builder.nonce(0);
         builder.contractAddress('SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY');
-        builder.contractName('pox-5-dummy-v1');
+        builder.contractName('pox-5-test');
         builder.functionName('register-for-bond');
         builder.functionArgs([
           { type: 'uint128', val: '210' },
-          { type: 'principal', val: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY.signer-manager-stackslabs-dummy-v1' },
+          { type: 'principal', val: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY.signer-manager-stackslabs-test' },
           { type: 'uint128', val: '1005000' },
           { type: 'optional' },
           { type: 'optional' },
@@ -191,25 +189,25 @@ describe('Stacks: Contract Builder', function () {
 
         const tx = await builder.build();
         const txJson = tx.toJson();
-        should.deepEqual(txJson.payload.contractName, 'pox-5-dummy-v1');
+        should.deepEqual(txJson.payload.contractName, 'pox-5-test');
         should.deepEqual(txJson.payload.contractAddress, 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY');
         should.deepEqual(txJson.payload.functionName, 'register-for-bond');
       });
 
       it('rehydrates an allowlisted non-canonical contract call (sign / explain / fee-rebuild path)', async () => {
         // `signTransaction` / `explainTransaction` / the fee re-build all go through `factory.from(hex)`,
         // which re-creates the builder — re-parsing must not reject the allowlisted contract.
-        const allowlist = [{ name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }];
+        const allowlist = [{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }];
         const builder = factoryProd.getContractBuilder();
         builder.allowedStakingContracts(allowlist);
         builder.fee({ fee: '180' });
         builder.nonce(0);
         builder.contractAddress('SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY');
-        builder.contractName('pox-5-dummy-v1');
+        builder.contractName('pox-5-test');
         builder.functionName('register-for-bond');
         builder.functionArgs([
           { type: 'uint128', val: '210' },
-          { type: 'principal', val: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY.signer-manager-stackslabs-dummy-v1' },
+          { type: 'principal', val: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY.signer-manager-stackslabs-test' },
           { type: 'uint128', val: '1005000' },
           { type: 'optional' },
           { type: 'optional' },
@@ -223,55 +221,47 @@ describe('Stacks: Contract Builder', function () {
         reparsed.numberSignatures(1);
         const payload = (await reparsed.build()).toJson().payload;
         should.deepEqual(payload.contractAddress, 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY');
-        should.deepEqual(payload.contractName, 'pox-5-dummy-v1');
+        should.deepEqual(payload.contractName, 'pox-5-test');
 
         // Without the allowlist the rebuild is rejected — canonical validation is preserved (no relaxation).
         (() => factoryProd.from(tx.toBroadcastFormat())).should.throw(ParseTransactionError);
       });
 
       it('rejects an allowlisted name followed by a canonical address (order-independent pair check)', function () {
         const builder = factoryProd.getContractBuilder();
-        builder.allowedStakingContracts([
-          { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-        ]);
-        builder.contractName('pox-5-dummy-v1'); // allowlisted name first
+        builder.allowedStakingContracts([{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }]);
+        builder.contractName('pox-5-test'); // allowlisted name first
         (() => builder.contractAddress('SP000000000000000000002Q6VF78')).should.throw(/not an allowlisted pair/);
       });
 
       it('rejects an allowlisted address followed by a canonical name (order-independent pair check)', function () {
         const builder = factoryProd.getContractBuilder();
-        builder.allowedStakingContracts([
-          { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-        ]);
+        builder.allowedStakingContracts([{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }]);
         builder.contractAddress('SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY'); // allowlisted address first
-        (() => builder.contractName('pox-5')).should.throw(/not an allowlisted pair/);
+        (() => builder.contractName('pox-4')).should.throw(/not an allowlisted pair/);
       });
 
       it('rejects duplicate allowlisted contract names', function () {
         const builder = factoryProd.getContractBuilder();
         (() =>
           builder.allowedStakingContracts([
-            { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-            { name: 'pox-5-dummy-v1', address: 'SP000000000000000000002Q6VF78' },
+            { name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
+            { name: 'pox-5-test', address: 'SP000000000000000000002Q6VF78' },
           ])).should.throw(/Duplicate staking contract name/);
       });
 
       it('rejects an allowlisted name paired with a different address', function () {
         const builder = factoryProd.getContractBuilder();
-        builder.allowedStakingContracts([
-          { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-        ]);
+        builder.allowedStakingContracts([{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }]);
         builder.contractAddress('SP000000000000000000002Q6VF78'); // canonical address, wrong pair
-        (() => builder.contractName('pox-5-dummy-v1')).should.throw(/not an allowlisted pair/);
+        (() => builder.contractName('pox-5-test')).should.throw(/not an allowlisted pair/);
       });
 
       it('rejects a function that is not in the pox-5 set for an allowlisted contract', function () {
         const builder = factoryProd.getContractBuilder();
-        builder.allowedStakingContracts([
-          { name: 'pox-5-dummy-v1', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' },
-        ]);
+        builder.allowedStakingContracts([{ name: 'pox-5-test', address: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY' }]);
         builder.contractAddress('SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY');
-        builder.contractName('pox-5-dummy-v1');
+        builder.contractName('pox-5-test');
         // `stack-stx` is a pox-4 function, not part of the pox-5 ABI the dummy mirrors.
         (() => builder.functionName('stack-stx')).should.throw(/is not supported contract function name/);
       });
@@ -288,6 +278,133 @@ describe('Stacks: Contract Builder', function () {
         );
       });
 
+      describe('network-configured staking contract pairs (SI-2089)', function () {
+        // The mainnet Stx network declares this as a pair-scoped, self-expiring pox-5 allowance.
+        const CONFIGURED_ADDRESS = 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY';
+        const CANONICAL_ADDRESS = 'SP000000000000000000002Q6VF78';
+
+        const withPairs = (pairs: ReadonlyArray<{ name: string; address: string; expiresAt?: string }>) =>
+          ({
+            ...coins.get(coinName),
+            network: { ...coins.get(coinName).network, allowedStakingContracts: pairs },
+          } as any);
+
+        const buildRegisterForBond = (factoryInstance: StxLib.TransactionBuilderFactory) => {
+          const builder = factoryInstance.getContractBuilder();
+          builder.fee({ fee: '180' });
+          builder.nonce(0);
+          builder.contractAddress(CONFIGURED_ADDRESS);
+          builder.contractName('pox-5');
+          builder.functionName('register-for-bond');
+          builder.functionArgs([
+            { type: 'uint128', val: '210' },
+            { type: 'principal', val: 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY.signer-manager' },
+            { type: 'uint128', val: '1005000' },
+            { type: 'optional' },
+            { type: 'optional' },
+          ]);
+          builder.fromPubKey(testData.TX_SENDER.pub);
+          builder.numberSignatures(1);
+          return builder;
+        };
+
+        it('accepts pox-5 at the configured network address', async function () {
+          const builder = buildRegisterForBond(factoryProd);
+          const tx = await builder.build();
+          should.deepEqual(tx.toJson().payload.contractAddress, CONFIGURED_ADDRESS);
+          should.deepEqual(tx.toJson().payload.contractName, 'pox-5');
+        });
+
+        it('parses a configured-address register-for-bond via from(hex) with NO caller allowlist', async function () {
+          const tx = await buildRegisterForBond(factoryProd).build();
+          const reparsed = factoryProd.from(tx.toBroadcastFormat());
+          reparsed.fromPubKey(testData.TX_SENDER.pub);
+          reparsed.numberSignatures(1);
+          const payload = (await reparsed.build()).toJson().payload as any;
+          should.deepEqual(payload.contractAddress, CONFIGURED_ADDRESS);
+          should.deepEqual(payload.contractName, 'pox-5');
+        });
+
+        it('rejects pox-4 at the configured network address (reviewer regression)', function () {
+          const builder = factoryProd.getContractBuilder();
+          builder.contractName('pox-4');
+          (() => builder.contractAddress(CONFIGURED_ADDRESS)).should.throw(/not an allowlisted pair/);
+        });
+
+        it('rejects send-many-memo at the configured network address', function () {
+          const builder = factoryProd.getContractBuilder();
+          builder.contractName('send-many-memo');
+          (() => builder.contractAddress(CONFIGURED_ADDRESS)).should.throw(/not an allowlisted pair/);
+        });
+
+        it('rejects an unknown address', function () {
+          const builder = factoryProd.getContractBuilder();
+          (() => builder.contractAddress('SP2TYC2AVC4GSB01F78H0XSVTH8WRGV95BXFG4BBR')).should.throw(
+            /Invalid contract address/
+          );
+        });
+
+        it('still accepts canonical pox-5 and pox-4 at the canonical address', function () {
+          const pox5 = factoryProd.getContractBuilder();
+          pox5.contractName('pox-5');
+          (() => pox5.contractAddress(CANONICAL_ADDRESS)).should.not.throw();
+          const pox4 = factoryProd.getContractBuilder();
+          pox4.contractName('pox-4');
+          (() => pox4.contractAddress(CANONICAL_ADDRESS)).should.not.throw();
+        });
+
+        it('honours the expiry: expired entry rejected, non-expired and absent accepted', function () {
+          const expired = new StxLib.TransactionBuilderFactory(
+            withPairs([{ name: 'pox-5', address: CONFIGURED_ADDRESS, expiresAt: '2020-01-01' }])
+          );
+          const expiredBuilder = expired.getContractBuilder();
+          expiredBuilder.contractName('pox-5');
+          (() => expiredBuilder.contractAddress(CONFIGURED_ADDRESS)).should.throw(/Invalid contract address/);
+
+          const active = new StxLib.TransactionBuilderFactory(
+            withPairs([{ name: 'pox-5', address: CONFIGURED_ADDRESS, expiresAt: '2999-01-01' }])
+          );
+          const activeBuilder = active.getContractBuilder();
+          activeBuilder.contractName('pox-5');
+          (() => activeBuilder.contractAddress(CONFIGURED_ADDRESS)).should.not.throw();
+
+          const noExpiry = new StxLib.TransactionBuilderFactory(
+            withPairs([{ name: 'pox-5', address: CONFIGURED_ADDRESS }])
+          );
+          const noExpiryBuilder = noExpiry.getContractBuilder();
+          noExpiryBuilder.contractName('pox-5');
+          (() => noExpiryBuilder.contractAddress(CONFIGURED_ADDRESS)).should.not.throw();
+        });
+
+        it('keeps the caller-supplied allowlist as a working override', async function () {
+          // A caller-only pair (not declared on the network) still works when passed explicitly.
+          const DUMMY_ADDRESS = 'SP2T758K6T2YRKG9Q0TJ16B6FP5QQREWZSESRS0PY';
+          const builder = factoryProd.getContractBuilder();
+          builder.allowedStakingContracts([{ name: 'pox-5-test', address: DUMMY_ADDRESS }]);
+          builder.fee({ fee: '180' });
+          builder.nonce(0);
+          builder.contractAddress(DUMMY_ADDRESS);
+          builder.contractName('pox-5-test');
+          builder.functionName('register-for-bond');
+          builder.functionArgs([
+            { type: 'uint128', val: '210' },
+            { type: 'principal', val: `${DUMMY_ADDRESS}.signer-manager` },
+            { type: 'uint128', val: '1005000' },
+            { type: 'optional' },
+            { type: 'optional' },
+          ]);
+          builder.fromPubKey(testData.TX_SENDER.pub);
+          builder.numberSignatures(1);
+          const tx = await builder.build();
+          should.deepEqual(tx.toJson().payload.contractAddress, DUMMY_ADDRESS);
+
+          // Without the caller allowlist the same address is not accepted by the network.
+          (() => factoryProd.getContractBuilder().contractAddress(DUMMY_ADDRESS)).should.throw(
+            /Invalid contract address/
+          );
+        });
+      });
+
       it('a signed contract call with args', async () => {
         const builder = initTxBuilder();
         builder.functionArgs([