xuperos

README

xuperos

面向公链应用场景设计的区块链执行引擎。

组件说明

reader: 只读组件。采用读写分离设计，降低代码复杂度。

ledger: 统一收敛账本变更操作（交易、同步块、创世块修改等）。

contract: 系统合约，考虑到系统合约和链强相关，放到引擎中实现，注册到合约组件。

应用案例

超级链开放网络。

对外接口

type BCEngine interface {
	// 初始化引擎
	Init(*xconf.EnvConf) error
	// 启动引擎(阻塞)
	Run()
	// 退出引擎，需要幂等
	Exit()
}

type Engine interface {
	BCEngine
	Context() *EngineCtx
	Get(string) Chain
	GetChains() []string
	SetRelyAgent(EngineRelyAgent) error
}

type Chain interface {
	Context() *ChainCtx
	Start()
	Stop()
	// 合约预执行
	PreExec(xctx.XContext, []*protos.InvokeRequest) (*protos.InvokeResponse, error)
	// 提交交易
	SubmitTx(xctx.XContext, *lpb.Transaction) error
	// 设置依赖实例化代理
	SetRelyAgent(ChainRelyAgent) error
}

type ChainReader interface {
	// 获取链状态 (GetBlockChainStatus)
	GetChainStatus() (*ChainStatus, error)
	// 检查是否是主干Tip Block (ConfirmBlockChainStatus)
	IsTrunkTipBlock(blkId []byte) (bool, error)
	// 获取系统状态
	GetSystemStatus() (*ChainStatus, error)
	// 获取节点NetUR
	GetNetURL() (string, error)
}

type ConsensusReader interface {
	// 获取共识状态
	GetConsStatus() (consBase.ConsensusStatus, error)
}

type ContractReader interface {
	// 查询该链合约统计数据
	QueryContractStatData() (*protos.ContractStatData, error)
	// 查询账户下合约状态
	GetAccountContracts(account string) ([]*protos.ContractStatus, error)
	// 查询地址下合约状态
	GetAddressContracts(address string, needContent bool) (map[string][]*protos.ContractStatus, error)
	// 查询地址下账户
	GetAccountByAK(address string) ([]string, error)
	// 查询合约账户ACL
	QueryAccountACL(account string) (*protos.Acl, bool, error)
	// 查询合约方法ACL
	QueryContractMethodACL(contract, method string) (*protos.Acl, bool, error)
}

type LedgerReader interface {
	// 查询交易信息（QueryTx）
	QueryTx(txId []byte) (*lpb.TxInfo, error)
	// 查询区块ID信息（GetBlock）
	QueryBlock(blkId []byte, needContent bool) (*lpb.BlockInfo, error)
	// 通过区块高度查询区块信息（GetBlockByHeight）
	QueryBlockByHeight(height int64, needContent bool) (*lpb.BlockInfo, error)
}

type UtxoReader interface {
	// 获取账户余额
	GetBalance(account string) (string, error)
	// 获取账户冻结余额
	GetFrozenBalance(account string) (string, error)
	// 获取账户余额详情
	GetBalanceDetail(account string) ([]*lpb.BalanceDetailInfo, error)
	// 拉取固定数目的utxo
	QueryUtxoRecord(account string, count int64) (*lpb.UtxoRecordDetail, error)
	// 按最大交易大小选择utxo
	SelectUTXOBySize(account string, isLock, isExclude bool) (*lpb.UtxoOutput, error)
	// 选择合适金额的utxo
	SelectUTXO(account string, need *big.Int, isLock, isExclude bool) (*lpb.UtxoOutput, error)
}

Documentation

Index

• Constants
• func EngineConvert(engine engines.BCEngine) (common.Engine, error)
• func NewEngine() engines.BCEngine
• type Chain
  • func LoadChain(engCtx *common.EngineCtx, bcName string) (*Chain, error)
  • func (t *Chain) Context() *common.ChainCtx
  • func (t *Chain) CreateParaChain() error
  • func (t *Chain) PreExec(ctx xctx.XContext, reqs []*protos.InvokeRequest, initiator string, ...) (*protos.InvokeResponse, error)
  • func (t *Chain) ProcBlock(ctx xctx.XContext, block *lpb.InternalBlock) error
  • func (t *Chain) SetRelyAgent(agent common.ChainRelyAgent) error
  • func (t *Chain) Start()
  • func (t *Chain) Stop()
  • func (t *Chain) SubmitTx(ctx xctx.XContext, tx *lpb.Transaction) error
• type ChainManagerImpl
  • func (m *ChainManagerImpl) Get(chainName string) (common.Chain, error)
  • func (m *ChainManagerImpl) GetChains() []string
  • func (m *ChainManagerImpl) LoadChain(chainName string) error
  • func (m *ChainManagerImpl) Put(chainName string, chain common.Chain)
  • func (m *ChainManagerImpl) StartChains()
  • func (m *ChainManagerImpl) Stop(chainName string) error
  • func (m *ChainManagerImpl) StopChains()
• type Engine
  • func (t *Engine) Context() *common.EngineCtx
  • func (t *Engine) Exit()
  • func (t *Engine) Get(name string) (common.Chain, error)
  • func (t *Engine) GetChains() []string
  • func (t *Engine) Init(envCfg *xconf.EnvConf) error
  • func (t *Engine) LoadChain(name string) error
  • func (t *Engine) Run()
  • func (t *Engine) SetRelyAgent(agent common.EngineRelyAgent) error
  • func (t *Engine) Stop(name string) error

Constants

const (
	// 提交交易cache有效期(s)
	TxIdCacheExpired = 120 * time.Second
	// 提交交易cache GC 周期（s）
	TxIdCacheGCInterval = 180 * time.Second
)

Functions

func EngineConvert

func EngineConvert(engine engines.BCEngine) (common.Engine, error)

转换引擎句柄类型 对外提供类型转义方法，以接口形式对外暴露

func NewEngine

func NewEngine() engines.BCEngine

Types

type Chain

type Chain struct {
	// contains filtered or unexported fields
}

定义一条链的具体行为，对外暴露接口错误统一使用标准错误

func LoadChain

func LoadChain(engCtx *common.EngineCtx, bcName string) (*Chain, error)

从本地存储加载链

func (*Chain) Context

func (t *Chain) Context() *common.ChainCtx

func (*Chain) CreateParaChain

func (t *Chain) CreateParaChain() error

创建平行链实例

func (*Chain) PreExec

func (t *Chain) PreExec(ctx xctx.XContext, reqs []*protos.InvokeRequest, initiator string, authRequires []string) (*protos.InvokeResponse, error)

交易预执行

func (*Chain) ProcBlock

func (t *Chain) ProcBlock(ctx xctx.XContext, block *lpb.InternalBlock) error

处理P2P网络同步到的区块

func (*Chain) SetRelyAgent

func (t *Chain) SetRelyAgent(agent common.ChainRelyAgent) error

供单测时设置rely agent为mock agent，非并发安全

func (*Chain) Start

func (t *Chain) Start()

阻塞

func (*Chain) Stop

func (t *Chain) Stop()

func (*Chain) SubmitTx

func (t *Chain) SubmitTx(ctx xctx.XContext, tx *lpb.Transaction) error

提交交易到交易池(xuperos引擎同时更新到状态机和交易池)

type ChainManagerImpl

type ChainManagerImpl struct {
	// contains filtered or unexported fields
}

ChainMgmtImpl 用于管理链操作

func (*ChainManagerImpl) Get

func (m *ChainManagerImpl) Get(chainName string) (common.Chain, error)

func (*ChainManagerImpl) GetChains

func (m *ChainManagerImpl) GetChains() []string

func (*ChainManagerImpl) LoadChain

func (m *ChainManagerImpl) LoadChain(chainName string) error

func (*ChainManagerImpl) Put

func (m *ChainManagerImpl) Put(chainName string, chain common.Chain)

func (*ChainManagerImpl) StartChains

func (m *ChainManagerImpl) StartChains()

func (*ChainManagerImpl) Stop

func (m *ChainManagerImpl) Stop(chainName string) error

func (*ChainManagerImpl) StopChains

func (m *ChainManagerImpl) StopChains()

type Engine

type Engine struct {
	// contains filtered or unexported fields
}

xuperos执行引擎，为公链场景订制区块链引擎

func (*Engine) Context

func (t *Engine) Context() *common.EngineCtx

获取执行引擎环境

func (*Engine) Exit

func (t *Engine) Exit()

关闭执行引擎，需要幂等

func (*Engine) Get

func (t *Engine) Get(name string) (common.Chain, error)

func (*Engine) GetChains

func (t *Engine) GetChains() []string

func (*Engine) Init

func (t *Engine) Init(envCfg *xconf.EnvConf) error

初始化执行引擎环境上下文

func (*Engine) LoadChain

func (t *Engine) LoadChain(name string) error

LoadChain load an instance of blockchain and start it dynamically

func (*Engine) Run

func (t *Engine) Run()

启动执行引擎，阻塞等待

func (*Engine) SetRelyAgent

func (t *Engine) SetRelyAgent(agent common.EngineRelyAgent) error

供单测时设置rely agent为mock agent，非并发安全

func (*Engine) Stop

func (t *Engine) Stop(name string) error