github.com/ava-labs/avalanchego@v1.11.11/vms/rpcchainvm/runtime/README.md (about)

     1  # Virtual Machine Runtime Engine (VMRE)
     2  
     3  The `VMRE` handles the lifecycle, compatibility and logging IO of a managed VM process.
     4  
     5  ## How it works
     6  
     7  The `runtime.Initializer` interface could be implemented to manage local or remote VM processes.
     8  This implementation is consumed by a gRPC server which serves the `Runtime`
     9  service. The server interacts with the underlying process and allows for the VM
    10  binary to communicate with AvalancheGo.
    11  
    12  ### Subprocess VM management
    13  
    14  The `subprocess` is currently the only supported `Runtime` implementation.
    15  It works by starting the VM's as a subprocess of AvalancheGo by `os.Exec`.
    16  
    17  ## Workflow
    18  
    19  - `VMRegistry` calls the RPC Chain VM `Factory`.
    20  - Factory Starts an instance of a `VMRE` server that consumes a `runtime.Initializer` interface implementation.
    21  - The address of this server is passed as a ENV variable `AVALANCHE_VM_RUNTIME_ENGINE_ADDR` via `os.Exec` which starts the VM binary.
    22  - The VM uses the address of the `VMRE` server to create a client.
    23  - Client sends a `Initialize` RPC informing the server of the `Protocol Version` and future `Address` of the RPC Chain VM server allowing it to perform a validation `Handshake`.
    24  - After the `Handshake` is complete the RPC Chain VM server is started which serves the `ChainVM` implementation.
    25  - The connection details for the RPC Chain VM server are now used to create an RPC Chain VM client.
    26  - `ChainManager` uses this VM client to bootstrap the chain powered by `Snowman` consensus.
    27  - To shutdown the VM `runtime.Stop()` sends a `SIGTERM` signal to the VM process.
    28  
    29  ## Debugging
    30  
    31  ### Process Not Found
    32  
    33  When runtime is `Bootstrapped` handshake success is observed during the `Initialize` RPC. Process not found means that the runtime Client in the VM binary could not communicate with the runtime Server on AvalancheGo. This could be the result of networking issues or other error in `Serve()`.
    34  
    35  ```bash
    36  failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: timeout"}
    37  ```
    38  
    39  ### Protocol Version Mismatch
    40  
    41  To ensure RPC compatibility the protocol version of AvalancheGo must match the subnet VM. To correct this error update the subnet VM's dependencies to the latest version AvalancheGo.
    42  
    43  ```bash
    44  failed to register VM {"vmID": "tGas3T58KzdjcJ2iKSyiYsWiqYctRXaPTqBCA11BqEkNg8kPc", "error": "handshake failed: protocol version mismatch avalanchego: 19 vm: 18"}
    45  ```