engine

README

区块链引擎

区块链引擎：定义一种区块链核心流程实现。

内核框架采用多引擎架构，每个引擎订制一套区块链内核实现，所有引擎注册到引擎工厂，外部通过工厂实例化引擎。 每个引擎提供执行引擎和读组件两部分能力。各引擎间交易、区块结构无关，共用内核核心组件。

引擎介绍

xuperos: 面向公链场景区块链网络内核实现。

xchain: 面向联盟联盟场景区块链网络内核实现。

使用示例

// 加载内核运行环境配置
envCfgPath := "/home/rd/xx/conf/env.yaml"
envCfg, _ := engines.LoadEnvConf(envCfgPath)

// 创建内核引擎实例
engine, _ := engines.CreateBCEngine("xchain", envCfg)

engine.Init()
engine.Start()
engine.Stop()

xEngine, _ := xuperos.EngineConvert(engine)
xChain := xEngine.Get("xuper")
xChain.PreExec()
xChain.ProcessTx()

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.Context, []*protos.InvokeRequest) (*protos.InvokeResponse, error)
	// 提交交易
	SubmitTx(xctx.Context, *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 CreateBCEngine(egName string, envCfg *xconf.EnvConf) (base.BasicEngine, error)
• func EngineConvert(engine base.BasicEngine) (base.Engine, error)
• func Engines() []string
• func NewEngine() base.BasicEngine
• func Register(name string, f NewBcEngineFunc)
• type Chain
  • func LoadChain(engCtx *base.EngineCtx, bcName string) (*Chain, error)
  • func (t *Chain) Context() *base.ChainCtx
  • func (t *Chain) CreateParaChain() error
  • func (t *Chain) PreExec(ctx xctx.Context, reqs []*protos.InvokeRequest, initiator string, ...) (*protos.InvokeResponse, error)
  • func (t *Chain) ProcBlock(ctx xctx.Context, block *protos.InternalBlock) error
  • func (t *Chain) SetRelyAgent(agent base.ChainRelyAgent) error
  • func (t *Chain) Start()
  • func (t *Chain) Stop()
  • func (t *Chain) SubmitTx(ctx xctx.Context, tx *protos.Transaction) error
• type ChainManagerImpl
  • func NewChainManagerImpl(engCtx *base.EngineCtx, log logger.Logger) *ChainManagerImpl
  • func (m *ChainManagerImpl) Get(chainName string) (base.Chain, error)
  • func (m *ChainManagerImpl) GetChains() []string
  • func (m *ChainManagerImpl) LoadChain(chainName string) error
  • func (m *ChainManagerImpl) Put(chainName string, chain base.Chain)
  • func (m *ChainManagerImpl) StartChains()
  • func (m *ChainManagerImpl) Stop(chainName string) error
  • func (m *ChainManagerImpl) StopChains()
• type Engine
  • func (t *Engine) Context() *base.EngineCtx
  • func (t *Engine) CreateNetwork(envCfg *xconf.EnvConf) (netBase.Network, error)
  • func (t *Engine) Exit()
  • func (t *Engine) Get(name string) (base.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) Put(s string, chain base.Chain)
  • func (t *Engine) Run()
  • func (t *Engine) StartChains()
  • func (t *Engine) Stop(name string) error
  • func (t *Engine) StopChains()
• type NewBcEngineFunc

Constants

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

Functions

func CreateBCEngine

func CreateBCEngine(egName string, envCfg *xconf.EnvConf) (base.BasicEngine, error)

采用工厂模式，对上层统一区块链执行引擎创建操作，方便框架开发

func EngineConvert

func EngineConvert(engine base.BasicEngine) (base.Engine, error)

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

func Engines

func Engines() []string

func NewEngine

func NewEngine() base.BasicEngine

func Register

func Register(name string, f NewBcEngineFunc)

Types

type Chain

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

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

func LoadChain

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

从本地存储加载链

func (*Chain) Context

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

func (*Chain) CreateParaChain

func (t *Chain) CreateParaChain() error

创建平行链实例

func (*Chain) PreExec

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

交易预执行

func (*Chain) ProcBlock

func (t *Chain) ProcBlock(ctx xctx.Context, block *protos.InternalBlock) error

处理P2P网络同步到的区块

func (*Chain) SetRelyAgent

func (t *Chain) SetRelyAgent(agent base.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.Context, tx *protos.Transaction) error

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

type ChainManagerImpl

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

ChainMgmtImpl 用于管理链操作

func NewChainManagerImpl

func NewChainManagerImpl(engCtx *base.EngineCtx, log logger.Logger) *ChainManagerImpl

func (*ChainManagerImpl) Get

func (m *ChainManagerImpl) Get(chainName string) (base.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 base.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() *base.EngineCtx

获取执行引擎环境

func (*Engine) CreateNetwork

func (t *Engine) CreateNetwork(envCfg *xconf.EnvConf) (netBase.Network, error)

func (*Engine) Exit

func (t *Engine) Exit()

关闭执行引擎，需要幂等

func (*Engine) Get

func (t *Engine) Get(name string) (base.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) Put

func (t *Engine) Put(s string, chain base.Chain)

func (*Engine) Run

func (t *Engine) Run()

启动执行引擎，阻塞等待

func (*Engine) StartChains

func (t *Engine) StartChains()

func (*Engine) Stop

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

func (*Engine) StopChains

func (t *Engine) StopChains()

type NewBcEngineFunc

type NewBcEngineFunc func() base.BasicEngine

创建engine实例方法