coretypes

package
v0.1.0 Latest Latest
Warning

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

 Go to latest Published: Mar 3, 2021 License: Apache-2.0, BSD-2-Clause Imports: 19 Imported by: 0

Documentation

Overview

Package 'coretypes' defines fundamental types used in the Wasp.

The core types are mostly based on the fundamental data types of Goshimmer

Index

Constants

View Source 
const AgentIDLength = ContractIDLength // max(ContractIDLength, address.Length)

AgentIDLength is the size of AgentID in bytes

View Source 
const ChainIDLength = address.Length

ChainIDLength size of the ChainID in bytes

View Source 
const ContractIDLength = ChainIDLength + HnameLength

ContractIDLength size of the contract ID in bytes

View Source 
const DefaultTTL = 1 * time.Hour
View Source 
const FuncInit = "init"

FuncInit is a name of the init function for any smart contract

View Source 
const HnameLength = 4
View Source 
const RequestIDLength = valuetransaction.IDLength + 2

RequestIDLength size of the RequestID in bytes

Variables

View Source 
var (
	// NilEntryPointFull represents empty full entry point
	NilEntryPointFull = nilEntryPoint(false)
	// NilEntryPointView represents empty view entry point
	NilEntryPointView = nilEntryPoint(true)
)
View Source 
var EntryPointInit = Hn(FuncInit)

EntryPointInit is a hashed name of the init function

View Source 
var (
	ErrWrongDataLength = errors.New("wrong data length")
)
View Source 
var ErrWrongTypeEntryPoint = fmt.Errorf("wrong type of entry point")
View Source 
var NilChainID = ChainID{}

Functions

func ReadAgentID 

func ReadAgentID(r io.Reader, agentID *AgentID) error

ReadAgentID decodes from binary representation

Types

type AgentID 

type AgentID [AgentIDLength]byte

AgentID represents exactly one of two types of entities on the ISCP ledger in one ID:

  • It can represent an address on the Tangle (controlled by some private key). In this case it can be interpreted as address.Address type (see MustAddress).
  • alternatively, it can represent a smart contract on the ISCP. In this case it can be interpreted as a coretypes.ContractID type (see MustContractID)

Type of ID represented by the AgentID can be recognized with IsAddress call. An attempt to interpret the AgentID in the wrong way invokes panic

func NewAgentIDFromAddress 

func NewAgentIDFromAddress(addr address.Address) AgentID

NewAgentIDFromAddress makes AgentID from address.Address

func NewAgentIDFromBytes 

func NewAgentIDFromBytes(data []byte) (ret AgentID, err error)

NewAgentIDFromBytes makes an AgentID from binary representation

func NewAgentIDFromContractID 

func NewAgentIDFromContractID(id ContractID) (ret AgentID)

NewAgentIDFromContractID makes AgentID from ContractID

func NewAgentIDFromSigScheme 

func NewAgentIDFromSigScheme(sigScheme signaturescheme.SignatureScheme) AgentID

NewAgentIDFromSigScheme makes AgentID from signaturescheme.SignatureScheme

func NewAgentIDFromString 

func NewAgentIDFromString(s string) (ret AgentID, err error)

NewAgentIDFromString parses the human-readable string representation

func NewRandomAgentID 

func NewRandomAgentID() AgentID

NewRandomAgentID creates random AgentID

func (AgentID) Base58 

func (a AgentID) Base58() string

func (AgentID) IsAddress 

func (a AgentID) IsAddress() bool

IsAddress checks if agentID represents address. 0 in the place of the contract's hname means it is an address This is based on the assumption that fro coretypes.Hname 0 is a reserved value

func (AgentID) MustAddress 

func (a AgentID) MustAddress() (ret address.Address)

MustAddress takes address or panic if not address

func (AgentID) MustContractID 

func (a AgentID) MustContractID() (ret ContractID)

MustContractID takes contract ID or panics if not a contract ID

func (AgentID) String 

func (a AgentID) String() string

String human readable string

type BLS 

type BLS interface {
	ValidSignature(data []byte, pubKey []byte, signature []byte) bool
	AddressFromPublicKey(pubKey []byte) (address.Address, error)
	AggregateBLSSignatures(pubKeysBin [][]byte, sigsBin [][]byte) ([]byte, []byte, error)
}

type Base58 

type Base58 interface {
	Decode(s string) ([]byte, error)
	Encode(data []byte) string
}

type BlobCache 

type BlobCache interface {
	GetBlob(h hashing.HashValue) ([]byte, bool, error)
	HasBlob(h hashing.HashValue) (bool, error)
}

type BlobCacheFull 

type BlobCacheFull interface {
	BlobCache
	// PutBlob ttl s TimeToLive, expiration time in Unix nanoseconds
	PutBlob(data []byte, ttl ...time.Duration) (hashing.HashValue, error)
}

type ChainID 

type ChainID address.Address

ChainID represents the global identifier of the chain

Currently it is an alias for the chain address (type address.Address) In the future it will be refactored as an alias for chain color (type balance.Color)

func NewChainIDFromBase58 

func NewChainIDFromBase58(b58 string) (ret ChainID, err error)

NewChainIDFromBase58 constructor decodes base58 string to the ChainID

func NewChainIDFromBytes 

func NewChainIDFromBytes(data []byte) (ret ChainID, err error)

NewChainIDFromBytes reconstructs a ChainID from its binary representation.

func NewRandomChainID 

func NewRandomChainID() ChainID

NewRandomChainID creates a random chain ID.

func (*ChainID) Read 

func (chid *ChainID) Read(r io.Reader) error

Read from reader

func (ChainID) String 

func (chid ChainID) String() string

String human readable form (base58 encoding)

func (*ChainID) Write 

func (chid *ChainID) Write(w io.Writer) error

Write to writer

type ColoredBalances 

type ColoredBalances interface {
	// Balance is balance of the color or 0 if color is not present
	Balance(color balance.Color) int64
	// Iterate over elements
	Iterate(func(color balance.Color, balance int64) bool)
	// IterateDeterministic iterates over elements in the order of lexicographically sorted keys
	IterateDeterministic(func(color balance.Color, balance int64) bool)
	// Len number of (non-zero) balances
	Len() uint16
	// Equal returns if balances equal color by color
	Equal(b1 ColoredBalances) bool
	// Diff return difference between receiver and parameter color by color
	Diff(b1 ColoredBalances) ColoredBalances
	// NonNegative is when all elements >= 0
	NonNegative() bool
	// AddToMap adds balances to the map color by color
	AddToMap(m map[balance.Color]int64)
	// TakeOutColor takes out balance with specified color
	TakeOutColor(col balance.Color) ColoredBalances
	// String human readable representation of the map
	String() string
}

ColoredBalances is an interface to immutable map of (color code: int64)

New colored balance can be created by cbalances.NewFromMap and cbalances.NewFromBalances

type ContractID 

type ContractID [ContractIDLength]byte

ContractID global identifier of the smart contract. It consists of chainID and the hname of the contract on the chain

func NewContractID 

func NewContractID(chid ChainID, contractHn Hname) (ret ContractID)

NewContractID creates new ContractID from chainID and contract hname

func NewContractIDFromBase58 

func NewContractIDFromBase58(base58string string) (ret ContractID, err error)

NewContractIDFromBase58 decodes contract ID from base58 string

func NewContractIDFromBytes 

func NewContractIDFromBytes(data []byte) (ret ContractID, err error)

NewContractIDFromBytes creates contract ID frm its binary representation

func NewContractIDFromString 

func NewContractIDFromString(s string) (ret ContractID, err error)

NewContractIDFromString parses the human-readable string representation of the contract ID

func (ContractID) Base58 

func (scid ContractID) Base58() string

Base58 base58 representation of the binary representation

func (ContractID) ChainID 

func (scid ContractID) ChainID() (ret ChainID)

ChainID returns ID of the native chain of the contract

func (ContractID) Hname 

func (scid ContractID) Hname() Hname

Hname returns hashed name of the contract, local ID on the chain

func (*ContractID) Read 

func (scid *ContractID) Read(r io.Reader) error

Read from reader

func (*ContractID) Short 

func (scid *ContractID) Short() string

Short human readable representation in short form

func (*ContractID) String 

func (scid *ContractID) String() string

String human readable representation of the contract ID <chainID>::<hanme>

func (*ContractID) Write 

func (scid *ContractID) Write(w io.Writer) error

Write to writer

type ED25519 

type ED25519 interface {
	ValidSignature(data []byte, pubKey []byte, signature []byte) bool
	AddressFromPublicKey(pubKey []byte) (address.Address, error)
}

type EntryPoint 

type EntryPoint interface {
	IsView() bool
	Call(ctx Sandbox) (dict.Dict, error)
	CallView(ctx SandboxView) (dict.Dict, error)
}

EntryPoint is an abstract interface by which VM is called by passing the Sandbox interface

type Hashing 

type Hashing interface {
	Blake2b(data []byte) hashing.HashValue
	Sha3(data []byte) hashing.HashValue
	Hname(name string) Hname
}

type Hname 

type Hname uint32

Hname is 4 bytes of blake2b hash of any string interpreted as little-endian uint32. 0 and not ^0 are reserved values and the coretypes.Hn ensures it is not returned

func Hn 

func Hn(funname string) (ret Hname)

Hn created hname from arbitrary string.

func HnameFromString 

func HnameFromString(s string) (Hname, error)

func NewHnameFromBytes 

func NewHnameFromBytes(data []byte) (ret Hname, err error)

NewHnameFromBytes constructor, unmarshalling

func (Hname) Bytes 

func (hn Hname) Bytes() []byte

func (*Hname) Read 

func (hn *Hname) Read(r io.Reader) error

func (Hname) String 

func (hn Hname) String() string

func (*Hname) Write 

func (hn *Hname) Write(w io.Writer) error

type LogInterface 

type LogInterface interface {
	Infof(format string, param ...interface{})
	Debugf(format string, param ...interface{})
	Panicf(format string, param ...interface{})
}

type PostRequestParams 

type PostRequestParams struct {
	TargetContractID ContractID
	EntryPoint       Hname
	TimeLock         uint32
	Params           dict.Dict
	Transfer         ColoredBalances
}

PostRequestParams is parameters of the PostRequest call

type Processor 

type Processor interface {
	GetEntryPoint(code Hname) (EntryPoint, bool)
	GetDescription() string
}

Processor is a abstract interface to the VM processor instance.

type RequestID 

type RequestID [RequestIDLength]byte

RequestID is a global ID of any smart contract request. In ISCP, each request is a section in the smart contract transaction (sctransaction.Transaction). The request ID is a concatenation of the transaction ID and little-endian 2 bytes of uint16 index of the section

func NewRequestID 

func NewRequestID(txid valuetransaction.ID, index uint16) (ret RequestID)

NewRequestID a constructor

func NewRequestIDFromBase58 

func NewRequestIDFromBase58(str58 string) (ret RequestID, err error)

NewRequestIDFromBase58 a constructor

func NewRequestIDFromBytes 

func NewRequestIDFromBytes(data []byte) (ret RequestID, err error)

NewRequestIDFromBytes a constructor

func (*RequestID) Base58 

func (rid *RequestID) Base58() string

func (*RequestID) Index 

func (rid *RequestID) Index() uint16

Index of the request ID

func (*RequestID) MarshalJSON 

func (rid *RequestID) MarshalJSON() ([]byte, error)

func (*RequestID) Read 

func (rid *RequestID) Read(r io.Reader) error

func (*RequestID) Short 

func (rid *RequestID) Short() string

func (*RequestID) String 

func (rid *RequestID) String() string

String is a human readable representation of the requestID

func (*RequestID) TransactionID 

func (rid *RequestID) TransactionID() *valuetransaction.ID

TransactionID of the request ID (copy)

func (*RequestID) UnmarshalJSON 

func (rid *RequestID) UnmarshalJSON(b []byte) error

func (*RequestID) Write 

func (rid *RequestID) Write(w io.Writer) error

type SCTransactionProperties 

type SCTransactionProperties interface {
	// address of the transaction sender. It may be address of the wallet or chain address
	SenderAddress() *address.Address
	// is it state transaction, i.e. transaction with the valid state section
	IsState() bool
	// is it origin transaction
	IsOrigin() bool
	// chain ID of the state section or panic if not a state transaction
	MustChainID() *ChainID
	// color of the state section or panic if not a state transaction
	MustStateColor() *balance.Color
	// number of minted tokens which are not request tokens
	NumFreeMintedTokens() int64
	// all tokens sent to the address but not included into the requests to that address
	// (normally 0. Needed for fallback processing otherwise those free tokens will be unaccounted
	// for and essentially lost
	FreeTokensForAddress(addr address.Address) ColoredBalances
	// string representation
	String() string
}

SCTransactionProperties defines interface to the properties of syntactically and semantically valid smart contract transaction.

type Sandbox 

type Sandbox interface {
	// ChainOwnerID AgentID of the current owner of the chain
	ChainOwnerID() AgentID
	// ContractCreator agentID which deployed contract
	ContractCreator() AgentID
	// ContractID is the ID of the current contract. Take chainID with ctx.ContractID().ChainID()
	ContractID() ContractID
	// Caller is the agentID of the caller.
	Caller() AgentID
	// Params of the current call
	Params() dict.Dict
	// State k/v store of the current call (in the context of the smart contract)
	State() kv.KVStore
	// DeployContract deploys contract on the same chain. 'initParams' are passed to the 'init' entry point
	DeployContract(programHash hashing.HashValue, name string, description string, initParams dict.Dict) error
	// Call calls the entry point of the contract with parameters and transfer.
	// If the entry point is full entry point, transfer tokens are moved between caller's and
	// target contract's accounts (if enough). If the entry point is view, 'transfer' has no effect
	Call(target Hname, entryPoint Hname, params dict.Dict, transfer ColoredBalances) (dict.Dict, error)
	// RequestID of the request in the context of which is the current call
	RequestID() RequestID
	// MintedSupply is number of free minted tokens, i.e. minted tokens which are sent to addresses
	// other than chain address. It is a proof of how many tokens has been minted with the
	// color of the transaction (after un-coloring all request tokens)
	// It may be used in use-cases such as Token Registry.
	// The color of the supply can be extracted from the RequestID
	// It is read-only method, it returns same value for all requests and all calls in the context of the transaction
	MintedSupply() int64
	// GetTimestamp return current timestamp of the context
	GetTimestamp() int64
	// GetEntropy 32 random bytes based on the hash of the current state transaction
	GetEntropy() hashing.HashValue // 32 bytes of deterministic and unpredictably random data
	// Balances returns colored balances owned by the smart contract
	Balances() ColoredBalances
	// IncomingTransfer return colored balances transferred by the call. They are already accounted into the Balances()
	IncomingTransfer() ColoredBalances
	// Balance return number of tokens of specific color in the balance of the smart contract
	Balance(col balance.Color) int64
	// TransferToAddress send tokens to the L1 ledger address
	TransferToAddress(addr address.Address, transfer ColoredBalances) bool
	// PostRequest sends cross-chain request
	PostRequest(par PostRequestParams) bool
	// Log interface provides local logging on the machine. It also includes Panicf methods which logs and panics
	Log() LogInterface
	// Event publishes "vmmsg" message through Publisher on nanomsg. It also logs locally, but it is not the same thing
	Event(msg string)
	//
	Utils() Utils
}

Sandbox is an interface given to the processor to access the VMContext and virtual state, transaction builder and request parameters through it.

type SandboxView 

type SandboxView interface {
	// ChainOwnerID AgentID of the current owner of the chain
	ChainOwnerID() AgentID
	// ContractCreator agentID which deployed contract
	ContractCreator() AgentID
	// ContractID is the ID of the current contract
	ContractID() ContractID
	// GetTimestamp return timestamp of the current state
	GetTimestamp() int64
	// Params of the current call
	Params() dict.Dict
	// State immutable k/v store of the current call (in the context of the smart contract)
	State() kv.KVStoreReader
	// Call calls another contract. Only calls view entry points
	Call(contractHname Hname, entryPoint Hname, params dict.Dict) (dict.Dict, error)
	// Balances is colored balances owned by the contract
	Balances() ColoredBalances
	// Log interface provides local logging on the machine. It includes Panicf method
	Log() LogInterface
	//
	Utils() Utils
}

SandboxView is an interface for read only call

type Utils 

type Utils interface {
	Base58() Base58
	Hashing() Hashing
	ED25519() ED25519
	BLS() BLS
}

Utils implement various utilities which are faster on host side than on wasm VM Implement deterministic stateless computations

Source Files

View all Source files

Directories

Path Synopsis
package cbalances implements coretypes.ColoredBalances interface
 package cbalances implements coretypes.ColoredBalances interface
package coreutil provides functions to describe interface of the core contract in a compact way
 package coreutil provides functions to describe interface of the core contract in a compact way
Package encodedargs implements special encoding of the dict.Dict which alows optimized transfer of big data through SC request.
 Package encodedargs implements special encoding of the dict.Dict which alows optimized transfer of big data through SC request.

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.