Data Model: EVM Contract

Purpose: The EVM Contract entity is an off-chain record that represents a deployed on-chain smart contract. It acts as the definitive link between a legal Offer and its tokenized, blockchain-based counterpart. This model stores the contract's on-chain address, its technical specifications, and a summary of its current state.

Fields/Attributes

Name	Type	Description	Validation Rules
Core Identification & Links
id	Unique Identifier	The primary internal system ID for the contract record.	• Required • System-generated, Read-only
offer_id	Foreign Key	A reference to the Offer that this smart contract represents.	• Required, Unique
Blockchain Details
status	Choice	The current status of the contract record in our system's lifecycle.	• Required • See Contract State Lifecycle.
address	Text	The unique public blockchain address of the deployed smart contract.	• Required, Unique per network
network	Choice	The blockchain network where the contract is deployed.	• Required • e.g., ETHEREUM_MAINNET
deployment_tx_hash	Text	The transaction hash of the deployment transaction that created the contract on the blockchain.	• Required, Unique
Token & Contract Specification
name	Text	The full, public name of the token represented by this contract.	• Required
symbol	Text	The abbreviated token symbol for the asset.	• Required
token_standard	Choice	The technical standard of the contract, defining its capabilities.	• Required • e.g., ERC20, ERC1400
total_supply	Big Integer	The maximum number of tokens that can ever be minted for this offering.	• Required
abi	JSON	The contract's Application Binary Interface, required for backend services to interact with it.	• Required
economic_model	Choice	Defines the economic model for how yield is handled by the contract.	• Required • Must be one of: PRICE_APPRECIATING, DIVIDEND_PAYING_BATCH, DIVIDEND_PAYING_STREAMING
Live On-Chain State
tokens_distributed	Big Integer	A dynamic, read-only field showing the current number of tokens that have been issued.	• Read-only • System-managed
Compliance & Feature Flags
is_allowlist_enabled	Boolean	A flag indicating if the contract restricts transfers only to wallets on an allow-list.	• Required
is_pausable	Boolean	A flag indicating if the contract allows administrators to pause all token transfers.	• Required
Metadata
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 last modified.	• Read-only

Key Relationships

• Offer: Each EVM Contract record is inextricably linked to exactly one Offer (a one-to-one relationship).

• EVM Transfers: An EVM Contract is the source, destination, or subject of many blockchain events like token mints and EVM-transfers.

Global Business Rules

• An EVM Contract record can only be created for an Offer that is in the LEGAL-ACCEPTED state or a subsequent active state.

• The address must be unique for a given network.

• The system must prevent any action that would cause tokens_distributed to exceed total_supply.

• The economic_model (DIVIDEND_PAYING or PRICE_APPRECIATING) must be set by the RWA Tokenization Engine before deployment. Once the contract's status is ACTIVE, this field is immutable.

  • If an EVM Contract's economic_model is DIVIDEND_PAYING_BATCH: The system will use the Smart Dividends Service (Capability A) to execute all profit distributions.

  • If an EVM Contract's economic_model is DIVIDEND_PAYING_STREAMING: The system will use the Smart Dividends Service (Capability B). All yield is handled automatically by the smart contract's internal logic.

  • If an EVM Contract's economic_model is PRICE_APPRECIATING: The system will use the Smart Dividends Service (Capability C). All yield is handled internally by the smart contract's exchangeRate logic. The Investor Portal will query the contract's current exchange rate (via the evm-api) to accurately display the value of an investor's holdings.

Auditing & Event History

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