Data Model: Transaction

Purpose: The Transaction entity represents a single, immutable financial event within the platform's wallet ecosystem. Each record acts as a permanent ledger entry, tracking the movement of funds for a specific purpose, such as an investment, deposit, or withdrawal. A business distribution remains a payout concept owned by its distribution service, not a current wallet transaction type. Once created, a transaction cannot be altered, ensuring a complete and auditable financial history.

Fields/Attributes

Name	Type	Description	Validation Rules
Core Identification
id	Unique Identifier	The primary internal system ID for the transaction.	• Required • System-generated, Read-only
Financial Details
amount	Currency	The monetary value of the transaction.	• Required • Must be a positive number
type	Choice	The current wire value for the wallet transaction's business purpose.	• Required • Must be one of: deposit, investment, withdrawal
description	Text	A human-readable memo describing the transaction and mentioning source and destination accounts.	• Required • System-generated
Status & Timestamps
status	Choice	The current state of the transaction.	• Required • Must be one of: created, pending, processed, cancelled, wait, failed
created_at	Timestamp	The date and time the transaction was initiated.	• Read-only
completed_at	Timestamp	The date and time the transaction was successfully settled or failed.	• Read-only
Associations & Context
source_wallet_id	Foreign Key	A reference to the Wallet from which funds were debited.	• Required • System-generated
destination_wallet_id	Foreign Key	A reference to the Wallet to which funds were credited.	• Required • System-generated
investment_id	Foreign Key	A reference to the Investment that this transaction is associated with.	• Nullable
provider_transaction_id	Text	The unique transaction ID from the external payment provider's system (e.g., Dwolla).	• Optional

Key Relationships

• Wallet: A Transaction is fundamentally linked to one or two Wallets . Many transactions can be associated with a single wallet (a many-to-one relationship).

• Investment: An Investment can be associated with one or more Transactions (e.g., the initial payment and a potential future refund) (a one-to-many relationship).

Global Business Rules

• Immutability: A Transaction record, once its status is processed or failed, is immutable. It cannot be edited or deleted. To reverse a transaction, the owning workflow must create a new opposing ledger event. This is critical for maintaining a perfect audit trail.

• Balance Checks: Before creating a withdrawal transaction, the wallet API verifies balance - out_balance. For a wallet-funded investment, the wallet API capacity check is balance + inc_balance - out_balance. These are separate checks.

• Atomic Operations: The creation of a Transaction and the corresponding updates to the source_wallet and destination_wallet balances must be an atomic operation. If any part of the process fails, the entire operation must be rolled back to prevent data inconsistency.

• Cancellable Transactions: A Transaction of type deposit or withdrawal can be cancelled by the user or an administrator while its status is pending. Once it is processed, cancelled, or failed, it is immutable.

Auditing & Event History

The system records significant actions or changes involving a Transaction as immutable entries in the system-wide EventLog.