VM API Data Model

Database Schema

The VM relies on three primary database tables to capture the contract information, contract states, and call receipts.

contracts Table

• Fields:

  • contract_id: A unique identifier for the smart contract.

  • type: Categorizes the contract, such as ERC20 or ERC721.

  • created_at & updated_at: Standard timestamps.

• Role: Maintains a registry of all smart contracts deployed or interacted with.

contract_states Table

• Fields:

  • contract_id: Reference to the contracts table.

  • ethscription_id: The ID of the Ethscription transaction that led to this particular contract state.

  • state: JSON object containing the contract's current state.

  • block_number & transaction_index: Ethereum block and transaction index that capture the state.

• Role: Holds historical states of smart contracts, enabling time-travel queries for auditing or state reversion.

contract_call_receipts Table

• Fields:

  • contract_id: Reference to the contracts table.

  • ethscription_id: ID of the initiating Ethscription.

  • caller: Ethereum address of the entity initiating the function call.

  • status: Execution status code.

  • function_name & function_args: Function details.

  • logs: Execution logs.

  • timestamp: Time of call.

  • error_message: Stored if the call results in an error.

• Role: Records the outcomes of all contract function calls, enabling debugging, auditing, and transaction history views.

Execution Flow

1. Transaction Initialization: Upon receiving a new Ethscription, initial validation occurs. If a new contract is deployed, a new row is created in the contracts table.

2. Pre-Execution State: The latest contract_state is fetched based on the contract_id to set the initial state of the smart contract.

3. Function Execution: The specified function in the smart contract is called, potentially altering its state.

4. Post-Execution State: A new row is added to contract_states capturing the updated contract state.

5. Receipt Logging: A new row is logged in contract_call_receipts with all the details of the function call, including its success or failure status.

6. API Exposure: This data is now accessible via various API endpoints, like ContractsController#show_call_receipt, which queries contract_call_receipts based on ethscription_id to deliver detailed transaction receipts.

By harmonizing the capabilities of Ethereum smart contracts with the efficiency of Ethscriptions, the VM creates a powerful environment for developing, deploying, and interacting with decentralized applications, all at a fraction of the cost usually associated with on-chain operations.