[SDK] Statics registry for wrapper↔underlying pairs

[0xPrabh]

Summary

• Add @bitgo/statics ERC-7984 wrapper↔underlying registry (wrapperAddress, underlyingErc20Address, rate, requiresApprovalReset, isVetted) with lookup helpers
• Wire vetted Hoodi (hteth:cusdt, hteth:ctest1) and Sepolia (sepeth:cusdt) test pairs, plus mainnet pairs aligned with existing erc7984Tokens (on-chain verified rate() / underlying())
• Unit tests covering lookups, network filters, USDT approval-reset flag, and uniqueness

Issue Number

CHALO-1156

Type of change

• New feature (non-breaking change which adds functionality)

How Has This Been Tested?

• yarn workspace @bitgo/statics unit-test --grep "ERC-7984 wrapper registry" (8 passing)
• yarn workspace @bitgo/statics build
• eslint on touched files

Checklist

• My code follows the style guidelines of this project
• I have performed a self-review of my own code
• My commits follow Conventional Commits and reference the ticket
• I have added tests that prove my feature works
• New and existing unit tests pass locally with my changes

Made with Cursor

[linear-code]

CHALO-1156

[0xPrabh]

@claude

[github-actions]

Claude finished @0xPrabh's task —— View job

---

Code Review for ERC-7984 Wrapper Registry ✅

Todo List:

• Analyze changed files and implementation
• Review code quality and best practices
• Check test coverage and quality
• Provide comprehensive feedback

I've completed a thorough analysis of the PR and found a well-implemented ERC-7984 wrapper registry feature. The code appears to be clean, well-documented, and follows good engineering practices.

📋 Summary

This PR adds ERC-7984 wrapper↔underlying registry functionality to the @bitgo/statics module, including lookup helpers for wrapper metadata (underlying ERC-20 address, rate, approval reset requirements) and vetted test pairs on Hoodi and Sepolia networks.

🔍 Code Analysis

✅ Positive Aspects:

1. Clean Type Safety: The Erc7984ConstructorOptions interface properly extends existing patterns with optional metadata fields:

   export interface Erc7984ConstructorOptions extends AccountConstructorOptions {
     contractAddress: string;
     underlyingErc20Address?: string;
     rate?: string; 
     requiresApprovalReset?: boolean;
   }

2. Good Implementation Pattern: The Erc7984Coin class follows the established pattern from other token types like Nep141Token.storageDepositAmount and XrpMptCoin.canTransfer for storing chain-specific metadata.

3. Proper Address Normalization: Constructor correctly lowercases the underlyingErc20Address for consistency:

   this.underlyingErc20Address = options.underlyingErc20Address?.toLowerCase();

4. Well-Structured Factory Functions: Both erc7984() and terc7984() factories are well-designed, with the testnet version requiring wrapper metadata while mainnet version keeps it optional.

5. Comprehensive Token Config: The getErc7984TokenConfig() function properly handles optional metadata with conditional spreading:

   ...(coin.underlyingErc20Address !== undefined && {
     underlyingErc20Address: coin.underlyingErc20Address.toLowerCase(),
   }),

6. Good Documentation: Clear JSDoc comments explaining the ERC-7984 standard and implementation choices.

🧪 Test Quality

✅ Excellent Test Coverage:

1. Comprehensive Test Cases: Tests cover all key functionality including:

   • Hoodi test pair validation
   • Wrapper metadata storage and retrieval
   • Mainnet behavior (undefined metadata)
   • Address normalization

2. Proper Test Structure: Clean test organization with helper functions and descriptive test names.

3. Edge Case Coverage: Tests verify both presence and absence of metadata fields appropriately.

🛠️ Implementation Details

File Changes Analysis:

1. account.ts (+40/-3): Adds Erc7984ConstructorOptions, Erc7984Coin class, and factory functions. Implementation is solid and follows established patterns.

2. erc7984Tokens.ts (+10/-4): Updates token definitions with wrapper metadata. The selective addition for test pairs while keeping mainnet unchanged is a smart approach.

3. tokenConfig.ts (+13/-1): Extends type definitions and config generation. Clean integration with existing token config patterns.

4. erc7984Tokens.ts (test) (+44/-0): Comprehensive unit tests covering all functionality aspects.

🔧 Minor Observations

1. Consistent with Repository Patterns: The implementation follows established patterns throughout the codebase for similar token metadata.

2. Network Strategy: Smart approach of populating metadata only for test pairs (Hoodi/Sepolia) while keeping mainnet configs unchanged until shield/unshield functionality ships.

3. Type Safety: Proper use of optional fields prevents breaking existing functionality while enabling new features.

✅ Overall Assessment

This is a high-quality implementation that:

• ✅ Follows established codebase patterns
• ✅ Maintains backward compatibility
• ✅ Has excellent test coverage
• ✅ Uses proper TypeScript practices
• ✅ Includes clear documentation
• ✅ Handles edge cases appropriately

Recommendation: APPROVE - The PR is ready for merge. The code is well-architected, thoroughly tested, and follows best practices consistently throughout.

[harman-bitgo]

lgtm