Virtual Machine (VM) Documentation for the Synnq Ecosystem

Introduction

The Virtual Machine (VM) in the Synnq Ecosystem is a powerful execution environment designed to run smart contracts securely and efficiently. This document provides an overview of the VM’s architecture, its role within the ecosystem, and guidelines on how to deploy, execute, and manage smart contracts.

Architecture and Components

The VM in the Synnq Ecosystem is built to support the execution of smart contracts, ensuring that they interact seamlessly with the blockchain and other ecosystem components. Below is an overview of the core components and functionalities of the VM:

• Engine: The core execution environment that runs WebAssembly (Wasm) code. It ensures the secure and isolated execution of smart contracts.

• Smart Contracts: Self-executing contracts with the terms of the agreement directly written into lines of code. They are deployed and executed within the VM.

• Modules and Linker: The VM uses Wasmtime’s module and linker system to handle the compilation and linking of smart contracts. This allows the VM to integrate various functionalities, such as handling NFT operations.

• Storage: A distributed storage system that persists smart contract code, state, and other related data.

• Mempool: A memory pool that temporarily holds transactions before they are added to the blockchain.

• KeyManager: A component that manages cryptographic keys, essential for signing transactions and verifying identities.

Core Functionalities

1. Deploying Smart Contracts

Deploying a smart contract involves compiling the Wasm code, storing the contract on the blockchain, and preparing it for execution:

• Compilation: The smart contract code is compiled into a Wasm module using the Wasmtime engine. This process ensures that the code is ready to be executed within the VM.

• Storage: After compilation, the contract code and its metadata are serialized and stored in the distributed storage system. This step ensures that the contract is permanently available and retrievable.

• Initialization: The VM initializes the contract, setting up its initial state and preparing it for interaction with the blockchain.

• Contract ID and Exports: Upon successful deployment, the VM returns a unique contract ID and a list of exported functions that the contract provides. These exports represent the public methods that can be invoked on the contract.

2. Executing Smart Contracts

Execution of a smart contract involves invoking one of its exported methods with the necessary arguments:

• Method Invocation: Users can call a specific method on a deployed smart contract by providing the contract ID, method name, and arguments. The VM executes the method in the context of the contract’s Wasm module.

• Handling Different Contract Types: Depending on the type of smart contract (e.g., NFT-related, financial), the VM may delegate execution to specific modules designed to handle those contracts. For instance, NFT contracts are handled by the NFT module.

• Interaction with Blockchain: During execution, the contract may interact with the blockchain, modify its state, or produce outputs based on the method's logic.

• Execution Response: After execution, the VM returns a JSON response containing the results of the method invocation, the contract ID, the method executed, and the status of the execution (success or failure).

3. Managing Contract State

The VM ensures that the state of each contract is maintained and can be updated or retrieved as needed:

• State Serialization: The state of a contract is serialized and stored in the distributed storage system after each execution. This process ensures that the contract’s state is persistent across executions.

• State Retrieval: The VM can retrieve the state of a contract from storage when needed, ensuring that the contract continues execution with its most recent state.

4. Error Handling

The VM includes robust error handling mechanisms to ensure that issues during compilation, execution, or storage are properly managed:

• Compilation Errors: If the Wasm code fails to compile, the VM returns a compilation error, detailing the issue to the user.

• Execution Errors: During execution, if a method encounters an issue (e.g., out-of-bounds memory access, missing function), the VM captures and reports the error.

• Storage Errors: Any issues related to storing or retrieving contract data from the distributed storage system are also handled and reported as storage errors.

Using the VM in the Synnq Ecosystem

Deployment Workflow

Initialize the VM: Begin by creating a new instance of the VirtualMachine using VirtualMachine::new().

Deploy a Contract:

• Provide the contract code (as a Wasm binary), storage reference, contract type, and owner information.
• Call deploy_contract to compile, store, and initialize the contract.
• On success, receive a unique contract ID and a list of available methods.

Execution Workflow

Retrieve Contract:

• Fetch the smart contract using the retrieve_contract function, providing the contract ID and storage reference.

Execute a Method:

• Use execute_contract to invoke a specific method on the contract. Provide necessary arguments, including the contract ID, method name, arguments, private key, storage, mempool, and key manager.

Managing State

• Save State: After each contract execution, the VM automatically saves the contract's state to ensure consistency.
• Load State: The VM can load the state of a contract at any time, allowing it to continue execution from where it left off.

Error Handling in the VM

The VM is designed with comprehensive error handling mechanisms to ensure robustness:

• Storage Errors: Occur during saving or loading of contract data. These errors typically indicate issues with the underlying storage system.

• Execution Errors: Occur during the execution of a contract method. These errors can result from various issues, including invalid memory access or runtime panics within the Wasm code.

• Compilation Errors: Occur during the initial compilation of the Wasm contract. These errors often indicate problems with the Wasm code itself, such as syntax errors or unsupported operations.