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


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.ethscriptions.com/ethscriptions-vm/ethscriptions-vm-api/vm-api-data-model.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.