feat(sdk-coin-polyx): replace placeholder v8 testnet metadata with live RPC

[nvrakesh06]

Summary

• Regenerate testnetV8.ts from testnet-rpc.polymesh.live (specVersion: 8000000, txVersion: 8) — metadata bytes now differ from v7 (no longer a placeholder copy).
• Add scripts/regenerateTestnetV8Material.ts for future refreshes.
• Extend V8TransferBuilder tests: metadata ≠ v7, transferWithMemo encodes call index 0x0528 (HSM method ID 1320).
• Document that mainnetV8.ts remains placeholder until mainnet v8 fork (mainnet still on spec 7004001).
• V8TokenTransferBuilder/V8HexTokenTransferBuilder now build the real v8 settlement arg shape. Previously they reused the v7 portfolios/bare-PortfolioId args against v8 metadata, which throws at build time (Method settlement::addAndAffirmWithMediators expects argument holderSet, but got undefined) — confirmed by re-running the existing test suite. v8 renames portfolios to holderSet and wraps every leg sender/receiver in an AssetHolder enum ({ Portfolio: { did, kind } }). Transaction.toJson() / loadInputsAndOutputs() gained dual-path decoding (v7 bare did, v8 portfolio.did) since the shared Transaction class serves both v7 and v8 SendToken txs.
• Added V8RegisterDidBuilder for identity.registerDid (0x0718) — BitGo's actual v8 DID Registrar path. The existing V8RegisterDidWithCDDBuilder only rebuilds the old cddRegisterDidWithCdd (0x0714) call against v8 metadata. Verified against the real testnetV8Material that registerDid takes only targetAccount (no secondaryKeys/expiry, unlike the CDD path) — this corrects the migration plan's dry-run note, which claimed an identical arg shape.
• Fixed the existing V8TransferBuilder call-index test, which asserted .toBroadcastFormat().method (a plain string — .method is undefined on it) instead of the raw method hex on the unsigned transaction.

All new/changed encode-decode paths were verified against the real committed testnetV8Material metadata registry (call indices, field names, and exact enum-variant casing for encode vs. decode), not just spec/tx version pass-through.

Why

CECHO-1471 shipped V8 builders with v7-mirroring metadata. Real v8 testnet signing requires actual chain metadata so builders emit correct call indices — and, for settlement/DID-registration, the correct v8 argument shape, since those two extrinsics genuinely changed on v8.

Depends on / pairs with

• HSM: feat/CECHO-1473-real-v8-hsm-method-ids-and-parsers (registers method IDs 1320 + 1816)
• WP: feat/CECHO-1471-wp-preserve-v8-builder-material (stops overwriting v8 builder material with IMS v7 metadata)

Follow-ups (not in this PR)

• Regenerate mainnetV8.ts after mainnet fork (~July 22, 2026)
• V8RejectInstructionBuilder — verify settlement.reject_instruction arg diff on v8 (plan §9, still open)
• Confirm with the Polymesh team whether BitGo's platform key must be permissioned on-chain as a DID Registrar before identity.registerDid is accepted (plan §6.2, open question Incorporate API changes #2) — V8RegisterDidBuilder is ready but untested against a live registrar-permissioned key

Test plan

• yarn unit-test for sdk-coin-polyx — 220 passing, 0 failing
• tsc --noEmit clean, eslint clean (0 errors)
• Verified testnetV8Material.metadata !== testnetMaterial.metadata
• Verified V8TokenTransferBuilder encodes holderSet + AssetHolder-wrapped legs and round-trips through decode against real v8 metadata
• Verified V8RegisterDidBuilder encodes call index 0x0718 (identity.registerDid) and round-trips through decode
• Dry-run v8 transfer/token-transfer/registerDid on testnet with Flipt enabled after HSM + WP PRs land

Made with Cursor + Claude Code

[linear-code]

CECHO-1471

[ArunBala-Bitgo]

@claude review this PR

[github-actions]

Claude finished @ArunBala-Bitgo's task —— View job

---

PR Review: Replace placeholder v8 testnet metadata with live RPC

Overall Assessment: ✅ Approved with Minor Comments

This is a well-structured PR that successfully replaces placeholder v8 metadata with real testnet data and implements proper v8 builders. The changes are technically sound with excellent test coverage.

Review Summary

Strengths:

• ✅ Proper v8 metadata integration: Real testnet metadata (spec 8000000, tx 8) replaces placeholder
• ✅ Correct call index handling: transferWithMemo uses v8 call index 0x0528 (HSM method ID 1320)
• ✅ Robust v8 settlement changes: Properly handles portfolios → holderSet rename and AssetHolder enum wrapping
• ✅ Excellent test coverage: Comprehensive tests verify encoding/decoding round-trips against real v8 metadata
• ✅ Clean architecture: New V8RegisterDidBuilder follows existing patterns consistently
• ✅ Dual-path transaction handling: Transaction class correctly handles both v7 and v8 settlement shapes

Key Technical Improvements:

1. v8TokenTransferBuilder (modules/sdk-coin-polyx/src/lib/v8TokenTransferBuilder.ts:47-70)

   • Correctly builds holderSet array and wraps legs in AssetHolder.Portfolio enum
   • Proper handling of v8's renamed settlement arguments vs v7's bare PortfolioId

2. V8RegisterDidBuilder (modules/sdk-coin-polyx/src/lib/v8RegisterDidBuilder.ts)

   • Clean implementation for identity.registerDid (call index 0x0718)
   • Correctly takes only targetAccount (unlike v7 CDD path with secondaryKeys/expiry)
   • Good validation and error handling

3. Transaction dual-path decoding (modules/sdk-coin-polyx/src/lib/transaction.ts:108-110)

   • extractPortfolioDID() helper handles both v7 ({ did }) and v8 ({ portfolio: { did } }) shapes
   • Clean separation of concerns for shared Transaction class

4. Test Quality

   • Tests verify actual call indices against real v8 metadata
   • Round-trip encoding/decoding proves compatibility
   • Validates that v8 metadata genuinely differs from v7 (not placeholder)

Minor Issues/Questions:

1. Schema Consistency (modules/sdk-coin-polyx/src/lib/txnSchema.ts:142)

   • v8 schema uses holderSet but v7 still validates portfolios field - ensure this doesn't cause confusion

2. Error Messages (modules/sdk-coin-polyx/src/lib/v8TokenTransferBuilder.ts:26)

   • assetHolderDID() throws generic Error instead of InvalidTransactionError for consistency

3. Documentation

   • Consider adding JSDoc for the extractPortfolioDID() helper function
   • v8 builders could benefit from more detailed class-level documentation about metadata differences

Security Considerations:

• ✅ No security issues identified
• ✅ Proper input validation throughout
• ✅ No hardcoded secrets or credentials
• ✅ Appropriate error handling for invalid transaction types

Testing:

• ✅ Excellent test coverage with 92+ new test lines
• ✅ Tests validate against real v8 metadata, not mocked data
• ✅ Round-trip encoding/decoding verification
• ✅ Call index verification matches expected HSM method IDs

This PR successfully delivers the v8 metadata integration with high code quality. The implementation is production-ready pending the HSM and WP dependency PRs mentioned in the description.

---

Job Run | Branch: feat/CECHO-1471-real-v8-testnet-metadata