CITA-Cloud 文档

CITA-Cloud是云原生的区块链定制框架，使企业用户能够快速构建面向自身业务的区块链系统。

介绍

CITA-Cloud由国内区块链行业的先驱和资深人士创建，他们致力于克服区块链技术在企业应用领域的难点。

通过早期在国产高性能联盟链CITA上开发以及落地应用方面的经验积累，发现联盟链虽然在架构上和公链大体一致，但在技术选型，规模、运维、互操作性等方面有很大的不同。

CITA-Cloud是一个面向企业场景，灵活，开放，可互操作和云原生的区块链框架。

灵活

企业场景非常多变，单独一种实现无法满足所有场景。

CITA-Cloud采用微服务架构，组件可以灵活替换，针对场景定制最适合的链。

快速定制

每个微服务可以有多种不同的实现，相互之间可以替换。

用户根据需要选择适合的组件，无需底层开发，就可以快速定制一条适合具体场景链。

比如，客户原来使用Fabric，因此已经积累了一些使用chaincode编写的智能合约。

但是因为在某些项目中必须使用国密算法，而无法使用Fabric。

使用CITA-Cloud框架，只要executor_chaincode和kms_sm两个微服务实现的组合，就能同时实现复用chaincode编写的智能合约和支持国密的目标。

在企业场景中，用户需求场景非常多变，共识算法也可以有不同的选择。

使用CITA-Cloud框架，在consensus_bft和consensus_raft两个共识微服务实现之间选择即可，不用任何的额外工作。

场景定制

如果已有的组件都不能满足用户需求，可以针对场景定制某个组件。

同时可以复用其他已有的组件，达到快速定制的目标。

例如，某著名科研机构使用CITA-Cloud框架，只用了两周的时间就完成其自主研发的国密算法实现到微服务的封装，快速完成特定场景的定制。

开放

CITA-Cloud使用Apache 2.0开源协议，并提供定制所需的架构、开发工具，以及一个开放的社区。

架构

使用标准的微服务架构，本身只规定了微服务间的接口，给具体微服务实现留有非常大的发挥空间。

微服务划分采用正交分解方式，实现核心流程可定制，功能组件可替换的能力。

借鉴控制面和数据面分离的架构思想。将区块链相关的核心流程和核心数据全部集中在名为controller的微服务中，其他五个微服务则类似于数据平面，被动调用。

每一个微服务都能独立完成某项功能，接口能够自洽，保证每个微服务都是标准组件。

语言无关

微服务间通信使用gRPC和ProtoBuf的组合，各种语言的开发者都可以方便的参与。

在开发过程中可以选择最适合的语言，方便复用已有的软件栈或者库。

可互操作

随着联盟链在金融，政企领域的应用，越来越多的同构和异构的区块链应运而生。

在促进区块链生态环境日渐丰富的同时，也呈现出割裂和碎片化的趋势。

如何实现区块链之间的互操作，使不同区块链能够协同工作，这是一个非常重要的挑战。

智能合约生态

CITA-Cloud可以通过替换executor微服务的实现来兼容多种智能合约引擎。

目前兼容了以太坊和Fabric两个最大的智能合约生态，未来还可以针对具体场景兼容更多的链的生态。

比如针对隐私，支持基于零知识证明的合约引擎。

跨链协议

CITA-Cloud兼容陆羽跨链协议，实现对异构链的互操作。

陆羽跨链协议是一个面向可信源的互操作协议，旨在成为一套灵活、统一、可靠的互操作协议，实现对不同可信源的便捷接入与可靠操作。

云原生

区块链与云原生都是非常基础的分布式技术，采用云原生已有的发展思路对区块链来说是一条捷径，可以复用云原生社区成熟的资源。

联盟链的生态相比公链差很多，只有借助云原生社区的生态，才能有足够的发展空间。

区块链相比云原生更侧重去中心化的特性，两者可以互补。

复用成熟组件

区块链涉及的技术非常多，包括网络，存储，共识，智能合约引擎等。

完全自己开发，投入非常大，且达到企业级可靠性需要的时间比较漫长。

但是其中很多技术在云原生社区已经有成熟的组件。

CITA-Cloud可以方便的将已有的成熟技术封装成微服务实现。

前面提到的Raft共识算法，复用PingCAP的Raft实现。

此实现在PingCA的产品中使用多年，经过生产环境的检验。

复用此实现，节省了大量的开发测试人力，也使得该微服务实现可靠性直接达到生产可用级别。

BaaS服务

借助云原生的能力，CITA-Cloud可以提升相关资源管理能力，实现自动化运维。

支持同一条链的多个节点部署在异地集群，甚至是不同实体的多个集群中。

架构设计

CITA-Cloud总体设计上采用微服务架构，划分为Controller，Network，Consensus，Storage，Executor，Crypto六个微服务。

_images/micro_service.png

微服务架构图

微服务接口定义参见cita_cloud_proto。

微服务之间相互解耦，达到不同实现可以灵活替换，自由组合的目的。解耦设计的细节参见底层链技术白皮书。

为了能够快速构建起完整的，成熟的生态。在之前解耦的基础上，让解耦出的每一个微服务都能独立完成某项功能，每个微服务的接口能够自洽。使其不只是作为CITA-Cloud的组件存在，还可以拥有自己独立的生态。

Network

Network微服务，维护与其他节点之间的网络连接，为本节点的其他微服务提供网络服务。

主要功能有收/发网络消息和节点管理，状态查询。

接收网络消息

收的部分采用了控制反转，收到的网络消息根据消息头中的module字段分发到其他微服务，并通过回调其他微服务的gRPC接口的方式在微服务间传递网络消息。

在6.6.0版本中废弃了注册接口，改为使用配置的方式获取其他需要网络服务的微服务gRPC接口信息。

// 网络消息分发时，回调的 gRPC 接口
// 注册网络服务的其他微服务必须实现该接口
service NetworkMsgHandlerService {
    rpc ProcessNetworkMsg(NetworkMsg) returns (common.StatusCode);
}

// 网络消息结构
message NetworkMsg {
    string module = 1;  // 接收的微服务名称
    string type = 2;    // 消息类型，用于在同一个微服务内区分不同的消息
    uint64 origin = 3;  // 消息的节点标识
    bytes msg = 4;      // 消息数据
}

发送网络消息

发的部分提供了单播(SendMsg)和广播(Broadcast)两个接口。

// 发送消息给一个特定的节点
// 通过消息中的 origin 字段指定接收节点的标识
rpc SendMsg(NetworkMsg) returns (common.StatusCode);

// 广播消息
// 消息中的 origin 字段被忽略
rpc Broadcast(NetworkMsg) returns (common.StatusCode);

关于消息中的origin字段，在收到网络消息之后，需要对其进行一个处理。

发送时填的是接收节点的标识，接收到之后会将该字段修改为发送节点的标识。

状态查询

message NetworkStatusResponse {
    uint64 peer_count = 1;
}

rpc GetNetworkStatus(common.Empty) returns (NetworkStatusResponse);

查询网络连接状态的接口，返回当前连接的节点数量。

注意，这个数量里不包括节点自身。因此，4个子节点的链，正常查询结果是3。

message NodeNetInfo {
    string multi_address = 1;
    uint64 origin = 2;
}

message TotalNodeNetInfo {
    repeated NodeNetInfo nodes = 1;
}

rpc GetPeersNetInfo(common.Empty) returns (common.TotalNodeNetInfo);

查询节点网络信息的接口，返回连接的邻居节点的网络地址和标识信息。

注意：网络微服务的实现可以是任意的网络协议，为了兼容不同的协议，这里展示用的是multi_address。

节点管理

message NodeNetInfo {
    string multi_address = 1;
    uint64 origin = 2;
}

rpc AddNode(common.NodeNetInfo) returns (common.StatusCode);

增加节点信息的接口(AddNode)，用于临时增加一个节点到网络中。

发展方向

独立出该微服务的初衷是网络部分比较复杂，希望该服务能隔离这部分复杂性，其他微服务就可以不用关心网络的具体情况。因此，其实现会朝着如下方向发展：

处理复杂的网络场景。比如，p2p，防火墙穿透，虚拟私有网络等场景。
对接多种协议。比如，TCP，UDP等。
提供更高的可靠性。比如，提供重发，限流，QoS，保证消息到达且仅到达一次等。

Storage

Storage微服务，主要提供KV存储相关的功能，涵盖了常用的增删改查功能。

用于保存交易，区块和一些链相关的全局信息。

存储分区

针对区块链业务，预先定义了不同的region，将不同类别的数据分别存放：

enum Regions {
    GLOBAL = 0;
    TRANSACTIONS = 1;
    HEADERS = 2;
    BODIES = 3;
    BLOCK_HASH = 4;
    PROOF = 5;
    RESULT = 6;
    TRANSACTION_HASH2BLOCK_HEIGHT = 7;
    BLOCK_HASH2BLOCK_HEIGHT = 8;  // In SQL db, reuse 4
    TRANSACTION_INDEX = 9;
    COMPACT_BLOCK = 10;
    FULL_BLOCK = 11;
    BUTTON = 12;
}

GLOBAL 保存链相关的全局信息，比如当前链的最新高度，对应的key为自定义的固定值。

TRANSACTIONS 保存交易哈希 -> 交易原始数据的对应关系。

HEADERS 保存区块高度 -> 区块头数据的对应关系。

BODIES 保存区块高度 -> 区块体数据的对应关系。

BLOCK_HASH 保存区块高度 -> 区块哈希的对应关系。

PROOF 保存区块高度 -> 区块证明的对应关系。

RESULT 保存区块高度 -> 区块执行结果的对应关系。

TRANSACTION_HASH2BLOCK_HEIGHT 保存交易哈希 -> 交易所在区块高度的对应关系。

BLOCK_HASH2BLOCK_HEIGHT 保存区块哈希 -> 区块高度的对应关系。即 BLOCK_HASH 的反查。

TRANSACTION_INDEX 保存交易哈希 -> 交易在所在区块中的序号的对应关系。

COMPACT_BLOCK 保存区块高度 -> 紧凑区块的对应关系。

FULL_BLOCK 保存区块高度 -> 完整区块的对应关系。

定制开发者可以根据自己的需要调整region列表。

store

message Content {
    uint32 region = 1;
    bytes key = 2;
    bytes value = 3;
}

// store key/value
rpc Store(Content) returns (common.StatusCode);

其中region即前述存储分区的枚举值。

注意:

key和value类型为bytes，需要调用方提前进行类型转换。
其语义是updata，同时包含增和改的功能。

load

message ExtKey {
    uint32 region = 1;
    bytes key = 2;
}

message Value {
    common.StatusCode status = 1;
    bytes value = 2;
}

// given a ext key return value
rpc Load(ExtKey) returns (Value);

delete

message ExtKey {
    uint32 region = 1;
    bytes key = 2;
}

// given a ext key delete it
rpc Delete(ExtKey) returns (common.StatusCode);
}

发展方向

联盟链的存储压力相较公链会大很多，可靠性要求也更高。因此，其实现会朝着如下方向发展：

大数据量。比如，分布式数据库。
更多功能。比如，冷热数据分离，备份等。

Crypto

Crypto微服务，主要提供其他微服务需要的密码学服务。

目前提供区块链最基础的签名和哈希服务。

GetCryptoInfo

message GetCryptoInfoResponse {
    common.StatusCode status = 1;
    string name = 2;
    uint32 hash_len = 3;
    uint32 signature_len = 4;
    uint32 address_len = 5;
}

// Get crypto info
rpc GetCryptoInfo(common.Empty) returns (GetCryptoInfoResponse);

查询结果：

name 算法组合的名称。
hash_len 哈希算法得出的哈希值的字节长度。
signature_len 签名算法得出的签名的字节长度。
address_len 账户地址的字节长度。

签名

message SignMessageRequest {
    bytes msg = 2;
}

message SignMessageResponse {
    common.StatusCode status = 1;
    bytes signature = 2;
}

// Sign a message
rpc SignMessage(SignMessageRequest) returns (SignMessageResponse);

本接口入参为签名所使用的账户的序号和要签名的消息，返回数字签名。

message RecoverSignatureRequest {
    bytes msg = 1;
    bytes signature = 2;
}

message RecoverSignatureResponse {
    common.StatusCode status = 1;
    bytes address = 2;
}

// Recover signature
rpc RecoverSignature(RecoverSignatureRequest) returns (RecoverSignatureResponse);

本接口入参为消息和其对应的数字签名，返回执行签名的账户地址。

注意：从接口定义看，似乎只能支持能恢复出公钥的签名算法。但是实际上可以把公钥附在签名后面，模拟出能恢复出公钥的签名算法。

哈希

message HashDataRequest {
    bytes data = 1;
}

message Hash {
    bytes hash = 1;
}

message HashResponse {
    StatusCode status = 1;
    Hash hash = 2;
}

// Hash data
rpc HashData(HashDataRequest) returns (common.HashResponse);

本接口入参为要哈希的数据，返回哈希值。

message VerifyDataHashRequest {
    bytes data = 1;
    bytes hash = 2;
}

// Verify hash of data
rpc VerifyDataHash(VerifyDataHashRequest) returns (common.StatusCode);

本接口入参为要哈希的数据和相应的哈希值，返回校验结果。

CheckTransactions

// check transactions
rpc CheckTransactions(blockchain.RawTransactions) returns (common.StatusCode);

本接口用于批量校验交易。

因为交易验证过程中设计大量的密码学校验，如果每次都发起rpc调用性能会比较差。

可以认为是一个特殊的批量调用接口。

发展方向

密码学在区块链中至关重要，独立出该微服务的初衷是将系统与所使用的密码学算法解耦，方便将来替换密码学算法。

因此，其实现会朝着如下方向发展：

新密码学算法的支持。比如，更加安全，更加高效的密码学算法。
更多密码学相关功能集成。比如，对称加密，零知识证明等。

Executor

Executor微服务，提供智能合约能力。

根据交易内容执行对应的智能合约，改变链上状态或者查询链上状态的。

Exec

// exec a block return executed_block_hash
rpc Exec(blockchain.Block) returns (common.HashResponse);

本接口入参为一个完整的区块数据，返回执行完区块中所有交易后的状态结果。

此结果数据类型为哈希值，类似以太坊的state_root。

Call

message CallRequest {
    bytes to = 1;
    bytes from = 2;
    bytes method = 3;
    repeated bytes args = 4;
    uint64 height = 5;
}

message CallResponse {
    bytes value = 1;
}

rpc Call(CallRequest) returns (CallResponse);

合约查询功能，调用合约中的指定方法，返回调用该方法的返回值。

其中height用于查询指定高度的状态。如果不设置该项，则表示默认查询最新状态。

发展方向

智能合约是区块链在可编程性方面很重要的功能。

该微服务只做了非常粗粒度的抽象，至于实现的细节，比如采用何种VM；状态有哪些内容；状态如何组织和保存，都由具体实现来决定。

其实现会朝着如下方向发展：

移植有广泛智能合约生态的引擎。比如，以太坊的EVM。
提供通用语言的Runtime，使得用户可以用通用编程语言编写智能合约，降低合约开发门槛。
针对一些特定应用场景，提供特定的VM和智能合约编程语言。比如可信计算，隐私计算，数据格式转换等。

Consensus

Consensus微服务，主要提供让提案在多个共识参与方之间达成一致的功能。

单独这个微服务的功能，可以认为是一个分歧解决机。

_images/consensus.png

共识微服务时序图

获取本节点提案

message Proposal {
    uint64 height = 1;
    bytes data = 2;
}

message ProposalResponse {
    StatusCode status = 1;
    Proposal proposal = 2;
}

rpc GetProposal(common.Empty) returns (common.ProposalResponse);

该接口实现在Controller微服务中,Consensus微服务去调用。

返回的提案数据类型为bytes，因为Consensus微服务不需要了解提案的具体内容。

检查其他节点的提案

rpc CheckProposal(common.Proposal) returns (common.StatusCode);

该接口实现在Controller微服务中,Consensus微服务去调用。

当本节点的Consensus微服务收到其他节点发送的提案，调用该接口检查提案是否合法。

提交共识结果

message ProposalWithProof {
    Proposal proposal = 1;
    bytes proof = 2;
}

message ConsensusConfiguration {
    uint64 height = 1;
    uint32 block_interval = 2;
    repeated bytes validators = 3;
}

message ConsensusConfigurationResponse {
    StatusCode status = 1;
    ConsensusConfiguration config = 2;
}

rpc CommitBlock(common.ProposalWithProof) returns (common.ConsensusConfigurationResponse);

该接口实现在Controller微服务中,Consensus微服务去调用。

共识达成之后，提交经过共识的提案以及相关证明，例如投票信息等。

Controller微服务会给Consensus微服务返回新的配置信息。

目前配置信息包括:

出块间隔。
共识参与方账户地址列表。

检查同步的提案

rpc CheckBlock(common.ProposalWithProof) returns (common.StatusCode);

该接口实现在Consensus微服务中,Controller微服务调用。

本节点进度落后的时候，Controller微服务会从其他节点同步已经共识过的提案及相关的证明。

Controller微服务本身无法验证证明是否合法，只能交由Consensus微服务来验证。

配置变更

rpc Reconfigure(common.ConsensusConfiguration) returns (common.StatusCode);

该接口实现在Consensus微服务中,Controller微服务调用。

发展方向

共识是区块链非常核心的功能，但是共识算法实现非常多样化。

该微服务尽量做到抽象，以适应不同的共识算法。

其实现会朝着如下方向发展：

更新更高效的共识算法。
针对一些特定应用场景。比如非拜占庭容错的共识算法等。

Controller

Controller微服务在整个区块链中处于核心的位置，主导所有主要的流程，并给上层用户提供RPC接口。

接口除了前述的针对Consensus微服务的接口，就是针对上层用户的RPC接口。其中最重要的是SendRawTransaction发送交易接口，剩下的都是一些信息查询接口。

单独就这个微服务来说，可以认为是一个提案管理系统。用户通过发送交易接口，提交原始交易数据，Controller管理这些原始交易数据。通过计算原始交易数据的哈希，组装成区块，并形成Consensus需要的提案，管理这些提案。这里所说的管理，包括持久化，同步，以及验证其合法性。

Blockchain.proto文件中定义了一套交易和区块的数据结构，但是前面所述的从原始交易数据如何产生最终Consensus需要的提案，并且这个过程还是要可验证的，这些都由具体实现决定。

Controller微服务给上层用户提供RPC接口有：

service RPCService {
    // flag means latest or pending.
    // true means pending, false means latest.
    rpc GetBlockNumber(Flag) returns (BlockNumber);

    rpc SendRawTransaction(blockchain.RawTransaction) returns (common.Hash);

    rpc SendRawTransactions(blockchain.RawTransactions) returns (common.Hashes);

    rpc GetBlockByHash(common.Hash) returns (blockchain.CompactBlock);

    rpc GetHeightByHash(common.Hash) returns (BlockNumber);

    rpc GetBlockByNumber(BlockNumber) returns (blockchain.CompactBlock);

    rpc GetStateRootByNumber (BlockNumber) returns (common.StateRoot);

    rpc GetProofByNumber (BlockNumber) returns (common.Proof);

    rpc GetBlockDetailByNumber(BlockNumber) returns (blockchain.Block);

    rpc GetTransaction(common.Hash) returns (blockchain.RawTransaction);

    rpc GetSystemConfig(common.Empty) returns (SystemConfig);

    rpc GetSystemConfigByNumber(BlockNumber) returns (SystemConfig);

    rpc GetBlockHash(BlockNumber) returns (common.Hash);

    rpc GetTransactionBlockNumber(common.Hash) returns (BlockNumber);

    rpc GetTransactionIndex(common.Hash) returns (TransactionIndex);

    // add new node
    rpc AddNode(common.NodeNetInfo) returns (common.StatusCode);

    rpc GetNodeStatus(common.Empty) returns (common.NodeStatus);

    rpc GetCrossChainProof(common.Hash) returns (CrossChainProof);
}

其中SendRawTransaction为发送交易接口。

如果发送交易失败，会在响应消息中将gRPC的Status设置为InvalidArgument，并将链返回的内部错误以字符串的形式嵌入其中。

发送普通交易可能的错误有：

结构错误：

NoTransaction/NoneRawTx – 交易结构错误，非支持的NormalTx和UtxoTx
NoneWitness – 交易结构中缺少签名信息
EncodeError – 编码错误
NoneTransaction – 交易结构中缺少Transaction

内容错误：

InvalidVersion – 交易结构中version非法
InvalidTo – 交易结构中to非法
InvalidNonce – 交易结构中nonce非法
InvalidValue – 交易结构中value非法
InvalidChainId – 交易结构中chain id非法
HashLenError – 交易结构中transaction_hash长度不符
HashCheckError – 交易结构中transaction_hash与交易内容不符
SigCheckError – 交易签名非法

运行时错误：

EmergencyBrake – 紧急制动打开，不接受交易
InvalidValidUntilBlock – 交易结构中valid unitl block非法
QuotaUsedExceed – 交易结构中quota超过上限
HistoryDupTx – 与历史区块中的交易重复
DupTransaction – 与交易池中的交易重复

这些接口还比较底层，用于查询链的各种信息。SDK或者中间件会封装更高层的接口，方面用户查询完整的信息。

发展方向

Controller微服务是整个区块链系统的控制中枢，其内部逻辑和流程非常复杂，可定制部分也比较多。

未来我们会进一步梳理该微服务，并尝试提供一个框架，方便用户自定义流程，甚至是自定义交易和块等核心数据结构。

组件

组件是各个微服务的实现。

每个组件单独一个代码仓库，仓库名称以微服务名称开头，下划线后接用于标识不同实现的名称。

构建物使用微服务名称，以便于相互替换。

比如network_zenoh，是基于zenoh实现的Network微服务，其构建物为可执行文件network。

组件分为两类：

原厂组件，即CITA-Cloud自带的组件。
第三方组件。

组件还有以下一些指标：

组件的成熟度：1-5，1表示仅实现必要的功能的最小实现，5表示非常成熟的实现。
组件的状态：开发中，维护中，废弃。
组件的授权状态：商业，或者开源。

原厂组件

network_zenoh

介绍：基于网络库zenoh实现。

特点：

基于QUIC网络协议，弱网络下更稳定，延迟更低。
支持TLS，通信加密保证安全。
支持Pub/Sub模式，提供更高层的接口，提供与底层网络连接无关的节点标识。
支持消息送达保证，更加稳定可靠。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

storage_opendal

介绍：基于opendal的实现。

特点：

冷热数据分离。热数据存在本地，冷数据存到云存储，可以使得本地存储数据量较小且相对固定。
共享第三层。多个节点共享第三层云存储，新节点无需恢复大量的冷数据，而只需通过恢复热数据即可快速加入。

第二层存储为rocksdb，特点：

高效，KV数据库，读写效率高。
可靠，多数区块链项目都使用rocksdb作为存储引擎，稳定性好。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

crypto_sm

介绍：国密算法的实现，使用sm2签名算法和sm3哈希算法。

特点：

符合中国国家密码标准。
高效，纯Rust实现，采用多种优化技术。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

crypto_eth

介绍：兼容以太坊算法的实现，使用secp256k1签名算法和keccak哈希算法。

特点：

兼容以太坊。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

executor_evm

介绍：基于以太坊的EVM实现。

特点：

兼容以太坊的智能合约生态。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

consensus_raft

介绍：基于Raft实现。

特点：

非拜占庭容错。
成熟实现，稳定可靠。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

consensus_overlord

介绍：基于overlord实现。

特点：

拜占庭容错。
成熟实现。
线性消息复杂度。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

controller

介绍：目前唯一的Controller实现。

特点：

先共识后执行。
高性能，流水线式并行。
utxo模型的系统配置管理。
丰富的治理功能。

代码仓库

镜像仓库

成熟度： 4

状态：维护中

授权：开源，Apache-2.0 License

废弃组件

consensus_bft

介绍：基于CITA-BFT实现。

特点：

拜占庭容错。
线性消息复杂度。

代码仓库

镜像仓库

成熟度： 4

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被consensus_overlord替代。两者同为BFT类算法，但是overlord在性能方面更有优势。

network_direct

介绍：基于tokio网络库的实现。

特点：

网络直连，简单可靠
无通信加密

代码仓库

镜像仓库

成熟度： 3

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被network_tls替代。因为区块链的去中心化属性，网络通信加密是比较基础的需求。

network_p2p

介绍：基于网络库tentacle实现。

特点：

支持secio，通信加密保证安全。
支持多路复用(yamux)，可以自定义协议。
支持节点发现，节点之间会自动交换连接的节点信息。

代码仓库

镜像仓库

成熟度： 4

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被network_zenoh替代。

network_tls

介绍：基于tokio-rustls实现。

特点：

支持TLS1.3，通信加密保证安全。
使用标准的x509证书，方便复用已有的基础设施。
支持白名单，便于权限管理。

代码仓库

镜像仓库

成熟度： 4

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被network_zenoh替代。

network_quic

介绍：基于QUIC网络协议的实现。

特点：

高效，基于UDP协议，开销更小。
安全，默认支持TLS，通信加密。
可靠，弱网络下效果更高。

代码仓库

镜像仓库

成熟度： 2

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被network_zenoh替代。

storage_rocksdb

介绍：基于rocksdb的实现。

特点：

高效，KV数据库，读写效率高。
可靠，多数区块链项目都使用rocksdb作为存储引擎，稳定性好。

代码仓库

镜像仓库

成熟度： 4

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被storage_opendal替代，storage_opendal提供更全面的功能，rocksdb仍作为其中的第二层存储。

storage_sqlite

介绍：基于sqlite的实现。

特点：

轻量，嵌入式数据库，开销小。
功能丰富，完整支持SQL。

代码仓库

镜像仓库

成熟度： 3

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：被storage_rocksdb替代。目前区块链的实现中主要还是以KV存储为主，SQL数据库的优势发挥不出来，反而性能上不如KV数据库。也许将来对链上数据分析有更多需求的时候可以切换至SQL数据库。

storage_tikv

介绍：基于tikv的实现。

特点：

扩展能力强，分布式KV数据库。
稳定可靠，支持分布式事务操作，得到广泛应用。

代码仓库

镜像仓库

成熟度： 2

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：这个组件主要就是验证使用分布式KV数据库的可行性。但是目前数据量还没有到这个程度，所以暂时搁置。

executor_chaincode

介绍：实验性兼容Fabric Chaincode实现。

特点：

兼容Fabric的智能合约生态。

代码仓库

镜像仓库

成熟度： 1

状态：废弃

授权：开源，Apache-2.0 License

废弃原因：本身就是实验性质的组件，为了验证框架有足够的灵活性。后期有相关需求之后完善之后成为executor_chaincode_ext。

第三方组件

废弃组件

executor_chaincode_ext

介绍：增强型兼容Fabric Chaincode实现。

特点：

兼容chaincode合约。
支持了CouchDB。
增加了chaincode事件相关功能。

代码仓库：无

镜像仓库：无

成熟度： 3

状态：废弃

授权：商业

废弃原因：专门为某个商业项目定制，后续没有类似的需求。

kms_sdibc

介绍：基于高性能国密算法实现。

特点：

性能好。

代码仓库：无

镜像仓库：无

成熟度： 4

状态：废弃

授权：商业

废弃原因：专门为某个商业项目定制，后续没有类似的需求。

部署指南

因为采用微服务架构，相比单体软件来说，运维部署比较复杂。

例如：微服务之间如何相互调用；启动顺序如何保证；配置项如何管理等等。

所幸微服务架构已经非常流行，相应的基础设施也已经非常成熟。其中最重要的一点就是云原生技术的发展，它大大简化了微服务架构的应用在运维部署，配置管理方面的工作。

运行环境

CITA-Cloud推荐的运行环境为k8s集群。

对于开发，可以是k3s等轻量级的k8s环境。
对于测试，可以是几台机器搭建的简单的k8s集群。
对于生产环境，推荐有专人维护的高可用k8s集群，或者云厂商提供的容器云方案。

其优点是：

不同环境的操作方式是统一的。
功能灵活，强大。可以实现各种复杂的配置，自动化运维等。
生态繁荣。基于云原生社区，有非常多成熟的配套工具和解决方案。

部署一条CITA-Cloud产生的链，除了准备好运行环境，还需要事先进行持久化存储和网络的设置。

持久化存储

链的节点是有状态的服务，需要挂载持久化存储保存数据。

为了方便对接不同类型的存储服务，我们使用了k8s中的PV/PVC概念对存储进行了抽象。

建议由运维人员配置StorageClass，对PV/PVC实行动态绑定。

对于开发环境，可以使用简单的本地存储。
对于测试环境，可以使用NFS，由单独一台磁盘比较大的机器提供存储。
对于生产环境，推荐使用各种成熟的云存储，分布式存储，NAS等专业存储系统。

网络

网络方面，需要微服务之间，以及节点之间可以通过网络相互访问。

目前推荐的部署方式是，一个节点一个Pod，里面包含6个微服务的容器。

微服务之间可以直接通过本地环回网络通信。

节点间的网络通信，如果所有节点都在一个k8s集群内部，可以通过k8s的Service来暴露节点的网络端口。如果是跨集群的情况，则需要使用NodePort或者LoaderBalancer等服务对外暴露节点的网络端口。

工具

配置工具

当前的配置工具为cloud-config，用于生成一条链多个节点，以及每个节点内多个微服务的配置文件。

该配置工具支持常用的大部分组件；适用于各种场景，开发或是生产，单集群或者多集群；支持多种配置模式，集中式，去中心化方式。

具体使用方法，请参考代码仓库中的README。

Node Operator

区块链类似于数据库，但与数据库又有一些不同的地方。相同的是都是有状态的服务，不同的是区块链在备份，迁移，升级，扩容等运维操作时都有特殊的要求。

对于备份来说，区块链每个节点都是一个副本，相当于自带热备方案。冷备也跟数据库不一样，不是按时间（比如每天备份），而是要考虑区块高度。
对于迁移和升级来说，区块链的节点是有身份的，因此不能先部署新的节点，再停老的节点，而是要反过来。
对于扩容来说，增加节点并不能提升区块链的性能，反而会造成反效果，只能扩容cpu，内存。存储也必须所有节点一起扩充。

因此，涉及到比较复杂的运维操作，则需要一些定制开发。而Operator在k8s领域就是用来扩展自定义功能的。

Node Operator以CRD的形式自定义了Backup/Restore等资源类型，提供了备份，恢复，消块，快照等针对链节点的复杂运维操作。

具体使用方法，请参考代码仓库中的README。

快速入门

本章介绍的是使用k3s作为运行环境，快速搭建一条链的操作方法。

关于更加深入的定制操作，请参阅定制章节。

环境准备

硬件配置建议

CPU：4核或以上
内存：8GB或以上
硬盘：30G或以上

软件依赖

操作系统

常见的Linux发行版本均可，例如：CentOS，Debian，Ubuntu等等。

docker

安装方法参见官方文档。

k3s

安装方法参见Rancher官方文档。

完成之后设置环境变量：

export KUBECONFIG=/etc/rancher/k3s/k3s.yaml

cloud-cli

该工具为CITA-Cloud链的命令行客户端，可以方便的对链进行常用的操作。

使用方法参见文档。

$ wget https://github.com/cita-cloud/cloud-cli/releases/download/v0.5.5/cldi-x86_64-unknown-linux-gnu.tar.gz
$ tar zxvf cldi-x86_64-unknown-linux-gnu.tar.gz
$ sudo mv ./cldi /usr/local/bin/
$ cldi -h
cldi 0.5.5
Rivtower Technologies <contact@rivtower.com>
The command line interface to interact with CITA-Cloud

Usage: cldi [OPTIONS] [COMMAND]

Commands:
  get          Get data from chain
  send         Send transaction
  call         Call executor
  create       create an EVM contract
  context      Context commands
  account      Account commands
  admin        The admin commands for managing chain
  rpc          Other RPC commands
  ethabi       Ethereum ABI coder.
  bench        Simple benchmarks
  watch        Watch blocks
  verify       Verify commands
  completions  Generate completions for current shell. Add the output script to `.profile` or `.bashrc` etc. to make it effective.
  help         Print this message or the help of the given subcommand(s)

Options:
  -c, --context <context>           context setting
  -r <controller-addr>              controller address
  -e <executor-addr>                executor address
  -u <account-name>                 account name
  -p <password>                     password to unlock the account
      --crypto <crypto-type>        The crypto type of the target chain [possible values: SM, ETH]
      --consensus <consensus-type>  The consensus type of the target chain [possible values: BFT, OVERLORD, RAFT]
  -t <connect-timeout>              connect timeout
  -h, --help                        Print help
  -V, --version                     Print version

运行链

生成超级管理员账户

使用 cldi 创建账户

$ cldi account generate -h
generate a new account

USAGE:
    cldi account generate [OPTIONS]

OPTIONS:
        --name <name>             The name for the new generated account, default to account address
    -p, --password <password>     The password to encrypt the account
        --crypto <crypto-type>    The crypto type for the generated account. [default: <current-
                                  context-crypto-type>] [possible values: SM, ETH]
    -h, --help                    Print help information

为了演示方便，这里不设置密码，加密算法也使用默认值。

$ cldi account generate --name admin
{
  "crypto_type": "SM",
  "address": "0xc8ca9cc77a7f822fdd0baef7a7740f9dba493455",
  "public_key": "0x0d9edfd3889ec752e92fb1aa53fdfc26512c6a0ea39deb12510e7ac4d0915c4d4f0a18a3c1cf2a5950319d429af38b13483e2ccc9bafd698f5ce2c7ef558ddf6",
  "secret_key": "0x50dc0c1655419938d83d924a3c3b4cbbd57de5df901ce4772272445605a52d43"
}

生成链的配置

设置环境变量：

# 设置docker镜像仓库
export DOCKER_REGISTRY=docker.io
export DOCKER_REPO=citacloud

# 设置链的版本
export RELEASE_VERSION=v6.7.0

# 设置链的类型和名称
export CHIAN_TYPE=overlord
# export CHIAN_TYPE=raft
export CHAIN_NAME=test-$CHIAN_TYPE

# 设置基础环境的Storage Class，这里使用k3s自带的local-path
export SC=local-path

# 设置链运行的命名空间
export NAME_SPACE=cita

生成链的配置文件：

# 生成初始的4个共识节点配置
# 注意：`--admin`参数必须设置为自己生成的账户地址，此处仅为演示，切勿在正式环境中使用演示值。
docker run -it --rm -v $(pwd):/data -w /data $DOCKER_REGISTRY/$DOCKER_REPO/cloud-config:$RELEASE_VERSION cloud-config create-k8s --chain-name $CHAIN_NAME --admin 0xc8ca9cc77a7f822fdd0baef7a7740f9dba493455 --nodelist localhost:40000:node0:k8s,localhost:40001:node1:k8s,localhost:40002:node2:k8s,localhost:40003:node3:k8s --controller_tag $RELEASE_VERSION --consensus_image consensus_$CHIAN_TYPE --consensus_tag $RELEASE_VERSION --network_tag $RELEASE_VERSION --storage_tag $RELEASE_VERSION --executor_tag $RELEASE_VERSION


# 生成所有节点配置的yaml文件
docker run -it --rm -v $(pwd):/data -w /data $DOCKER_REGISTRY/$DOCKER_REPO/cloud-config:$RELEASE_VERSION cloud-config update-yaml --chain-name $CHAIN_NAME --storage-class $SC --docker-registry $DOCKER_REGISTRY --docker-repo $DOCKER_REPO --domain node0
docker run -it --rm -v $(pwd):/data -w /data $DOCKER_REGISTRY/$DOCKER_REPO/cloud-config:$RELEASE_VERSION cloud-config update-yaml --chain-name $CHAIN_NAME --storage-class $SC --docker-registry $DOCKER_REGISTRY --docker-repo $DOCKER_REPO --domain node1
docker run -it --rm -v $(pwd):/data -w /data $DOCKER_REGISTRY/$DOCKER_REPO/cloud-config:$RELEASE_VERSION cloud-config update-yaml --chain-name $CHAIN_NAME --storage-class $SC --docker-registry $DOCKER_REGISTRY --docker-repo $DOCKER_REPO --domain node2
docker run -it --rm -v $(pwd):/data -w /data $DOCKER_REGISTRY/$DOCKER_REPO/cloud-config:$RELEASE_VERSION cloud-config update-yaml --chain-name $CHAIN_NAME --storage-class $SC --docker-registry $DOCKER_REGISTRY --docker-repo $DOCKER_REPO --domain node3

启动链

# 创建命名空间
kubectl create ns $NAME_SPACE

# 部署所有节点
kubectl apply -f $CHAIN_NAME-node0/yamls/ -n $NAME_SPACE
kubectl apply -f $CHAIN_NAME-node1/yamls/ -n $NAME_SPACE
kubectl apply -f $CHAIN_NAME-node2/yamls/ -n $NAME_SPACE
kubectl apply -f $CHAIN_NAME-node3/yamls/ -n $NAME_SPACE

查看运行情况

$ kubectl get pod -n $NAME_SPACE
NAME                                                    READY   STATUS    RESTARTS   AGE
test-overlord-node0-0                                   5/5     Running   0          8m3s
test-overlord-node1-0                                   5/5     Running   0          8m3s
test-overlord-node2-0                                   5/5     Running   0          8m3s
test-overlord-node3-0                                   5/5     Running   0          8m3s

查看日志：

$ kubectl logs -f $CHAIN_NAME-node0-0 -c controller -n $NAME_SPACE
2022-11-16T07:47:40.586458114+00:00 INFO controller::chain - finalize_block height: 23363
2022-11-16T07:47:41.615000522+00:00 INFO controller::health_check - healthcheck entry!
2022-11-16T07:47:41.615016195+00:00 INFO controller::health_check - healthcheck: block increase 23359 23363 1668584861615
2022-11-16T07:47:43.072274837+00:00 INFO controller::chain - add_proposal: tx poll len 0
2022-11-16T07:47:43.073818092+00:00 INFO controller::chain - proposal 23364 block_hash 0x98b1ed689464622d6b48ce8aaf26b3429d3e1dbbba9c6699ca2d0ea1d710f66b prevhash 0x6be134f00d78f7129e29b6db9b7a55a387472acc929ec7809645319c5c0455a5
2022-11-16T07:47:45.931514828+00:00 INFO controller::controller - chain_check_proposal: add remote proposal(0x4fe40496e71bf7a1d3344c6778c2cd9bea547763772fd276ab086ea3ceafe95c)
2022-11-16T07:47:45.935420225+00:00 INFO controller::controller - chain_check_proposal: finished
2022-11-16T07:47:46.014057182+00:00 INFO controller::node_manager - update node: NodeAddress(0a423460911494e1)
2022-11-16T07:47:46.014086372+00:00 INFO controller::controller - update global status node(NodeAddress(0a423460911494e1)) height(23364)
2022-11-16T07:47:46.015283211+00:00 INFO controller::chain - commit_block height: 23364 hash 0x4fe40496e71bf7a1d3344c6778c2cd9bea547763772fd276ab086ea3ceafe95c
2022-11-16T07:47:46.020220810+00:00 INFO controller::chain - exec_block(23364): status: Success, state_root: 0x56e81f171bcc55a6ff8345e692c0f86e5b48e01b996cadc001622fb5e363b421
2022-11-16T07:47:46.023409938+00:00 INFO controller::chain - finalize_block height: 23364

基本操作

指定链的RPC端口

链有两个rpc地址，分别是controller和executor微服务。

我们可以通过-r和-e来告诉cldi如何访问链：

使用如下命令映射节点0的rpc端口到本地。

$ kubectl port-forward -n $NAME_SPACE pod/$CHAIN_NAME-node0-0 50002:50002 50004:50004

对应的cli参数为：

-r localhost:50004 -e localhost:50002

查看块高

$ cldi -r localhost:50004 -e localhost:50002 get block-number
24806

查看系统配置

$ cldi -r localhost:50004 -e localhost:50002 get system-config
{
  "admin": "0xc8ca9cc77a7f822fdd0baef7a7740f9dba493455",
  "admin_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "block_interval": 3,
  "block_interval_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "block_limit": 100,
  "block_limit_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "chain_id": "0x63586a3c0255f337c77a777ff54f0040b8c388da04f23ecee6bfd4953a6512b4",
  "chain_id_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "emergency_brake": false,
  "emergency_brake_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "quota_limit": 1073741824,
  "quota_limit_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "validators": [
    "0x99ac6b222e64af1231dec421dbc22af377f178e070c62dfe272dd28ab2f69fd319fad5240068658e9f57831438bad431",
    "0xb594f9095578711c21f809e0f0cf3c5a2cb93b9b0f260075cea25af5aec2bea4aabe5e302fb31e289f550412fabe923b"
    "0xad93329676dfe026a591fdd6243d630cb28d2cd0e12a7ac2b2e52e1263709112e7e8aed5bfcb010ff207cf6ff58e1143",
    "0x95efa4fdd194a376885c30339a84c0636cf625254e9e7ee71b60b4a51ade4cb5741973f2839a08ff1d9197cdfff0dfd3"
  ],
  "validators_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000",
  "version": 0,
  "version_pre_hash": "0x000000000000000000000000000000000000000000000000000000000000000000"
}

停止链

kubectl delete -f $CHAIN_NAME-node0/yamls/ -n $NAME_SPACE
kubectl delete -f $CHAIN_NAME-node1/yamls/ -n $NAME_SPACE
kubectl delete -f $CHAIN_NAME-node2/yamls/ -n $NAME_SPACE
kubectl delete -f $CHAIN_NAME-node3/yamls/ -n $NAME_SPACE

账户操作

创建账户

$ cldi account generate --name user
{
  "crypto_type": "SM",
  "address": "0xf4b80a27b7d526028183e705604b865c1458c838",
  "public_key": "0x71ebc3701780b4ac6a6ae0817e2fa402fb26082e6eade00f117015a1063a5c3af6e1f74c26c01f87af5ddea20fb28ff6d1a20f5438416afe95e9247ab2e517ce",
  "secret_key": "0x2757242a6138e9617b30ec63f6a240b880d25851d86d9d15849f2d45061d3288"
}

选择操作使用的账户

$ cldi -u user -r localhost:50004 -e localhost:50002
cldi> 

-u选择使用该账户，后续将以该账户的身份发送交易。

进入cldi的交互式模式。

发送交易

编译合约

这里以Counter合约为例:

$ cat Counter.sol 
pragma solidity ^0.4.24;

contract Counter {
    uint public count;
    
    function add() public {
        count += 1;
    }
    
    function reset() public {
        count = 0;
    }
}

$ curl -o solc -L https://github.com/ethereum/solidity/releases/download/v0.4.24/solc-static-linux
$ chmod +x solc
$ sudo mv ./solc /usr/local/bin/
$ solc --hashes --bin Counter.sol 

======= Counter.sol:Counter =======
Binary: 
608060405234801561001057600080fd5b5060f58061001f6000396000f3006080604052600436106053576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff16806306661abd1460585780634f2be91f146080578063d826f88f146094575b600080fd5b348015606357600080fd5b50606a60a8565b6040518082815260200191505060405180910390f35b348015608b57600080fd5b50609260ae565b005b348015609f57600080fd5b5060a660c0565b005b60005481565b60016000808282540192505081905550565b600080819055505600a165627a7a72305820a841f5848c8c68bc957103089b41e192a79aed7ac2aebaf35ae1e36469bd44d90029
Function signatures: 
4f2be91f: add()
06661abd: count()
d826f88f: reset()

创建合约

cldi> create 0x608060405234801561001057600080fd5b5060f58061001f6000396000f3006080604052600436106053576000357c0100000000000000000000000000000000000000000000000000000000900463ffffffff16806306661abd1460585780634f2be91f146080578063d826f88f146094575b600080fd5b348015606357600080fd5b50606a60a8565b6040518082815260200191505060405180910390f35b348015608b57600080fd5b50609260ae565b005b348015609f57600080fd5b5060a660c0565b005b60005481565b60016000808282540192505081905550565b600080819055505600a165627a7a72305820faa1d1f51d7b5ca2b200e0f6cdef4f2d7e44ee686209e300beb1146f40d32dee0029
0xf18153579e86b4d81617bf9d3b34e1ca2d0433296927f4b04d5c5219d2d82d46

创建合约的参数是编译合约输出的二进制字节码，注意前面要增加0x前缀。

返回值为这笔创建合约交易的交易哈希。

查看交易回执

cldi> get receipt 0xf18153579e86b4d81617bf9d3b34e1ca2d0433296927f4b04d5c5219d2d82d46
{
  "block_number": 454,
  "contract_addr": "0xa4582f4966bdef3a2839e2f256a714426508ddb7",
  "cumulative_quota_used": "0x0000000000000000000000000000000000000000000000000000000000018ed3",
  "error_msg": "",
  "legacy_cita_block_hash": "0x09b2e445d5b3a5e118bb0aad8d812d237ff24f2aa9e37da75e5c68d43ddcdbba",
  "logs": [],
  "logs_bloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
  "quota_used": "0x0000000000000000000000000000000000000000000000000000000000018ed3",
  "state_root": "0x28913fc520eaf50c72fad929d0f57c94ad487bfd63278a57cb40ef370a7697a0",
  "tx_hash": "0xf18153579e86b4d81617bf9d3b34e1ca2d0433296927f4b04d5c5219d2d82d46",
  "tx_index": 0
}

参数为前一步操作返回的交易哈希。

返回值为该笔交易的执行结果信息，其中contract_addr字段为刚才部署的合约的地址。

得到合约地址后，就可以调用其中的方法。

查询合约状态

查询合约中的count值：

cldi> call 0xa4582f4966bdef3a2839e2f256a714426508ddb7 0x06661abd
0x0000000000000000000000000000000000000000000000000000000000000000

第一个参数为合约地址。

第二个参数为要调用的count()方法的函数签名。

返回值为count的当前值。

发送交易

向合约发送交易，调用add方法改变count的值：

cldi> send 0xa4582f4966bdef3a2839e2f256a714426508ddb7 0x4f2be91f
0x24f0bc60340c49e875a8701e80849725a0a10e1bf47990e8c9cb399e31acea05

第一个参数为合约地址。

第二个参数为要调用的add()方法的函数签名。

等待交易上链之后，再次查询就可以发现合约状态有了变化：

cldi> call 0xa4582f4966bdef3a2839e2f256a714426508ddb7 0x06661abd
0x0000000000000000000000000000000000000000000000000000000000000001

定制

CITA-Cloud本身不是一条链，而是一个区块链定制框架，定位类似于Substrate和Cosmos SDK。

但是Substrate和Cosmos SDK更类似于传统的应用开发框架，比如Java的Spring。框架提供一些现成的功能组件和代码自动生成的功能，目的是简化定制开发工作，但是仍然需要进行代码开发。

而CITA-Cloud沿袭了一直以来的微服务架构，并进一步结合了云原生的思想，更类似于PaaS化的开发框架。用户可以不需要代码开发，通过选择并配置组件来构建一条链；也可以根据自己的特殊需求来定制开发相应的组件，结合已有的其他组件构建一条链。

定制链

CITA-Cloud划分为Controller，Network，Consensus，Storage，Executor，Crypto六个微服务，详情参见架构设计章节。

用户可以从现有的组件（参见组件章节）中，根据自己的场景选择6个组件，每个组件必须对应一个前述的微服务，即可组合成一条链。类似于：

_images/kfc.jpg

具体配置方法，参考部署指南章节配置工具部分。

定制组件

定制有两种方式：

fork现有组件（参见组件章节），对其进行定制化开发。
已有对应某个微服务的功能完善的库，新实现一个组件。

对于后一种情况，参考架构设计章节对应的微服务部分，封装已有的库，实现对应的gRPC接口，然后提供对应的Docker镜像。

RPC

CITA-Cloud为用户提供功能丰富的RPC接口，并在不断更新完善中。这些RPC接口主要分为两部分，分别由Controller和Executor提供，Controller主要提供区块链信息数据查询、发送交易、添加节点相关接口，Executor主要提供合约、账户、交易执行相关接口。

示例中使用grpcurl调用这些接口，bytes类型的参数需要传入base64编码后的值，返回结果中的bytes类型也是base64编码后的值。

Controller RPC

GetBlockNumber

查询当前区块高度

接口

rpc GetBlockNumber(Flag) returns (BlockNumber);
参数

bool flag: true表示获取Pending状态的块高；false表示获取latest状态的块高
示例

$ grpcurl -emit-defaults -plaintext -d '{"flag": "false"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetBlockNumber
{
  "blockNumber": "1632"
}

GetNodeStatus

查询当前节点状态

接口

rpc GetNodeStatus(common.Empty) returns (common.NodeStatus);
参数

无
示例

$ grpcurl -emit-defaults -plaintext -d '' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetNodeStatus
{
  "isDanger": false,
  "isSync": false,
  "version": "6.6.3",
  "selfStatus": {
    "height": "72",
    "address": "mOhkarWP6rvHflW7WTotEq+jRYM=",
    "nodeNetInfo": null
  },
  "peersCount": "3",
  "peersStatus": [
    {
      "height": "72",
      "address": "OHQt7esHjdYaN++ada8HozVrRq4=",
      "nodeNetInfo": {
        "multiAddress": "/dns4/127.0.0.1/tcp/40002/tls/test-chain-2",
        "origin": "4067926863296040406"
      }
    },
    {
      "height": "72",
      "address": "4t8sZtTXWW171+g/ww+UG4EdWZM=",
      "nodeNetInfo": {
        "multiAddress": "/dns4/127.0.0.1/tcp/40001/tls/test-chain-1",
        "origin": "16347833992547359085"
      }
    },
    {
      "height": "72",
      "address": "+Nh2xYHoOKtJQfCcYj1d+9pUVWs=",
      "nodeNetInfo": {
        "multiAddress": "/dns4/127.0.0.1/tcp/40003/tls/test-chain-3",
        "origin": "17931212507035744427"
      }
    }
  ]
}

GetSystemConfig / GetSystemConfigByNumber

查询当前系统配置/查询指定高度的系统配置

接口

rpc GetSystemConfig(common.Empty) returns (SystemConfig) / rpc GetSystemConfigByNumber(BlockNumber) returns (SystemConfig);
参数

无 / uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "100"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetSystemConfigByNumber
{
  "version": 0,
  "chainId": "Y1hqPAJV8zfHend/9U8AQLjDiNoE8j7O5r/UlTplErQ=",
  "admin": "eYA2BKam4PwAKR6Lnh7z8grxr1k=",
  "blockInterval": 3,
  "validators": [
    "eYA2BKam4PwAKR6Lnh7z8grxr1k=",
    "6WOv57ByszRv0OzM39kH8JhJQq8=",
    "SnxP0ScLDh7xkW/Ld2ZueTNYMnw=",
    "b0IurgflE6JTuUf/IaIE/k0CF58="
  ],
  "emergencyBrake": false,
  "versionPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "chainIdPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "adminPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "blockIntervalPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "validatorsPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "emergencyBrakePreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "quotaLimit": 1073741824,
  "quotaLimitPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA",
  "blockLimit": 100,
  "blockLimitPreHash": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA"
}

GetBlockByNumber / GetBlockDetailByNumber

查询指定高度的区块。GetBlockByNumber的内容只包括version、header、body（其中是该区块包含的交易哈希），GetBlockDetailByNumber能获取区块的更多信息，包括version、header、body（其中是该区块包含的完整交易）

接口

rpc GetBlockByNumber(BlockNumber) returns (blockchain.CompactBlock); / rpc GetBlockDetailByNumber(BlockNumber) returns (blockchain.Block);
参数

uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "100"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetBlockByNumber
{
  "version": 0,
  "header": {
    "prevhash": "jo2yzstN8kK4yUrzGjwewIILMC8qNaKX2QHsYZJ7n20=",
    "timestamp": "1673418837346",
    "height": "100",
    "transactionsRoot": "GrIdg1XPoX+OYRlIMegajyK+yMco/vt0ftA161CCqis=",
    "proposer": "eYA2BKam4PwAKR6Lnh7z8grxr1k="
  },
  "body": {
    "txHashes": [
      
    ]
  }
}

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "75"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetBlockDetailByNumber
{
  "version": 0,
  "header": {
    "prevhash": "jo2yzstN8kK4yUrzGjwewIILMC8qNaKX2QHsYZJ7n20=",
    "timestamp": "1673418837346",
    "height": "100",
    "transactionsRoot": "GrIdg1XPoX+OYRlIMegajyK+yMco/vt0ftA161CCqis=",
    "proposer": "eYA2BKam4PwAKR6Lnh7z8grxr1k="
  },
  "body": {
    "body": [
      
    ]
  },
  "proof": "",
  "stateRoot": "VugfFxvMVab/g0XmksD4bltI4BuZbK3AAWIvteNjtCE="
}

GetBlockHash

查询指定高度区块的哈希值

接口

rpc GetBlockHash(BlockNumber) returns (common.Hash);
参数

uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "100"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetBlockHash
{
  "hash": "xs6WmcxhL7apHujKixeYw7Yk+B2W3dd9o86OFVavbPQ="
}

GetStateRootByNumber

查询指定高度区块的StateRoot（状态树的根哈希值）

接口

rpc GetStateRootByNumber (BlockNumber) returns (common.StateRoot);
参数

uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "100"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetStateRootByNumber
{
  "stateRoot": "VugfFxvMVab/g0XmksD4bltI4BuZbK3AAWIvteNjtCE="
}

GetProofByNumber

查询指定高度区块的Proof（区块合法证明）

接口

rpc GetProofByNumber (BlockNumber) returns (common.Proof);
参数

uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "10"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetProofByNumber
{
  "proof": "CgAAAAAAAAAAAAAAAAAAAAQAAAABQgAAAAAAAAAweDY4ZWYyMzg3OTVhYTVkNjAxMTRiYTgyMTgyYTI1MTU5MGRhODA4MGE4M2Y1MGRjZTg3NzcxNjNlZTI1YmFmMjMDAAAAAAAAAAoAAAAAAAAAAAAAAAAAAAAEAAAAAUIAAAAAAAAAMHg2OGVmMjM4Nzk1YWE1ZDYwMTE0YmE4MjE4MmEyNTE1OTBkYTgwODBhODNmNTBkY2U4Nzc3MTYzZWUyNWJhZjIzgAAAAAAAAAAPrGoG3fM9XdW+EWKyye0aPDd0d6YQoolm1fkp7yYXYyFFjg//gnDWBrseMP2iSsiP/KCFrCuOTgUWv8hPrkLZbG7UtF7JzUS5ywCrsN55sGwK6MJaeQYWZ67yai/yKPwZM6GTIQZmKHkWUfCVqw/NapocKA5Uum6x1IoDNoP99goAAAAAAAAAAAAAAAAAAAAEAAAAAUIAAAAAAAAAMHg2OGVmMjM4Nzk1YWE1ZDYwMTE0YmE4MjE4MmEyNTE1OTBkYTgwODBhODNmNTBkY2U4Nzc3MTYzZWUyNWJhZjIzgAAAAAAAAAAKTsiHpNgw3lX5sf0Tb8c9SJoLHWUky/0vD6dOg2SwxLN8Ecv6VA1C4vIAjnkKuZz8ObSl3bgFw8PB2js81JfMYEGfyOw5OjD9wOBLbib1HonOXv9hS+u9OIw9/BKNsh95RLKgh7GljqKS7imASytRgNNC/Po6dH3Ld1GWaH3uDAoAAAAAAAAAAAAAAAAAAAAEAAAAAUIAAAAAAAAAMHg2OGVmMjM4Nzk1YWE1ZDYwMTE0YmE4MjE4MmEyNTE1OTBkYTgwODBhODNmNTBkY2U4Nzc3MTYzZWUyNWJhZjIzgAAAAAAAAADY7vMi70yCTq1oYT5e9vJO411Db5rWbpO1C485qo+4tYCtEgwehM2jXPM79TUc9+AxMi0EfY4BDh8vyfieiIVoMcmPN9rePduqGOuh5wKzbsMLpv3fO69MLhpjV257si1b4CGWrge5OhPkAWK3J3DiHWQYLVhAV4scesNpEB5QCQ=="
}

GetHeightByHash

根据区块哈希值查询对应区块的高度

接口

rpc GetHeightByHash(common.Hash) returns (BlockNumber);
参数

bytes hash: 区块哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "xs6WmcxhL7apHujKixeYw7Yk+B2W3dd9o86OFVavbPQ="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetHeightByHash
{
  "blockNumber": "100"
}

GetBlockByHash

根据区块哈希值查询对应的区块

接口

rpc GetBlockByHash(common.Hash) returns (blockchain.CompactBlock);
参数

bytes hash: 区块哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "xs6WmcxhL7apHujKixeYw7Yk+B2W3dd9o86OFVavbPQ="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetBlockByHash
{
  "version": 0,
  "header": {
    "prevhash": "4H/+Gc9wP2oKWpcXhchu2PucnXzxzTH85XJcd/JeXF8=",
    "timestamp": "1673431776734",
    "height": "100",
    "transactionsRoot": "GrIdg1XPoX+OYRlIMegajyK+yMco/vt0ftA161CCqis=",
    "proposer": "mOhkarWP6rvHflW7WTotEq+jRYM="
  },
  "body": {
    "txHashes": [
      
    ]
  }
}

SendRawTransaction / SendRawTransactions

发送交易，RawTransaction有两种类型：普通交易UnverifiedTransaction normal_tx和治理交易UnverifiedUtxoTransaction utxo_tx，发送的交易除了交易体还包含了bytes transaction_hash和Witness witness，witness中又包含signature，transaction_hash和signature都是需要计算的，因此使用grpcurl调用此接口会比较麻烦，建议使用相关工具（如cldi）发送交易。

接口

rpc SendRawTransaction(blockchain.RawTransaction) returns (common.Hash);

参数

oneof tx {
      UnverifiedTransaction normal_tx = 1;
      UnverifiedUtxoTransaction utxo_tx = 2;
  }

oneof类型表示normal_tx和utxo_tx字段只能有一个有值。 RawTransaction详见cita_cloud_proto。

示例

$ grpcurl -emit-defaults -plaintext -d '{"normal_tx": {"transaction": { "version": 0, "to": "a2WNQSBYfQH91o2+oFKuwqHBPew=", "nonce": "6797892813804568799", "quota": "200000", "validUntilBlock": "169", "data": "BmYavQ==", "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=", "chainId": "Y1hqPAJV8zfHend/9U8AQLjDiNoE8j7O5r/UlTplErQ=" }, "transactionHash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw=", "witness": { "signature": "qG8g7+F2BxJt9QKggM/hMOwMNDmM9995kjV3UrtxY4mi4rJZV6s8t9cNgTL0LGzE7gsFqntwnv38uIYcdY3ZyPambVwKOl9K85PjwALji59M9LORT4W6A51eybh1Ag+khGDkf5wnEr71kYvFdH8ROIx/YYtys+k6PjV3vvczLfs=", "sender": "a2WNQSBYfQH91o2+oFKuwqHBPew=" }}}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/SendRawTransaction
{
  "hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="
}

GetTransaction

根据交易哈希值查询对应的交易

接口

rpc GetTransaction(common.Hash) returns (blockchain.RawTransaction);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetTransaction
{
  "normalTx": {
    "transaction": {
      "version": 0,
      "to": "a2WNQSBYfQH91o2+oFKuwqHBPew=",
      "nonce": "6797892813804568799",
      "quota": "200000",
      "validUntilBlock": "169",
      "data": "BmYavQ==",
      "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA=",
      "chainId": "Y1hqPAJV8zfHend/9U8AQLjDiNoE8j7O5r/UlTplErQ="
    },
    "transactionHash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw=",
    "witness": {
      "signature": "qG8g7+F2BxJt9QKggM/hMOwMNDmM9995kjV3UrtxY4mi4rJZV6s8t9cNgTL0LGzE7gsFqntwnv38uIYcdY3ZyPambVwKOl9K85PjwALji59M9LORT4W6A51eybh1Ag+khGDkf5wnEr71kYvFdH8ROIx/YYtys+k6PjV3vvczLfs=",
      "sender": "a2WNQSBYfQH91o2+oFKuwqHBPew="
    }
  }
}

GetTransactionBlockNumber

根据交易哈希值查询对应交易所在的块高

接口

rpc GetTransactionBlockNumber(common.Hash) returns (BlockNumber);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetTransactionBlockNumber
{
  "blockNumber": "107"
}

GetTransactionIndex

根据交易哈希值查询对应交易在所在区块中的序号

接口

rpc GetTransactionIndex(common.Hash) returns (TransactionIndex);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetTransactionIndex
{
  "txIndex": "0"
}

AddNode

添加节点

接口

rpc AddNode(common.NodeNetInfo) returns (common.StatusCode);
参数
```
message NodeNetInfo {
  string multi_address = 1;
  uint64 origin = 2;
}
```
multi_address是添加节点的网络地址信息，origin是节点地址的前8个字节转换为64位无符号整型的结果
示例

$ grpcurl -emit-defaults -plaintext -d '{ "multiAddress": "/dns4/127.0.0.1/tcp/40001/tls/test-chain-1", "origin": "16347833992547359085" }' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/AddNode
{
  "code": 0
}

GetCrossChainProof

获取跨链证明

接口

rpc GetCrossChainProof(common.Hash) returns (CrossChainProof);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/controller.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50004 controller.RPCService/GetCrossChainProof
{
  "version": 0,
  "chainId": "Y1hqPAJV8zfHend/9U8AQLjDiNoE8j7O5r/UlTplErQ=",
  "proposal": {
    "preStateRoot": "z7OLj3I0Wge52dht/Wehgj6L4hbArs+GY9/QsHi8rZI=",
    "proposal": {
      "version": 0,
      "header": {
        "prevhash": "YLJ/O9MiaUoRVB5j1V+4fMgyTvn0MCIWqmB4JiUoGIc=",
        "timestamp": "1687334197360",
        "height": "50",
        "transactionsRoot": "O1JV/1UTJGnyxPrnRbHxx5YajCBlizbCBLwDN9LOOak=",
        "proposer": "x+nzQBPukPmVH7VqMNFqh+F03Cg="
      },
      "body": {
        "txHashes": [
          "do38caZae78ZfQqz0IDHdbG8oeIxrFRylRv3+svh9eg="
        ]
      }
    }
  },
  "receiptProof": {
    "receipt": "+QEqglIIuQEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMDAgKB2jfxxplp7vxl9CrPQgMd1sbyh4jGsVHKVG/f6y+H16A==",
    "receiptProof": "wA==",
    "rootsInfo": {
      "height": "50",
      "stateRoot": "bXg4C9xF4cXv2V8a9YwPgq0WjCdytJkkTFqbuZg6toI=",
      "receiptRoot": "tO1g3jO9tjU/XimtDqtgodzV3V3b2DWpfmumE8m1kI4="
    }
  },
  "proof": "",
  "stateRoot": "2ZVY1e/4V/DQh3a3+ydvI3HDUXqpbKyNMjE9qlGPJgw="
}

Executor RPC

GetTransactionReceipt

根据交易哈希值查询对应交易的收据（执行信息）

接口

rpc GetTransactionReceipt(common.Hash) returns (Receipt);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetTransactionReceipt
{
  "transactionHash": "2+3XKgIA+DFzKULl23LTC6JjBXFjShffE5gznUWbSrw=",
  "transactionIndex": "0",
  "blockHash": "GNtzrxx6h+K0SojFLrd8BsdhQiHCbgNdT4jvr0iKj0A=",
  "blockNumber": "107",
  "cumulativeQuotaUsed": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAUgg=",
  "quotaUsed": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAUgg=",
  "contractAddress": "AAAAAAAAAAAAAAAAAAAAAAAAAAA=",
  "logs": [
    
  ],
  "stateRoot": "bXg4C9xF4cXv2V8a9YwPgq0WjCdytJkkTFqbuZg6toI=",
  "logsBloom": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA==",
  "errorMessage": ""
}

GetBalance

查询账户地址余额

接口

rpc GetBalance(common.Address) returns (Balance);
参数

bytes address: 账户地址
示例

$ grpcurl -emit-defaults -plaintext -d '{"address": "a2WNQSBYfQH91o2+oFKuwqHBPew="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetBalance
{
  "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAA="
}

GetTransactionCount

查询账户地址发送的交易数量

接口

rpc GetTransactionCount(common.Address) returns (Nonce);
参数

bytes address: 账户地址
示例

$ grpcurl -emit-defaults -plaintext -d '{"address": "a2WNQSBYfQH91o2+oFKuwqHBPew="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetTransactionCount
{
  "nonce": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE="
}

GetCode

根据合约地址查询对应合约的字节码

接口

rpc GetCode(common.Address) returns (ByteCode);
参数

bytes address: 合约地址
示例

$ grpcurl -emit-defaults -plaintext -d '{"address": "Req3cucyj4Vkugo9aVQW1VLDpfM="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetCode
{
  "byteCode": "YIBgQFJgBDYQYFNXYAA1fAEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAkARj/////xaAYwZmGr0UYFhXgGNPK+kfFGCAV4Bj2Cb4jxRglFdbYACA/Vs0gBVgY1dgAID9W1BgamCoVltgQFGAgoFSYCABkVBQYEBRgJEDkPNbNIAVYItXYACA/VtQYJJgrlZbAFs0gBVgn1dgAID9W1BgpmDAVlsAW2AAVIFWW2ABYACAgoJUAZJQUIGQVVBWW2AAgIGQVVBWAKFlYnp6cjBYIPqh0fUde1yisgDg9s3vTy1+RO5oYgnjAL6xFG9A0y3uACk="
}

GetAbi

根据合约地址查询保存的合约Abi。在此操作之前需要发送一个特殊交易保存合约地址对应的Abi。

接口

rpc GetAbi(common.Address) returns (ByteAbi);
参数

bytes address: 合约地址
示例

$ grpcurl -emit-defaults -plaintext -d '{"address": "Req3cucyj4Vkugo9aVQW1VLDpfM="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetAbi
{
  "bytesAbi": "WwoJewoJCWNvbnN0YW50OiB0cnVlLAoJCWlucHV0czogW10sCgkJbmFtZTogY291bnQsCgkJb3V0cHV0czogWwoJCQl7CgkJCQluYW1lOiAsCgkJCQl0eXBlOiB1aW50MjU2CgkJCX0KCQldLAoJCXBheWFibGU6IGZhbHNlLAoJCXN0YXRlTXV0YWJpbGl0eTogdmlldywKCQl0eXBlOiBmdW5jdGlvbgoJfSwKCXsKCQljb25zdGFudDogZmFsc2UsCgkJaW5wdXRzOiBbXSwKCQluYW1lOiBhZGQsCgkJb3V0cHV0czogW10sCgkJcGF5YWJsZTogZmFsc2UsCgkJc3RhdGVNdXRhYmlsaXR5OiBub25wYXlhYmxlLAoJCXR5cGU6IGZ1bmN0aW9uCgl9LAoJewoJCWNvbnN0YW50OiBmYWxzZSwKCQlpbnB1dHM6IFtdLAoJCW5hbWU6IHJlc2V0LAoJCW91dHB1dHM6IFtdLAoJCXBheWFibGU6IGZhbHNlLAoJCXN0YXRlTXV0YWJpbGl0eTogbm9ucGF5YWJsZSwKCQl0eXBlOiBmdW5jdGlvbgoJfQpd"
}

EstimateQuota

估算执行交易需要消耗的quota

接口

rpc EstimateQuota(executor.CallRequest) returns (ByteQuota);
参数
```
message CallRequest {
  bytes to = 1;
  bytes from = 2;
  bytes method = 3;
  repeated bytes args = 4;
  uint64 height = 5;
}
```
EstimateQuota接口实际上只需要to、from和method三个参数，其他参数用默认值即可，不影响计算。from是交易发送者的地址，用户调用该接口时可以随意指定，交易发送者会影响交易的执行过程。如果是调用合约交易，则需要则to是合约地址，method是要调用的合约方法；如果是创建合约交易，则to是20字节的0，method是合约字节码。
示例

$ grpcurl -emit-defaults -plaintext -d '{"to": "Req3cucyj4Vkugo9aVQW1VLDpfM=", "from": "a2WNQSBYfQH91o2+oFKuwqHBPew=", "method": "TyvpHw=="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/EstimateQuota
{
  "bytesQuota": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAoRY="
}

GetReceiptProof

获取交易的ReceiptProof

接口

rpc GetReceiptProof(common.Hash) returns (ReceiptProof);
参数

bytes hash: 交易哈希值
示例

$ grpcurl -emit-defaults -plaintext -d '{"hash": "do38caZae78ZfQqz0IDHdbG8oeIxrFRylRv3+svh9eg="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetReceiptProof
{
  "receipt": "+QEqglIIuQEAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAMDAgKB2jfxxplp7vxl9CrPQgMd1sbyh4jGsVHKVG/f6y+H16A==",
  "receiptProof": "wA==",
  "rootsInfo": {
    "height": "50",
    "stateRoot": "bXg4C9xF4cXv2V8a9YwPgq0WjCdytJkkTFqbuZg6toI=",
    "receiptRoot": "tO1g3jO9tjU/XimtDqtgodzV3V3b2DWpfmumE8m1kI4="
  }
}

GetRootsInfo

获取指定高度的RootsInfo

接口

rpc GetRootsInfo(BlockNumber) returns (RootsInfo);
参数

uint64 block_number: 指定高度
示例

$ grpcurl -emit-defaults -plaintext -d '{"block_number": "50"}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/vm/evm.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 evm.RPCService/GetRootsInfo
{
  "height": "50",
  "stateRoot": "bXg4C9xF4cXv2V8a9YwPgq0WjCdytJkkTFqbuZg6toI=",
  "receiptRoot": "tO1g3jO9tjU/XimtDqtgodzV3V3b2DWpfmumE8m1kI4="
}

Call

查询链上数据

接口

rpc Call(CallRequest) returns (CallResponse);
参数
```
message CallRequest {
  bytes to = 1;
  bytes from = 2;
  bytes method = 3;
  repeated bytes args = 4;
  uint64 height = 5;
}
```
to是合约地址；from是交易发送者的地址，用户调用该接口时可以随意指定；method是要查询的数据；通过height查询该数据在指定高度的值，0(默认值)代表当前高度。
示例

$ grpcurl -emit-defaults -plaintext -d '{"to": "13TPTHVrw0WmEi/XdSVt5Wa4S4E=", "from": "a2WNQSBYfQH91o2+oFKuwqHBPew=", "method": "BmYavQ=="}' \
-proto ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos/executor.proto \
-import-path ~/cita-cloud/cloud-common-rs/cloud-proto/protos/protos \
127.0.0.1:50002 executor.ExecutorService/Call
{
  "value": "AAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAE="
}

路线图

2020.4 项目启动
2020.8 白皮书发布
2020.10 首个版本发布
2021.7 v6.0.0发布，协议稳定，将作为长期支持大版本
2022.3 引入Rollup方案。

版本发布

历史版本

6.6.5

主要更新内容如下：

底链微服务

新增storage_opendal微服务
- 对接多种存储后端
- 冷热数据分层管理
新增executor_noop微服务
- 适用只存证 layer 1
controller_crdt调研
- crdt_macro
consensus_raft
- fix: get term error & fix: cover conflict entry
- recommit entry && transfer leader timeout depend on block interval
controller
- optimize get_proposal
- optimize finalize_block
- optimize log
cloud-config
- 结合kustomize
cldi
- 在node status里增加init block number
其他
- 修复共识与controller高度不一致的问题
- Jaeger 使用远程采样配置
- panic hook修复
- 优化日志

云原生

cita-node-operator 同步上游

集成测试

统计同步时间
添加namespace环境变量

Controller

[Feature]

[feat] add init height in node status @rink1969

[Fix]

[fix] fix skip reenter error when checking executor @JLerxky

[fix] fix update sc @JLerxky

[Optim]

[optim] optim: skip and log ReenterBlock @JLerxky

[optim] update auth and pool after block is persisted @JLerxky

[optim] optim: log @Jayanring

[optim] move update systemconfig after exec block; ignore update if empty blo… @rink1969

[optim] update auth even empty block @rink1969

[optim] optimize get_proposal @rink1969

[Chore]

[chore] update keepalive config @rink1969

[chore] replace panic hook @Jayanring

[chore] chore: debug print error @Jayanring

network_zenoh

[Chore]

[chore] replace panic hook @Jayanring]

consensus_overlord

[Chore]

[chore] replace panic hook @Jayanring

[chore] chore: debug print error @Jayanring

consensus_raft

[Feature]

[feat] recommit entry && transfer leader timeout depend on block interval @Jayanring

[Fix]

[fix] fix: get term error & fix: cover conflict entry @Jayanring

[fix] replace panic hook @Jayanring

[fix] chore: debug print error @Jayanring

executor_evm

[Chore]

[chore] replace panic hook @Jayanring

crypto_eth

[Chore]

[chore] replace panic hook with common-rs @rink1969

[chore] get inner err info @rink1969

crypto_sm

[Chore]

[chore] replace panic hook with common-rs @rink1969

storage_rocksdb

[Optim]

[optim] optim: not store global hash @Jayanring

[Chore]

[chore] replace panic hook @Jayanring

[chore] chore: debug print error @Jayanring

cita_cloud_proto

[Feature]

[feat] add init height in node status @rink1969

cloud-common-rs

[Feature]

[feat] add jaeger sampler @Jayanring

[feat] add init height in node status @rink1969

[feat] add panic hook @rink1969

[Fix]

[fix] fix: get local offset @Jayanring

[Optim]

[optim] optim wal clear_file @JLerxky

cloud-config

[Feature]

[feat] gen kustomization @rink1969

[Fix]

[fix] fix debug @rink1969

[Chore]

[chore] remove /etc/timezone @rink1969

cloud-cli

[Feature]

[feat] add init height in node status @rink1969

v6.6.4

主要更新内容如下：

底链微服务

bft微服务
- 废弃该共识
raft微服务
- 修复consensus重启后raft会卡住的问题
controller微服务
- 添加danger模式
- commit block耗时长的问题（wal的IO操作引起的）
- check_proposal添加检查
- get_node_status优化，整合network信息
network微服务
- 升级依赖的zenoh库
- 修复network zid panic的问题
cloud-config
- 增加关闭健康检查的选项
- 为链节点微服务添加work node时区映射
cache组件
- 输出性能测试报告
cldi
- 修复release问题
console/provider组件
- console组件与rivspace联调中
- provider组件开发中
其他
- 优化微服务输出的日志，让定位问题更加方便
- 更新微服务镜像中的grpc-health-check至最新版本
- 修复u64::from_be_bytes函数调用相关问题
- 修复微服务帮助信息没有version的问题
- 集成测试混沌测试用例加强

云原生

cita-node-operator支持新的备份恢复CRD(Duplicate和Recover)
cita-node-operator与开源版operator相关问题修复与联调

SLA测试

正在迁移SLA环境

Controller

[Feature]

[feat] add danger mode for bft to overlord @rink1969

[feat] add is_danger in node_status@rink1969

[feat] tracing @JLerxky

[Fix]

[fix] Validator address @Jayanring

[fix] proposal missing pre_proof @Jayanring

[fix] update health probe binary @ rink1969

[fix] check timestamp @ rink1969

[fix] clap help info @Jayanring

[Optim]

[optim] process_network_msg log print @Jayanring

[optim] Async wal @JLerxky

[optim] check_proposal @Jayanring

[Chore]

[chore] check_proposal add warn @JLerxky

network_zenoh

[Feature]

[feat] use tracing @JLerxky

[Fix]

[fix] domain convert to zenoh_id inconsistent @JLerxky

[fix] reconnect if disconnected @JLerxky

[fix] set unicast max_links 4 @JLerxky

[fix] clap help info @JLerxky

[Optim]

[optim] health_check_msg and zenoh_id @JLerxky

[Chore]

[chore] Upgrade dependencies @JLerxky

[chore] update zenoh @JLerxky

[chore] update Dockerfile @rink1969

consensus_raft

[Fix]

[fix] upgrade grpc probe @rink1969

[fix] clap help info @rink1969

executor_evm

[Refactor]

[refactor] use tracing @rink1969

[Fix]

[fix] tracer init @JLerxky

[fix] upgrade grpc probe @rink1969

[fix] clap help info @Jayanring

crypto_eth

[Feat]

[feat] trace @Jayanring

[Fix]

[fix] upgrade grpc probe @rink1969

[fix] clap help info @Jayanring

crypto_sm

[Fix]

[fix] Tracing @Jayanring

[fix] upgrade grpc probe @rink1969

[fix] clap help info @Jayanring

[Chore]

[chore] update deps @Jayanring

storage_rocksdb

[Feature]

[feat] trace @Jayanring

[Fix]

[fix] upgrade grpc probe @rink1969

[fix] clap help info @Jayanring

cita_cloud_proto

[Feature]

[feat] add is_danger in node status @rink1969

cloud-common-rs

[Feature]

[feat] Async wal @JLerxky

[feat] Tracer @JLerxky

[Refactor]

[refactor] metrics @Jayanring

cloud-config

[Fix]

[fix] Host aliases @JLerxky

[fix] search @JLerxky

[fix] add disable-metrics in env-dev and env-k8s @Jayanring

[Feature]

[feat] tracing @JLerxky

[feat] Add is danger @rink1969

[Chore]

[chore] rm node-log @JLerxky

[chore] mnt timezone file @Jayanring

cloud-cli

[Optim]

[optim] node_status @Jayanring

[Feature]

[feat] add lib @JLerxky

[Chore]

[chore] remove bft @Jayanring

兼容性

与上一个版本数据兼容。
因为网络微服务实现升级，不能与上个版本混用。

已知问题

无

v6.6.3

主要更新内容如下：

底链微服务

controller微服务
- GetNodeStatus接口替换GetVersion/GetPeerCount/GetPeersInfo接口
raft微服务
- raft节点switch over后共识panic问题修复
network微服务
- network 添加 connected info
cldi
- cldi命令超时问题修复
- cldi admin update-validators help命令添加
- cldi bench send问题修复
cloud-config
- 修复import-account没有生成node_address
公共服务
- 拆分cita_cloud_proto为proto文件和rust代码
- rust代码部分与cloud-util，cloud-code合并到一个仓库（cloud-common-rs）
- status-code添加至proto文件中

云原生

支持轻量化部署
cita-node-operator节点任务串行化
cita-node-operator支持对象存储备份与恢复

SLA测试

sla运维操作脚本

其他

缓存与cldi压力测试对比
缓存文档添加

Controller

[Feature]

[feat] get node status @Jayanring

[Chore]

[chore] use common @JLerxky

network_zenoh

[Feature]

[feat] connected info and update origin by CHECK msg @JLerxky

[Chore]

[chore] Use common @JLerxky

consensus_bft

[Chore]

[chore] use common @JLerxky

consensus_raft

[Chore]

[chore] use common @JLerxky

executor_evm

[Chore]

[chore] use common @JLerxky

crypto_eth

[Chore]

[chore] use common @JLerxky

crypto_sm

[Chore]

[chore] use common @JLerxky

storage_rocksdb

[Chore]

[chore] use common @JLerxky

cita_cloud_proto

[Feature]

[feat] get node status @Jayanring

[Chore]

[chore] Simplified @JLerxky

cloud-common-rs

[Optimize]

[optim] metrics parse request info @Jayanring

cloud-config

[Optimize]

[optim] import-account store node_address@Jayanring

cloud-cli

[Feature]

[feat] get node status@Jayanring

[feat] rpc request timeout@Jayanring

[Chore]

[chore] use cloud-common-rs@Jayanring

[Fix]

[fix] add Timeout @rink1969[fix] fix bench send error@NaughtyDogOfSchrodinger

兼容性

与上一个版本数据兼容。
可以与上个版本混用。

已知问题

cloud-config执行import-account命令导入账户，会缺少node_address，导致后续操作失败。影响范围：v6.3.0 - v6.6.2。
cloud-cli执行bench send命令进行性能压测时，如果发送交易时间超过100个区块的时间（默认情况下为5分钟），会导致发送交易失败。影响范围：v0.5.2之前的版本。

如果以上问题影响了正常使用，请尽快升级到最新版本。

v6.6.2

主要更新内容如下：

network_zenoh升级上游zenoh版本。
network_zenoh在健康检查时增加打印消息时延信息。
重构raft日志模块。
定位raft删除单个节点日志后panic的问题。
cloud-op增加消块时是否删除共识日志的开关。
cldi文档增加升级报错的说明。
executor_evm增加估算quota的接口。
cldi增加估算quota的子命令。
增加可靠性测试。
集成测试增加运维操作相关的用例。
优化集成测试的日志输出。
修复operator备份和快照操作中的问题。
实验性增加缓存中间件。

Controller

[Feature]

[feat] update deps @rink1969

[Fix]

[fix] fix wal load @rink1969

Network_zenoh

[Feature]

[feat] update_zenoh @JLerxky

[feat] print_latency @JLerxky

[feat] update_deps @rink1969

Consensus_bft

[Feature]

[feat] update_deps @rink1969

Consensus_overload

[Feature]

[feat] update_deps @rink1969

[Chore]

[chore] fix_check_block @rink1969

Consensus_raft

[Feature]

[feat] refactor storage @Jayanring

[feat] update deps @rink1969

Executor_evm

[Feature]

[feat] expose estimate-quota @Jayanring

[feat] update_deps @rink1969

Crypto_eth

[Feature]

[feat] update_deps @rink1969

Crypto_sm

[Feature]

[feat] update_deps @rink1969

Storage_rocksdb

[Feature]

[feat] update_deps @rink1969

Cita_cloud_proto

[Feature]

[feat] update deps @rink1969

[feat] estimate-quota @Jayanring

Cloud-util

[Feature]

[feat] update deps @rink1969

Cloud-config

[Feature]

[feat] update deps @rink1969

Cloud-cli

[Feature]

[feat] add_trouble_shooting @rink1969

[feat] update_deps @rink1969

[feat] add-estimate-quota @Jayanring

Cloud-op

[Feature]

[feat] add clear consensus data option @Jayanring

[feat] state recover add reserve consensus option @Jayanring

[feat] update_deps @rink1969

[Fix]

[fix] fix-lockid @Jayanring

Integration-test

[Feature]

[feat] add operator test @acechef

Cita-node-operator

[Fix]

[fix] fix backup @acechef

兼容性

与上一个版本数据兼容。
不能与上个版本混用。因为网络微服务升级，新老版本之间网络不通。

已知问题

cloud-op消块后没有配套回退system config中的quota_limite。导致消块后重新同步时，如果遇到修改quota_limit的交易，将会无法同步。影响范围：v6.5.0 - v6.6.1
选择consensus_overlord的链重启后重新执行wal中记录的区块时，可能会报错，导致节点无法继续出块。影响范围：共识为overlord的链。

请使用以上版本的链尽快升级到最新版本。

v6.6.1

主要更新内容如下：

添加grpc metrics功能，能够实时统计Cita-Cloud运行时各微服务间调用的次数、耗时等数据，并在cloud-config中添加开关
优雅退出
将镜像仓库从docker hub迁移到harbor
集成测试改进
- 添加nft性能测试
- 添加同步节点升级为共识节点测试
- 添加raft共识节点更改测试
支持获取指定高度system-config
cldi添加解析proof功能
修复consensus_raft更改validators异常
- 修复移除leader后异常
- 支持增删多节点
- 支持一次性更换一批节点
反亲和性
修复共识微服务单独重启问题
守护节点

Controller

[Feature]

[feat] add metrics @Jayanring

[feat] feat: handle sigterm @JLerxky

[feat] get block add stateroot proof @Jayanring

[feat] get system-config by block-number @Jayanring

[Fix]

[fix] fix match_data panic when init @Jayanring

[Optimize]

[optim] optim: controller server single restart @Pencil-Yao

[optim] optim: misbehave handling logical @Pencil-Yao

[optim] optim: server not ready info print @Pencil-Yao

[optim] deny change of chain_id and block_limit @Jayanring

[Chore]

[chore] fix: change image registry @acechef

[chore] read node_address from file @Jayanring

[chore] fix clippy @Jayanring

Network_zenoh

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[feat] feat: send health check msg @JLerxky

[Chore]

[chore] fix: change image registry @acechef

[chore] read node_address from file @Jayanring

Consensus_bft

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Optimize]

[optim] optim: consensus-server single restart @Pencil-Yao

[optim] optim: use timeout replace interval @Pencil-Yao

[Chore]

[chore] fix: change image registry @acechef

[chore] expose LeaderVote @Jayanring

[chore] read node_address from file @Jayanring

Consensus_overload

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Optimize]

[optim] optim: consensus-server single restart @Pencil-Yao

[Chore]

[chore] fix: change image registry @acechef

[chore] remove unused config items @rink1969

Consensus_raft

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[feat] feat: support replacing all validators at one time @Jayanring

[Fix]

[fix] fix consensus stop when remove leader @Jayanring

[Optimize]

[optim] optim: consensus-server single restart @Pencil-Yao

[Chore]

[chore] fix: change image registry @acechef

[chore] read node_address from file @Jayanring

Executor_evm

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Fix]

[fix] fix: receipt legacy block hash @Pencil-Yao

[fix] fix: docker image build @Pencil-Yao

[fix] fix: quota_uesd is 0 @Pencil-Yao

[Chore]

[chore] fix: change image registry @acechef

[chore] CloudBlock add stateroot @Jayanring

Crypto_eth

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Chore]

[chore] fix: change image registry @acechef

Crypto_sm

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Chore]

[chore] fix: change image registry @acechef

Storage_rocksdb

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Chore]

[chore] fix: change image registry @acechef

[chore] get block add state_root proof @Jayanring

Cita_cloud_proto

[Feature]

[feat] get system-config by number @Jayanring

[feat] get block add stateroot proof @Jayanring

Cloud-util

[Feature]

[feat] add metrics @Jayanring

[feat] feat: add handle_signals @JLerxky

[Fix]

[fix] fix metrics AlreadyReg @Jayanring

[fix] fix duplicate register when restart @Jayanring

[Chore]

[chore] use regex @Jayanring

[chore] chore: modify exporter log info @Jayanring

Cloud-config

[Feature]

[feat] –init-node add –disable-metrics option @Jayanring

[feat] set pod_anti_affinity @rink1969

[Fix]

[fix] fix env_k8s metrics port @Jayanring

[fix] fix crypto log config file @rink1969

[fix] fix create-dev node_address path @Jayanring

[fix] add mount account cm @rink1969

[fix] fix: Permission denied @k4nzdroid

[Chore]

[chore] fix: change image registry @acechef

[chore] add common name @rink1969

[chore] use addr in account configmap @rink1969

Integration-test

[Feature]

[feat] add nft performance test @rink1969

[feat] set sync node to validator @JLerxky

[feat] add only one validator test to raft @JLerxky

[Fix]

[fix] fix remove last validator @JLerxky

[fix] fix pip install PyYaml @JLerxky

[fix] fix pyyaml load @JLerxky

[fix] fix: use validator_address @JLerxky

[fix] fix: use exec_bad when expect a bad result @JLerxky

[fix] fix watch sync node @JLerxky

[fix] fix: add kubectl timeout @acechef

[fix] fix get system-config not up to date @JLerxky

[Optimize]

[optim] update update-validators @JLerxky

[optim] optim: use retry exec @JLerxky

[optim] check quota used @JLerxky

[optim] change log level @NaughtyDogOfSchrodinger

[Chore]

[chore] fix: change image registry @acechef

[chore] use harbor image @JLerxky

[chore] fix: modify update_chain_config.sh @acechef

[chore] keep same args with nft bench @rink1969

[chore] remove set-block-limit.py @JLerxky

[chore] fix: update Dockerfile @acechef

[chore] update height_bad_result @JLerxky

[chore] update chain config @JLerxky

[chore] sort script @JLerxky

[chore] print bad receipt @JLerxky

[chore] update yaml @JLerxky

Cloud_cli

[Feature]

[feat] get system config by height @Jayanring

[feat] get block add state_root proof @Jayanring

[feat] parse proof @Jayanring

[Fix]

[fix] fix: build image error @acechef

[Optimize]

[optim] identify validators @Jayanring

[optim] remove admin set-block-kimit @Jayanring

[optim] optim watch @JLerxky

[optim] add get_compact_block_by_number @JLerxky

[Chore]

[chore] add non root user @miaojun

[chore] fix: change image registry @acechef

v6.6.0

主要更新内容如下：

将network_tls微服务废弃，启用network_zenoh微服务
consensus_overlord微服务完善

bft升级overlord

controller微服务

优化同步过程
调整proof not influence proposal_hash
批量广播交易、优化tps
适配network_zenoh

grpc封装高层client

实现retry功能、增加keepalive设置

call支持指定块高
健康检查

network检查一定时间内是否有已连接的节点

依赖库升级

tonic升级到0.7、prost升级到0.10
其它依赖升到当前最新版本

Controller

[Feature]

[feat] set tcp and http2 keep alive @rink1969

[hard-fork!] feat: proof not influence proposal_hash @Pencil-Yao

[Fix]

[fix] optim: set false sync state when height not grow @Pencil-Yao

[fix] fix check proposal failed @rink1969

[fix] optim: set true sync state when send sync req @Pencil-Yao

[fix] mv quota limit form controller config to system config @rink1969

[Refactor]

[refactor] switch to retryclient @Jayanring

[refactor] change origin @JLerxky

[Chore]

[chore] chore: broadcast increased status @Pencil-Yao

[chore] change multicast to broadcast @JLerxky

[chore] add healthcheck info @ rink1969

[chore] optim: tps! @Pencil-Yao

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Network_zenoh

[new] Release v6.6.0

Consensus_bft

[Fix]

[fix] fix check proposal failed @rink1969

[fix] fix wrong lock round @rink1969

[fix] optim: add NewViewRes to optimize newview step @Pencil-Yao

[fix] fix: leader not send newview @Pencil-Yao

[Refactor]

[refactor] switch to retryclient @Jayanring

[Chore]

[chore] chore: optim newview process @Pencil-Yao

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Consensus_overload

[new] Release v6.6.0

Consensus_raft

[Refactor]

[refactor] refactor: handle internal error @NaughtyDogOfSchrodinger

[refactor] switch to retryclient @Jayanring

[Chore]

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Executor_evm

[Feature]

[feat] add height in call request @NaughtyDogOfSchrodinger

[Chore]

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Crypto_eth

[Refactor]

[refactor] update tonic and prost @Jayanring

Crypto_sm

[Refactor]

[refactor] update tonic and prost @Jayanring

Storage_rocksdb

[Feature]

[feat] switch to retryclient @Jayanring

[Chore]

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Network_tls[Archived]

Cita_cloud_proto

[Feature]

[feat] add height in CallRequest @NaughtyDogOfSchrodinger

[Refactor]

[refactor] add client retry @rink1969

[refactor] add retry for NetworkMsgHandlerServiceClient @rink1969

[refactor] connect lazy @rink1969

[refactor] add evm client @rink1969

[Chore]

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Cloud-util

[Refactor]

[refactor] switch to retryclient @Jayanring

[Chore]

[chore] chore: upgrade tonic and prost @NaughtyDogOfSchrodinger

Cloud-cli

[Refactor]

[refactor] refactor: adapt for call with height @NaughtyDogOfSchrodinger

[refactor] remove p2p tls related code @Jayanring

[refactor] display timestamp when get block @Jayanring

[refactor] ignore empty net-info when getting peers-info @JLerxky

[Chore]

[chore] chore: upgrae tonic and prost @NaughtyDogOfSchrodinger

[Fix]

[fix] fix: watch_cmd is pending in bench send @JLerxky

[fix] fix send default quota @Jayanring

Cloud-config

[Fix]

[fix] fix default quota limit in init-node @rink1969

[Refactor]

[refactor] support network_zenoh @JLerxky

[refactor] change svc clusterip; rename yamls @rink1969

[refactor] mv quota limit from node config to chain config @rink1969

[Chore]

[chore] env_dev add overlord config @JLerxky

[chore] judge the is_stdout in the write_log4rs @JLerxky

[chore] remove redundant moduleconfig @Jayanring

[chore] remove p2p tls related code @Jayanring

[chore] add debug info for release @rink1969

[chore] change default consensus from raft to bft @rink1969

[chore] set default output to stdout @rink1969

[chore] remove sh -c in command @rink1969

Integration-test

[Feature]

[feat] check tx in pool @rink1969

[feat] feat: add build image action @acechef

[feat] enhance chaos test @rink1969

[feat] add sync node @JLerxky

[Refactor]

[refactor] change ‘timestamp’ to ‘time’ @JLerxky

[refactor] remove tls type test chain @JLerxky

[Chore]

[chore] increase delay after stop node @rink1969

[chore] update get_peers_info @JLerxky

[chore] add test chain type @JLerxky

v6.5.0

主要更新内容如下：

将kms微服务替换成crypto微服务
提供交易池内交易查询的功能
cldi 执行 get_block 返回 proof 信息
增加对于单个交易quota限制和block的quota总量限制
微服务常量统一管理
controller微服务的health_check增加出块检查
修复WAL文件损坏的问题
修复cloud-config添加新节点后原有节点配置未更新的问题

Controller

[Feature]

[feat] kms to crypto @rink1969

[feat] health check block number increase @rink1969

[feat] get pool tx @JLerxky

[Refactor]

[refactor] add quota limit @NaughtyDogOfSchrodinger

[refactor] fix dead lock @NaughtyDogOfSchrodinger

[refactor] Uniform constant @NaughtyDogOfSchrodinger

[Chore]

[chore] optiom quota limit & code type @Pencil-Yao

Consensus_bft

[Feature]

[feat] kms to crypto @rink1969

Storage_rocksdb

[Feature]

[feat] kms to crypto @rink1969

[feat] add panic hook and health check load/store @rink1969

Cloud-cli

[Feature]

[feat] get pool tx @JLerxky

[feat] get block proof @JLerxky

[Refactor]

[refactor] add quota limit @NaughtyDogOfSchrodinger

Cloud-config

[Feature]

[feat] kms to crypto @rink1969

[Fix]

[fix] refresh chain config for old nodes @rink1969

[Refactor]

[refactor] adapt for add quota limit @NaughtyDogOfSchrodinger

兼容性问题

升级到该版本会导致crypto服务起不来，需要导出私钥，并修改配置文件

v6.4.1

本次版本更新主要在系统稳定性方面做了优化，并修复了一些bug。

主要更新内容如下：

业务监控指标对接监控平台
check_proposal_proof bug修复
libsm错误处理问题修复
实验性支持consensus_overlord

Controller

[Feature]

[feat] support consensus_overlord @rink1969

Consensus_bft

[Fix]

[fix] fix commit_block proof inconsistent @JLerxky

Cloud-config

[Feature]

[feat] support consensus_overlord @rink1969

[feat] adapt for libsm @NaughtyDogOfSchrodinger

Executor_evm

[Optimization]

[optim] add debug info in release @rink1969

Storage_rocksdb

[Feature]

[feat] adapt for libsm @NaughtyDogOfSchrodinger

Kms_sm

[Fix]

[fix] adapt for fix panic in libsm @NaughtyDogOfSchrodinger

Cloud-cli

[Feature]

[feat] upgrade libsm; support overlord @rink1969

兼容性问题

数据兼容 v6.4.1 与 v6.4.0 数据完全兼容。旧有的 v6.3.3 以及 v6.3.4 链跑出来的数据，只需要停链然后使用新的 v6.4.0 镜像启动，就可以正常出块。
版本兼容 v6.4.1 与 v6.4.0 版本的节点可以混合组成网络，并正常出块
配置变更 v6.4.1 与 v6.4.0 的配置未发生修改或减少

遗留问题

WAL损坏问题。
增加删除节点会报错。

v6.4.0

更新概览：本次版本在稳定性和运维方面做了逐多优化，如果你想要多方共同参与创建联盟链，同时又不想暴露自己的私钥，那么你可以关心gitops这一新功能；如果你担心自己的机器哪天会爆炸，那么你可以关注cloud-op新的快照功能；如果你想要想要节省硬盘运维开销，那么你可以关注execuotr-evm的full mode模式，这比过去的archive mode在硬盘占用上有不少的提升。主要更新内容如下：

集成测试的搭建
cita-cloud集成gitops
运维工具cloud-op提供快照功能
提供输出完整区块的RPC接口，同时cloud-cli完成支持
execuotr-evm支持full mode和archive mode切换
charts增加微服务资源限制
controller正确处理节点重连和关机情况
network-tls的TLS证书支持多级证书体系
cita-cloud增加了健康检查(livness check)
executor_evm的evm升级到London

Controller

[Feature]

[feat] add inner block growth check @Pencil-Yao

[feat] add rpc get_block_detail_by_number @JLerxky

[feat] add health check @Pencil-Yao

[feat] add health check @rink1969

[Fix]

[fix] repeat node set @Pencil-Yao

[Optimization]

[optim] handle repeat & idle node @Pencil-Yao

[optim] hanle the same origin node @Pencil-Yao

[optim] record package limit in utxo db @NaughtyDogOfSchrodinger

Consensus_raft

[Feature]

[feat] add health check @rink1969

Consensus_bft

[Feature]

[feat] add health check @rink1969

[Optimization]

[optim] optimize handle commit entries @NaughtyDogOfSchrodinger

Cloud-config

[Feature]

[feat] add livness probe @rink1969

[feat] Support gitops @rink1969

[feat] add container resource requirements @rink1969

[Fix]

[fix] panic when create-dev @rink1969

[fix] update node, protect rewrite file in used @rink1969

Executor_evm

[Feature]

[feat] add health check @rink1969

[feat] add base_fee opcode @JLerxky

[feat] support switch between full mode and archive mode @Pencil-Yao

Storage_rocksdb

[Feature]

[feat] add health check @rink1969

Kms_sm

[Feature]

[feat] add health check @rink1969

Network_tls

[Feature]

[feat] add health check @rink1969

[Optimization]

[optim] update dependence tokio-rustls and unit-test @Pencil-Yao

Network_p2p

[Feature]

[feat] add health check @rink1969

kms_eth

[Feature]

[feat] add health check @rink1969

Cloud-cli

[Feature]

[feat] add get_block_detail @JLerxky

[feat] add set-package-limit and set-block-limit sub-command @NaughtyDogOfSchrodinger

[Optimization]

[optim] use cloud proto @JLerxky

兼容性问题

数据兼容 v6.4.0 与 v6.3.3 以及 v6.3.4 数据完全兼容。旧有的 v6.3.3 以及 v6.3.4 链跑出来的数据，只需要停链然后使用新的 v6.4.0 镜像启动，就可以正常出块。
版本兼容 v6.4.0 与 v6.3.3 以及 v6.3.4 版本的节点可以混合组成网络，并正常出块
配置变更 v6.4.0 与 v6.3.3 以及 v6.3.4 的配置未发生修改或减少

遗留问题

WAL损坏问题。
增加删除节点会报错。

v6.3.3

本次版本在稳定性和运维方面做了优化，主要更新内容如下：

修复上个版本 WAL 功能引入的问题。
支持消块工具。可以修复因为意外导致区块链节点数据不一致的问题。
梳理微服务的命令行参数。参数统一从配置文件传递，配置更清晰，更统一。也为将来支持gitops打下基础。
network支持配置文件热更新。增加删除节点之后，已有节点可以自动感知到网络的变化。
CLI重构。新增交互式模式，优化用户体验。参见文档。
更新文档。新的文档更加面向链的定制开发者。参见文档。
k8s Operator实验性支持。参见项目。

修改详情：

Controller

[Feature]

[feat] update readme @rink1969 @JLerxky

[feat] Support cloud-op @Pencil-Yao @JLerxky

[Fix]

[fix] Add the judgment of not redoing wal @JLerxky

[fix] save current_block_hash before saving current_block_height @Pencil-Yao

[Optimization]

[optim] handle add existed peer @Jayanring

[optim] use cloud_util::wal @JLerxky

[optim] run -c & -l @JLerxky

Consensus_raft

[Feature]

[feat] update readme @rink1969 @NaughtyDogOfSchrodinger

[feat] support recover @Pencil-Yao

Consensus_bft

[Feature]

[feat] update readme @NaughtyDogOfSchrodinger

[feat] Support cloud-op @Pencil-Yao @JLerxky

[Optimization]

[optim] use cloud_util::wal @JLerxky

[optim] run -c & -l @JLerxky

Cloud-config

[Feature]

[feat] Update k8s subcmd @NaughtyDogOfSchrodinger

[feat] output stdout and log file at same time @rink1969

[Fix]

[fix] fix typo @rink1969

[fix] add license and copyright info @rink1969

[fix] update images @rink1969

[fix] fix update node, protect rewrite file in used @rink1969

[Optimization]

[optim] github ci & fix: fmt @Pencil-Yao @Jayanring

[chore] update clap @JLerxky

Executor_evm

[Feature]

[feat] update readme @rink1969

[feat] Support cloud-op @Pencil-Yao @JLerxky

[Optimization]

[optim] run -c & -l @JLerxky

Storage_rocksdb

[Feature]

[feat] update readme @rink1969

[feat] Support cloud-op @Pencil-Yao @JLerxky

[Optimization]

[optim] run -c & -l @JLerxky

Kms_sm

[Feature]

[feat] remove create subcmd; update example and readme @rink1969

[Optimization]

[optim] run -c & -l @JLerxky

Network_tls

[Feature]

[feat] update readme @rink1969

[feat] support hot update + peer-count + origin @Pencil-Yao @Jayanring

[Optimization]

[optim] run -c @JLerxky

Network_p2p

[Feature]

[feat] update readme @rink1969

[Optimization]

[optim] run -c & -l @JLerxky

Kms_eth

[Feature]

[feat] remove create subcmd; update example and readme @rink1969

[Fix]

[fix] check invalid msg @rink1969

[Optimization]

[optim] run -c & -l @JLerxky

兼容性问题

数据兼容

v6.3.3 与 v6.3.2 数据完全兼容。旧有的 v6.3.2 链跑出来的数据，只需要停链然后使用新的 v6.3.3 镜像启动，就可以正常出块。
版本兼容

v6.3.3 与 v6.3.2 版本的节点可以混合组成网络，并正常出块
配置变更

微服务的参数有变化，但是采用默认值的情况下，行为与v6.3.2一致。

如果有自行设置参数的情况，可能需要进行修改。

遗留问题

WAL损坏问题。

v6.3.2

本次版本更新对稳定性和运维作了优化，稳定性方面链能够在高负载的情况下更稳定的运行，主要更新内容如下：

优化了 consensus_bft 由于网络时延问题导致的无法正常出块的问题；
controller 具备 WAL 的能力，可以处理进程突然被杀掉而引发的存储问题。
升级的微服务添加了 apache license

修改详情：

Controller 

[Feature]

[feat] add wal [@JLerxky @Pencil-Yao @Jayanring]

[feat] support retransmit chain_status_init regularly [@Pencil-Yao ]

[feat] store genesis system config [@JLerxky @Jayanring]

[Fix]

[fix] executor init [@Pencil-Yao]

[fix] in csi mode, can’t send block request [@Pencil-Yao]

[fix] dup tx in busy environment [@Pencil-Yao]

[Optimization]

[optim] confirm executor when init chain [@Jayanring]

[optim] process earlystatus logic [@Pencil-Yao ]

[optim] chain lock [@Pencil-Yao ]

Consensus_bft 

[Fix]

[fix] handle leader_commit error with dup-tx [@Pencil-Yao ]

Executor_evm 

[Feature]

[feat] hanle same or invalid block re-enter [@Pencil-Yao ]

[Optimization]

[optim] use reenter-invalid block code [@Pencil-Yao ]

Cloud-config 

[Feature]

[feat] rewrite! from cita_cloud_config [@NaughtyDogOfSchrodinger, @Pencil-Yao ]

[feat] support config [@NaughtyDogOfSchrodinger ]

[BugFix]

[fix] fix series 6.3.0 adaption problem [@Pencil-Yao, @NaughtyDogOfSchrodinger ]

兼容性问题

数据兼容

v6.3.2 与 v6.3.1 数据完全兼容。旧有的 v6.3.1 链跑出来的数据，只需要停链然后使用新的 v6.3.2 镜像启动，就可以正常出块。
版本兼容

v6.3.2 与 v6.3.1 版本的节点可以混合组成网络，并正常出块

常见问题

ALL #0 - 所有集成环境，如果后续增加集成环境也包含在内
BST 链 #1 - BST 单链集成环境
REP 链 #2 - REP 单链集成环境

Syntax	Description
问题现象	节点重启时，很快出现报错并退出: ProposalTooLow, src/chain.rs:715
出现频率	必现
链	ALL #0
影响版本	v6.3.2
问题原因	怀疑机器磁盘io占用较高，导致删除WAL文件的时候的出现了堵塞
解决方法	备份 ./data/wal_chain 目录后，将./data/wal_chain 目录内除 index 文件之外的其它文件删除重启当前节点

Syntax	Description
问题现象	raft节点日志文件损坏或者删除，重启报panic：Thread main panicked at to_commit 87 is out of range [last_index 5]rs:715
出现频率	必现
链	选择raft共识的链
影响版本	所有版本
问题原因	raft算法认为日志损坏属于异常情况，需要人工介入处理
解决方法	将日志损坏的节点从validator列表中删除，加入新节点，或者清理损坏的节点日志，重新加入validator列表