feat(sdk-coin-polyx): add v8 metadata and base V8 builders

[bitgo-ai-agent-dev]

What

• Add src/resources/mainnetV8.ts and src/resources/testnetV8.ts: Polymesh v8 material with specVersion: 8000000 and txVersion: 8 (metadata bytes mirror v7 as a placeholder; will be replaced with actual v8 chain metadata once it is live).
• Add getV8Material() helper in utils.ts returning the correct v8 material by network type.
• Add six V8-prefixed builder classes (thin subclasses that swap in v8 material):
  • V8TransferBuilder — balances.transferWithMemo
  • V8HexTransferBuilder — balances.transferWithMemo with hex memo encoding
  • V8RegisterDidWithCDDBuilder — identity.cddRegisterDidWithCdd
  • V8TokenTransferBuilder — settlement.addAndAffirmWithMediators
  • V8HexTokenTransferBuilder — settlement.addAndAffirmWithMediators with hex memo
  • V8PreApproveAssetBuilder — asset.preApproveAsset
• Add six getV8*Builder() factory methods to TransactionBuilderFactory.
• Export all V8 builders from src/lib/index.ts.
• Remove stray console.log debug artifact from PreApproveAssetBuilder.
• Add 25 unit tests verifying v8 material, factory methods, and correct specVersion/txVersion in tx output.

Why

Polymesh is migrating its chain runtime from spec version 7 to version 8 (Polymesh v8 Migration, BASE-2). Downstream services (HSM, wallet-platform, indexer) need dedicated V8 builder classes and factory methods to construct and sign v8 transactions independently of the existing v7 builders — ensuring zero disruption to in-flight v7 traffic during the cutover period.

Test plan

• tsc --noEmit — zero TypeScript errors
• mocha --grep 'V8' — 25 new unit tests all pass
• Full unit suite — 197 passing, 1 pre-existing credential-gated failure unrelated to this change

Ticket: CECHO-1471

[linear-code]

CECHO-1471

[nvrakesh06]

@claude review

[github-actions]

Claude finished @nvrakesh06's task —— View job

---

Code Review Summary

Overall Assessment: ✅ APPROVED - This is a well-structured, focused PR that cleanly implements Polymesh v8 support through a sensible pattern of inheritance-based V8 builders.

---

Architecture & Design

✅ Excellent separation of concerns: The PR uses a clean inheritance pattern where V8 builders are thin wrappers that swap in v8 material while inheriting all behavior from their v7 counterparts.

✅ Consistent naming convention: All V8 builders follow the V8*Builder pattern.

✅ Proper abstraction: The getV8Material() helper in utils.ts:80-84 centralizes material selection logic.

---

Implementation Quality

✅ Minimal, focused changes: Each V8 builder is just ~15 lines and follows the exact same pattern:

export class V8TransferBuilder extends TransferBuilder {
  constructor(_coinConfig: Readonly<CoinConfig>) {
    super(_coinConfig);
    this.material(utils.getV8Material(_coinConfig.network.type));
  }
}

✅ Correct metadata structure: The v8 material files use:

• specVersion: 8000000 (significantly higher than v7)
• txVersion: 8 (proper versioning)

✅ Clean factory integration: The 6 new factory methods in transactionBuilderFactory.ts:91-113 follow existing patterns and don't call .material() since V8 builders set it in their constructors.

✅ Proper exports: All V8 builders are correctly exported from src/lib/index.ts:27-32.

---

Code Quality

✅ Cleanup included: Removed stray console.log debug artifact from preApproveAssetBuilder.ts:77.

✅ Type safety: All builders maintain proper typing through inheritance.

✅ Documentation: Each V8 builder has clear JSDoc explaining its purpose and relationship to the base class.

---

Test Coverage

✅ Comprehensive testing: 25 new unit tests across 6 test files covering:

• Material verification (specVersion/txVersion)
• Factory method functionality
• Transaction building with correct v8 metadata in output
• Memo encoding behavior (for hex variants)

✅ Test quality: Tests properly verify the key requirement - that built transactions carry v8 specVersion/txVersion:

should.deepEqual(txJson.specVersion, testnetV8Material.specVersion);
should.deepEqual(txJson.transactionVersion, testnetV8Material.txVersion);

---

Migration Strategy

✅ Zero-disruption approach: This design allows downstream services to migrate gradually:

• V7 builders continue working unchanged
• V8 builders provide parallel functionality
• No breaking changes to existing APIs

---

Potential Improvements (Minor)

1. Metadata placeholder: The PR mentions metadata bytes mirror v7 as placeholder. Ensure this gets updated when actual v8 chain metadata is available.

2. Version validation: Consider adding runtime validation that v8 specVersion > v7 specVersion to catch configuration errors.

---

Verdict

This PR demonstrates excellent software engineering practices:

• Clean, maintainable architecture
• Consistent implementation patterns
• Comprehensive test coverage
• Clear documentation
• Safe migration strategy

The inheritance-based approach is the right design choice here, avoiding code duplication while providing the needed v8 functionality. Ready to merge once v8 chain metadata becomes available.

---

Job Run: View Logs