CSHLD-1652: Build @bitgo/abstract-utxo to expose new ZEC address helper exports

[abhi-bitgo]

Summary

Extends Zec.isValidAddress to recognize well-formed ZIP-316 Unified Addresses (Sapling/Orchard) in addition to transparent addresses, and adds standalone helpers for classifying/validating Zcash addresses without needing a coin/SDK instance.

Linear: CSHLD-1652

Changes

• modules/abstract-utxo/src/impl/zec/address.ts (new): isShieldedZcashAddress, getZcashAddressKind, isValidZcashAddress
• modules/abstract-utxo/src/impl/zec/zec.ts: Zec.isValidAddress now falls back to shielded-address recognition
• modules/abstract-utxo/src/impl/zec/index.ts: re-export the new address module
• modules/abstract-utxo/test/unit/impl/zec/unit/address.ts (new): unit tests covering transparent/shielded/garbage/cross-network cases

Test Plan

• yarn unit-test --scope abstract-utxo (new address.ts test suite passes)
• tsc --noEmit and yarn lint clean

[linear-code]

CSHLD-1652

[abhi-bitgo]

@claude review this pr

[github-actions]

Claude finished @abhi-bitgo's task —— View job

---

PR Review: CSHLD-1652 - Build @bitgo/abstract-utxo to expose new ZEC address helper exports

Overview ✅

This PR successfully extends Zcash address validation to support ZIP-316 Unified Addresses (shielded addresses) while maintaining backward compatibility with transparent addresses. The implementation is clean, well-documented, and thoroughly tested.

Code Quality Analysis

✅ Strengths:

1. Clean Architecture - The new address.ts module provides standalone utility functions that are well-separated from the coin implementation, making them reusable across the codebase.

2. Robust Error Handling - Proper try-catch blocks with fallback logic in modules/abstract-utxo/src/impl/zec/address.ts:26-35. The functions gracefully handle invalid addresses by catching exceptions and returning appropriate values.

3. Type Safety - Good use of TypeScript with the ZcashAddressKind type and proper return types throughout.

4. Comprehensive Testing - The test suite in modules/abstract-utxo/test/unit/impl/zec/unit/address.ts covers:

   • Mainnet unified addresses
   • Testnet unified addresses
   • Transparent addresses
   • Cross-network validation (rejecting mainnet address on testnet)
   • Invalid/garbage input handling

5. Backward Compatibility - The Zec.isValidAddress implementation in modules/abstract-utxo/src/impl/zec/zec.ts:23-28 properly extends the base class method with fallback logic.

⚠️ Areas for Improvement:

1. Documentation Clarity - The comment in modules/abstract-utxo/src/impl/zec/address.ts:27-29 about ZcashNetworkName permitting 'zcash'/'zcashTest' could be clearer. Consider adding a brief explanation of why this behavior exists.

2. Type Casting Safety - The cast network as CoinName in modules/abstract-utxo/src/impl/zec/address.ts:30 is documented but could potentially be error-prone. Consider adding runtime validation or a helper function.

3. Test Vector Source - While the ZIP-316 test vectors are well-documented as coming from BitGoWASM, consider adding a comment with the specific commit hash or version for traceability.

Security Considerations ✅

• Input Validation: All functions properly validate input addresses before processing
• No Direct Buffer Operations: Uses safe WASM library calls instead of manual parsing
• Network Isolation: Properly validates addresses against the correct network to prevent cross-network confusion

Performance Considerations ✅

• Efficient Fallback Logic: The transparent address check happens first (faster path), then falls back to shielded validation
• Exception Handling: Uses exceptions for control flow appropriately, as parsing failures are expected for invalid addresses

API Design ✅

The new exported functions provide a clean, intuitive API:

• isShieldedZcashAddress() - specific shielded address check
• getZcashAddressKind() - classification with validation
• isValidZcashAddress() - general validation (matches existing patterns)

Test Coverage ✅

Excellent test coverage with realistic test vectors and edge cases. The tests verify both positive and negative cases across different networks and address types.

Minor Suggestions:

1. Consider adding a JSDoc comment to ZcashAddressKind type explaining when each variant is used
2. The test could benefit from testing more transparent address formats (P2SH, etc.) if supported
3. Consider adding performance benchmarks if this will be called frequently

Verdict: ✅ APPROVE

This is a well-implemented feature that safely extends Zcash address validation capabilities. The code follows BitGoJS patterns, maintains backward compatibility, and includes comprehensive testing. Ready to merge.

---

Job Run: View workflow runs

[github-actions]

⚠️ Unit tests are failing on Node 26.x (Current release line, non-blocking). This is not an LTS version yet, so it does not block merge, but it signals an incompatibility to fix before Node 26.x becomes LTS.

View run

[abhishekagrawal080]

looks good

[veetragjain]

Not all unified address are valid with respect to bitgo, only ones with orchard receiver are valid