Rust SDK for FISCO-BCOS ,like some rusted but solid gears , help to build blockchain application with FISCO-BCOS
FISCO BCOS的轻量级版本Rust SDK, 基础网络、国密非国密算法支持、合约解析能力较为完备，附带命令行交互控制台。
-
本项目的定位是一个学习/研究/编程兴趣的项目，仅供学习参考。如有正式的使用需求，建议在熟悉rust语言的前提下，仅部分参考本项目和FISCO BCOS相关的实现，去开发自己的生产级sdk，并经过严谨测试验证后使用。
-
本项目并非唯一且官方的fisco bcos rust sdk，社区陆续会有其他优秀的rust的sdk实现，提供多种选择和参考可能性
支持FISCO BCOS3.0 release版本，支持FISCO BCOS2.x的RPC/Channel协议，国密和非国密算法，友好解析交易(Transaction)、回执(Receipt)、事件（Event）
有命令行控制台，支持创建和查询账户，以及合约类（部署调用），查询类的操作。
- 支持FISCO BCOS 3.x接口: JSON-RPC。对于FISCO BCOS3.x，客户端采用ffi方式包装C语言开发的底层SDK库，由SDK库负责网络协议封装和安全通信细节。
- 支持FISCO BCOS 2.x接口: JSON-RPC。对于FISCO BCOS2.x，客户端基于Channel协议与FISCO BCOS进行通信，保证节点与SDK安全加密通信的同时，可接收节点推送的消息。
- FISCO BCOS2.0国密和非国密的Channel协议
- 支持交易的部署、发送交易、call
- 支持解析解析功能：包括交易输入、交易输出、Event Log等ABI数据的拼装和解析。
- 支持基于pem文件的账户创建和私钥读取。
- 引用WeDPR的密码库进行HASH，签名, 该密码库支持ECDSA和SM2,3,4
- 控制台支持Struct参数，数组等复杂数据结构，SDK调用方法参见src/sample/structdemo.rs
- 支持FISCO BCOS2.0 合约事件监听，参见相应调用
已经验证的rust版本
rustc 1.54.0-nightly (ed597e7e1 2021-06-08)
rustc 1.55.0-nightly (67b03007c 2021-07-23)
rustc 1.66.0-nightly (f5193a9fc 2022-09-25)
rust版本的本身更新较快，请按rust官网指引安装配置。
考虑到稳定性和完备性，暂未发布最新版本，建议直接套用源代码，并在开发使用中完善。
(FISCO BCOS2.x):
fn main() {
//enable log
log4rs::init_file("log4rs.yml", Default::default()).unwrap();
//load config and init the bcossdk
let mut bcossdk = BcosSDK::new_from_config("conf/config.toml").unwrap();
//get node version,other apis see fisco-bcos document or sample
let res = bcossdk.getNodeVersion();
println!("res {:?}",res);
}
(FISCO BCOS3.x):
fn main() {
//enable log
log4rs::init_file("log4rs.yml", Default::default()).unwrap();
//load config and init the bcossdk
let bcos3client = Bcos3Client::new(cli.default_configfile().as_str()).unwarap();
//get blocknumber,other apis see fisco-bcos document or sample
let res = bcossdk.getBlockNumber();
println!("res {:?}",res);
}
Tips:调用sdk代码前，应保证调用过一次日志初始化语句：
log4rs::init_file("log4rs.yml", Default::default()).unwrap();
- src/bcossdk : 主要的sdk代码，代码本身已经比较模块化，有注释，欢迎查阅
- src/bcos3sdk : 整合FISCO BCOS3.x的C语言SDK
- src/console : 命令行控制台实现代码
- src/sample: 陆续增加一些sample
- conf : 配置文件,运行前，先将client_config.toml.sample复制为client_config.toml,并仔细理解和修改里面的配置值，尤其是ip端口和证书
- sdk : 连接节点的证书，国密和非国密的都放到这里
- contracts : 合约的sol，abi，bin等
- gm: 考虑到同时连接国密和非国密节点，推荐建立一个gm目录，包含以上的conf,sdk,contracts等目录结构，保存国密节点所需的配置、证书、私钥、合约定义和代码等
- log: 控制台运行后会自动生成log目录，保存日志文件。日志配置见log4rs，默认配置是输出滚动日志，可根据实际需要修改。
FISCO BCOS 3.x的rust sdk通过FFI方式封装C语言实现的接口库，协议、通信、证书等细节封装在C/C++库里。
ABI格式编解码和2.x的客户端一样依旧用rust实现。
重要:
最新版本的C语言的SDK库文件可到文件下载连接,下载相应操作系统的库文件。
如windows平台上的bcos-c-sdk.dll/.lib,linux平台上的libbcos-c-sdk.so等。
下载后放到当前目录的编译环境路径和运行环境路径下，具体路径取决于开发者的特定项目结构、环境配置。总之一定要在编译期和运行期能映射到C语言SDK库。
- 在linux下编译时，有可能会报告ld找不到库，可以尝试将libbcos-c-sdk.so复制到target/debug/deps/目录下
C语言SDK接口实现代码
https://github.com/FISCO-BCOS/bcos-c-sdk
C++客户端代码 https://github.com/FISCO-BCOS/bcos-cpp-sdk
主要配置文件是 conf/config.toml，项目提供了conf/config.toml.sample,将其复制或去掉sample后缀即可。
目前的配置文件同时包含FISCO BCOS2/FISCO BCOS3的配置，初始化时会全部加载，后续可以优化为特定版本客户端只加载特定的配置
配置项解释：
[common]
crypto = "ECDSA"
accountpem = "conf/client.pem"
contractpath = "./contracts"
solc = "./bin/solc"
solcgm = "./bin/solc-gm"
#------------------FISCO BCOS3.0 Begin----------------------------------------
[bcos3]
# FISCO BCOS3.0的配置段，如连接FISCO BCOS2.0版本，无需关心此段
# FISCO BCOS3.0 c底层sdk的配置，都在bcos3_config_file里，无需配置在此文件
sdk_config_file ="./bcos3sdklib/bcos3_sdk_config.ini"
group = "group0"
#-------------------FISCO BCOS3.0 End-----------------------------------------
#------------------FISCO BCOS2.0 Begin----------------------------------------
[bcos2]
chainid = 1
groupid = 1
protocol = "CHANNEL"
[rpc]
url = "http://127.0.0.1:8545"
timeout = 3
[channel]
ip = "127.0.0.1"
port = 20200
tlskind = "ECDSA"
timeout = 10
nativelib_echo_mode = 0
cacert = "sdk/ca.crt"
sdkcert = "sdk/sdk.crt"
sdkkey = "sdk/sdk.key"
gmcacert = "sdk/gmca.crt"
gmsdkcert = "sdk/gmsdk.crt"
gmsdkkey = "sdk/gmsdk.key"
gmensdkcert = "sdk/gmensdk.crt"
gmensdkkey = "sdk/gmensdk.key"
#------------------FISCO BCOS2.0 End----------------------------------------
cargo run -- --help 控制台本身的help(采用StructOpt库默认格式）
典型命令如
cargo run -- bcos3 deploy HelloWorld
命令行选项：
-c, --config <configfile>
-c 配置文件，全路径如-c conf/config.toml
-n, --contractname <contractname>
-n 显式的指定合约名，主要是供解析交易和回执时使用，不用带后缀，如"HelloWorld"
cargo run -- usage bcossdk的操作命令字帮助，建议查看包括 usage account，usage contract，usage get或usage all
注意，控制台调用区块链的RPC接口时，在此版本开始需要区分bcos2，bcos3的客户端，如
查询类：
cargo run -- bcos2 getBlockNumber
cargo run -- bcos3 getBlockNumber
更多命令参见cargo run -- usage get
合约：
cargo run -- bcos2 deploy HelloWorld
cargo run -- bcos2 sendtx HelloWorld latest set "new data"
cargo run -- bcos3 deploy HelloWorld
cargo run -- bcos3 sendtx HelloWorld latest set "new data"
账户管理、合约编译这些无节点版本区别的，则不需要加bcos2/bcos3参数
下载链接参见 Github Release:包含多版本/多平台
根据实际操作系统版本、国密或非国密，下载相应的二进制文件，解压并放到bin/目录下，或者和配置路径对应
建议同时下载0.4.25和6.x的solc
数组
合约数组如uint256[3] nums，那么在rust层面，其参数构造可以是 [1,2,3],同理，字符串数组对应['a','b','c']
在控制台输入时，数组参数需要加上中括号，比如[1, 2, 3]，数组中是字符串或字节类型，加双引号或单引号，例如[“alice”, ”bob”]，注意数组参数中不要有空格；布尔类型为true或者false。
结构体
合约结构体如
struct User {
string name;
uint256 age;
}
对应rust的tuple类型，如 ('alice',23)
如果是结构体数组 User[] _users, 则对应tuple数组如[('alice',23),('bob',28)]
在控制台输入时，按以上格式输入即可。举例
单个结构体参数
cargo run -- bcos3 sendtx TestStruct latest addUser ('alice',23)
两个参数，第二个参数是结构体
cargo run -- bcos3 sendtx TestStruct latest addbyname alice ('alice',23)
结构体数组参数
cargo run -- bcos3 sendtx TestStruct latest addUsers [('alice',23),('bob',28)]
查询，返回的是结构体
cargo run -- bcos3 call TestStruct latest getUser alice
重要提示:
- 输入数据的 \, "等字符可能会被转义，所以参数应尽量不包含牵涉转义的各种字符，保持简单。
- 如输入的数据一定要包含转移字符，建议按urlencode,b64等模式先做编码，避免转义问题
- 或者修改src/bcossdk/liteutils.rs里的split_param方法，修改其转义实现，这个方法在数组参数，结构体参数，数组嵌套结构体参数解析时会被多次调用， 导致转义次数会不止一次，最终输出的结果可能会不如输入者预期。
channel协议用于FISCO BCOS 2.x。FISCO BCOS 3.x采用了新的协议，不是这个版本的channel协议，如使用3.x的节点，无需关注此节。
channel协议要求在客户端和节点之间TLS长连接，使用证书握手和加密，详细参见：Channel协议
TLS实现分为国密和非国密两种，国密的证书私钥文件会比非国密多两个（sdk加密证书和key）。
对非国密TLS，本项目直接使用了ssl库，在系统上要求安装了ssl。在linux上要设置OPENSSL_DIR=[如：/usr/local/ssl],否则编译时rust的openssl-sys库会报错。
对国密版本，采用了TASSL开源库以及简单的C LIB封装对接，需要在不同平台上手动编译出动态库（dll或so)，并确保这些动态库和相关的依赖库，都部署在项目目录或系统目录下，可加载。
如果想使用国密版本channel协议，请仔细阅读native_ssock_lib下的README
要将c语言项目编译出来的动态库，全部复制到和可执行程序相同的目录或系统目录下下，才可以加载成功
在linux上，可以配置LD_LIBRARY_PATH=[so库所在目录]并生效
加载动态库的rust实现参见src/bcossdk/bcos_tls_native.rs，如有兴趣建议仔细走读，并进行优化，目前的实现在生命周期和稳定性方面有优化空间
- AMOP的完整实现（有待补充，需在多节点多机构之间开发测试验证）
- 优化代码风格，以更符合rust领域的规范
- 优化错误处理，包括错误码，错误逻辑，边界异常等
- 优化生命周期/内存管理细节
- 优化性能
-
欢迎clone,fork，可以参考/复制所需代码,欢迎交流讨论。
-
欢迎并非常感谢您的贡献，请参阅代码贡献流程。
-
如项目对您有帮助，欢迎star支持！
FISCO BCOS开源社区是国内活跃的开源社区，社区长期为机构和个人开发者提供各类支持与帮助。已有来自各行业的数千名技术爱好者在研究和使用FISCO BCOS。如您对FISCO BCOS开源技术及应用感兴趣，欢迎加入社区获得更多支持与帮助。
Rust SDK的开源协议为MIT License. 详情参考LICENSE。