Data Models - Dataclass definitions for all return types

[Haydart]

---

name: Data Models - Dataclass definitions for all return types
status: open
created: 2025-09-19T16:02:24Z
updated: 2025-09-19T16:42:04Z
github: #129
depends_on: []
parallel: true
conflicts_with: []

Data Models - Dataclass definitions for all return types

Objective

Define simple Pydantic models for Solana blockchain service return types, ensuring type safety and clear data structures.

Acceptance Criteria

Core Models

• TokenHolding - SPL token holding with mint address, name, symbol, balance, decimals
• TokenMetadata - Token metadata with name, symbol, decimals
• FundingTransaction - First funding transaction with signature, timestamp, amount, from_address
• Transaction - Basic transaction with signature and timestamp
• WalletBalance - Simple wallet SOL balance representation

Technical Requirements

Pydantic Implementation

• Use Pydantic BaseModel for all data models
• Add proper type hints for all fields
• Use Pydantic's built-in validation
• Include optional fields with defaults where appropriate

Basic Validation

• Address format validation for Solana addresses
• Amount validation (positive numbers)
• Basic timestamp handling with datetime types

Serialization

• JSON serialization via Pydantic's built-in methods
• Support for API response parsing

Implementation Notes

Standalone Design

• No integration with existing pump.fun models
• No dependencies on current token_models.py
• Clean, simple implementation

Type Safety

• Proper type hints for all fields
• Pydantic validation for data integrity
• Optional fields handled with Union types

Files to Create/Modify

• src/services/solana_models.py (new)

Testing Requirements

• Unit tests for Pydantic model validation
• Basic serialization tests
• Type checking validation

Dependencies

This task can be executed in parallel as it defines the foundational data structures that will be used by the service implementation and other components.

[Haydart]

Closing as part of epic completion - SimpleSolanaService implementation is complete