contract

README

合约领域组件编程规范

1.领域上下文。

2.对外暴露接口。

3.驱动组件约束接口。

4.公共数据结构。

Documentation

Index

• Constants
• Variables
• func Register(name string, f NewManagerFunc)
• func ToPbLimits(limits Limits) []*protos.ResourceLimit
• func ValidContractName(contractName string) error
• type ChainCore
• type Context
• type ContextConfig
• type ContractConfig
  • func DefaultContractConfig() *ContractConfig
• type ContractEventState
• type CrossQueryState
• type EVMConfig
  • func (e *EVMConfig) DriverName() string
  • func (e *EVMConfig) IsEnable() bool
• type Iterator
• type KContext
• type KernMethod
• type KernRegistry
• type Limits
  • func FromPbLimits(rlimits []*protos.ResourceLimit) Limits
  • func (l *Limits) Add(l1 Limits) *Limits
  • func (l Limits) Exceed(l1 Limits) bool
  • func (l *Limits) Sub(l1 Limits) *Limits
  • func (l *Limits) TotalGas(gasPrice *protos.GasPrice) int64
• type LogConfig
• type Manager
  • func CreateManager(name string, cfg *ManagerConfig) (Manager, error)
• type ManagerConfig
• type NativeConfig
  • func (n *NativeConfig) DriverName() string
  • func (n *NativeConfig) IsEnable() bool
• type NativeDockerConfig
• type NewManagerFunc
• type RWSet
• type Response
• type SandboxConfig
• type State
• type StateSandbox
• type UTXORWSet
• type UTXOState
• type UtxoReader
• type WasmConfig
  • func (w *WasmConfig) DriverName() string
  • func (w *WasmConfig) IsEnable() bool
• type XMState
• type XVMConfig
• type XkernelConfig
  • func (x *XkernelConfig) DriverName() string
  • func (x *XkernelConfig) IsEnable() bool

Constants

const (
	// StatusOK is used when contract successfully ends.
	StatusOK = 200
	// StatusErrorThreshold is the status dividing line for the normal operation of the contract
	StatusErrorThreshold = 400
	// StatusError is used when contract fails.
	StatusError = 500
)

Variables

var MaxLimits = Limits{
	Cpu:    maxResourceLimit,
	Memory: maxResourceLimit,
	Disk:   maxResourceLimit,
	XFee:   maxResourceLimit,
}

MaxLimits describes the maximum limit of resources

Functions

func Register

func Register(name string, f NewManagerFunc)

func ToPbLimits

func ToPbLimits(limits Limits) []*protos.ResourceLimit

// FromPbLimits converts Limits to []*pb.ResourceLimit

func ValidContractName

func ValidContractName(contractName string) error

ValidContractName return error when contractName is not a valid contract name.

Types

type ChainCore

type ChainCore interface {
	// GetAccountAddress get addresses associated with account name
	GetAccountAddresses(accountName string) ([]string, error)
	// VerifyContractPermission verify permission of calling contract
	VerifyContractPermission(initiator string, authRequire []string, contractName, methodName string) (bool, error)
	// VerifyContractOwnerPermission verify contract ownership permisson
	VerifyContractOwnerPermission(contractName string, authRequire []string) error
	// QueryTransaction query confirmed tx
	QueryTransaction(txid []byte) (*pb.Transaction, error)
	// QueryBlock query block
	QueryBlock(blockid []byte) (ledger.BlockHandle, error)
}

ChainCore is the interface of chain service

type Context

type Context interface {
	Invoke(method string, args map[string][]byte) (*Response, error)
	ResourceUsed() Limits
	Release() error
}

Context define context interface

type ContextConfig

type ContextConfig struct {
	State StateSandbox

	Initiator   string
	AuthRequire []string

	Caller string

	Module       string
	ContractName string

	ResourceLimits Limits

	// Whether contract can be initialized
	CanInitialize bool

	// The amount transfer to contract
	TransferAmount string

	// Contract being called
	// set by bridge to check recursive contract call
	ContractSet map[string]bool

	// ContractCodeFromCache control whether fetch contract code from XMCache
	ContractCodeFromCache bool
}

ContextConfig define the config of context

type ContractConfig

type ContractConfig struct {
	EnableDebugLog bool
	EnableUpgrade  bool
	LogDriver      logs.Logger

	Native  NativeConfig
	Wasm    WasmConfig
	Xkernel XkernelConfig
	EVM     EVMConfig
}

ContractConfig define the config of XuperBridge

func DefaultContractConfig

func DefaultContractConfig() *ContractConfig

type ContractEventState

type ContractEventState interface {
	AddEvent(events ...*protos.ContractEvent)
}

type CrossQueryState

type CrossQueryState interface {
}

CrossQueryState 对XuperBridge暴露对跨链只读合约的操作能力

type EVMConfig

type EVMConfig struct {
	Enable bool
	Driver string
}

func (*EVMConfig) DriverName

func (e *EVMConfig) DriverName() string

func (*EVMConfig) IsEnable

func (e *EVMConfig) IsEnable() bool

type Iterator

type Iterator interface {
	Key() []byte
	Value() []byte
	Next() bool
	Error() error
	// Iterator 必须在使用完毕后关闭
	Close()
}

Iterator iterates over key/value pairs in key order

type KContext

type KContext interface {
	// 交易相关数据
	Args() map[string][]byte
	Initiator() string
	Caller() string
	AuthRequire() []string

	// 状态修改接口
	StateSandbox

	AddResourceUsed(delta Limits)
	ResourceLimit() Limits

	Call(module, contract, method string, args map[string][]byte) (*Response, error)

	// 合约异步事件调用
	EmitAsyncTask(event string, args interface{}) error
}

type KernMethod

type KernMethod func(ctx KContext) (*Response, error)

type KernRegistry

type KernRegistry interface {
	RegisterKernMethod(contract, method string, handler KernMethod)
	UnregisterKernMethod(ctract, method string)
	// RegisterShortcut 用于contractName缺失的时候选择哪个合约名字和合约方法来执行对应的kernel合约
	RegisterShortcut(oldmethod, contract, method string)
	GetKernMethod(contract, method string) (KernMethod, error)
}

type Limits

type Limits struct {
	Cpu    int64
	Memory int64
	Disk   int64
	XFee   int64
}

Limits describes the usage or limit of resources

func FromPbLimits

func FromPbLimits(rlimits []*protos.ResourceLimit) Limits

// FromPbLimits converts []*pb.ResourceLimit to Limits

func (*Limits) Add

func (l *Limits) Add(l1 Limits) *Limits

Add accumulates resource limits, returns self.

func (Limits) Exceed

func (l Limits) Exceed(l1 Limits) bool

Exceed judge whether resource exceeds l1

func (*Limits) Sub

func (l *Limits) Sub(l1 Limits) *Limits

Sub sub limits from l

func (*Limits) TotalGas

func (l *Limits) TotalGas(gasPrice *protos.GasPrice) int64

// TotalGas converts resource to gas

type LogConfig

type LogConfig struct {
	Module         string `yaml:"module,omitempty"`
	Filepath       string `yaml:"filepath,omitempty"`
	Filename       string `yaml:"filename,omitempty"`
	Fmt            string `yaml:"fmt,omitempty"`
	Console        bool   `yaml:"console,omitempty"`
	Level          string `yaml:"level,omitempty"`
	Async          bool   `yaml:"async,omitempty"`
	RotateInterval int    `yaml:"rotateinterval,omitempty"`
	RotateBackups  int    `yaml:"rotatebackups,omitempty"`
}

LogConfig is the log config of node

type Manager

type Manager interface {
	NewContext(cfg *ContextConfig) (Context, error)
	NewStateSandbox(cfg *SandboxConfig) (StateSandbox, error)
	GetKernRegistry() KernRegistry
}

func CreateManager

func CreateManager(name string, cfg *ManagerConfig) (Manager, error)

type ManagerConfig

type ManagerConfig struct {
	Basedir  string
	BCName   string
	EnvConf  *xconfig.EnvConf
	Core     ChainCore
	XMReader ledger.XMReader

	Config *ContractConfig // used by testing
}

type NativeConfig

type NativeConfig struct {
	Driver string
	// Timeout (in seconds) to stop native code process
	StopTimeout int
	Docker      NativeDockerConfig
	Enable      bool
}

NativeConfig contains the two above config

func (*NativeConfig) DriverName

func (n *NativeConfig) DriverName() string

func (*NativeConfig) IsEnable

func (n *NativeConfig) IsEnable() bool

type NativeDockerConfig

type NativeDockerConfig struct {
	Enable    bool
	ImageName string
	Cpus      float32
	Memory    string
}

NativeDockerConfig native contract use docker config

type NewManagerFunc

type NewManagerFunc func(cfg *ManagerConfig) (Manager, error)

type RWSet

type RWSet struct {
	RSet []*ledger.VersionedData
	WSet []*ledger.PureData
}

type Response

type Response struct {
	// Status 用于反映合约的运行结果的错误码
	Status int `json:"status"`
	// Message 用于携带一些有用的debug信息
	Message string `json:"message"`
	// Data 字段用于存储合约执行的结果
	Body []byte `json:"body"`
}

Response is the result of the contract run

type SandboxConfig

type SandboxConfig struct {
	XMReader   ledger.XMReader
	UTXOReader UtxoReader
}

type State

type State interface {
	XMState
	UTXOState
	CrossQueryState
	ContractEventState
}

State 抽象了链的状态机接口，合约通过State里面的方法来修改状态。

type StateSandbox

type StateSandbox interface {
	State
	// Flush将缓存的UTXO，CrossQuery等内存状态写入到读写集
	// 没有调用Flush只能得到KV数据的读写集
	Flush() error
	RWSet() *RWSet
	UTXORWSet() *UTXORWSet
}

StateSandbox 在沙盒环境里面执行状态修改操作，最终生成读写集

type UTXORWSet

type UTXORWSet struct {
	Rset []*protos.TxInput
	WSet []*protos.TxOutput
}

type UTXOState

type UTXOState interface {
	Transfer(from string, to string, amount *big.Int) error
}

XMState 对XuperBridge暴露对账本的UTXO操作能力

type UtxoReader

type UtxoReader interface {
	SelectUtxo(string, *big.Int, bool, bool) ([]*protos.TxInput, [][]byte, *big.Int, error)
}

type WasmConfig

type WasmConfig struct {
	Enable bool
	Driver string
	XVM    XVMConfig
}

WasmConfig wasm config

func (*WasmConfig) DriverName

func (w *WasmConfig) DriverName() string

func (*WasmConfig) IsEnable

func (w *WasmConfig) IsEnable() bool

type XMState

type XMState interface {
	Get(bucket string, key []byte) ([]byte, error)
	//扫描一个bucket中所有的kv, 调用者可以设置key区间[startKey, endKey)
	Select(bucket string, startKey []byte, endKey []byte) (Iterator, error)
	Put(bucket string, key, value []byte) error
	Del(bucket string, key []byte) error
}

XMState 对XuperBridge暴露对XModel的读写接口，不同于XMReader， Get和Select方法得到的不是VersionedData，而是[]byte

type XVMConfig

type XVMConfig struct {
	// From 0 to 3
	// The higher the number, the faster the program runs,
	// but the compilation speed will be slower
	OptLevel int `yaml:"optlevel"`
}

XVMConfig contains the xvm configuration

type XkernelConfig

type XkernelConfig struct {
	Enable bool
	Driver string

	Registry KernRegistry
}

func (*XkernelConfig) DriverName

func (x *XkernelConfig) DriverName() string

func (*XkernelConfig) IsEnable

func (x *XkernelConfig) IsEnable() bool