Data Model: Wallet

Purpose: The Wallet entity represents an investor's fiat currency balance on the platform. It is a digital ledger powered by a third-party payment provider (Dwolla) that is securely tied to a Profile. It facilitates seamless funding for investments and the reception of distributions.

Fields/Attributes

Name	Type	Description	Validation Rules
id	Unique Identifier	The primary internal system ID for the wallet.	• Required • System-generated
profile_id	Foreign Key	A reference to the Profile that owns this wallet.	• Required, Unique
status	Choice	The current verification and operational status of the wallet with the provider.	• Required • See Wallet Status Lifecycle for values.
balance	Currency	The current actual amount of funds held in the wallet.	• Required • Defaults to 0.00
incoming_balance	Currency	A read-only balance representing funds that are in transit to the wallet but have not yet settled (e.g., pending deposits or distributions).	• Read-only • System-managed • Defaults to 0.00
outgoing_balance	Currency	A read-only balance representing funds that are committed to a pending investment but have not yet left the wallet. These funds are "locked."	• Read-only • System-managed • Defaults to 0.00
provider_customer_id	Text	The unique Customer ID for the user in the provider's system.	• Required, Unique
provider_source_id	Text	The unique ID for this wallet from the third-party provider's system (e.g., Dwolla's funding source ID).	• Required, Unique
created_at	Timestamp	The date and time the wallet record was created.	• Read-only
updated_at	Timestamp	The date and time the wallet was last modified.	• Read-only

Note on Calculating Available Balance: The user's Available Balance (the amount they can withdraw or use for a new investment) must always be calculated as: balance - outgoing_balance.

Key Relationships

• Profile: A Wallet belongs to exactly one Profile (a one-to-one relationship).

• Transactions: A Wallet is the source or destination for many Transaction records, creating a full ledger history (a one-to-many relationship).

• Funding Sources: A Wallet can have multiple FundingSource records linked to it (a one-to-many relationship).

Global Business Rules

• A Wallet must only be created for a Profile after its kyc_status is approved.

• SDIRA profiles cannot have a Wallet.

• A Wallet cannot be used to send or receive funds until its status is verified.

• Each eligible Profile can have only one Wallet.

• The user's Available Balance (the amount they can withdraw or use for a new investment) must always be calculated as: balance - outcoming_balance.

• Funding Source Limit: A Wallet can have a maximum of 6 active FundingSource records linked at any given time.

Auditing & Event History

Every significant action or change made to an Wallet is recorded as an immutable entry in a system-wide EventLog. This creates a complete and tamper-proof audit trail for compliance and operational tracking.