feat(statics): add Pearl to statics and utxo-lib networks

[manojkumar138]

Summary

Defines Pearl's coin identity and network parameters in @bitgo/statics and @bitgo/utxo-lib, and teaches the surrounding UTXO modules that Pearl exists.

No SDK coin class yet — that follows in PR 2. This PR only makes Pearl a known network.

Chain Type

UTXO — Taproot-only (BIP-340 Schnorr signatures, BIP-341 script-path spending with a NUMS internal key). Pearl is a btcd fork.

Taproot-only is the load-bearing detail in this PR. @bitgo/wasm-utxo — already merged and authoritative — supports only p2trLegacy and p2trMusig2 for Pearl:

btc   -> [ p2sh, p2shP2wsh, p2wsh, p2trLegacy, p2trMusig2 ]
ltc   -> [ p2sh, p2shP2wsh, p2wsh ]
pearl -> [ p2trLegacy, p2trMusig2 ]

utxo-lib is made to agree, so BitGoJS never advertises wallet script types the chain layer rejects.

Coin Codes & Tickers

Variant	Coin code	Ticker	utxo-lib network
Mainnet	pearl	PEARL	pearl
Testnet	tpearl	TPEARL	tpearl

Names match @bitgo/wasm-utxo (coinNames: [..., "pearl", "tpearl"]) and indexer-utxo (CoinSymbol.pearl / CoinSymbol.tpearl).

The testnet network is keyed tpearl rather than the usual <name>Test. This is deliberate: wasm-utxo's NetworkName is UtxolibName | CoinName, and its legacy UtxolibName union is frozen for pre-existing coins — Pearl was added only to CoinName. Both pearl and tpearl are valid CoinNames that pass through toCoinName() unchanged, so the naming keeps utxo-lib's NetworkName assignable to wasm-utxo's without needing an upstream release.

Network Parameters

Parameter	Mainnet	Testnet
Bech32m HRP	prl	tprl
BIP-44 coin type	808276	1
Derivation path	m/86'/808276'/0'	m/86'/1'/0'
Decimals	8	8
pubKeyHash / scriptHash / wif	0x00 / 0x05 / 0x80	0x6f / 0xc4 / 0xef

Mainnet reuses Bitcoin's base58 version bytes, so a Bitcoin base58 address is also a structurally valid Pearl address. That is expected and shows up in the utxo-bin fixtures below. In practice Pearl wallets are bech32m-only.

Changes

@bitgo/statics

File	Change
src/base.ts	CoinFamily.PEARL, UnderlyingAsset.PEARL
src/networks.ts	Pearl / PearlTestnet classes + Networks.main/Networks.test entries
src/utxo.ts	pearl / tpearl coin entries with explicit PEARL / TPEARL suffixes and MULTISIG + BULK_TRANSACTION + DISTRIBUTED_CUSTODY features
test/unit/fixtures/expectedColdFeatures.ts	both names added to justMultiSig

@bitgo/utxo-lib

File	Change
src/networks.ts	pearl / tpearl network objects, coins.PEARL, NetworkName union, getMainnet(), isPearl(), supportsSegwit(), supportsTaproot()
src/bitgo/outputScripts.ts	isSupportedScriptType() — Taproot-only guard
src/bitgo/transaction.ts	pearl added to the six Bitcoin-like factory switches

The Pearl block sits between litecoinTest and zcash in the networks object because a test asserts mainnets are ordered alphabetically.

isSupportedScriptType needed an explicit guard rather than a derived answer. It hardcodes p2sh → always true and derives the rest from supportsSegwit/supportsTaproot, so no combination of those two flags can express "Taproot-only". supportsSegwit/supportsTaproot both stay true — those describe chain capability, and Pearl does have both activated; script-type support is the wallet-policy question and now lives where that question is asked.

transaction.ts — Pearl joins bitcoin/bitcoincash/bitcoinsv/bitcoingold/dogecoin/ecash in createTransactionFromBuffer, createPsbtFromBuffer, createPsbtFromTransaction, createPsbtForNetwork, createTransactionBuilderForNetwork, and createTransactionBuilderFromTransaction. Without this, createPsbtForNetwork threw unsupported network.

Deliberately not touched: getDefaultTransactionVersion, setTransactionBuilderDefaults, setPsbtDefaults (Pearl falls to default → version 1, correct for a btcd fork), and the SIGHASH_FORKID switches in UtxoPsbt.ts / UtxoTransaction.ts / signature.ts (Pearl has no forkid, and getDefaultSigHash's default already yields SIGHASH_DEFAULT for p2tr).

@bitgo/utxo-core

src/dustThreshold.ts — Pearl added to getDustRelayLimit (3000 sat/kB) and getSpendSize (Bitcoin group).

Not an assumption: btcd's GetDustThreshold is 3 * totalSize where totalSize = SerializeSize + 41 + 107/WitnessScaleFactor. Applying a 3000 sat/kB rate to that same spend size is arithmetically identical, so Pearl slots into the existing Bitcoin path rather than needing its own branch. Yields 546 sats for a 34-byte non-witness output and 306 sats for a Taproot output — same as BTC.

@bitgo/utxo-bin

src/args/parseNetwork.ts — Pearl added to the hardcoded networkOrder array, which otherwise threw unknown network. Production code, not a test.

Dependency bump

@bitgo/wasm-utxo ^4.21.1 → ^4.27.0 across abstract-utxo, utxo-bin, utxo-core, utxo-descriptors, utxo-ord, utxo-staking. 4.27.0 is the first release carrying pearl/tpearl; the older pin made utxo-lib's widened NetworkName unassignable.

Test fixtures and suites

File	Change
utxo-lib/test/networks.ts	segwit/taproot table; isPearl added to shared pubkey/script/WIF prefix groups and bech32Coins
utxo-lib/test/bitgo/outputScripts.ts	expected script types — ['p2tr', 'p2trMusig2']
utxo-lib/test/address/fixtures/{pearl,tpearl}.json	new — address vectors
utxo-lib/test/bitgo/fixtures/psbt/psbt{,-lite}.pearl.*.json	new — 6 PSBT fixtures
utxo-bin/test/fixtures/formatAddress/*	8 new Pearl fixtures + 50 existing updated
abstract-utxo/test/unit/coins.ts	['pearl', undefined] / ['tpearl', undefined] — no coin class until PR 2
abstract-utxo/test/unit/util/utxoCoins.ts	new hasUtxoCoinForNetwork predicate
abstract-utxo/test/unit/transaction/fixedScript/parsePsbt.ts	filtered by that predicate

The 50 updated utxo-bin fixtures are purely additive — pearl/tpearl appended to candidate-network lists, because Pearl mainnet shares Bitcoin's base58 prefixes. No existing value changed.

Pearl is excluded from three suites that cannot apply to it:

• fixtures_thirdparty/{parse,download}.ts — these pull sighash.json/tx_valid.json from each coin's upstream C++ tree. Pearl is a Go btcd fork with no such vectors.
• integration_local_rpc/parse.ts — needs pre-generated regtest fixtures; the generator has no Pearl node support.
• psbt/Psbt.ts (extractP2msOnlyHalfSignedTx) and psbt/SignVerifyLegacy.ts — P2MS-only by definition, and the legacy suite's fixed output set assumes several legacy-signable inputs where Pearl contributes one.

Verification

All eight affected modules, zero failures:

Module	Result
statics	32180 passing
utxo-lib	4470 passing
utxo-core	239 passing
abstract-utxo	1553 passing
utxo-bin	245 passing
utxo-descriptors	35 passing
utxo-ord	173 passing
utxo-staking	59 passing

utxo-descriptors, utxo-ord, utxo-staking, blockapis, and unspents pass untouched. All modules build clean; prettier and eslint clean. Address and PSBT fixtures confirmed deterministic (deleted, regenerated, byte-identical).

Dependencies

Already merged upstream:

• BitGo/wasm-utxo#328 — Pearl network support ✅
• BitGo/indexer-utxo#957 — Pearl coin support ✅

Follow-ups

• PR 2 — abstract-utxo Prl/Tprl classes + sdk-coin-pearl. Since Pearl is Taproot-only, those classes will need to expose only p2tr / p2trMusig2 rather than inheriting AbstractUtxoCoin's defaults.
• PR 3 — coinFactory + bitgo module registration.
• Pearl has no round-trip transaction coverage in utxo-lib yet; generating regtest fixtures needs a Pearl node in integration_local_rpc/generate.

Related

• Ticket: CECHO-1780 (Duplex BitGoJS)
• TDD: Duplex/Pearl full onboarding
• Part 1 of 3

🤖 Generated with Claude Code

[linear-code]

CECHO-1780

[manojkumar138]

@claude review

[github-actions]

Claude finished @manojkumar138's task —— View job

---

Code Review - Pearl (PEARL) Integration

✅ Completed Reviews

1. Base Configuration (modules/statics/src/base.ts) ✅

• Pearl coin family properly added to CoinFamily enum (line 113)
• Pearl underlying asset properly added to UnderlyingAsset enum (line 1688)
• Integration follows existing patterns correctly

2. Network Classes (modules/statics/src/networks.ts) ✅

• Pearl mainnet network class properly implemented (lines 1434-1439)
• PearlTestnet network class properly implemented (lines 1441-1446)
• Both implement UtxoNetwork interface correctly
• Networks registered in Networks.main and Networks.test objects
• Explorer URLs set to undefined (appropriate for new network)

3. UTXO Coin Definitions (modules/statics/src/utxo.ts) ✅

• PEARL_FEATURES properly defined (lines 146-151) with appropriate feature set:
  • All default UTXO features included
  • MULTISIG, BULK_TRANSACTION, DISTRIBUTED_CUSTODY added
• Pearl mainnet entry properly configured (lines 329-339):
  • UUID: 4518a5b9-00d3-476e-bc40-d3f87eb82250
  • Name: pearl / Display: Pearl
  • Uses correct network reference and asset
  • Suffix: PEARL
• Pearl testnet entry properly configured (lines 340-350):
  • UUID: 5d88723a-7e86-43c7-9fb1-f4cee7abc48f
  • Name: tpearl / Display: Testnet Pearl
  • Suffix: TPEARL

4. UTXO-lib Network Configuration (modules/utxo-lib/src/networks.ts) ✅

• Pearl coin properly added to coins object (line 36)
• NetworkName type extended with pearl and tpearl (lines 59-60)
• Pearl mainnet network properly configured (lines 334-342):
  • Message prefix: \x18Pearl Signed Message:\n
  • Bech32 HRP: prl ✅ (matches spec)
  • Standard Bitcoin-compatible key derivation
• Pearl testnet network properly configured (lines 343-351):
  • Bech32 HRP: tprl ✅ (matches spec)
  • Standard testnet configuration
• getMainnet() function updated to handle Pearl networks (lines 436-438)
• isPearl() helper function added (lines 563-565)
• Taproot support properly enabled (line 598) ✅
• SegWit support properly enabled (line 592) ✅

5. Test Fixtures and Validation ✅

• Comprehensive address test fixtures present for both networks
• Pearl mainnet addresses use prl1 prefix ✅
• Pearl testnet addresses use tprl1 prefix ✅
• Address formats properly support:
  • P2PKH (legacy addresses)
  • P2WPKH (SegWit v0)
  • P2TR (Taproot) ✅
  • P2TR-MuSig2 (Taproot multisig) ✅
• PSBT test fixtures comprehensive, including unsigned/half-signed/full-signed
• Format fixtures for address display

🎯 Key Validation Points ✅

1. Taproot-only Focus: Pearl properly configured as Taproot-enabled coin
2. Bech32m Addresses: Correct HRP prefixes (prl/tprl) implemented
3. Network Parameters: Standard Bitcoin-compatible parameters used
4. Feature Set: Appropriate features enabled (multisig, bulk transactions, distributed custody)
5. Test Coverage: Comprehensive test fixtures for all address types and transaction formats
6. Integration Consistency: All components properly reference each other

📊 Review Summary

Status: ✅ APPROVED

The Pearl (PEARL) cryptocurrency integration is well-implemented and complete. The implementation properly follows BitGo's established patterns and includes:

• Complete statics configuration across all required modules
• Proper UTXO network definitions with Taproot support
• Comprehensive test coverage with correct address formats
• Consistent naming and referencing across all components

The integration correctly implements Pearl as a Taproot-enabled UTXO coin with bech32m addressing (prl/tprl prefixes) and includes all necessary features for BitGo wallet functionality.

No issues identified. Ready for merge.