vmcommon

package module
v0.0.1 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Sep 29, 2023 License: GPL-3.0 Imports: 3 Imported by: 15

README


kalyan3104-vm-common

Common structs between VM and node

Documentation

Index

Constants

View Source 
const (
	METADATA_UPGRADEABLE = 1
	METADATA_RESERVED_1  = 2
	METADATA_RESERVED_2  = 4
	METADATA_RESERVED_3  = 8
)

Variables

This section is empty.

Functions

This section is empty.

Types

type BlockchainHook 

type BlockchainHook interface {
	// 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 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)

	// 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

	// ProcessBuiltInFunction will process the builtIn function for the created input
	ProcessBuiltInFunction(input *ContractCallInput) (*VMOutput, error)

	// GetBuiltinFunctionNames returns the names of protocol built-in functions
	GetBuiltinFunctionNames() FunctionNames

	// GetAllState returns the full state of the account, all the key-value saved
	GetAllState(address []byte) (map[string][]byte, error)

	// GetUserAccount returns a user account
	GetUserAccount(address []byte) (UserAccountHandler, error)

	// GetShardOfAddress returns the shard ID of a given address
	GetShardOfAddress(address []byte) uint32

	// IsSmartContract returns whether the address points to a smart contract
	IsSmartContract(address []byte) bool
}

BlockchainHook is the interface for VM blockchain callbacks

type CallType 

type CallType int

CallType specifies the type of SC invocation (in terms of asynchronicity) 

const (
	// DirectCall means that the call is an explicit SC invocation originating from a user Transaction
	DirectCall CallType = iota

	// AsynchronousCall means that the invocation was performed from within
	// another SmartContract from another Shard, using asyncCall
	AsynchronousCall

	// AsynchronousCallBack means that an AsynchronousCall was performed
	// previously, and now the control returns to the caller SmartContract's callBack method
	AsynchronousCallBack
)

type CodeMetadata 

type CodeMetadata struct {
	Upgradeable bool
}

CodeMetadata represents smart contract code metadata

func CodeMetadataFromBytes 

func CodeMetadataFromBytes(bytes []byte) CodeMetadata

CodeMetadataFromBytes creates a metadata object from bytes

func (*CodeMetadata) ToBytes 

func (metadata *CodeMetadata) ToBytes() []byte

ToBytes converts the metadata to bytes

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/KalyanNetwork/kalyan3104-vm/iele/compiler/compiler.AssembleIeleCode
	ContractCode []byte

	// ContractCodeMetadata is the code metadata of the contract being created.
	ContractCodeMetadata []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(data []byte) ([]byte, error)

	// Keccak256 cryptographic function
	Keccak256(data []byte) ([]byte, error)

	// Ripemd160 cryptographic function
	Ripemd160(data []byte) ([]byte, error)

	// Ecrecover calculates the corresponding Ethereum address for the public key which created the given signature
	// https://ewasm.readthedocs.io/en/mkdocs/system_contracts/
	Ecrecover(hash []byte, recoveryID []byte, r []byte, s []byte) ([]byte, error)
}

CryptoHook interface for VM krypto functions

type FunctionNames 

type FunctionNames = map[string]struct{}

FunctionNames (alias) is a map of function names

type LogEntry 

type LogEntry struct {
	Identifier []byte
	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 map containing pointers to StorageUpdate structs,
	// indexed with strings produced by `string(StorageUpdate.Offset)`, for fast
	// access by the Offset of the StorageUpdate. These StorageUpdate structs
	// will be processed by the Node to modify the storage of the SmartContract.
	// Please note that it is likely that not all existing account storage keys
	// show up here.
	StorageUpdates map[string]*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

	// CodeMetadata is the metadata of the code
	// Like "Code", this field will be populated when a new SC must be created after the transaction.
	CodeMetadata []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

	// CallType will be set if the output account must be invoked as a smart contract
	CallType CallType
}

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

	// ExecutionFailed is returned when the execution of the specified function has failed.
	ExecutionFailed ReturnCode = 10

	// UpgradeFailed is returned when the upgrade of the contract has failed
	UpgradeFailed ReturnCode = 11
)

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 UserAccountHandler 

type UserAccountHandler interface {
	AddressBytes() []byte
	GetNonce() uint64
	GetCode() []byte
	GetCodeMetadata() []byte
	GetCodeHash() []byte
	GetRootHash() []byte
	GetBalance() *big.Int
	GetDeveloperReward() *big.Int
	GetOwnerAddress() []byte
	GetUserName() []byte
	IsInterfaceNil() bool
}

UserAccountHandler defines a user account

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 Kalyan 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

	// CallType is the type of SmartContract call
	// Based on this value, the VM is informed of whether the call is direct,
	// asynchronous, or asynchronous callback.
	CallType CallType

	// 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

	// OriginalTxHash
	OriginalTxHash []byte

	// CurrentTxHash
	CurrentTxHash []byte
}

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

	// ReturnMessage is a message set by the SmartContract, destined for the
	// caller
	ReturnMessage string

	// 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 accounts changed as a result of the
	// Transaction. It is a map containing pointers to OutputAccount structs,
	// indexed with strings produced by `string(OutputAccount.Address)`, for fast
	// access by the Address of the OutputAccount.
	// This information tells the Node 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 map[string]*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.

Source Files

View all Source files

Directories

Path Synopsis

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.