feat(sdk-coin-stx): read the staking allowance from the tx prebuild

The vault rehydrates a transaction to explain and sign, so a register
targeting a non-canonical PoX-5 test contract is rejected unless the
allowlist reaches the SDK there. Rather than a shared network allowance
(which would apply to every SDK consumer), read the pair the exporting
deployment declares on the transaction's coinSpecific.

signTransaction falls back to
params.txPrebuild.coinSpecific.allowedStakingContracts and
explainTransaction to params.coinSpecific.allowedStakingContracts, so the
offline vault works unchanged - it already passes the whole exported
transaction as the prebuild.

The allowance is an explicit, per-deployment declaration, never derived
from the transaction. Absent means canonical-only and fails closed. The
caller-supplied allowedStakingContracts option still takes precedence.

verifyTransaction forwards the prebuild's coinSpecific to its internal
explain call too, so verify resolves the allowance the same way explain
and sign do.

SI-2089

TICKET: SI-2089

Author: Doddanna17

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

@@ -120,7 +120,14 @@ export class Stx extends BaseCoin {
       return this.verifySbtcWithdrawTransaction(rawTx, txParams.sbtcWithdrawParams);
     }
 
-    const explainedTx = await this.explainTransaction({ txHex: rawTx, feeInfo: { fee: '' } });
+    const explainedTx = await this.explainTransaction({
+      txHex: rawTx,
+      feeInfo: { fee: '' },
+      // Resolve the staking allowance the same way explainTransaction/signTransaction do, so a prebuild
+      // declaring `coinSpecific.allowedStakingContracts` verifies instead of throwing ParseTransactionError.
+      // `VerifyTransactionOptions.txPrebuild` is the wider sdk-core type, hence the cast.
+      coinSpecific: (txPrebuild as { coinSpecific?: ExplainTransactionOptions['coinSpecific'] })?.coinSpecific,
+    });
     const recipient = txParams.recipients?.[0];
     if (recipient !== undefined && explainedTx) {
       const txOutput = explainedTx.outputs[0];
@@ -283,9 +290,13 @@ export class Stx extends BaseCoin {
    */
   async signTransaction(params: StxSignTransactionOptions): Promise<SignedTransaction> {
     const factory = new StxLib.TransactionBuilderFactory(coins.get(this.getChain()));
-    const txBuilder = factory.from(params.txPrebuild.txHex, {
-      allowedStakingContracts: params.allowedStakingContracts,
-    });
+    // The staking allowance is an explicit, per-deployment declaration emitted by wallet-platform in
+    // the exported transaction (`coinSpecific.allowedStakingContracts`). It is deliberately NOT
+    // derived from the transaction itself (that would defeat the check). When absent, validation is
+    // canonical-only and fails closed.
+    const allowedStakingContracts =
+      params.allowedStakingContracts ?? params.txPrebuild?.coinSpecific?.allowedStakingContracts;
+    const txBuilder = factory.from(params.txPrebuild.txHex, { allowedStakingContracts });
     const prvKeys = params.prv instanceof Array ? params.prv : [params.prv];
     prvKeys.forEach((prv) => txBuilder.sign({ key: prv }));
     if (params.pubKeys) txBuilder.fromPubKey(params.pubKeys);
@@ -318,7 +329,11 @@ export class Stx extends BaseCoin {
     }
 
     const factory = new StxLib.TransactionBuilderFactory(coins.get(this.getChain()));
-    const txBuilder = factory.from(txHex, { allowedStakingContracts: params.allowedStakingContracts });
+    // Same rule as signTransaction: the allowance is an explicit, per-deployment declaration carried
+    // on the transaction's `coinSpecific`, never derived from the transaction. Absent ⇒ canonical-only
+    // (fail-closed).
+    const allowedStakingContracts = params.allowedStakingContracts ?? params.coinSpecific?.allowedStakingContracts;
+    const txBuilder = factory.from(txHex, { allowedStakingContracts });
 
     if (params.publicKeys !== undefined) {
       txBuilder.fromPubKey(params.publicKeys);

modules/sdk-coin-stx/src/types.ts

@@ -34,6 +34,12 @@ export interface ExplainTransactionOptions {
    * explicitly so no shared/instance state is involved. Empty/omitted ⇒ canonical-only.
    */
   allowedStakingContracts?: ReadonlyArray<{ name: string; address: string }>;
+  /**
+   * Explicit, per-deployment staking allowance emitted by wallet-platform on the exported
+   * transaction. Used as a fallback when no top-level `allowedStakingContracts` is supplied; it is
+   * never derived from the transaction itself. Absent ⇒ canonical-only (fail-closed).
+   */
+  coinSpecific?: { allowedStakingContracts?: ReadonlyArray<{ name: string; address: string }> };
 }
 
 export interface StxSignTransactionOptions extends SignTransactionOptions {
@@ -48,4 +54,6 @@ export interface StxSignTransactionOptions extends SignTransactionOptions {
 export interface TransactionPrebuild extends BaseTransactionPrebuild {
   txHex: string;
   source: string;
+  /** @see ExplainTransactionOptions.coinSpecific */
+  coinSpecific?: { allowedStakingContracts?: ReadonlyArray<{ name: string; address: string }> };
 }

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

@@ -222,6 +222,131 @@ describe('STX:', function () {
     assert.doesNotThrow(() => JSON.stringify(explain.contractFunctionArgs));
   });
 
+  describe('PoX-5 non-canonical staking allowance from the tx prebuild (SI-2089)', () => {
+    const TEST_ADDRESS = 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY';
+    const testPair = [{ name: 'pox-5', address: TEST_ADDRESS }];
+
+    // Build requires the caller allowlist (the builder is canonical-only); the produced hex targets
+    // the non-canonical test address under the canonical `pox-5` name.
+    const buildConfiguredRegisterForBond = async () => {
+      const factory = new StxLib.TransactionBuilderFactory(coins.get(coinNameTest));
+      const builder = factory.getContractBuilder();
+      builder.allowedStakingContracts(testPair);
+      builder.fee({ fee: '180' });
+      builder.nonce(0);
+      builder.contractAddress(TEST_ADDRESS);
+      builder.contractName('pox-5');
+      builder.functionName('register-for-bond');
+      builder.functionArgs([
+        { type: 'uint128', val: '210' },
+        { type: 'principal', val: `${TEST_ADDRESS}.signer-manager` },
+        { type: 'uint128', val: '1005000' },
+        { type: 'optional' },
+        { type: 'optional' },
+      ]);
+      builder.fromPubKey(resources.TX_SENDER.pub);
+      builder.numberSignatures(1);
+      return await builder.build();
+    };
+
+    it('signs a prebuild carrying coinSpecific.allowedStakingContracts with no top-level allowlist', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      const signed = await basecoin.signTransaction({
+        prv: resources.TX_SENDER.prv,
+        pubKeys: [resources.TX_SENDER.pub],
+        txPrebuild: {
+          txHex: tx.toBroadcastFormat(),
+          coinSpecific: { allowedStakingContracts: testPair },
+        },
+      });
+      const signedHex = signed.halfSigned?.txHex ?? signed.txHex;
+      assert.ok(signedHex, 'expected a signed transaction hex');
+
+      // The signed hex round-trips through the same prebuild-declared allowance.
+      const reparsed = new StxLib.TransactionBuilderFactory(coins.get(coinNameTest)).from(signedHex, {
+        allowedStakingContracts: testPair,
+      });
+      const payload = (await reparsed.build()).toJson().payload as any;
+      payload.contractAddress.should.equal(TEST_ADDRESS);
+      payload.contractName.should.equal('pox-5');
+    });
+
+    it('rejects the same prebuild when the coinSpecific allowance is absent (fail-closed)', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      await assert.rejects(
+        basecoin.signTransaction({
+          prv: resources.TX_SENDER.prv,
+          pubKeys: [resources.TX_SENDER.pub],
+          txPrebuild: { txHex: tx.toBroadcastFormat() },
+        }),
+        /error parsing the raw transaction/
+      );
+    });
+
+    it('lets a top-level allowedStakingContracts take precedence over coinSpecific', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      // The top-level pair matches while the coinSpecific pair does not — the top-level must win.
+      const signed = await basecoin.signTransaction({
+        prv: resources.TX_SENDER.prv,
+        pubKeys: [resources.TX_SENDER.pub],
+        allowedStakingContracts: testPair,
+        txPrebuild: {
+          txHex: tx.toBroadcastFormat(),
+          coinSpecific: {
+            allowedStakingContracts: [{ name: 'pox-5', address: 'SP2T758K6T2YRKG9Q0TJ16B6FP5QQREWZSESRS0PY' }],
+          },
+        },
+      });
+      assert.ok(signed.halfSigned?.txHex ?? signed.txHex, 'expected a signed transaction hex');
+    });
+
+    it('explains a prebuild carrying coinSpecific.allowedStakingContracts with no top-level allowlist', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      const explain = await basecoin.explainTransaction({
+        txHex: tx.toBroadcastFormat(),
+        publicKeys: [resources.TX_SENDER.pub],
+        feeInfo: { fee: '' },
+        coinSpecific: { allowedStakingContracts: testPair },
+      });
+      explain.contractAddress.should.equal(TEST_ADDRESS);
+      explain.contractName.should.equal('pox-5');
+    });
+
+    it('rejects explain when the coinSpecific allowance is absent (fail-closed)', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      await assert.rejects(
+        basecoin.explainTransaction({ txHex: tx.toBroadcastFormat(), feeInfo: { fee: '' } }),
+        /error parsing the raw transaction/
+      );
+    });
+
+    it('verify resolves the prebuild allowance: it gets past parsing and fails only on the pre-existing public-keys gap', async function () {
+      // `verifyTransaction` forwards `coinSpecific` to its internal explain call, so the non-canonical
+      // address is now admitted. It then fails on the PRE-EXISTING gap that it never supplies public
+      // keys to explain (a contract-call build requires them) — unrelated to the allowance, and
+      // deliberately not changed here.
+      const tx = await buildConfiguredRegisterForBond();
+      await assert.rejects(
+        basecoin.verifyTransaction({
+          txPrebuild: { txHex: tx.toBroadcastFormat(), coinSpecific: { allowedStakingContracts: testPair } },
+          txParams: { recipients: [] },
+        } as any),
+        /supply at least 1 public key/
+      );
+    });
+
+    it('verify still fails at parsing when the prebuild allowance is absent (fail-closed)', async function () {
+      const tx = await buildConfiguredRegisterForBond();
+      await assert.rejects(
+        basecoin.verifyTransaction({
+          txPrebuild: { txHex: tx.toBroadcastFormat() },
+          txParams: { recipients: [] },
+        } as any),
+        /error parsing the raw transaction/
+      );
+    });
+  });
+
   it('should explain a fungible token transfer transaction with memo', async function () {
     const explain = await basecoin.explainTransaction({
       txHex: testData.txForExplainFungibleTokenTransfer,

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,51 @@ describe('Stacks: Contract Builder', function () {
         );
       });
 
+      describe('canonical-only validation and the caller-supplied allowlist (SI-2089)', function () {
+        // The PoX-5 test contract lives at a non-canonical address; the SDK has no network-level
+        // allowance, so it is only accepted when the caller supplies it explicitly.
+        const TEST_ADDRESS = 'SP3JVSE4ZB5GMDJP5XBPX7ZB1BG3QDFW7RCEQJDMY';
+        const CANONICAL_ADDRESS = 'SP000000000000000000002Q6VF78';
+
+        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('rejects the test address without a caller allowlist (fail-closed)', function () {
+          const builder = factoryProd.getContractBuilder();
+          builder.contractName('pox-5');
+          (() => builder.contractAddress(TEST_ADDRESS)).should.throw(/Invalid contract address/);
+        });
+
+        it('rejects pox-4 and send-many-memo at the test address (no network allowance)', function () {
+          const pox4 = factoryProd.getContractBuilder();
+          pox4.contractName('pox-4');
+          (() => pox4.contractAddress(TEST_ADDRESS)).should.throw(/Invalid contract address/);
+          const sendMany = factoryProd.getContractBuilder();
+          sendMany.contractName('send-many-memo');
+          (() => sendMany.contractAddress(TEST_ADDRESS)).should.throw(/Invalid contract address/);
+        });
+
+        it('scopes a caller allowlist to the exact (name, address) pair', function () {
+          const builder = factoryProd.getContractBuilder();
+          builder.allowedStakingContracts([{ name: 'pox-5', address: TEST_ADDRESS }]);
+          builder.contractName('pox-4');
+          (() => builder.contractAddress(TEST_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('a signed contract call with args', async () => {
         const builder = initTxBuilder();
         builder.functionArgs([