Documentation ¶
Index ¶
- Constants
- Variables
- func IsAllowedToSaveUnderKey(key []byte) bool
- func IsEmptyAddress(address []byte) bool
- func IsMetachainIdentifier(identifier []byte) bool
- func IsSmartContractAddress(rcvAddress []byte) bool
- func IsSmartContractOnMetachain(identifier []byte, rcvAddress []byte) bool
- func IsSystemAccountAddress(address []byte) bool
- func SafeSubUint64(a, b uint64) (uint64, error)
- type AcceptPayableHandler
- type AccountDataHandler
- type AccountHandler
- type AccountsAdapter
- type BaseOperationCost
- type BlockchainHook
- type BuiltInCost
- type BuiltInFunctionContainer
- type BuiltinFunction
- type CodeMetadata
- type ContractCallInput
- type ContractCreateInput
- type Coordinator
- type CryptoHook
- type DCTGlobalSettingsHandler
- type DCTRoleHandler
- type DCTTransfer
- type DCTTransferParser
- type EpochNotifier
- type EpochSubscriberHandler
- type FunctionNames
- type GasCost
- type LogEntry
- type Marshalizer
- type OutputAccount
- type OutputTransfer
- type ParsedDCTTransfers
- type PayableHandler
- type ReturnCode
- type StorageUpdate
- type UserAccountHandler
- type VMExecutionHandler
- type VMInput
- type VMOutput
Constants ¶
const ( // MetadataUpgradeable is the bit for upgradable flag MetadataUpgradeable = 1 // MetadataPayable is the bit for payable flag MetadataPayable = 2 // MetadataReadable is the bit for readable flag MetadataReadable = 4 )
const NumInitCharactersForScAddress = 10
NumInitCharactersForScAddress numbers of characters for smart contract address identifier
const ShardIdentiferLen = 2
ShardIdentiferLen number of characters for shard identifier in an address
const VMTypeLen = 2
VMTypeLen number of characters with VMType identifier in an address, these are the last 2 characters from the initial identifier
Variables ¶
var ErrSubtractionOverflow = errors.New("uint64 subtraction overflowed")
ErrSubtractionOverflow signals that uint64 subtraction overflowed
var SystemAccountAddress = bytes.Repeat([]byte{255}, 32)
SystemAccountAddress is the hard-coded address in which we save global settings on all shards
Functions ¶
func IsAllowedToSaveUnderKey ¶
IsAllowedToSaveUnderKey returns if saving key-value in data tries under given key is allowed
func IsEmptyAddress ¶
IsEmptyAddress returns whether an address is empty
func IsMetachainIdentifier ¶
IsMetachainIdentifier verifies if the identifier is of type metachain
func IsSmartContractAddress ¶
IsSmartContractAddress verifies if a set address is of type smart contract
func IsSmartContractOnMetachain ¶
IsSmartContractOnMetachain verifies if an address is smart contract on metachain
func IsSystemAccountAddress ¶
IsSystemAccountAddress returns true if given address is system account address
func SafeSubUint64 ¶
SafeSubUint64 performs subtraction on uint64 and returns an error if it overflows
Types ¶
type AcceptPayableHandler ¶ added in v0.0.6
type AcceptPayableHandler interface { SetPayableHandler(payableHandler PayableHandler) error IsInterfaceNil() bool }
AcceptPayableHandler defines the methods to accept a payable handler through a set function
type AccountDataHandler ¶
type AccountDataHandler interface { RetrieveValue(key []byte) ([]byte, error) SaveKeyValue(key []byte, value []byte) error IsInterfaceNil() bool }
AccountDataHandler models what how to manipulate data held by a SC account
type AccountHandler ¶
type AccountHandler interface { AddressBytes() []byte IncreaseNonce(nonce uint64) GetNonce() uint64 IsInterfaceNil() bool }
AccountHandler models a state account, which can journalize and revert It knows about code and data, as data structures not hashes
type AccountsAdapter ¶
type AccountsAdapter interface { GetExistingAccount(address []byte) (AccountHandler, error) LoadAccount(address []byte) (AccountHandler, error) SaveAccount(account AccountHandler) error RemoveAccount(address []byte) error Commit() ([]byte, error) JournalLen() int RevertToSnapshot(snapshot int) error GetNumCheckpoints() uint32 GetCode(codeHash []byte) []byte RootHash() ([]byte, error) RecreateTrie(rootHash []byte) error IsInterfaceNil() bool }
AccountsAdapter is used for the structure that manages the accounts on top of a trie.PatriciaMerkleTrie implementation
type BaseOperationCost ¶
type BaseOperationCost struct { StorePerByte uint64 ReleasePerByte uint64 DataCopyPerByte uint64 PersistPerByte uint64 CompilePerByte uint64 AoTPreparePerByte uint64 }
BaseOperationCost defines cost for base operation cost
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) // GetStorageData 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) // GetBlockhash 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) // GetCode returns the code for the given account GetCode(UserAccountHandler) []byte // 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 // IsPayable checks weather the provided address can receive MOA or not IsPayable(address []byte) (bool, error) // SaveCompiledCode saves to cache and storage the compiled code SaveCompiledCode(codeHash []byte, code []byte) // GetCompiledCode returns the compiled code if it finds in the cache or storage GetCompiledCode(codeHash []byte) (bool, []byte) // ClearCompiledCodes clears the cache and storage of compiled codes ClearCompiledCodes() // GetDCTToken loads the DCT digital token for the given key GetDCTToken(address []byte, tokenID []byte, nonce uint64) (*dct.DCToken, error) // GetSnapshot gets the number of entries in the journal as a snapshot id GetSnapshot() int // RevertToSnapshot reverts snaphots up to the specified one RevertToSnapshot(snapshot int) error // IsInterfaceNil returns true if there is no value under the interface IsInterfaceNil() bool }
BlockchainHook is the interface for VM blockchain callbacks
type BuiltInCost ¶
type BuiltInCost struct { ChangeOwnerAddress uint64 ClaimDeveloperRewards uint64 SaveUserName uint64 SaveKeyValue uint64 DCTTransfer uint64 DCTBurn uint64 DCTLocalMint uint64 DCTLocalBurn uint64 DCTNFTCreate uint64 DCTNFTAddQuantity uint64 DCTNFTBurn uint64 DCTNFTTransfer uint64 DCTNFTChangeCreateOwner uint64 DCTNFTMultiTransfer uint64 DCTNFTAddURI uint64 DCTNFTUpdateAttributes uint64 }
BuiltInCost defines cost for built-in methods
type BuiltInFunctionContainer ¶
type BuiltInFunctionContainer interface { Get(key string) (BuiltinFunction, error) Add(key string, function BuiltinFunction) error Replace(key string, function BuiltinFunction) error Remove(key string) Len() int Keys() map[string]struct{} IsInterfaceNil() bool }
BuiltInFunctionContainer defines the methods for the built-in protocol container
type BuiltinFunction ¶
type BuiltinFunction interface { ProcessBuiltinFunction(acntSnd, acntDst UserAccountHandler, vmInput *ContractCallInput) (*VMOutput, error) SetNewGasConfig(gasCost *GasCost) IsActive() bool IsInterfaceNil() bool }
BuiltinFunction defines the methods for the built-in protocol smart contract functions
type CodeMetadata ¶
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 Function string // AllowInitFunction specifies whether calling the initialization method of // the smart contract is allowed or not AllowInitFunction bool }
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. 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 vmcommon. We also do not need to specify a Function field, because on creation `init` is always called.
type Coordinator ¶
type Coordinator interface { NumberOfShards() uint32 ComputeId(address []byte) uint32 SelfId() uint32 SameShard(firstAddress, secondAddress []byte) bool CommunicationIdentifier(destShardID uint32) string IsInterfaceNil() bool }
Coordinator defines what a shard state coordinator should hold
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) // IsInterfaceNil returns true if there is no value under the interface IsInterfaceNil() bool }
CryptoHook interface for VM krypto functions
type DCTGlobalSettingsHandler ¶
type DCTGlobalSettingsHandler interface { IsPaused(token []byte) bool IsLimitedTransfer(tokenKey []byte) bool IsInterfaceNil() bool }
DCTGlobalSettingsHandler provides global settings functions for an DCT token
type DCTRoleHandler ¶
type DCTRoleHandler interface { CheckAllowedToExecute(account UserAccountHandler, tokenID []byte, action []byte) error IsInterfaceNil() bool }
DCTRoleHandler provides IsAllowedToExecute function for an DCT
type DCTTransfer ¶
type DCTTransfer struct { // DCTValue is the value (amount of tokens) transferred by the transaction. // Before reaching the VM this value is subtracted from sender balance (CallerAddr) // and to added to the smart contract balance. // It is often, but not always zero in SC calls. DCTValue *big.Int // DCTTokenName is the name of the token which was transferred by the transaction to the SC DCTTokenName []byte // DCTTokenType is the type of the transferred token DCTTokenType uint32 // DCTTokenNonce is the nonce for the given NFT token DCTTokenNonce uint64 }
DCTTransfer defines the structure for and DCT / NFT transfer
type DCTTransferParser ¶
type DCTTransferParser interface { ParseDCTTransfers(sndAddr []byte, rcvAddr []byte, function string, args [][]byte) (*ParsedDCTTransfers, error) IsInterfaceNil() bool }
DCTTransferParser can parse single and multi DCT / NFT transfers
type EpochNotifier ¶
type EpochNotifier interface { RegisterNotifyHandler(handler EpochSubscriberHandler) IsInterfaceNil() bool }
EpochNotifier can notify upon an epoch change and provide the current epoch
type EpochSubscriberHandler ¶
type EpochSubscriberHandler interface { EpochConfirmed(epoch uint32, timestamp uint64) IsInterfaceNil() bool }
EpochSubscriberHandler defines the behavior of a component that can be notified if a new epoch was confirmed
type FunctionNames ¶
type FunctionNames = map[string]struct{}
FunctionNames (alias) is a map of function names
type GasCost ¶
type GasCost struct { BaseOperationCost BaseOperationCost BuiltInCost BuiltInCost }
GasCost holds all the needed gas costs for system smart contracts
type LogEntry ¶
LogEntry represents an entry in the contract execution log. TODO: document all fields.
type Marshalizer ¶
type Marshalizer interface { Marshal(obj interface{}) ([]byte, error) Unmarshal(obj interface{}, buff []byte) error IsInterfaceNil() bool }
Marshalizer defines the 2 basic operations: serialize (marshal) and deserialize (unmarshal)
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 // 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 // CodeDeployerAddress will be populated in case of contract deployment or upgrade (both direct and indirect) CodeDeployerAddress []byte // BalanceDelta is by how much the balance should change following the SC execution. // A negative value indicates that balance should decrease. BalanceDelta *big.Int // OutputTransfers represents the cross shard calls for this account OutputTransfers []OutputTransfer // GasUsed will be populated if the contract was called in the same shard GasUsed 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.
func (*OutputAccount) MergeOutputAccounts ¶
func (o *OutputAccount) MergeOutputAccounts(outAcc *OutputAccount)
MergeOutputAccounts merges the given account into the current one
func (*OutputAccount) MergeStorageUpdates ¶
func (o *OutputAccount) MergeStorageUpdates(outAcc *OutputAccount)
MergeStorageUpdates will copy all the storage updates from the given output account
type OutputTransfer ¶
type OutputTransfer struct { // Value to be transferred Value *big.Int // GasLimit to used for the call GasLimit uint64 // GasLocked holds the amount of gas to be kept aside for the eventual callback execution GasLocked uint64 // Data to be used in cross call Data []byte // CallType is set if it is a smart contract invocation CallType vm.CallType // SenderAddress is the actual sender for the given output transfer, this is needed when // contract A calls contract B and contract B does the transfers SenderAddress []byte }
OutputTransfer contains the fields needed to create transfers to another shard
type ParsedDCTTransfers ¶
type ParsedDCTTransfers struct { DCTTransfers []*DCTTransfer RcvAddr []byte CallFunction string CallArgs [][]byte }
ParsedDCTTransfers defines the struct for the parsed dct transfers
type PayableHandler ¶
PayableHandler provides IsPayable function which returns if an account is payable or not
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 // SimulateFailed is returned when tx simulation fails execution SimulateFailed ReturnCode = 12 )
func (ReturnCode) String ¶
func (rc ReturnCode) String() string
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 { GetCodeMetadata() []byte GetCodeHash() []byte GetRootHash() []byte AccountDataHandler() AccountDataHandler AddToBalance(value *big.Int) error GetBalance() *big.Int ClaimDeveloperRewards([]byte) (*big.Int, error) GetDeveloperReward() *big.Int ChangeOwnerAddress([]byte, []byte) error SetOwnerAddress([]byte) GetOwnerAddress() []byte SetUserName(userName []byte) GetUserName() []byte AccountHandler }
UserAccountHandler models a user account, which can journalize account's data with some extra features like balance, developer rewards, owner
type VMExecutionHandler ¶
type VMExecutionHandler interface { // RunSmartContractCreate computes how a smart contract creation should be performed RunSmartContractCreate(input *ContractCreateInput) (*VMOutput, error) // RunSmartContractCall computes the result of a smart contract call and how the system must change after the execution RunSmartContractCall(input *ContractCallInput) (*VMOutput, error) // GasScheduleChange sets a new gas schedule for the VM GasScheduleChange(newGasSchedule map[string]map[string]uint64) // GetVersion returns the version of the VM instance GetVersion() string // IsInterfaceNil returns true if there is no value under the interface IsInterfaceNil() bool }
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 MOA value (amount of tokens) transferred by the transaction. // Before reaching the VM this value is subtracted from sender balance (CallerAddr) // and to added 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 vm.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 // GasLocked is the amount of gas that must be kept unused during the current // call, because it will be used later for a callback. This field is only // used during asynchronous calls. GasLocked uint64 // OriginalTxHash OriginalTxHash []byte // CurrentTxHash CurrentTxHash []byte // PrevTxHash PrevTxHash []byte // DCTTransfers DCTTransfers []*DCTTransfer // ReturnCallAfterError ReturnCallAfterError bool }
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 vmcommon. // 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 vm.ReturnDataKind) (interface{}, error)
GetFirstReturnData is a helper function that returns the first ReturnData of VMOutput, interpreted as specified.