arwen

Documentation

Index

• Constants
• Variables
• func AddHostContext(ctx VMHost) int
• func BooleanToInt(b bool) int
• func CustomStorageKey(keyType string, associatedKey []byte) []byte
• func GetCryptoContext(context unsafe.Pointer) vmcommon.CryptoHook
• func GetSCCode(fileName string) []byte
• func GuardedGetBytesSlice(data []byte, offset int32, length int32) ([]byte, error)
• func GuardedMakeByteSlice2D(length int32) ([][]byte, error)
• func IfNil(checker nilInterfaceChecker) bool
• func InverseBytes(data []byte) []byte
• func PadBytesLeft(data []byte, size int) []byte
• func RemoveAllHostContexts()
• func RemoveHostContext(idx int)
• func TimeTrack(start time.Time, message string)
• func U64MulToBigInt(x, y uint64) *big.Int
• func WithFault(err error, context unsafe.Pointer, failExecution bool) bool
• type AsyncCallExecutionMode
• type AsyncCallInfo
  • func (aci *AsyncCallInfo) GetData() []byte
  • func (aci *AsyncCallInfo) GetDestination() []byte
  • func (aci *AsyncCallInfo) GetGasLimit() uint64
  • func (aci *AsyncCallInfo) GetValueBytes() []byte
• type AsyncCallInfoHandler
• type AsyncCallStatus
• type AsyncContext
• type AsyncContextInfo
• type AsyncGeneratedCall
  • func (ac *AsyncGeneratedCall) GetData() []byte
  • func (ac *AsyncGeneratedCall) GetDestination() []byte
  • func (ac *AsyncGeneratedCall) GetGasLimit() uint64
  • func (ac *AsyncGeneratedCall) GetValueBytes() []byte
  • func (ac *AsyncGeneratedCall) IsInterfaceNil() bool
• type BigIntContext
  • func GetBigIntContext(context unsafe.Pointer) BigIntContext
• type BlockchainContext
  • func GetBlockchainContext(context unsafe.Pointer) BlockchainContext
• type BreakpointValue
• type CallArgsParser
• type CodeDeployInput
• type MeteringContext
  • func GetMeteringContext(context unsafe.Pointer) MeteringContext
• type OutputContext
  • func GetOutputContext(context unsafe.Pointer) OutputContext
• type RuntimeContext
  • func GetRuntimeContext(context unsafe.Pointer) RuntimeContext
• type StateStack
• type StorageContext
  • func GetStorageContext(context unsafe.Pointer) StorageContext
• type StorageStatus
• type VMHost
  • func GetVmContext(context unsafe.Pointer) VMHost
• type VMHostParameters

Constants

const AddressLen = 32

const AddressLenEth = 20

const ArgumentLenEth = 32

const AsyncDataPrefix = "asyncCalls"

const BalanceLen = 32

const CallBackFunctionName = "callBack"

const CallbackDefault = "callBack"

const HashLen = 32

const InitFunctionName = "init"

const InitFunctionNameEth = "solidity.ctor"

const TimeLockKeyPrefix = "timelock"

const UpgradeFunctionName = "upgradeContract"

Variables

var ErrArgIndexOutOfRange = errors.New("argument index out of range")

var ErrArgOutOfRange = errors.New("argument out of range")

var ErrAsync = errors.New("invalid gas percentage provided for async call")

var ErrAsyncContextDoesNotExist = errors.New("async context was not created yet")

var ErrBadBounds = errors.New("bad bounds")

var ErrBadLowerBounds = fmt.Errorf("%w (lower)", ErrBadBounds)

var ErrBadUpperBounds = fmt.Errorf("%w (upper)", ErrBadBounds)

var ErrBitwiseNegative = errors.New("bitwise operations only allowed on positive integers")

var ErrCallBackFuncCalledInRun = fmt.Errorf("%w (calling callBack() directly is forbidden)", ErrInvalidFunction)

var ErrCallBackFuncNotExpected = fmt.Errorf("%w (unexpected callback was received)", ErrInvalidFunction)

var ErrContractInvalid = fmt.Errorf("invalid contract code")

var ErrContractNotFound = fmt.Errorf("%w (not found)", ErrContractInvalid)

var ErrDivZero = errors.New("division by 0")

var ErrExecutionFailed = errors.New("execution failed")

var ErrFailedTransfer = errors.New("failed transfer")

var ErrFailedTransferDuringAsyncCall = fmt.Errorf("%w (failed during async call)", ErrFailedTransfer)

var ErrFuncNotFound = fmt.Errorf("%w (not found)", ErrInvalidFunction)

var ErrFunctionNonvoidSignature = fmt.Errorf("%w (nonvoid signature)", ErrInvalidFunction)

var ErrFunctionRunError = errors.New("function run error")

var ErrInitFuncCalledInRun = fmt.Errorf("%w (calling init() directly is forbidden)", ErrInvalidFunction)

var ErrInvalidAPICall = errors.New("invalid API call")

var ErrInvalidAccount = errors.New("account does not exist")

var ErrInvalidCallOnReadOnlyMode = errors.New("operation not permitted in read only mode")

var ErrInvalidFunction = errors.New("invalid function")

var ErrInvalidFunctionName = fmt.Errorf("%w (invalid name)", ErrInvalidFunction)

var ErrInvalidUpgradeArguments = fmt.Errorf("%w (invalid arguments)", ErrUpgradeFailed)

var ErrMaxInstancesReached = fmt.Errorf("%w (max instances reached)", ErrExecutionFailed)

var ErrMemoryDeclarationMissing = fmt.Errorf("%w (missing memory declaration)", ErrContractInvalid)

var ErrNegativeLength = errors.New("negative length")

var ErrNotEnoughGas = errors.New("not enough gas")

var ErrReturnCodeNotOk = errors.New("return not is not ok")

var ErrShiftNegative = errors.New("bitwise shift operations only allowed on positive integers and by a positive amount")

var ErrSignalError = errors.New("error signalled by smartcontract")

var ErrStoreKalyan3104ReservedKey = errors.New("cannot write to storage under Kalyan3104 reserved key")

var ErrTransferInsufficientFunds = fmt.Errorf("%w (insufficient funds)", ErrFailedTransfer)

var ErrTransferNegativeValue = fmt.Errorf("%w (negative value)", ErrFailedTransfer)

var ErrUnhandledRuntimeBreakpoint = errors.New("unhandled runtime breakpoint")

var ErrUpgradeFailed = errors.New("upgrade failed")

var Zero = big.NewInt(0)

Zero is the big integer 0

Functions

func AddHostContext

func AddHostContext(ctx VMHost) int

func BooleanToInt

func BooleanToInt(b bool) int

func CustomStorageKey

func CustomStorageKey(keyType string, associatedKey []byte) []byte

func GetCryptoContext

func GetCryptoContext(context unsafe.Pointer) vmcommon.CryptoHook

func GetSCCode

func GetSCCode(fileName string) []byte

func GuardedGetBytesSlice

func GuardedGetBytesSlice(data []byte, offset int32, length int32) ([]byte, error)

func GuardedMakeByteSlice2D

func GuardedMakeByteSlice2D(length int32) ([][]byte, error)

func IfNil

func IfNil(checker nilInterfaceChecker) bool

IfNil tests if the provided interface pointer or underlying object is nil

func InverseBytes

func InverseBytes(data []byte) []byte

func PadBytesLeft

func PadBytesLeft(data []byte, size int) []byte

func RemoveAllHostContexts

func RemoveAllHostContexts()

func RemoveHostContext

func RemoveHostContext(idx int)

func TimeTrack

func TimeTrack(start time.Time, message string)

func U64MulToBigInt

func U64MulToBigInt(x, y uint64) *big.Int

func WithFault

func WithFault(err error, context unsafe.Pointer, failExecution bool) bool

Types

type AsyncCallExecutionMode

type AsyncCallExecutionMode uint

const (
	SyncCall AsyncCallExecutionMode = iota
	AsyncBuiltinFunc
	AsyncUnknown
)

type AsyncCallInfo

type AsyncCallInfo struct {
	Destination []byte
	Data        []byte
	GasLimit    uint64
	ValueBytes  []byte
}

AsyncCallInfo contains the information required to handle the asynchronous call of another SmartContract

func (*AsyncCallInfo) GetData

func (aci *AsyncCallInfo) GetData() []byte

func (*AsyncCallInfo) GetDestination

func (aci *AsyncCallInfo) GetDestination() []byte

func (*AsyncCallInfo) GetGasLimit

func (aci *AsyncCallInfo) GetGasLimit() uint64

func (*AsyncCallInfo) GetValueBytes

func (aci *AsyncCallInfo) GetValueBytes() []byte

type AsyncCallInfoHandler

type AsyncCallInfoHandler interface {
	GetDestination() []byte
	GetData() []byte
	GetGasLimit() uint64
	GetValueBytes() []byte
}

type AsyncCallStatus

type AsyncCallStatus uint8

AsyncCallStatus represents the different status an async call can have

const (
	AsyncCallPending AsyncCallStatus = iota
	AsyncCallResolved
	AsyncCallRejected
)

type AsyncContext

type AsyncContext struct {
	Callback   string
	AsyncCalls []*AsyncGeneratedCall
}

AsyncContext is a structure containing a group of async calls and a callback

that should be called when all these async calls are resolved

type AsyncContextInfo

type AsyncContextInfo struct {
	CallerAddr      []byte
	ReturnData      []byte
	AsyncContextMap map[string]*AsyncContext
}

AsyncContextInfo is the structure resulting after a smart contract call that has initiated one or more async calls. It will

type AsyncGeneratedCall

type AsyncGeneratedCall struct {
	Status          AsyncCallStatus
	Destination     []byte
	Data            []byte
	GasLimit        uint64
	ValueBytes      []byte
	SuccessCallback string
	ErrorCallback   string
	ProvidedGas     uint64
}

AsyncGeneratedCall holds the information abount an async call

func (*AsyncGeneratedCall) GetData

func (ac *AsyncGeneratedCall) GetData() []byte

GetData returns the transaction data of the async call

func (*AsyncGeneratedCall) GetDestination

func (ac *AsyncGeneratedCall) GetDestination() []byte

GetDestination returns the destination of an async call

func (*AsyncGeneratedCall) GetGasLimit

func (ac *AsyncGeneratedCall) GetGasLimit() uint64

GetGasLimit returns the gas limit of the current async call

func (*AsyncGeneratedCall) GetValueBytes

func (ac *AsyncGeneratedCall) GetValueBytes() []byte

GetValueBytes returns the byte representation of the value of the async call

func (*AsyncGeneratedCall) IsInterfaceNil

func (ac *AsyncGeneratedCall) IsInterfaceNil() bool

IsInterfaceNil returns true if there is no value under the interface

type BigIntContext

type BigIntContext interface {
	StateStack

	Put(value int64) int32
	GetOne(id int32) *big.Int
	GetTwo(id1, id2 int32) (*big.Int, *big.Int)
	GetThree(id1, id2, id3 int32) (*big.Int, *big.Int, *big.Int)
}

func GetBigIntContext

func GetBigIntContext(context unsafe.Pointer) BigIntContext

type BlockchainContext

type BlockchainContext interface {
	NewAddress(creatorAddress []byte) ([]byte, error)
	AccountExists(addr []byte) bool
	GetBalance(addr []byte) []byte
	GetBalanceBigInt(addr []byte) *big.Int
	GetNonce(addr []byte) (uint64, error)
	CurrentEpoch() uint32
	GetStateRootHash() []byte
	LastTimeStamp() uint64
	LastNonce() uint64
	LastRound() uint64
	LastEpoch() uint32
	CurrentRound() uint64
	CurrentNonce() uint64
	CurrentTimeStamp() uint64
	CurrentRandomSeed() []byte
	LastRandomSeed() []byte
	IncreaseNonce(addr []byte)
	GetCodeHash(addr []byte) ([]byte, error)
	GetCode(addr []byte) ([]byte, error)
	GetCodeSize(addr []byte) (int32, error)
	BlockHash(number int64) []byte
	GetOwnerAddress() ([]byte, error)
	GetShardOfAddress(addr []byte) uint32
	IsSmartContract(addr []byte) bool
}

func GetBlockchainContext

func GetBlockchainContext(context unsafe.Pointer) BlockchainContext

type BreakpointValue

type BreakpointValue uint64

const (
	BreakpointNone BreakpointValue = iota
	BreakpointExecutionFailed
	BreakpointAsyncCall
	BreakpointSignalError
	BreakpointSignalExit
	BreakpointOutOfGas
)

type CallArgsParser

type CallArgsParser interface {
	ParseData(data string) (string, [][]byte, error)
	IsInterfaceNil() bool
}

CallArgsParser defines the functionality to parse transaction data for a smart contract call

type CodeDeployInput

type CodeDeployInput struct {
	ContractCode         []byte
	ContractCodeMetadata []byte
	ContractAddress      []byte
}

CodeDeployInput contains code deploy state, whether it comes from a ContractCreateInput or a ContractCallInput

type MeteringContext

type MeteringContext interface {
	GasSchedule() *config.GasCost
	UseGas(gas uint64)
	FreeGas(gas uint64)
	RestoreGas(gas uint64)
	GasLeft() uint64
	BoundGasLimit(value int64) uint64
	BlockGasLimit() uint64
	DeductInitialGasForExecution(contract []byte) error
	DeductInitialGasForDirectDeployment(input CodeDeployInput) error
	DeductInitialGasForIndirectDeployment(input CodeDeployInput) error
	UnlockGasIfAsyncStep()
	GetGasLockedForAsyncStep() uint64
}

func GetMeteringContext

func GetMeteringContext(context unsafe.Pointer) MeteringContext

type OutputContext

type OutputContext interface {
	StateStack
	PopMergeActiveState()
	CensorVMOutput()
	AddToActiveState(rightOutput *vmcommon.VMOutput)

	GetOutputAccount(address []byte) (*vmcommon.OutputAccount, bool)
	WriteLog(address []byte, topics [][]byte, data []byte)
	Transfer(destination []byte, sender []byte, gasLimit uint64, value *big.Int, input []byte) error
	SelfDestruct(address []byte, beneficiary []byte)
	GetRefund() uint64
	SetRefund(refund uint64)
	ReturnCode() vmcommon.ReturnCode
	SetReturnCode(returnCode vmcommon.ReturnCode)
	ReturnMessage() string
	SetReturnMessage(message string)
	ReturnData() [][]byte
	ClearReturnData()
	Finish(data []byte)
	GetVMOutput() *vmcommon.VMOutput
	AddTxValueToAccount(address []byte, value *big.Int)
	DeployCode(input CodeDeployInput)
	CreateVMOutputInCaseOfError(err error) *vmcommon.VMOutput
}

func GetOutputContext

func GetOutputContext(context unsafe.Pointer) OutputContext

type RuntimeContext

type RuntimeContext interface {
	StateStack

	InitStateFromContractCallInput(input *vmcommon.ContractCallInput)
	SetCustomCallFunction(callFunction string)
	GetVMInput() *vmcommon.VMInput
	SetVMInput(vmInput *vmcommon.VMInput)
	GetSCAddress() []byte
	SetSCAddress(scAddress []byte)
	GetVMType() []byte
	Function() string
	Arguments() [][]byte
	GetCurrentTxHash() []byte
	GetOriginalTxHash() []byte
	ExtractCodeUpgradeFromArgs() ([]byte, []byte, error)
	SignalUserError(message string)
	FailExecution(err error)
	SetRuntimeBreakpointValue(value BreakpointValue)
	GetRuntimeBreakpointValue() BreakpointValue
	GetAsyncCallInfo() *AsyncCallInfo
	SetAsyncCallInfo(asyncCallInfo *AsyncCallInfo)
	AddAsyncContextCall(contextIdentifier []byte, asyncCall *AsyncGeneratedCall) error
	GetAsyncContextInfo() *AsyncContextInfo
	GetAsyncContext(contextIdentifier []byte) (*AsyncContext, error)
	PushInstance()
	PopInstance()
	RunningInstancesCount() uint64
	ClearInstanceStack()
	ReadOnly() bool
	SetReadOnly(readOnly bool)
	StartWasmerInstance(contract []byte, gasLimit uint64) error
	SetMaxInstanceCount(uint64)
	VerifyContractCode() error
	SetInstanceContext(instCtx *wasmer.InstanceContext)
	GetInstanceContext() *wasmer.InstanceContext
	GetInstanceExports() wasmer.ExportsMap
	GetInitFunction() wasmer.ExportedFunctionCallback
	GetFunctionToCall() (wasmer.ExportedFunctionCallback, error)
	GetPointsUsed() uint64
	SetPointsUsed(gasPoints uint64)
	MemStore(offset int32, data []byte) error
	MemLoad(offset int32, length int32) ([]byte, error)
	CleanInstance()
	SetInstanceContextID(id int)
	Kalyan3104APIErrorShouldFailExecution() bool
	CryptoAPIErrorShouldFailExecution() bool
	BigIntAPIErrorShouldFailExecution() bool
}

func GetRuntimeContext

func GetRuntimeContext(context unsafe.Pointer) RuntimeContext

type StateStack

type StateStack interface {
	InitState()
	PushState()
	PopSetActiveState()
	PopDiscard()
	ClearStateStack()
}

type StorageContext

type StorageContext interface {
	StateStack

	SetAddress(address []byte)
	GetStorageUpdates(address []byte) map[string]*vmcommon.StorageUpdate
	GetStorage(key []byte) []byte
	SetStorage(key []byte, value []byte) (StorageStatus, error)
}

func GetStorageContext

func GetStorageContext(context unsafe.Pointer) StorageContext

type StorageStatus

type StorageStatus int

const (
	StorageUnchanged StorageStatus = iota
	StorageModified
	StorageAdded
	StorageDeleted
)

type VMHost

type VMHost interface {
	Crypto() vmcommon.CryptoHook
	Blockchain() BlockchainContext
	Runtime() RuntimeContext
	BigInt() BigIntContext
	Output() OutputContext
	Metering() MeteringContext
	Storage() StorageContext

	CreateNewContract(input *vmcommon.ContractCreateInput) ([]byte, error)
	ExecuteOnSameContext(input *vmcommon.ContractCallInput) (*AsyncContextInfo, error)
	ExecuteOnDestContext(input *vmcommon.ContractCallInput) (*vmcommon.VMOutput, *AsyncContextInfo, error)
	EthereumCallData() []byte
	GetAPIMethods() *wasmer.Imports
	GetProtocolBuiltinFunctions() vmcommon.FunctionNames
}

func GetVmContext

func GetVmContext(context unsafe.Pointer) VMHost

type VMHostParameters

type VMHostParameters struct {
	VMType                       []byte
	BlockGasLimit                uint64
	GasSchedule                  config.GasScheduleMap
	ProtocolBuiltinFunctions     vmcommon.FunctionNames
	Kalyan3104ProtectedKeyPrefix []byte
}

VMHostParameters represents the parameters to be passed to VMHost