# VM API By Example

Given this contract:

```ruby
class Contracts::OpenMintToken < Contract
  is :ERC20
  
  uint256 :public, :maxSupply
  uint256 :public, :perMintLimit
  
  constructor(
    name: :string,
    symbol: :string,
    maxSupply: :uint256,
    perMintLimit: :uint256,
    decimals: :uint256
  ) {
    ERC20(name: name, symbol: symbol, decimals: decimals)
    s.maxSupply = maxSupply
    s.perMintLimit = perMintLimit
  }
  
  function :mint, { amount: :uint256 }, :public do
    require(amount > 0, 'Amount must be positive')
    require(amount <= s.perMintLimit, 'Exceeded mint limit')
    
    require(s.totalSupply + amount <= s.maxSupply, 'Exceeded max supply')
    
    _mint(to: msg.sender, amount: amount)
  end
  
  function :airdrop, { to: :addressOrDumbContract, amount: :uint256 }, :public do
    require(amount > 0, 'Amount must be positive')
    require(amount <= s.perMintLimit, 'Exceeded mint limit')
    
    require(s.totalSupply + amount <= s.maxSupply, 'Exceeded max supply')
    
    _mint(to: to, amount: amount)
  end
end
```

What happens when the Ethscriptions VM receives an ethscription with this data uri?

{% code overflow="wrap" %}

```
data:application/vnd.esc.contract.call+json,{"contractId":"0xdb6c87fd9b5e1aafdbc9cf4550856abde133e08e04910fe5fc319b63f5c08b3f","functionName":"mint","args":{"amount":5},"salt":"010e00f8408679670da12261c013b222"}
```

{% endcode %}

#### Step 1: Ethscription Validation

* The Ethscriptions VM first validates the incoming Ethscription transaction.
* It extracts the `content_uri` and decodes it to obtain the JSON payload containing `contractId`, `functionName`, and `args`.

#### Step 2: Contract Lookup

* The VM queries the `contracts` table to find the corresponding contract using the `contractId` provided (`0xdb6c87fd9b5e1aafdbc9cf4550856abde133e08e04910fe5fc319b63f5c08b3f` in this case).
* If the contract exists the VM proceeds to the next step.

#### Step 3: Pre-Execution State

* The VM fetches the latest state of the contract from the `contract_states` table based on the `contract_id`.
* The VM uses this state to set the initial values of state variables such as `maxSupply`, `perMintLimit`, and `totalSupply`.

#### Step 4: Function Parameters Validation

* The VM determines that the mint function exists on the contract.
* The VM then validates the parameters passed to the `mint` function, in this case, `amount: 5`. This includes type validations.
* Checks are made according to the conditions in the smart contract:
  * `amount` must be positive
  * `amount` must be less than or equal to `perMintLimit`
  * `totalSupply` + `amount` must be less than or equal to `maxSupply`

#### Step 5: Execute Mint Function

* If the validation checks pass, the VM calls the `mint` function.
* `_mint` is internally invoked, which increases the `totalSupply` and updates the balance of `msg.sender`.

#### Step 6: Post-Execution State

* A new entry is added to the `contract_states` table to reflect the state change post-minting.
* This includes the updated `totalSupply`, and the updated balance for `msg.sender`.

#### Step 7: Log Receipt

* A new row is inserted into the `contract_call_receipts` table, containing details of the function call, including:
  * `contract_id`
  * `ethscription_id`
  * `caller`
  * `status` (indicating success or failure)
  * `function_name` (in this case, "mint")
  * `function_args` (in this case, `{"amount": 5}`)
  * `logs` (any events emitted or other logs)
  * `timestamp`

#### Step 8: API Availability

* After the execution and logging, all this newly created data becomes available via API endpoints for querying or analysis.

Through these steps, the Ethscriptions VM efficiently executes the contract method, updates the state, and logs all necessary information for further interactions or audits.


---

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