protocol

type API struct {
	Namespace string      // 对外的命名空间
	Version   string      // api版本
	Service   interface{} // 方法集合
	Public    bool        // 可供公众使用
}

type APIs interface {
	// Syncing 同步状态
	Syncing(ctx context.Context) (*models.SyncingStatus, error)

	// SendRawTransaction 发送交易
	SendRawTransaction(ctx context.Context, txType types.TxType, rawTx hexutil.Bytes) (types.Hash, error)
	// GetTransaction 根据Hash获取交易
	GetTransaction(ctx context.Context, hash types.Hash) models.Transaction
	// GetTransactionReceipt 根据Hash获取交易收据
	GetTransactionReceipt(ctx context.Context, hash types.Hash) (models.Transaction, error)
	// GetTransactionLogs 根据Hash获取交易Logs
	GetTransactionLogs(ctx context.Context, hash types.Hash) ([]*statetype.Log, error)

	// BlockHeight 获取最新的区块高度
	BlockHeight(ctx context.Context) (*hexutil.Uint64, error)
	// GetBlockByHash 根据区块Hash获取区块信息
	GetBlockByHash(ctx context.Context, blockHash types.Hash) (*models.Block, error)
	// GetBlockByHeight 根据区块高度获取区块信息
	GetBlockByHeight(ctx context.Context, blockHeight hexutil.Uint64) (*models.Block, error)
	// GetBlockTransactionCountByHash 根据区块Hash获取区块交易个数
	GetBlockTransactionCountByHash(ctx context.Context, blockHash types.Hash) (*hexutil.Uint64, error)
	// GetBlockTransactionCountByHeight 根据区块高度获取区块交易个数
	GetBlockTransactionCountByHeight(ctx context.Context, blockHeight hexutil.Uint64) (*hexutil.Uint64, error)
	// GetTransactionByBlockHashAndIndex 查询指定块内具有指定索引序号的交易
	GetTransactionByBlockHashAndIndex(ctx context.Context, blockHash types.Hash, txIndex hexutil.Uint64) (models.Transaction, error)
	// GetTransactionByBlockHeightAndIndex 查询指定块内具有指定索引序号的交易
	GetTransactionByBlockHeightAndIndex(ctx context.Context, blockHeight hexutil.Uint64, txIndex hexutil.Uint64) (models.Transaction, error)

	// GetCode 回去合约对应的代码
	GetCode(ctx context.Context, contract types.Address, blockHeight hexutil.Uint64) (*hexutil.Bytes, error)
	// Call 调用合约，无需在区块链上创建交易
	Call(ctx context.Context, hash models.VmMessage) (*hexutil.Bytes, error)
	// EstimateGas 估算交易的gas
	EstimateGas(ctx context.Context, transaction models.Transaction) (*hexutil.Uint64, error)
	// CompileContract 编译合约
	CompileContract(ctx context.Context, compileType CompileType, contract hexutil.Bytes) (*hexutil.Bytes, error)

	// FilterSubscribeHeaders 过滤订阅header
	FilterSubscribeHeaders(ctx context.Context) (*models.Header, error)

	// APIs api集合
	APIs() []API
	RegisterAPI(apis []API)
}

type AppContext interface {
	Caller() string   // 调用模块名称
	App() Application // 从ctx 获取App实例
}

type AppContexts interface {
	Ctx(t types.TxType) AppContext
}

type Application interface {
	// Start 启动app
	Start() error
	// Stop 停止app
	Stop() error
	// NewAppContexts 创建一个新的appContext
	NewAppContexts(module string, args ...interface{}) (AppContext, error)

	// TxPool 每个app可自我维护一个txPool，如果不自我维护，那么将会使用默认的
	// 如果返回nil,nil-->使用默认的txPool
	// 如果返回nil,err-->有错误返回，会报错
	// 如果返回!nil,nil-->使用app自定义的txPool
	TxPool(config Config, apps Apps, blockReader BlockReader, broadcaster Broadcaster) (TxPool, error)

	TxValidator

	// DeleteErrTx 删除错误的交易
	DeleteErrTx(txI models.Transaction) error
	// DeleteOkTx 删除OK的交易
	DeleteOkTx(txI models.Transaction) error

	GetCacheNonce(ctx AppContext, account string) (uint64, error)

	// Prepare 计算出stateRoot
	Prepare(ctx AppContext, header *models.Header, txs models.TransactionSortedList, totalGas uint64) *models.TxsStatus

	// Commit 提交txs,返回root【commit】提交到数据库
	Commit(ctx AppContext, header *models.Header) error
}

type Apps interface {
	// Register 注册application
	Register(txType types.TxType, app Application)
	// App 根据txType获取application
	App(txType types.TxType) (Application, error)
	// NewAppContexts 创建新的context
	NewAppContexts(module string, preRoot []byte) (AppContexts, error)
	// Prepare 预处理交易
	Prepare(ctx AppContexts, preRoot []byte, header *models.Header, txs models.Transactions, totalGas uint64) ([]byte, models.AppsStatus)
	// Commit 提交
	Commit(ctx AppContexts, header *models.Header) error
}

type BlockReadWriter interface {
	BlockWriter
	BlockReader
}

type BlockReader interface {
	// Start 启动
	Start() error
	// Stop 停止
	Stop() error
	// IsRunning 判断blockChain是否正在执行
	IsRunning() bool

	// CurrentHeader 获取当前的header
	CurrentHeader() *models.Header
	// GetHeader 根据hash及区块高度获取区块头
	GetHeader(hash types.Hash, number uint64) *models.Header
	// GetHeaderByHash 根据区块hash获取区块头
	GetHeaderByHash(hash types.Hash) *models.Header
	// GetHeaderByNumber 根据区块高度获取区块头
	GetHeaderByNumber(number uint64) *models.Header
	// HasHeader 根据hash及区块高度判断区块是否存在
	HasHeader(hash types.Hash, number uint64) bool

	// CurrentBlock 获取当前区块
	CurrentBlock() *models.Block
	// GetBlock 根据hash及区块高度获取区块
	GetBlock(hash types.Hash, number uint64) *models.Block
	// GetBlockByHash 根据hash获取区块
	GetBlockByHash(hash types.Hash) *models.Block
	// GetBlockByNumber 根据区块高度获取区块
	GetBlockByNumber(number uint64) *models.Block
	// HasBlock 根据hash及区块高度判断区块是否存在
	HasBlock(hash types.Hash, number uint64) bool

	// GetBlockHashesFromHash 从指定hash开始获取一系列区块hash, 降序
	GetBlockHashesFromHash(hash types.Hash, max uint64) []types.Hash
	// GetBody 根据hash获取区块的交易内容
	GetBody(hash types.Hash) *models.Body
	// ValidateBody 验证区块的body
	ValidateBody(block *models.Block) error

	// GetAncestor 根据hash及区块高度，祖先高度获取区块hash及高度
	GetAncestor(hash types.Hash, number, ancestor uint64, maxNonCanonical *uint64) (types.Hash, uint64)
	// SubscribeChainHeadEvent 链订阅
	SubscribeChainHeadEvent(ch chan<- eventtype.ChainHeadEvent) event.Subscription
}

type BlockWriter interface {
	// InsertBlock 写入区块, 不包含状态处理, 不包含校验
	InsertBlock(block *models.Block, propagate bool) (err error)
	// ProcessBlock 区块处理，校验，状态处理(同步或接收到广播的区块信息)
	ProcessBlock(block *models.Block, propagate bool) (err error)
}

type Broadcaster interface {
	Start() error // Start 启动
	Stop() error  // Stop 停止

	SubscribeMsg(msgType uint, ch chan<- *models.P2PMessage) event.Subscription // 订阅消息
	SubscribeNewPeer(newPeerCh chan models.P2PID) event.Subscription            // 订阅新接入
	SubscribeDropPeer(dropPeerCh chan models.P2PID) event.Subscription          // 订阅移除peer

	Broadcast(peers []models.P2PID, mType uint, payload []byte) error          // Broadcast 广播数据
	BroadcastTxs(peerId *models.P2PID, txs []models.Transaction, isForce bool) // BroadcastTxs 广播交易

	RegisterTrustPeer(peerID models.P2PID) error   // 注册trust peer
	DeregisterTrustPeer(peerID models.P2PID) error // 注销trust peer
}

type ChainContext interface {
	GetHeader(bHash types.Hash, height uint64) *models.Header // 获取header
}

type ChainContext2 interface {
	GetStateDb() StateDB
	GetOrigin() types.Address
	GetTime() *big.Int
	GetBlockNum() *big.Int
}

type CompileType int

type Config interface {
	SetDatabase(db DatabaseReader) error

	ChainConfig() models.ChainConfig //链配置
	GenesisBlock() *models.Block     //获取创世区块

	LocalConfig() *models.LocalConfig                 //本地所有配置
	TxSizeLimit() types.StorageSize                   //交易的size
	DatabaseConfig() models.DatabaseConfig            //获取数据库本地配置
	BlockchainConfig() models.BlockchainLocalConfig   //获取blockchain本地配置
	TxPoolConfig() models.TxPoolLocalConfig           //获取交易池本地配置
	NodeKeyConfig() models.NodeKeyLocalConfig         //获取nodeKey本地配置
	PackerConfig() models.PackerLocalConfig           //获取packer本地配置
	EnablePacker() bool                               //是否启动打包
	BroadcasterConfig() models.BroadcasterLocalConfig //获取Broadcaster本地配置
	P2PConfig() models.P2PConfig                      //获取p2p本地配置
	ConsensusConfig() models.ConsensusLocalConfig     //获取consensus本地配置
}

type Consensus interface {
	Start() error // 启动引擎
	Stop() error  // 停止引擎

	Begin() error

	// VerifyHeader 检查Header是否符合引擎的一致规则。
	// 可在此选择验证seal，或通过VerifySeal方法明确验证。
	// 同步或接收到广播的区块信息时调用此方法。此处header已被签名并包含共识内容
	VerifyHeader(blockReader BlockReader, header *models.Header) error
	// VerifyHeaders 批量验证区块头
	VerifyHeaders(blockReader BlockReader, headers []*models.Header, seals []bool) (chan<- struct{}, <-chan error)

	// Prepare 根据规则初始化header的字段。以内联方式执行
	// 如初始化header.Consensus，header.Timestamp，此时的header还未被签名
	Prepare(blockReader BlockReader, header *models.Header) error

	// Finalize 运行交易后状态修改（例如区块奖励）并组装最终区块。
	// 注意：header和stateDb可能会更新，以反映最终确定时发生的任何共识规则（例如区块奖励）。
	// 组装header及txs形成block，此时的block还未被签名
	Finalize(blockReader BlockReader, header *models.Header, txs models.Transactions) (*models.Block, error)

	// Seal 根据block进行密封处理（区块签名），并且放入chan中
	// 注意：该方法立即返回，并将异步发送结果。根据一致性算法，还可能返回多个结果。
	// 使用nodeKey对区块进行签名处理，并真实地开启共识核心处理
	Seal(ctx context.Context, blockReader BlockReader, block *models.Block, results chan<- *models.Block) error
}

type Contract interface {
	AsDelegate() Contract                                          // 将contract设置为委托代理调用并返回当前contract
	Caller() types.Address                                         // 当contract是委托代理调用时，将递归调用，包括调用方的调用方的委托调用。
	UseGas(gas uint64) (ok bool)                                   // 尝试使用gas并将其减去，成功后返回true
	Address() types.Address                                        // 返回合约地址
	Value() *big.Int                                               // 返回合约的值（从其调用者发送给它）
	SetCallCode(addr *types.Address, hash types.Hash, code []byte) // 设置合约地址对应的code和hash
}

type ContractRef interface {
	Address() types.Address
}

type Database interface {
	DatabaseReader
	DatabaseWriter
}

type DatabaseReader interface {
	Start() error // 启动
	Stop() error  // 停止

	ChainConfig() (*models.ChainConfig, error)                                  // 获取最新的链配置
	GetChainConfig(hash types.Hash, height uint64) (*models.ChainConfig, error) // 根据区块hash和高度获取最新的链配置
	GetChainConfigByHash(hash types.Hash) (*models.ChainConfig, error)          // 根据区块hash获取最新的链配置
	GetChainConfigByHeight(height uint64) (*models.ChainConfig, error)          // 根据区块高度获取最新的链配置

	LatestHeader() (*models.Header, error)                            // 获取数据库当前的header
	GetHeader(hash types.Hash, height uint64) (*models.Header, error) // 根据hash及高度获取header
	GetHeaderByHash(hash types.Hash) (*models.Header, error)          // 根据hash获取header
	GetHeaderByHeight(height uint64) (*models.Header, error)          // 根据高度获取header
	GetHeaderHeight(hash types.Hash) (*uint64, error)                 // 根据hash获取其对应的高度
	HasHeader(hash types.Hash, height uint64) (bool, error)           // 根据hash及高度判断header是否存在

	CurrentBlock() (*models.Block, error)                           // 当前区块
	GetBlock(hash types.Hash, height uint64) (*models.Block, error) // 根据hash及高度获取区块
	GetBlockByHash(hash types.Hash) (*models.Block, error)          // 根据hash获取区块
	GetBlockByHeight(height uint64) (*models.Block, error)          // 根据高度获取区块
	HasBlock(hash types.Hash, number uint64) (bool, error)          // 根据hash及number判断区块是否存在

	GetCanonicalHash(height uint64) (bHash types.Hash, err error) // 获取标准hash
	LatestBlockHash() (bHash types.Hash, err error)               // 获取最新的区块hash
	LatestHeaderHash() (bHash types.Hash, err error)              // 获取最新的header头hash

	GetBody(hash types.Hash, height uint64) (*models.Body, error) // 获取body

	GetTransaction(hash types.Hash) (tx models.Transaction, blockHash types.Hash, blockHeight uint64, txIndex uint64, err error) // 获取交易内容
	GetReceipts(bHash types.Hash, height uint64) (statetype.Receipts, error)                                                     // 获取区块所有的receipt
}

type DatabaseWriter interface {
	WriteBlock(block *models.Block) (err error)                                              // 写入区块
	WriteHeader(header *models.Header) (err error)                                           // 写入header
	WriteChainConfig(bHash types.Hash, height uint64, chainConfig *models.ChainConfig) error // 写入链配置
	WriteLatestBlockHash(bHash types.Hash) error                                             // 写入最新的区块hash
	WriteLatestHeaderHash(bHash types.Hash) error                                            // 写入最新的header头hash
	WriteCanonicalHash(bHash types.Hash, height uint64) error                                // 写入标准的hash
	WriteTxsLookup(block *models.Block) error                                                // 写入交易的索引
	WriteReceipts(bHash types.Hash, height uint64, receipts statetype.Receipts) error        // 写入receipt

	DeleteBlock(blockAbs []models.BlockAbstract, currentHeight, desHeight uint64) error // 删除区块
}

type Handshake interface {
	Start() error
	Stop() error
	RequestHandshake(id models.P2PID) error // 对p2p进行握手协议处理
	SubscribeHandshake(msg chan *models.HandshakeMsg) event.Subscription
}

type KVStore interface {
	KVStoreReader
	KVStoreWriter
	KVStoreDeleter
}

type KVStoreDeleter interface {
	Delete(key []byte) error
}

type KVStoreReader interface {
	Has(key []byte) (bool, error)
	Get(key []byte) ([]byte, error)
}

type KVStoreWriter interface {
	Put(key []byte, value []byte) error
}

type Key interface {
	Marshal() ([]byte, error)     // key序列化
	Unmarshal(input []byte) error // key反序列化
	Equals(Key) bool              // 判断key是否一致
	Raw() ([]byte, error)         // 返回x509格式
	Type() KeyType                // 密钥类型
	Hash() func() hash.Hash       // hash算法
}

type KeyType int32

type Node interface {
	Init() error  // 初始化模块
	Start() error // 启动
	Stop() error  // 停止
	Wait()        // 等待

	Database() Database
	KVDatabase() kvstore.Database
	Config() Config
	BlockReadWriter() BlockReadWriter
	NodeKey() NodeKey
	Apps() Apps
	APIs() APIs
	AddTxPool(txType types.TxType, txPool TxPool)

	SetConsensus(consensus Consensus) error
}

type NodeKey interface {
	ID() (models.NodeID, error)                                                     // 获取节点的ID
	IdFromPub(pub crypto.PublicKey) (models.NodeID, error)                          // 通过公钥获取ID
	PubKey(pubKey crypto.PublicKey) (PubKey, error)                                 // 原生公钥转公钥
	Sign(data []byte) (*signature.SignResult, error)                                // 使用节点私钥签名数据
	Verify(data []byte, signResult *signature.SignResult) (bool, error)             // 验证签名，sig是data对应Hash的签名
	RecoverId(data []byte, signResult *signature.SignResult) (models.NodeID, error) // 从签名中获取地址
	RecoverPub(data []byte, signResult *signature.SignResult) (PubKey, error)       // 从签名中公钥
}

type OPCode interface {
	IsPush() bool
	String() string
	Byte() byte
}

type P2PService interface {
	Start() error     // 启动p2p服务
	Stop() error      // 停止p2p服务
	Id() models.P2PID // 本节点peerId

	NetURL() string                       // 本节点网络标识
	RemotePeers() []models.P2PID          // 已经连接的节点列表
	P2PInfo() map[string]*models.P2PInfo  // 已经连接的节点URL
	HandshakeSuccess(peerId models.P2PID) //  握手成功

	Send(peerId models.P2PID, msg *models.P2PMessage) error // 发送p2p消息

	AddPeer(peerUrl string) error       // 添加节点
	DropPeer(peerId models.P2PID) error // 删除节点

	SubscribeMsg(msgType uint, ch chan<- *models.P2PMessage) event.Subscription // 订阅节点信息
	SubscribeHandshakePeer(ch chan<- models.P2PID) event.Subscription           // 新节点事件
	SubscribeNewPeer(ch chan<- models.P2PID) event.Subscription                 // 新节点事件
	SubscribeDropPeer(ch chan<- models.P2PID) event.Subscription                // 节点断开事件
}

type Packer interface {
	Start() error
	Stop() error
}

type Permission interface {
	IsAdmin(key string, height uint64) bool
	IsPeer(peerId models.P2PID, height uint64) bool

	AddSupervisor(key string, info permission.MemberInfo) error
	DelSupervisor(key string) error

	AddPermission(peerId models.P2PID, key string, info permission.MemberInfo, r permission.RoleType) error
	DelPermission(peerId models.P2PID, key string, r permission.RoleType) error
}

type PrecompiledContract interface {
	RequiredGas(input []byte) uint64  // RequiredPrice calculates the contract gas use
	Run(input []byte) ([]byte, error) // Run runs the precompiled contract
}

type PrivKey interface {
	Key
	Sign(data []byte) (*signature.SignResult, error) // 对bytes进行签名
	GetPublic() PubKey                               // 获取私钥对应的公钥
}

type PubKey interface {
	Key
	Verify(data []byte, signResult *signature.SignResult) (bool, error) // 验证签名，sig是data对应Hash的签名
}

type RequestSync interface {
	RequestOneHeader(peerId models.P2PID, hash types.Hash) error
	RequestHeadersByHash(peerId models.P2PID, origin types.Hash, amount int, skip int, reverse bool) error
	RequestHeadersByNumber(peerId models.P2PID, origin uint64, amount int, skip int, reverse bool) error
	HandleBlockHeadersMsg(peerId models.P2PID, headers []*models.Header) error
	HandleBlockBodiesMsg(peerId models.P2PID, request []*models.Body)
}

type ResponseSync interface {
	SendBlockHeaders(peerId models.P2PID, query ext.GetBlockHeadersData)
	SendBlockBodies(peerId models.P2PID, hashes []types.Hash)
}

type StateDB interface {
	CreateAccount(addr types.Address) // 创建账户

	SubBalance(addr types.Address, amount *big.Int) // 减少余额
	AddBalance(addr types.Address, amount *big.Int) // 增加余额
	GetBalance(addr types.Address) *big.Int         // 获取余额

	GetNonce(addr types.Address) uint64        // 获取nonce
	SetNonce(addr types.Address, nonce uint64) // 设置nonce

	GetCodeHash(addr types.Address) types.Hash // 根据contract获取对应的codeHash
	GetCode(addr types.Address) []byte         // 根据contract获取code
	SetCode(addr types.Address, code []byte)   // 设置contract对应的code
	GetCodeSize(addr types.Address) int        // 获取code对应的size

	AddRefund(gas uint64) // 添加退款
	SubRefund(gas uint64) // 减少退款
	GetRefund() uint64    // 获取退款

	GetCommittedState(addr types.Address, hash types.Hash) types.Hash
	GetState(addr types.Address, hash types.Hash) types.Hash
	SetState(addr types.Address, key types.Hash, value types.Hash)

	Suicide(addr types.Address) bool
	HasSuicided(addr types.Address) bool

	// Exist reports whether the given account exists in state.
	// Notably this should also return true for suicided accounts.
	Exist(addr types.Address) bool
	// Empty returns whether the given account is empty. Empty
	// is defined according to EIP161 (balance = nonce = code = 0).
	Empty(addr types.Address) bool

	RevertToSnapshot(int)
	Snapshot() int

	AddLog(log *statetype.Log)
	AddPreimage(hash types.Hash, preimage []byte)

	ForEachStorage(addr types.Address, cb func(key, value types.Hash) bool) error
}

type Syncer interface {
	Start() error
	Stop() error
}

type Tracer interface {
	CaptureStart(from types.Address, to types.Address, call bool, input []byte, gas uint64, value *big.Int) error
	CaptureState(env VM, pc uint64, op OPCode, gas, cost uint64, contract Contract, depth int, err error) error
	CaptureLog(env VM, msg string) error
	CaptureFault(env VM, pc uint64, op OPCode, gas, cost uint64, contract Contract, depth int, err error) error
	CaptureEnd(output []byte, gasUsed uint64, t time.Duration, err error) error
}

type TxPool interface {
	Start() error // 启动
	Stop() error  // 停止

	Add(peerId *models.P2PID, tx models.Transaction) error                 // 添加交易
	Exist(hash types.Hash) bool                                            // 判断hash是否存在
	Get(hash types.Hash) (models.Transaction, models.TxStatus)             // 通过hash获取交易
	GetTxs(txsLimit uint64) []models.Transaction                           // 获取指定数量的交易
	FetchTxs(txsLimit uint64, headerTimestamp uint64) []models.Transaction // 获取需打包的交易
	Fallback(txs []models.Transaction) error                               // 放回交易集
	Delete(tx models.Transaction, noErr bool) error                        // 删除交易
	Len() uint64                                                           // 交易池的数量

}

type TxPools interface {
	Start() error // 启动
	Stop() error  // 停止

	Register(txType types.TxType, txPool TxPool)
	TxPool(txType types.TxType) (TxPool, error)

	Add(peerId *models.P2PID, tx models.Transaction) error                          // 添加交易
	Get(txType types.TxType, hash types.Hash) (models.Transaction, models.TxStatus) // 通过hash获取交易
	GetTxs(txsLimit uint64) map[types.TxType][]models.Transaction                   // 获取指定数量的交易
	FetchTxs(txsLimit uint64, headerTimestamp uint64) models.Transactions           // 获取需打包的交易
	Fallback(txType types.TxType, txs []models.Transaction) error                   // 放回交易集
	Delete(txType types.TxType, txs []models.Transaction, noErr bool) error         // 删除交易
	Len() map[types.TxType]uint64                                                   // 交易池的数量

	Subscribe(ch chan []models.Transaction) event.Subscription // 订阅
}

type TxValidator interface {
	// ValidateTx 添加transaction时进行校验
	ValidateTx(ctx AppContext, txI models.Transaction) error
	// ValidateTxSafe 验证交易，打包等检测
	ValidateTxSafe(ctx AppContext, txI models.Transaction, headerTimestamp uint64) error
}

type VM interface {
	VmName() string // vm名称

	Cancel()         // 取消合约处理
	Cancelled() bool // 合约是否已经取消

	Call(caller ContractRef, addr types.Address, input []byte, gas uint64, value *big.Int) (ret []byte, leftOverGas uint64, err error)
	CallCode(caller ContractRef, addr types.Address, input []byte, gas uint64, value *big.Int) (ret []byte, leftOverGas uint64, err error)
	DelegateCall(caller ContractRef, addr types.Address, input []byte, gas uint64) (ret []byte, leftOverGas uint64, err error)
	StaticCall(caller ContractRef, addr types.Address, input []byte, gas uint64) (ret []byte, leftOverGas uint64, err error)

	Create(caller ContractRef, code []byte, gas uint64, value *big.Int) (ret []byte, contractAddr types.Address, leftOverGas uint64, err error)
	Create2(caller ContractRef, code []byte, gas uint64, endowment *big.Int, salt *big.Int) (ret []byte, contractAddr types.Address, leftOverGas uint64, err error)

	DB() StateDB
	Coinbase() types.Address // 当前节点的地址

}