vmcommon

README

me-vm-common

Common structs between VM and node

Documentation

Index

• type BlockchainHook
• type Bn128G2Point
• type Bn128Point
• type ContractCallInput
• type ContractCreateInput
• type CryptoHook
• type LogEntry
• type OutputAccount
• type ReturnCode
  • func (rc ReturnCode) String() string
• type ReturnDataKind
• type StorageUpdate
• type VMExecutionHandler
• type VMInput
• type VMOutput
  • func (vmOutput *VMOutput) GetFirstReturnData(asType ReturnDataKind) (interface{}, error)

Types

type BlockchainHook

type BlockchainHook interface {
	// An account with Balance = 0 and Nonce = 0 is considered to not exist
	AccountExists(address []byte) (bool, error)

	// NewAddress yields the address of a new SC account, when one such account is created.
	// The result should only depend on the creator address and nonce.
	// Returning an empty address lets the VM decide what the new address should be.
	NewAddress(creatorAddress []byte, creatorNonce uint64, vmType []byte) ([]byte, error)

	// Should yield the balance of an account.
	// Should yield zero if account does not exist.
	GetBalance(address []byte) (*big.Int, error)

	// Should yield the nonce of an account.
	// Should yield zero if account does not exist.
	GetNonce(address []byte) (uint64, error)

	// Should yield the storage value for a certain account and index.
	// Should return an empty byte array if the key is missing from the account storage,
	// or if account does not exist.
	GetStorageData(accountAddress []byte, index []byte) ([]byte, error)

	// Should return whether of not an account is SC.
	IsCodeEmpty(address []byte) (bool, error)

	// Should return the compiled and assembled SC code.
	// Should yield an empty byte array if the account is a wallet.
	GetCode(address []byte) ([]byte, error)

	// Returns the hash of the block with the asked nonce if available
	GetBlockhash(nonce uint64) ([]byte, error)

	// LastNonce returns the nonce from from the last committed block
	LastNonce() uint64

	// LastRound returns the round from the last committed block
	LastRound() uint64

	// LastTimeStamp returns the timeStamp from the last committed block
	LastTimeStamp() uint64

	// LastRandomSeed returns the random seed from the last committed block
	LastRandomSeed() []byte

	// LastEpoch returns the epoch from the last committed block
	LastEpoch() uint32

	// GetStateRootHash returns the state root hash from the last committed block
	GetStateRootHash() []byte

	// CurrentNonce returns the nonce from the current block
	CurrentNonce() uint64

	// CurrentRound returns the round from the current block
	CurrentRound() uint64

	// CurrentTimeStamp return the timestamp from the current block
	CurrentTimeStamp() uint64

	// CurrentRandomSeed returns the random seed from the current header
	CurrentRandomSeed() []byte

	// CurrentEpoch returns the current epoch
	CurrentEpoch() uint32
}

BlockchainHook is the interface for VM blockchain callbacks

type Bn128G2Point

type Bn128G2Point struct {
	X1 *big.Int
	X2 *big.Int
	Y1 *big.Int
	Y2 *big.Int
}

Bn128G2Point point on a curve

type Bn128Point

type Bn128Point struct {
	X *big.Int
	Y *big.Int
}

Bn128Point point on a curve

type ContractCallInput

type ContractCallInput struct {
	VMInput

	// RecipientAddr is the smart contract public key, "to".
	RecipientAddr []byte

	// Function is the name of the smart contract function that will be called.
	// The function must be public (e.g. in Iele `define public @functionName(...)`)
	Function string
}

ContractCallInput VM input when calling a function from an existing contract

type ContractCreateInput

type ContractCreateInput struct {
	VMInput

	// ContractCode is the code of the contract being created, assembled into a byte array.
	// For Iele VM, to convert a .iele file to this assembled byte array, see
	// src/github.com/Dharitri-org/me-vm/iele/compiler/compiler.AssembleIeleCode
	ContractCode []byte
}

ContractCreateInput VM input when creating a new contract. Here we have no RecipientAddr because the address (PK) of the created account will be provided by the VM. We also do not need to specify a Function field, because on creation `init` is always called.

type CryptoHook

type CryptoHook interface {
	// Sha256 cryptographic function
	Sha256(str string) (string, error)

	// Keccak256 cryptographic function
	Keccak256(str string) (string, error)

	// Ripemd160 cryptographic function
	Ripemd160(str string) (string, error)

	// EcdsaRecover cryptographic function
	EcdsaRecover(hash string, v *big.Int, r string, s string) (string, error)

	// Sha256 cryptographic function
	Bn128valid(p Bn128Point) (bool, error)

	// Bn128g2valid
	Bn128g2valid(p Bn128G2Point) (bool, error)

	// Bn128add
	Bn128add(p1 Bn128Point, p2 Bn128Point) (Bn128Point, error)

	// Bn128mul
	Bn128mul(k *big.Int, p Bn128Point) (Bn128Point, error)

	// Bn128ate
	Bn128ate(l1 []Bn128Point, l2 []Bn128G2Point) (bool, error)
}

CryptoHook interface for VM krypto functions

type LogEntry

type LogEntry struct {
	Address []byte
	Topics  [][]byte
	Data    []byte
}

LogEntry represents an entry in the contract execution log. TODO: document all fields.

type OutputAccount

type OutputAccount struct {
	// Address is the public key of the account.
	Address []byte

	// Nonce is the new account nonce.
	Nonce uint64

	// Balance is the account balance after running a SC.
	// Only used for some tests now, please ignore. Might be removed in the future.
	Balance *big.Int

	// BalanceDelta is by how much the balance should change following the SC execution.
	// A negative value indicates that balance should decrease.
	BalanceDelta *big.Int

	// StorageUpdates is a list of key-value pairs
	// that should be updated in the account storage.
	// Please note that it is likely that not all existing
	// account storage keys show up here.
	StorageUpdates []*StorageUpdate

	// Code is the assembled code of a smart contract account.
	// This field will be populated when a new SC must be created after the transaction.
	Code []byte

	// Data will be populated if there is a transfer to this output account which has to
	// be further interpreted or verified
	Data []byte

	// GasLimit will be populated if the call is a smart contract call for another shard
	GasLimit uint64
}

OutputAccount shows the state of an account after contract execution. It can be an existing account or a new account created by the transaction. Note: the current implementation might also return unmodified accounts.

type ReturnCode

type ReturnCode int

ReturnCode is an enum with the possible error codes returned by the VM

const (
	// Ok is returned when execution was completed normally.
	Ok ReturnCode = 0

	// FunctionNotFound is returned when the input specifies a function name that does not exist or is not public.
	FunctionNotFound ReturnCode = 1

	// FunctionWrongSignature is returned when the wrong number of arguments is provided.
	FunctionWrongSignature ReturnCode = 2

	// ContractNotFound is returned when the called contract does not exist.
	ContractNotFound ReturnCode = 3

	// UserError is returned for various execution errors.
	UserError ReturnCode = 4

	// OutOfGas is returned when VM execution runs out of gas.
	OutOfGas ReturnCode = 5

	// AccountCollision is returned when created account already exists.
	AccountCollision ReturnCode = 6

	// OutOfFunds is returned when the caller (sender) runs out of funds.
	OutOfFunds ReturnCode = 7

	// CallStackOverFlow is returned when stack overflow occurs.
	CallStackOverFlow ReturnCode = 8

	// ContractInvalid is returned when the contract is invalid.
	ContractInvalid ReturnCode = 9
)

func (ReturnCode) String

func (rc ReturnCode) String() string

type ReturnDataKind

type ReturnDataKind int

ReturnDataKind specifies how to interpret VMOutputs's return data. More specifically, how to interpret returned data's first item.

const (
	// AsBigInt to interpret as big int
	AsBigInt ReturnDataKind = 1 << iota
	// AsBigIntString to interpret as big int string
	AsBigIntString
	// AsString to interpret as string
	AsString
	// AsHex to interpret as hex
	AsHex
)

type StorageUpdate

type StorageUpdate struct {
	// Offset is the storage key.
	// The VM treats this as a big.Int.
	Offset []byte

	// Data is the new storage value.
	// The VM treats this as a big.Int.
	// Zero indicates missing data for the key (or even a missing key),
	// therefore a value of zero here indicates that
	// the storage map entry with the given key can be deleted.
	Data []byte
}

StorageUpdate represents a change in the account storage (insert, update or delete) Note: current implementation might also return unmodified storage entries.

type VMExecutionHandler

type VMExecutionHandler interface {
	// Computes how a smart contract creation should be performed
	RunSmartContractCreate(input *ContractCreateInput) (*VMOutput, error)

	// Computes the result of a smart contract call and how the system must change after the execution
	RunSmartContractCall(input *ContractCallInput) (*VMOutput, error)
}

VMExecutionHandler interface for any Dharitri VM endpoint

type VMInput

type VMInput struct {
	// CallerAddr is the public key of the wallet initiating the transaction, "from".
	CallerAddr []byte

	// Arguments are the call parameters to the smart contract function call
	// For contract creation, these are the parameters to the @init function.
	// For contract call, these are the parameters to the function referenced in ContractCallInput.Function.
	// If the number of arguments does not match the function arity,
	// the transaction will return FunctionWrongSignature ReturnCode.
	Arguments [][]byte

	// CallValue is the value (amount of tokens) transferred by the transaction.
	// The VM knows to subtract this value from sender balance (CallerAddr)
	// and to add it to the smart contract balance.
	// It is often, but not always zero in SC calls.
	CallValue *big.Int

	// GasPrice multiplied by the gas burned by the transaction yields the transaction fee.
	// A larger GasPrice will incentivize block proposers to include the transaction in a block sooner,
	// but will cost the sender more.
	// The total fee should be GasPrice x (GasProvided - VMOutput.GasRemaining - VMOutput.GasRefund).
	// Note: the order of operations on the sender balance is:
	// 1. subtract GasPrice x GasProvided
	// 2. call VM, which will subtract CallValue if enough funds remain
	// 3. reimburse GasPrice x (VMOutput.GasRemaining + VMOutput.GasRefund)
	GasPrice uint64

	// GasProvided is the maximum gas allowed for the smart contract execution.
	// If the transaction consumes more gas than this value, it will immediately terminate
	// and return OutOfGas ReturnCode.
	// The sender will not be charged based on GasProvided, only on the gas burned,
	// so it doesn't cost the sender more to have a higher gas limit.
	GasProvided uint64
}

VMInput contains the common fields between the 2 types of SC call.

type VMOutput

type VMOutput struct {
	// ReturnData is the function call returned result.
	// This value does not influence the account state in any way.
	// The value should be accessible in a UI.
	// ReturnData is part of the transaction receipt.
	ReturnData [][]byte

	// ReturnCode is the function call error code.
	// If it is not `Ok`, the transaction failed in some way - gas is, however, consumed anyway.
	// This value does not influence the account state in any way.
	// The value should be accessible to a UI.
	// ReturnCode is part of the transaction receipt.
	ReturnCode ReturnCode

	// GasRemaining = VMInput.GasProvided - gas used.
	// It is necessary to compute how much to charge the sender for the transaction.
	GasRemaining uint64

	// GasRefund is how much gas the sender earned during the transaction.
	// Certain operations, like freeing up storage, actually return gas instead of consuming it.
	// Based on GasRefund, the sender could in principle be rewarded instead of taxed.
	GasRefund *big.Int

	// OutputAccounts contains data about all acounts changed as a result of the transaction.
	// This data tells the network how to update the account data.
	// It can contain new accounts or existing changed accounts.
	// Note: the current implementation might also retrieve accounts that were not changed.
	OutputAccounts []*OutputAccount

	// DeletedAccounts is a list of public keys of accounts that need to be deleted
	// as a result of the transaction.
	DeletedAccounts [][]byte

	// TouchedAccounts is a list of public keys of accounts that were somehow involved in the VM execution.
	// TODO: investigate what we need to to about these.
	TouchedAccounts [][]byte

	// Logs is a list of event data logged by the VM.
	// Smart contracts can choose to log certain events programatically.
	// There are 3 main use cases for events and logs:
	// 1. smart contract return values for the user interface;
	// 2. asynchronous triggers with data;
	// 3. a cheaper form of storage (e.g. storing historical data that can be rendered by the frontend).
	// The logs should be accessible to the UI.
	// The logs are part of the transaction receipt.
	Logs []*LogEntry
}

VMOutput is the return data and final account state after a SC execution.

func (*VMOutput) GetFirstReturnData

func (vmOutput *VMOutput) GetFirstReturnData(asType ReturnDataKind) (interface{}, error)

GetFirstReturnData is a helper function that returns the first ReturnData of VMOutput, interpreted as specified.