feat(statics): add TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY CoinFeatures

Add two new values to the CoinFeature enum in @bitgo/statics:

- TOKENIZED_EQUITY: economic-nature marker for any tokenized stock.
  Drives generic behavior (pricing off the underlying, asset-class
  reporting). May be set for BitGo-issued or third-party tokens.
- BITGO_TOKENIZED_EQUITY: BitGo first-party permissioned goStocks
  marker. Drives whitelist-destination withdrawal validation and
  allowlist/segregation behavior. Requires TOKENIZED_EQUITY to also
  be set (invariant enforced in BaseCoin.validateOptions).

Apply both flags to all goSPCX representations:
  sol:gospcx, tsol:gospcx, tsol:stggospcx (on-chain tokens) and
  ofcsol:gospcx, ofctsol:gospcx, ofctsol:stggospcx (OFC mirrors).

No other goStock tokens receive these flags in this ticket;
behavioral enforcement (withdrawal allowlist checks) is out of scope
and tracked in TDD §13.4.

Ticket: SCAAS-10372
Session-Id: a4128cc9-058b-4a15-ab67-160780260e8a
Task-Id: a0f7361a-becc-4c21-ab18-99920c0c7a35

Author: BitGo Agent

modules/statics/src/base.ts

@@ -602,6 +602,20 @@ export enum CoinFeature {
    * This coin supports bring-your-own-validator (BYOV) staking
    */
   BYOV_VALIDATOR = 'byov-validator',
+
+  /**
+   * This coin is a tokenized equity (e.g. a tokenized stock). Drives generic
+   * behavior such as pricing off the underlying and asset-class reporting.
+   * May be set for both BitGo-issued and third-party tokenized equities.
+   */
+  TOKENIZED_EQUITY = 'tokenized-equity',
+
+  /**
+   * This coin is a BitGo first-party permissioned tokenized equity (a goStock).
+   * Drives whitelist-destination withdrawal validation and allowlist/segregation
+   * behavior. MUST only be set together with TOKENIZED_EQUITY.
+   */
+  BITGO_TOKENIZED_EQUITY = 'bitgo-tokenized-equity',
 }
 
 /**
@@ -4623,6 +4637,12 @@ export abstract class BaseCoin {
       throw new MissingRequiredCoinFeatureError(options.name, Array.from(requiredFeatures));
     }
 
+    // BITGO_TOKENIZED_EQUITY requires TOKENIZED_EQUITY to also be present
+    const featureSet = new Set(options.features);
+    if (featureSet.has(CoinFeature.BITGO_TOKENIZED_EQUITY) && !featureSet.has(CoinFeature.TOKENIZED_EQUITY)) {
+      throw new MissingRequiredCoinFeatureError(options.name, [CoinFeature.TOKENIZED_EQUITY]);
+    }
+
     // assets require a valid uuid v4 id
     if (!BaseCoin.isValidUuidV4(options.id)) {
       throw new InvalidIdError(options.name, options.id);

modules/statics/src/coins/ofcCoins.ts

@@ -1644,7 +1644,7 @@ export const ofcCoins = [
     'SPCX goStock',
     6,
     UnderlyingAsset['sol:gospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN]
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY]
   ),
   ofcsolToken(
     'e343b3c2-dcbb-4a9f-a60e-3dd79825c5fb',
@@ -2034,15 +2034,15 @@ export const ofcCoins = [
     'Test SPCX goStock',
     6,
     UnderlyingAsset['tsol:stggospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN]
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY]
   ),
   tofcsolToken(
     '84f901ed-5654-47a7-9d08-7ff7c27a8c16',
     'ofctsol:gospcx',
     'Test SPCX goStock',
     6,
     UnderlyingAsset['tsol:gospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN]
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY]
   ),
   tofcsolToken(
     '750f0e40-c5b9-464f-874f-dc455cf1494b',

modules/statics/src/coins/solTokens.ts

@@ -3686,7 +3686,7 @@ export const solTokens = [
     '98iaHRfvCnaihEHcLK5EpwLq3w5yHiKKfSgpYLcxEScB',
     '98iaHRfvCnaihEHcLK5EpwLq3w5yHiKKfSgpYLcxEScB',
     UnderlyingAsset['tsol:stggospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN],
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY],
     ProgramID.Token2022ProgramId
   ),
   tsolToken(
@@ -3697,7 +3697,7 @@ export const solTokens = [
     '4gvEw3Lx2gkAByv4X8hLnHujneN5bwtMGSu2ZDoip4vj',
     '4gvEw3Lx2gkAByv4X8hLnHujneN5bwtMGSu2ZDoip4vj',
     UnderlyingAsset['tsol:gospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN],
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY],
     ProgramID.Token2022ProgramId
   ),
   solToken(
@@ -3708,7 +3708,7 @@ export const solTokens = [
     'AAVvaNDwkGfxGNaf1HJ5JzfwDb1PYmAgXSixRsczyrk4',
     'AAVvaNDwkGfxGNaf1HJ5JzfwDb1PYmAgXSixRsczyrk4',
     UnderlyingAsset['sol:gospcx'],
-    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN],
+    [...SOL_TOKEN_FEATURES, CoinFeature.STABLECOIN, CoinFeature.TOKENIZED_EQUITY, CoinFeature.BITGO_TOKENIZED_EQUITY],
     ProgramID.Token2022ProgramId
   ),
   tsolToken(

modules/statics/test/unit/base.ts

@@ -1,7 +1,8 @@
-import { CoinFamily } from '../../src';
+import { CoinFamily, CoinFeature, coins } from '../../src';
 
 const should = require('should');
 const { UnderlyingAsset } = require('../../src/base');
+const { solToken, ProgramID } = require('../../src/account');
 
 describe('UnderlyingAsset', function () {
   it('UnderlyingAsset values should be unique', function () {
@@ -36,3 +37,88 @@ describe('zkSync Era Base Types', function () {
     UnderlyingAsset.ZKSYNCERA.should.equal('zksyncera');
   });
 });
+
+describe('Tokenized Equity CoinFeatures', function () {
+  it('TOKENIZED_EQUITY feature value should be tokenized-equity', function () {
+    CoinFeature.TOKENIZED_EQUITY.should.equal('tokenized-equity');
+  });
+
+  it('BITGO_TOKENIZED_EQUITY feature value should be bitgo-tokenized-equity', function () {
+    CoinFeature.BITGO_TOKENIZED_EQUITY.should.equal('bitgo-tokenized-equity');
+  });
+
+  it('sol:gospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('sol:gospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('tsol:gospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('tsol:gospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('tsol:stggospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('tsol:stggospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('ofcsol:gospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('ofcsol:gospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('ofctsol:gospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('ofctsol:gospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('ofctsol:stggospcx should have both TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY', function () {
+    const coin = coins.get('ofctsol:stggospcx');
+    coin.features.should.containEql(CoinFeature.TOKENIZED_EQUITY);
+    coin.features.should.containEql(CoinFeature.BITGO_TOKENIZED_EQUITY);
+  });
+
+  it('invariant: BITGO_TOKENIZED_EQUITY without TOKENIZED_EQUITY should throw MissingRequiredCoinFeatureError', function () {
+    let threw = false;
+    let errorMessage = '';
+    let errorType = '';
+    try {
+      solToken(
+        '00000000-0000-0000-0000-000000000001',
+        'test:invalidgostock',
+        'Invalid goStock',
+        6,
+        'AAVvaNDwkGfxGNaf1HJ5JzfwDb1PYmAgXSixRsczyrk4',
+        'AAVvaNDwkGfxGNaf1HJ5JzfwDb1PYmAgXSixRsczyrk4',
+        UnderlyingAsset['sol:gospcx'],
+        [
+          CoinFeature.ACCOUNT_MODEL,
+          CoinFeature.REQUIRES_BIG_NUMBER,
+          CoinFeature.VALUELESS_TRANSFER,
+          CoinFeature.TRANSACTION_DATA,
+          CoinFeature.CUSTODY,
+          CoinFeature.CUSTODY_BITGO_TRUST,
+          CoinFeature.TSS,
+          CoinFeature.TSS_COLD,
+          CoinFeature.BULK_TRANSACTION,
+          CoinFeature.BITGO_TOKENIZED_EQUITY,
+        ],
+        ProgramID.Token2022ProgramId
+      );
+    } catch (err: unknown) {
+      threw = true;
+      if (err instanceof Error) {
+        errorMessage = err.message;
+        errorType = err.constructor.name;
+      }
+    }
+    threw.should.be.true();
+    errorType.should.equal('MissingRequiredCoinFeatureError');
+    errorMessage.should.containEql('tokenized-equity');
+  });
+});