github.com/MetalBlockchain/metalgo@v1.11.9/snow/engine/common/vm.go (about)

     1  // Copyright (C) 2019-2024, Ava Labs, Inc. All rights reserved.
     2  // See the file LICENSE for licensing terms.
     3  
     4  package common
     5  
     6  import (
     7  	"context"
     8  	"net/http"
     9  
    10  	"github.com/MetalBlockchain/metalgo/api/health"
    11  	"github.com/MetalBlockchain/metalgo/database"
    12  	"github.com/MetalBlockchain/metalgo/snow"
    13  	"github.com/MetalBlockchain/metalgo/snow/validators"
    14  )
    15  
    16  // VM describes the interface that all consensus VMs must implement
    17  type VM interface {
    18  	AppHandler
    19  
    20  	// Returns nil if the VM is healthy.
    21  	// Periodically called and reported via the node's Health API.
    22  	health.Checker
    23  
    24  	// Connector represents a handler that is called on connection connect/disconnect
    25  	validators.Connector
    26  
    27  	// Initialize this VM.
    28  	// [chainCtx]: Metadata about this VM.
    29  	//     [chainCtx.networkID]: The ID of the network this VM's chain is
    30  	//                           running on.
    31  	//     [chainCtx.chainID]: The unique ID of the chain this VM is running on.
    32  	//     [chainCtx.Log]: Used to log messages
    33  	//     [chainCtx.NodeID]: The unique staker ID of this node.
    34  	//     [chainCtx.Lock]: A Read/Write lock shared by this VM and the
    35  	//                      consensus engine that manages this VM. The write
    36  	//                      lock is held whenever code in the consensus engine
    37  	//                      calls the VM.
    38  	// [dbManager]: The manager of the database this VM will persist data to.
    39  	// [genesisBytes]: The byte-encoding of the genesis information of this
    40  	//                 VM. The VM uses it to initialize its state. For
    41  	//                 example, if this VM were an account-based payments
    42  	//                 system, `genesisBytes` would probably contain a genesis
    43  	//                 transaction that gives coins to some accounts, and this
    44  	//                 transaction would be in the genesis block.
    45  	// [toEngine]: The channel used to send messages to the consensus engine.
    46  	// [fxs]: Feature extensions that attach to this VM.
    47  	Initialize(
    48  		ctx context.Context,
    49  		chainCtx *snow.Context,
    50  		db database.Database,
    51  		genesisBytes []byte,
    52  		upgradeBytes []byte,
    53  		configBytes []byte,
    54  		toEngine chan<- Message,
    55  		fxs []*Fx,
    56  		appSender AppSender,
    57  	) error
    58  
    59  	// SetState communicates to VM its next state it starts
    60  	SetState(ctx context.Context, state snow.State) error
    61  
    62  	// Shutdown is called when the node is shutting down.
    63  	Shutdown(context.Context) error
    64  
    65  	// Version returns the version of the VM.
    66  	Version(context.Context) (string, error)
    67  
    68  	// Creates the HTTP handlers for custom chain network calls.
    69  	//
    70  	// This exposes handlers that the outside world can use to communicate with
    71  	// the chain. Each handler has the path:
    72  	// [Address of node]/ext/bc/[chain ID]/[extension]
    73  	//
    74  	// Returns a mapping from [extension]s to HTTP handlers.
    75  	//
    76  	// For example, if this VM implements an account-based payments system,
    77  	// it have an extension called `accounts`, where clients could get
    78  	// information about their accounts.
    79  	CreateHandlers(context.Context) (map[string]http.Handler, error)
    80  }