Data Model: EVM Transfer

Purpose: The EVM Transfer entity is an immutable, off-chain record of an on-chain transaction. It serves as a verifiable log of all token movements, such as issuance from an Investment or payouts from a Distribution, providing a crucial link between platform events and blockchain facts.

Fields/Attributes

Name	Type	Description	Validation Rules
id	Unique Identifier	The primary internal system ID for the transfer record.	• Required • System-generated
transaction_tx	Text	The unique transaction hash (TxHash) from the blockchain, linking to a block explorer.	• Required, Unique per network
status	Choice	The real-time status of the transaction on the blockchain.	• Required • See Transfer Status Lifecycle.
from_address	Text	The sender's wallet address.	• Required
to_address	Text	The receiver's wallet address.	• Required
amount	Big Integer	The number of tokens transferred.	• Required
evm_contract_id	Foreign Key	A reference to the EVM Contract whose tokens were transferred.	• Required
investment_id	Foreign Key	A reference to the off-chain Investment that triggered this transfer.	• Nullable
distribution_id	Foreign Key	A reference to the off-chain Distribution that triggered this transfer.	• Nullable
timestamp	Timestamp	The date and time the transaction was confirmed on the blockchain (from the block timestamp).	• Read-only
offer_id	Foreign Key	A reference to the off-chain offering these tokens belong to.	• Nullable
symbol	Text	The token symbol.	• Required
type	Text	A type of the transfer.	• Required
created_at	Timestamp	The date and time the record was created in our system.	• Read-only
updated_at	Timestamp	The date and time the record was changed.	• Read-only

Key Relationships

• EVM Contract: An EVM Transfer always involves tokens managed by one EVM Contract (a many-to-one relationship).

• Investment / Distribution: An EVM Transfer can be directly triggered by and linked to an Investment or Distribution record, providing a complete audit trail.

• EVM Wallets: An EVM Transfer is implicitly linked to one or two EVM Wallet records. The system establishes this link by matching the from_address and to_address fields against the addresses stored in the EVM Wallet model.

Global Business Rules

• An EVM Transfer record is created when a transaction is broadcast to the blockchain.

• The status of a transfer must be updated by a background service (a blockchain listener) that monitors its hash.

• Once a record reaches a terminal state (CONFIRMED or FAILED), it is immutable and cannot be altered.

Auditing & Event History

Every significant action or change made to an EVM Transfer 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.