Token Holdings Query - SPL token account parsing and metadata enrichment

[Haydart]

---

name: Token Holdings Query - SPL token account parsing and metadata enrichment
status: open
created: 2025-09-19T16:02:24Z
updated: 2025-09-19T16:42:04Z
github: #130
depends_on: [127, 129, 124]
parallel: false
conflicts_with: []

Task: Token Holdings Query - SPL token account parsing and metadata enrichment

Description

Implement the get_token_holdings() method in the SolanaBlockchainService class to retrieve and parse SPL token account data for a given wallet address. This method enriches raw token account data with metadata (name, symbol) and converts balances to human-readable format using token decimals.

Acceptance Criteria

• get_token_holdings(address: str) -> List[TokenHolding] method implemented
• SPL token account discovery using get_token_accounts_by_owner() RPC call
• Token balance conversion from raw units to decimal format using token decimals
• Token metadata retrieval for name and symbol information
• TokenHolding dataclass population with all required fields
• Filtering of zero-balance token accounts
• Error handling for metadata retrieval failures (graceful degradation)
• Retry logic for both token account and metadata RPC calls
• Unit tests will be handled in Unit Testing - Comprehensive test suite with mocked responses #128

Technical Details

Implementation Approach

• Use get_token_accounts_by_owner() to discover SPL token accounts
• Parse token account data to extract mint address and raw balance
• Call get_token_metadata() for each discovered token to get name/symbol
• Convert raw token balance using decimals field from token metadata
• Filter out accounts with zero balances to reduce noise
• Handle metadata retrieval failures gracefully (use mint address as fallback)

Key Considerations

• Error Recovery: Continue processing other tokens if individual metadata fails
• Edge Cases: Handle wallets with no SPL tokens, failed metadata calls

Code Locations/Files Affected

• src/services/solana_blockchain_service.py (get_token_holdings method)
• Uses TokenHolding dataclass from Data Models - Dataclass definitions for all return types #129

Dependencies

• Core Service Implementation - SolanaBlockchainService class with RPC client setup #127: Core Service Implementation (SolanaBlockchainService class)
• Data Models - Dataclass definitions for all return types #129: Data Models (TokenHolding and TokenMetadata dataclasses)
• Error Handling - Custom exception classes and retry logic #124: Error Handling (custom exception classes)

Effort Estimate

• Size: M
• Hours: 6-8 hours
• Parallel: false (requires core service and data models)

Definition of Done

• get_token_holdings method implemented and functional
• SPL token account discovery working correctly
• Token balance conversion using proper decimals
• Token metadata enrichment with name and symbol
• TokenHolding dataclass properly populated
• Zero-balance filtering implemented
• Graceful handling of metadata retrieval failures
• Error handling tested for various failure scenarios
• Method returns correct List[TokenHolding] type as per interface
• Unit tests will be handled in Unit Testing - Comprehensive test suite with mocked responses #128

[Haydart]

Closing as part of epic completion - SimpleSolanaService implementation is complete