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.

[Copilot]

Pull request overview

This PR introduces Pearl (pearl / tpearl) as a recognized UTXO network across BitGoJS’ statics + UTXO stack (statics, utxo-lib, utxo-core, utxo-bin, abstract-utxo tests), including Taproot-only wallet script-type enforcement to match @bitgo/wasm-utxo behavior.

Changes:

• Adds Pearl network definitions (mainnet/testnet) and detection helpers in @bitgo/utxo-lib, including Taproot-only script-type gating in outputScripts.isSupportedScriptType.
• Registers Pearl coin metadata in @bitgo/statics (family/asset/network/utxo coin entries + expectedColdFeatures).
• Updates dust threshold logic, CLI network parsing order, tests, and extensive address/PSBT fixtures; bumps @bitgo/wasm-utxo to ^4.27.0 across affected modules.

Reviewed changes

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

Show a summary per file

File	Description
yarn.lock	Bumps @bitgo/wasm-utxo and updates transitive lock entries.
modules/utxo-staking/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/utxo-ord/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/utxo-descriptors/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/utxo-core/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/utxo-bin/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/abstract-utxo/package.json	Bumps @bitgo/wasm-utxo to ^4.27.0.
modules/statics/src/base.ts	Adds CoinFamily.PEARL and UnderlyingAsset.PEARL.
modules/statics/src/networks.ts	Adds Pearl mainnet/testnet network objects to Networks.
modules/statics/src/utxo.ts	Adds pearl/tpearl UTXO coin entries and feature set.
modules/statics/test/unit/fixtures/expectedColdFeatures.ts	Adds pearl/tpearl to expected cold-feature fixtures.
modules/utxo-lib/src/networks.ts	Adds pearl/tpearl networks, NetworkName union updates, and helpers (isPearl, segwit/taproot support).
modules/utxo-lib/src/bitgo/outputScripts.ts	Enforces Taproot-only script type support for Pearl via isSupportedScriptType.
modules/utxo-lib/src/bitgo/transaction.ts	Enables transaction/PSBT factory support for networks.pearl.
modules/utxo-core/src/dustThreshold.ts	Treats Pearl like BTC-group for dust relay limit and spend size.
modules/utxo-core/test/dustThreshold.ts	Adds Pearl expected dust-threshold test vectors.
modules/utxo-bin/src/args/parseNetwork.ts	Adds Pearl to the CLI network ordering (mainnet group).
modules/utxo-lib/test/networks.ts	Extends network property-sharing groups and feature expectation table for Pearl.
modules/utxo-lib/test/bitgo/outputScripts.ts	Adds expected script types for Pearl (p2tr, p2trMusig2).
modules/utxo-lib/test/integration_local_rpc/parse.ts	Skips Pearl in regtest fixture suite until generator supports it.
modules/utxo-lib/test/fixtures_thirdparty/parse.ts	Excludes Pearl from third-party fixture parsing.
modules/utxo-lib/test/fixtures_thirdparty/download.ts	Excludes Pearl from third-party fixture downloads.
modules/utxo-lib/test/bitgo/psbt/Psbt.ts	Skips a p2ms-only extraction suite for Pearl.
modules/utxo-lib/test/bitgo/psbt/SignVerifyLegacy.ts	Skips legacy PSBT signing suite for taproot-only Pearl.
modules/utxo-lib/test/address/fixtures/pearl.json	Adds Pearl address vectors.
modules/utxo-lib/test/address/fixtures/tpearl.json	Adds Pearl testnet address vectors.
modules/utxo-lib/test/bitgo/fixtures/psbt/psbt.pearl.unsigned.json	Adds Pearl PSBT fixture (unsigned).
modules/utxo-lib/test/bitgo/fixtures/psbt/psbt.pearl.halfsigned.json	Adds Pearl PSBT fixture (half-signed).
modules/utxo-lib/test/bitgo/fixtures/psbt/psbt-lite.pearl.unsigned.json	Adds Pearl “lite” PSBT fixture (unsigned).
modules/utxo-lib/test/bitgo/fixtures/psbt/psbt-lite.pearl.halfsigned.json	Adds Pearl “lite” PSBT fixture (half-signed).
modules/abstract-utxo/test/unit/coins.ts	Documents Pearl networks as lacking coin classes yet (undefined).
modules/abstract-utxo/test/unit/util/utxoCoins.ts	Adds hasUtxoCoinForNetwork predicate for tests.
modules/abstract-utxo/test/unit/transaction/fixedScript/parsePsbt.ts	Filters AcidTest suite by hasUtxoCoinForNetwork.
modules/utxo-bin/test/fixtures/formatAddress/pearl_p2pkh_default_1LCVrCgbT26Ui1QyrhaGvvhrkVdDRAXxtt.txt	Adds Pearl formatAddress fixture (p2pkh).
modules/utxo-bin/test/fixtures/formatAddress/pearl_p2wkh_default_prl1q62tshlryz9lrjlw9edaf4l5l3v3deg03gw29k2.txt	Adds Pearl formatAddress fixture (p2wkh).
modules/utxo-bin/test/fixtures/formatAddress/pearl_p2tr_default_prl1p8gv9m64s539mycj4m29wu8thy5n3y6u36xs58wq3yezrmqygwfns2yff0j.txt	Adds Pearl formatAddress fixture (p2tr).
modules/utxo-bin/test/fixtures/formatAddress/pearl_p2trMusig2_default_prl1p5xqvqger0zdpcq6s3jznfz352exhk356p9hml6c69matmggrve9sq7apju.txt	Adds Pearl formatAddress fixture (p2trMusig2).
modules/utxo-bin/test/fixtures/formatAddress/tpearl_p2pkh_default_mziT9FmaG3XjV7tbaGYekqvBcVDvGnY3EZ.txt	Adds tpearl formatAddress fixture (p2pkh).
modules/utxo-bin/test/fixtures/formatAddress/tpearl_p2wkh_default_tprl1q62tshlryz9lrjlw9edaf4l5l3v3deg03lufv9q.txt	Adds tpearl formatAddress fixture (p2wkh).
modules/utxo-bin/test/fixtures/formatAddress/tpearl_p2tr_default_tprl1p8gv9m64s539mycj4m29wu8thy5n3y6u36xs58wq3yezrmqygwfnsptdhs8.txt	Adds tpearl formatAddress fixture (p2tr).
modules/utxo-bin/test/fixtures/formatAddress/tpearl_p2trMusig2_default_tprl1p5xqvqger0zdpcq6s3jznfz352exhk356p9hml6c69matmggrve9st3eldf.txt	Adds tpearl formatAddress fixture (p2trMusig2).
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2pkh_default_1LCVrCgbT26Ui1QyrhaGvvhrkVdDRAXxtt.txt	Updates network candidate list to include Pearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2pkh_default_1LCVrCgbT26Ui1QyrhaGvvhrkVdDRAXxtt.all.txt	Updates converted network list to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2sh_default_361UWADXqgPsdf8L5Jga6GNPauMuBtT1eW.txt	Updates network candidate list to include Pearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2sh_default_361UWADXqgPsdf8L5Jga6GNPauMuBtT1eW.all.txt	Updates converted network list to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2shP2wsh_default_33qtbAwm4ooBtMQenssbqDE1J4gSMMBRnb.txt	Updates network candidate list to include Pearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2shP2wsh_default_33qtbAwm4ooBtMQenssbqDE1J4gSMMBRnb.all.txt	Updates converted network list to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2tr_default_bc1p8gv9m64s539mycj4m29wu8thy5n3y6u36xs58wq3yezrmqygwfnsjhucex.all.txt	Adds Pearl/tpearl conversions for taproot addresses.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2trMusig2_default_bc1p5xqvqger0zdpcq6s3jznfz352exhk356p9hml6c69matmggrve9scdgsyg.all.txt	Adds Pearl/tpearl conversions for taproot-musig2 addresses.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2wkh_default_bc1q62tshlryz9lrjlw9edaf4l5l3v3deg034uw28c.all.txt	Adds Pearl/tpearl conversions for segwit v0 addresses.
modules/utxo-bin/test/fixtures/formatAddress/bitcoin_p2wsh_default_bc1qeu6xmet5wqslj2w0wac0hx5gj6dupmp869cajrkt3kw6ud3kkecsdzf7hn.all.txt	Adds Pearl/tpearl conversions for segwit v0 scripts.
modules/utxo-bin/test/fixtures/formatAddress/testnet_p2pkh_default_mziT9FmaG3XjV7tbaGYekqvBcVDvGnY3EZ.txt	Updates candidate network lists to include tpearl where prefixes collide.
modules/utxo-bin/test/fixtures/formatAddress/testnet_p2sh*_default_2M*.txt	Updates candidate network lists to include tpearl where prefixes collide.
modules/utxo-bin/test/fixtures/formatAddress/cash_*.all.txt	Updates converted network list to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/sv_*	Updates network candidate lists to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/bch_*	Updates network candidate lists to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/btg_*	Updates network candidate lists to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/doge_*	Updates network candidate lists to include tpearl.
modules/utxo-bin/test/fixtures/formatAddress/ecash_*	Updates network candidate lists to include Pearl/tpearl.
modules/utxo-bin/test/fixtures/formatAddress/litecoinTest_*	Updates network candidate lists to include tpearl.

---

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