engineio

type CallEncoder ¶

type CallEncoder interface {
	EncodeInputs(map[string]any, ReferenceProvider) ([]byte, error)
	DecodeOutputs([]byte) (map[string]any, error)
}

CallEncoder is an interface with capabilities to encode inputs and decode outputs for a specific callable site. It can be generated from either a Manifest or LogicDriver.

type CallResult ¶

type CallResult interface {
	// Ok specifies whether the execution call was successful.
	// If true, Error() must return nil.
	Ok() bool
	// Fuel specifies the amount of EngineFuel that was consumed
	// for the execution call regardless of its successful run.
	Fuel() EngineFuel
	// Outputs returns the encoded outputs for the execution call.
	// May be nil if the call has no return values
	Outputs() []byte

	// Error returns the encoded error for the execution call (if any).
	// Must return a non-nil value if Ok() is false and vice versa.
	//
	// The output bytes must be decodable into an ErrorResult
	// using the DecodeErrorResult method of EngineRuntime
	Error() []byte
}

CallResult is the output of the Call method of Engine. It expresses the amount of engine fuel consumed for the call along with result of the call which can either be some outputs or an error response

type Callsite ¶

type Callsite struct {
	Ptr  ElementPtr
	Kind CallsiteKind
}

Callsite represents a callable point in a Logic. It can be resolved from a string identifier with the GetCallsite method on Logic

type CallsiteKind ¶

type CallsiteKind int

CallsiteKind represents the type of callable point in a Logic.

const (
	LocalCallsite CallsiteKind = iota
	InvokableCallsite
	InteractableCallsite
	DeployerCallsite
	EnlisterCallsite
)

func (callsite *CallsiteKind) Depolorize(depolorizer *polo.Depolorizer) error

func (callsite CallsiteKind) MarshalJSON() ([]byte, error)

func (callsite CallsiteKind) MarshalYAML() (interface{}, error)

func (callsite CallsiteKind) Polorize() (*polo.Polorizer, error)

func (callsite CallsiteKind) String() string

func (callsite *CallsiteKind) UnmarshalJSON(data []byte) error

func (callsite *CallsiteKind) UnmarshalYAML(node *yaml.Node) error

type Classdef ¶

type Classdef struct {
	Ptr ElementPtr
}

Classdef represents a class definition in a Logic. It can be resolved from a string by looking it up on the LogicDriver

type ContextStateKind ¶

type ContextStateKind int

ContextStateKind represents the scope of stateful data in a context

const (
	PersistentState ContextStateKind = iota
	EphemeralState
)

func (state *ContextStateKind) Depolorize(depolorizer *polo.Depolorizer) error

func (state ContextStateKind) MarshalJSON() ([]byte, error)

func (state ContextStateKind) MarshalYAML() (interface{}, error)

func (state ContextStateKind) Polorize() (*polo.Polorizer, error)

func (state ContextStateKind) String() string

func (state *ContextStateKind) UnmarshalJSON(data []byte) error

func (state *ContextStateKind) UnmarshalYAML(node *yaml.Node) error

type ContextStateMatrix ¶

type ContextStateMatrix map[ContextStateKind]ElementPtr

ContextStateMatrix is matrix indicating the use of different types of context state and the element pointers for them

func (matrix ContextStateMatrix) Ephemeral() bool

func (matrix ContextStateMatrix) Persistent() bool

type CryptoDriver ¶

type CryptoDriver interface {
	ValidateSignature(sig []byte) bool
	VerifySignature(data, sig, pub []byte) (bool, error)
}

CryptoDriver represents an interface for cryptographic operations. It can be used to validate signature formats and verify them for a public key. This interfaces allows us to pass the capabilities of go-moi's crypto package to different engine runtimes.

func FetchCryptoDriver(kind EngineKind) (CryptoDriver, bool)

type CtxDriver ¶

type CtxDriver interface {
	Address() identifiers.Address
	LogicID() identifiers.LogicID

	GetStorageEntry([]byte) ([]byte, bool)
	SetStorageEntry([]byte, []byte) bool
}

CtxDriver represents an interface for accessing and manipulating context information of an account state. It is bounded to the context of particular account and can only mutate within applicable portions of the context state within the bounds of the logic's namespace

type DependencyDriver ¶

type DependencyDriver interface {
	fmt.Stringer
	json.Marshaler
	json.Unmarshaler

	polo.Polorizable
	polo.Depolorizable

	Insert(uint64, ...uint64)
	Remove(uint64)

	Size() uint64
	Iter() <-chan uint64
	Contains(uint64) bool
	Edges(uint64) []uint64
	Dependencies(uint64) []uint64
}

DependencyDriver represents an interface for an engine's element dependency manager.

It must be expressible as a string and encodable with JSON and POLO. It manages the dependency relationship between element pointers with the pointers being vertices and their relationship being directional edges.

type ElementKind ¶

type ElementKind string

ElementKind is a type alias for an element kind string

type ElementPtr ¶

type ElementPtr = uint64

ElementPtr is a type alias for an element pointer

type Encoding ¶ added in v0.1.1

type Encoding int

Encoding is an enum with variants that describe encoding schemes supported for file objects.

const (
	POLO Encoding = iota
	JSON
	YAML
)

type Engine ¶

type Engine interface {
	// Kind returns the kind of engine
	Kind() EngineKind

	// Call calls a logical callsite on the Engine's Logic.
	// The callsite and input calldata are provided in the given IxnDriver.
	// Optionally accepts some participant CtxDriver objects based on the interaction type.
	Call(context.Context, IxnDriver, ...CtxDriver) (CallResult, error)
}

Engine is an execution engine interface with a specific EngineKind. A new Engine instance can be spawned from an EngineRuntime with its SpawnEngine method an is bound to a specific Logic and EnvDriver.

An Engine can be used to perform calls on its Logic with an IxnDriver and some optional participants with their CtxDriver objects.

type EngineFuel ¶

type EngineFuel = uint64

EngineFuel is a measure of execution effort

type EngineKind ¶

type EngineKind string

EngineKind is an enum with its variants representing the set of valid engines

const (
	// PISA is the EngineKind for the PISA VM Runtime.
	// The canonical implementation is available at https://github.com/sarvalabs/go-pisa
	PISA EngineKind = "PISA"

	// MERU is the EngineKind for a hypothetical engine runtime that works as a
	// WASI (WebAssembly) based VM Runtime for MOI. No implementation exists yet.
	MERU EngineKind = "MERU"
)

type EngineRuntime ¶

type EngineRuntime interface {
	// Kind returns the kind of engine that the factory can produce
	Kind() EngineKind
	// Version returns the semver version string of the engine runtime
	Version() string

	// SpawnEngine returns a new Engine instance and initializes it with some
	// Fuel, a LogicDriver, the CtxDriver associated with the logic and an EnvDriver.
	// Will return an error if the LogicDriver and its CtxDriver do not match.
	SpawnEngine(EngineFuel, Logic, CtxDriver, EnvDriver) (Engine, error)

	// CompileManifest generates a LogicDescriptor from a Manifest, which can then be used to generate
	// a LogicDriver object. The fuel spent during compile is returned with any potential error.
	CompileManifest(EngineFuel, *Manifest) (*LogicDescriptor, EngineFuel, error)

	// ValidateCalldata verifies the calldata and callsite in an IxnObject.
	// The LogicDriver must describe a callsite which accepts the calldata.
	ValidateCalldata(Logic, IxnDriver) error

	// GetElementGenerator returns a generator function for an element schema with the
	// given ElementKind. Returns false, if no such element is defined by the runtime
	GetElementGenerator(ElementKind) (ManifestElementGenerator, bool)

	// GetCallEncoder returns a CallEncoder object for a given
	// callsite element pointer from a LogicDriver object
	GetCallEncoder(*Callsite, Logic) (CallEncoder, error)

	// DecodeDependencyDriver decodes the given bytes of the given
	// encoding into a DepDriver that is supported by the engine runtime
	DecodeDependencyDriver([]byte, Encoding) (DependencyDriver, error)

	// DecodeErrorResult decodes the given bytes into an
	// ErrorResult that is used by the engine runtime
	DecodeErrorResult([]byte) (ErrorResult, error)
}

EngineRuntime is the base definition for execution engine runtime. It is used for runtime level behavioural capabilities rather for logic execution. This can include: - Compiling Manifest objects for the runtime into a Logic - Spawning execution Engine instances for a specific Logic - Validating input calldata for a specific callsite on a Logic - Obtaining a calldata encoder for a specific callsite on a Logic - Decoding DependencyDriver and ErrorResult objects for the runtime

func FetchEngineRuntime(kind EngineKind) (EngineRuntime, bool)

type EnvDriver ¶

type EnvDriver interface {
	Timestamp() int64
	ClusterID() string
}

EnvDriver represents a driver for environmental information. It describes information about the execution context such as the consensus cluster ID or execution timestamp.

type ErrorResult ¶

type ErrorResult interface {
	Engine() EngineKind
	String() string
	Bytes() []byte
	Reverted() bool
}

ErrorResult is an interface for an engine specific error message. It is returned as raw bytes within CallResult if an execution call fails.

It can be decoded from the raw data using the DecodeErrorResult method of EngineRuntime

type Hash ¶

type Hash = [32]byte

Hash is a 256-bit checksum digest

type IxnDriver ¶

type IxnDriver interface {
	IxnType() IxnType

	FuelPrice() *big.Int
	FuelLimit() uint64

	Callsite() string
	Calldata() []byte
}

IxnDriver represents a driver for interaction information. It describes the callsite and input calldata for execution calls along with other information such as the Interaction's fuel parameters or transfer funds.

type IxnType ¶

type IxnType interface {
	IxnID() int
	String() string
}

IxnType is an interface that describes the different kinds of interactions available on go-moi. Each IxnType has a unique ID and a string representation. It is implemented by common.IxType.

type Logic ¶

type Logic interface {
	// LogicID returns the unique Logic ID of the Logic
	LogicID() identifiers.LogicID
	// Engine returns the EngineKind of the Logic
	Engine() EngineKind
	// Manifest returns the hash of the logic's Manifest
	Manifest() Hash

	// IsSealed returns whether the state of the Logic has been sealed
	IsSealed() bool
	// IsAssetLogic returns whether the Logic is used for regulating an Asset
	IsAssetLogic() bool
	// IsInteractive returns whether the Logic supports Interactable Callsites
	IsInteractive() bool

	// PersistentState returns the pointer to the persistent state element
	// with a confirmation that the Logic defines a PersistentState
	PersistentState() (ElementPtr, bool)
	// EphemeralState returns the pointer to the ephemeral state element
	// with a confirmation that the Logic defines a EphemeralState
	EphemeralState() (ElementPtr, bool)

	// GetElementDeps returns the aggregated dependencies of an element pointer.
	// The aggregation includes all sub-dependencies recursively.
	GetElementDeps(ElementPtr) []ElementPtr
	// GetElement returns the LogicElement for a given element pointer with confirmation of its existence.
	GetElement(ElementPtr) (*LogicElement, bool)
	// GetCallsite returns Callsite for a given string name with confirmation of its existence.
	GetCallsite(string) (*Callsite, bool)
	// GetClassdef returns class Datatype for a given string name with confirmation of its existence.
	GetClassdef(string) (*Classdef, bool)
}

Logic is an interface for logic that can be executed within an Engine. Every logic is uniquely identified with a LogicID and serves as a source of code, elements and metadata that the Engine and its EngineRuntime can use during execution of a specific callsite within the Logic.

A Logic can usually be constructed with the information available within a LogicDescriptor. For example, go-moi uses the LogicDescriptor as the source for generating a state.LogicObject which implements the Logic interface and is the canonical object for all logic content.

The Logic contains within it one or more Callsite entries that can be called using the Call method on Engine. It also contains descriptions for various logical elements, addressed by their ElementPtr identifiers and Classdef entries for custom class definitions.

type LogicDescriptor ¶

type LogicDescriptor struct {
	Engine EngineKind

	ManifestRaw  []byte
	ManifestHash Hash
	Interactive  bool

	Dependency DependencyDriver
	Elements   LogicElementTable
	CtxState   ContextStateMatrix

	Callsites map[string]*Callsite
	Classdefs map[string]*Classdef
}

LogicDescriptor is a container type returned by the CompileManifest method of EngineRuntime. It allows different engine runtime to have a unified output standard when compiling manifests.

It serves as a source of information from which an object that implements the Logic interface can be generated. It contains within it the manifest's runtime engine, raw contents and hash apart from entries for the callsites and classdefs.

type LogicElement ¶

type LogicElement struct {
	// Kind represents some type identifier for the element
	Kind ElementKind
	// Deps represents the relational neighbours of the element
	Deps []ElementPtr
	// Data represents the data container for the element
	Data []byte
}

LogicElement represents a generic container for a logic Element. It is uniquely identified with a group name and an index pointer. Engine implementations are responsible for handling namespacing and index conflicts within a group.

type LogicElementTable ¶

type LogicElementTable map[ElementPtr]*LogicElement

LogicElementTable is a lookup map for LogicElements indexed by their ElementPtr

type Manifest ¶

type Manifest struct {
	Syntax   string            `yaml:"syntax" json:"syntax"`
	Engine   ManifestEngine    `yaml:"engine" json:"engine"`
	Elements []ManifestElement `yaml:"elements" json:"elements"`
}

Manifest is the canonical deployment artifact for logics in MOI.

It is a composite artifact that describes the bytecode, the binary interface (ABI) and other parameters for the runtime of choice. The spec for LogicManifests is available at https://sarvalabs.notion.site/Logic-Manifest-Standard-93f5fee1af8d4c3cad155b9827b97930?pvs=4

func NewManifest(data []byte, encoding Encoding) (*Manifest, error)

func ReadManifestFile(path string) (*Manifest, error)

func (manifest *Manifest) Depolorize(depolorizer *polo.Depolorizer) (err error)

func (manifest Manifest) Encode(encoding Encoding) ([]byte, error)

func (manifest Manifest) Hash() ([32]byte, error)

func (manifest Manifest) Header() ManifestHeader

func (manifest *Manifest) UnmarshalJSON(data []byte) (err error)

func (manifest *Manifest) UnmarshalYAML(node *yaml.Node) error

type ManifestElement ¶

type ManifestElement struct {
	Ptr  ElementPtr            `yaml:"ptr" json:"ptr"`
	Deps []ElementPtr          `yaml:"deps" json:"deps"`
	Kind ElementKind           `yaml:"kind" json:"kind"`
	Data ManifestElementObject `yaml:"data" json:"data"`
}

ManifestElement describes a single element in the Manifest. It is converted into a LogicElement after compilation.

Each element is of a particular type (described by the engine runtime) and is identified by a unique 64-bit pointer and describes its dependencies with other elements in the manifest.

The data of the manifest element must be resolved into the format specific for the runtime based on its kind. The raw object to decode into can be accessed with the GetElementGenerator method of EngineRuntime.

type ManifestElementGenerator ¶

type ManifestElementGenerator func() ManifestElementObject

ManifestElementGenerator is a generator function that returns an empty instance of the element type

type ManifestElementObject ¶

type ManifestElementObject interface {
	polo.Polorizable
	polo.Depolorizable
}

The ManifestElementObject is a placeholder that we can decode the element's data into. Types that implement them are specified by the runtime and must de/serializable to all supported formats.

type ManifestEngine ¶

type ManifestEngine struct {
	Kind  string   `yaml:"kind" json:"kind"`
	Flags []string `yaml:"flags" json:"flags"`
}

ManifestEngine describes the engine specific information in the Manifest

type ManifestHeader ¶

type ManifestHeader struct {
	Syntax string         `yaml:"syntax" json:"syntax"`
	Engine ManifestEngine `yaml:"engine" json:"engine"`
}

ManifestHeader represents the header for a Manifest and describes its syntax form and engine specification. Useful for determining which engine to use to handle the Manifest. Every engine's manifest implementation must be able to decode into this header.

func (header ManifestHeader) LogicEngine() EngineKind

type ReferenceProvider ¶

type ReferenceProvider interface {
	GetReference(ReferenceVal) (any, bool)
}

ReferenceProvider resolves a ReferenceVal into an encodable value confirming the resolution

type ReferenceVal ¶

type ReferenceVal string

ReferenceVal is a reference identifier that resolves to an encodable value

func (ref ReferenceVal) String() string