Wallet Entities

This document describes the core entities in the wallets domain and their relationships.

Entity Relationship Diagram

Wallet

The Wallet entity represents a custodial wallet that can hold multiple tokens across a specific blockchain.

Properties

• id: WalletId - Unique identifier composed of owner and blockchain
• blockchain: Blockchain - The blockchain this wallet operates on
• owner: WalletOwner - The owner identifier (usually a user ID)
• balance: Amount - Current native token balance
• feeMultiplier: Amount - Multiplier for transaction fees (default: 1.0)
• depositsEnabled: boolean - Whether deposits are allowed
• withdrawalsEnabled: boolean - Whether withdrawals are allowed
• updatedAt: Date - Last update timestamp
• createdAt: Date - Creation timestamp

Key Methods

Static Methods

• create(owner, blockchain) - Creates a new wallet
• fromDto(dto) - Creates wallet from DTO
• fromId(id) - Creates wallet from ID

Instance Methods

• derivePathFor(purposeIndex, index) - Gets derivation path for address generation
• nativeCoin() - Returns the native coin ID for this blockchain
• extendedPublicKey() - Gets the extended public key from environment
• mnemonic() - Gets the mnemonic phrase from environment
• updateBalance(amount) - Updates the wallet balance
• updateFeeMultiplier(multiplier) - Updates fee multiplier
• updateDepositsEnabled(enabled) - Enables/disables deposits
• updateWithdrawalsEnabled(enabled) - Enables/disables withdrawals

Usage Example

// Create a new wallet
const wallet = Wallet.create(
  WalletOwner.fromString('user123'),
  Blockchain.fromString('ETH')
)

// Update settings
wallet.updateDepositsEnabled(false)
wallet.updateFeeMultiplier(Amount.fromString('1.5'))

WalletAddress

The WalletAddress entity represents a specific address within a wallet for receiving funds. It's an abstract class with two concrete implementations.

Properties

• id: WalletAddressId - Unique identifier
• wallet: Wallet - Parent wallet reference
• purposeIndex: number - Purpose index in HD derivation (usually 0 for deposits)
• index: number - Address index in HD derivation
• address: BlockchainAddress - The actual blockchain address
• balance: Amount - Current balance at this address
• inUse: boolean - Whether address is currently assigned to a user
• lastUsedAt: Date - When address was last used
• updatedAt: Date - Last update timestamp
• createdAt: Date - Creation timestamp

Key Methods

• updateBalance(amount) - Updates address balance
• markAsUsedAt() - Updates last used timestamp
• markAsInUse() - Marks address as in use
• markAsAvailable() - Marks address as available for reuse
• isToken() - Abstract method to check if it's a token address
• coinId() - Abstract method to get coin ID

Concrete Implementations

WalletNativeAddress

For native blockchain tokens (ETH, BTC, SOL, etc.)

WalletTokenAddress

For specific tokens (USDT, USDC, etc.) - extends a native address with token information

Transaction

The Transaction entity represents a blockchain transaction within the system.

Properties

• id: TransactionId - Unique identifier
• wallet: Wallet - Associated wallet
• motive: TransactionMotive - Purpose of transaction (deposit, withdrawal, sweep, etc.)
• amount: Amount - Transaction amount
• senders: TransactionParticipant[] - Sending addresses and amounts
• recipients: TransactionParticipant[] - Receiving addresses and amounts
• status: TransactionStatus - Current status (pending, confirmed, failed, etc.)
• token: Token - Optional token (for token transfers)
• txHash: BlockchainTxHash - Optional blockchain transaction hash
• updatedAt: Date - Last update timestamp
• createdAt: Date - Creation timestamp

Key Methods

Static Methods

• create(wallet, senders, recipients, motive, token?) - Creates new transaction
• fromDto(dto) - Creates transaction from DTO

Instance Methods

• updateStatus(status) - Updates transaction status
• participants() - Gets all participants (senders + recipients)
• addresses() - Gets all involved addresses
• isWaitingForSettlement() - Checks if transaction is within settlement window

Transaction Motives

• DEPOSIT - Incoming funds from external source
• WITHDRAWAL - Outgoing funds to external destination
• SWEEP - Internal consolidation of funds
• FEE - Fee payment transaction
• RESOURCE - Resource allocation (e.g., Tron energy)

Transaction Statuses

• PENDING - Created but not yet sent
• SENT - Sent to blockchain
• CONFIRMED - Confirmed on blockchain
• FAILED - Failed to process
• CANCELLED - Manually cancelled

WalletToken

The WalletToken entity represents the holding of a specific token within a wallet.

Properties

• wallet: Wallet - Parent wallet
• token: Token - Token information
• balance: Amount - Current token balance
• depositsEnabled: boolean - Whether deposits are enabled for this token
• withdrawalsEnabled: boolean - Whether withdrawals are enabled for this token
• updatedAt: Date - Last update timestamp
• createdAt: Date - Creation timestamp

Key Methods

• updateBalance(amount) - Updates token balance
• updateDepositsEnabled(enabled) - Enables/disables deposits
• updateWithdrawalsEnabled(enabled) - Enables/disables withdrawals

Address Generation Strategy

The system uses HD (Hierarchical Deterministic) wallet derivation with the following structure:

m/blockchain_derivation_path/account'/purpose_index/address_index

• account: Derived from wallet owner
• purpose_index: Always 0 for deposit addresses
• address_index: Incremental index (0 to 1000 max)

When the maximum number of addresses is reached, the system reuses the oldest used address.

State Management

Address Lifecycle

1. Created - New address generated
2. In Use - Assigned to user for deposits
3. Available - Can be reused after period of inactivity

Transaction Lifecycle

1. Created - Transaction object created
2. Pending - Waiting to be sent
3. Sent - Submitted to blockchain
4. Confirmed - Confirmed on blockchain
5. Failed/Cancelled - Terminal states

Balance Updates

Balances are updated through various triggers:

• Deposit detection
• Transaction confirmation
• Manual balance scans
• Sweep operations