feat(statics): add TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY CoinFeatures

[bitgo-ai-agent-dev]

What

• Add TOKENIZED_EQUITY (tokenized-equity) to the CoinFeature enum in @bitgo/statics: economic-nature marker for any tokenized stock (BitGo-issued or third-party). Drives generic behavior — pricing off the underlying, asset-class reporting.
• Add BITGO_TOKENIZED_EQUITY (bitgo-tokenized-equity) to CoinFeature: BitGo first-party permissioned goStocks marker. Drives whitelist-destination withdrawal validation and allowlist/segregation behavior.
• Enforce invariant in BaseCoin.validateOptions: a coin that has BITGO_TOKENIZED_EQUITY must also have TOKENIZED_EQUITY; violating this throws MissingRequiredCoinFeatureError.
• 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).
• Add unit tests covering enum values, per-coin presence, and the invariant.

Why

• TDD §4.1 "Coin-feature tagging (near-term)": tactical tagging of tokenized equities is needed to drive downstream behaviors (pricing, reporting, withdrawal allowlist checks) scoped to goSPCX.
• AMS's convertStringsToCoinFeatures() silently drops unknown strings, so the enum values must exist before AMS config can carry these flags. No downstream schema changes are required once the enum is in place.
• Behavioral enforcement (withdrawal destination-allowlist checks) is out of scope for this ticket and tracked in TDD §13.4.

Decision log

1. Invariant placement (base.ts:validateOptions vs. a separate utility): Added the BITGO_TOKENIZED_EQUITY → TOKENIZED_EQUITY check directly in BaseCoin.validateOptions. This is the single entry point for all coin construction and is where all other feature-constraint checks already live (requiredFeatures, disallowedFeatures). A separate utility would be easy to forget.

2. Which goSPCX tokens to tag: The ticket says "every representation of that token: the sol: mainnet token, the tsol: testnet twin, and the ofc: mirror." There are two testnet variants (tsol:gospcx and tsol:stggospcx) — both refer to the same goSPCX token on different testnet deployments and both already carry STABLECOIN, so both received the new flags for consistency.

3. Replacing STABLECOIN: The ticket does not ask to remove the existing STABLECOIN feature from goSPCX. The STABLECOIN flag is left in place to avoid breaking any downstream consumers that depend on it until a formal deprecation plan is in place. The new flags are additive.

Test evidence

Unit tests in test/unit/base.ts covering:

• TOKENIZED_EQUITY enum value = 'tokenized-equity' ✓
• BITGO_TOKENIZED_EQUITY enum value = 'bitgo-tokenized-equity' ✓
• sol:gospcx, tsol:gospcx, tsol:stggospcx, ofcsol:gospcx, ofctsol:gospcx, ofctsol:stggospcx each have both features ✓
• Invariant: constructing a coin with BITGO_TOKENIZED_EQUITY but without TOKENIZED_EQUITY throws an error mentioning 'tokenized-equity' ✓

TypeScript compilation (npx tsc --noEmit) passes with zero errors.

CI fix: initial run had 1 failing test — invariant: BITGO_TOKENIZED_EQUITY without TOKENIZED_EQUITY should throw MissingRequiredCoinFeatureError — because should.throws(fn, callbackFn) triggers TypeError: Function has non-object prototype 'undefined' in instanceof check in Node 20/22/24 when the error class prototype isn't fully resolved across module boundaries. Replaced with an explicit try/catch that captures threw and errorMessage then asserts both.

Copilot review

No Copilot review yet (first CI round still running).

Open questions

None.

Ticket: SCAAS-10372

[linear-code]

SCAAS-10372

[bitgo-ai-agent-dev]

@claude Please review this PR.

[bitgo-ai-agent-dev]

Requesting a Copilot review.

[Copilot]

Pull request overview

Adds new CoinFeature markers in @bitgo/statics for tokenized equities (generic) and BitGo-issued permissioned tokenized equities (goStocks), and enforces a construction-time invariant to keep these features consistent across coin definitions.

Changes:

• Introduces TOKENIZED_EQUITY and BITGO_TOKENIZED_EQUITY in CoinFeature.
• Enforces BITGO_TOKENIZED_EQUITY ⇒ TOKENIZED_EQUITY in BaseCoin.validateOptions via MissingRequiredCoinFeatureError.
• Tags all goSPCX representations (SOL + OFC mirrors, mainnet + testnet variants) with both features and adds unit tests for enum values, tagging, and the invariant.

Reviewed changes

Copilot reviewed 4 out of 4 changed files in this pull request and generated 1 comment.

File	Description
modules/statics/src/base.ts	Adds the two new CoinFeature enum values and enforces the BITGO_TOKENIZED_EQUITY → TOKENIZED_EQUITY invariant during coin construction.
modules/statics/src/coins/solTokens.ts	Applies both features to SOL-chain goSPCX token definitions (mainnet + testnet variants).
modules/statics/src/coins/ofcCoins.ts	Applies both features to OFC mirror coin definitions for goSPCX (mainnet + testnet variants).
modules/statics/test/unit/base.ts	Adds unit tests validating enum values, per-coin tagging, and the invariant behavior.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[bitgo-ai-agent-dev]

Copilot review (round 1) — addressed:

• Copilot comment: Changed catch (err: any) → catch (err: unknown), added errorType captured via err.constructor.name (guarded by instanceof Error), and added assertion errorType.should.equal('MissingRequiredCoinFeatureError') for stronger type verification without fragile cross-module instanceof checks.

[bitgo-ai-agent-dev]

@claude Please re-review this PR.