# 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.