1.5. XuperChain RPC 接口使用说明¶
XuperChain为方便用户深度使用 XuperChain 的各项功能,提供了多语言版本的SDK(JS,Golang,C#,Java,Python),这里我们以Golang为例来介绍一下XuperChain的RPC接口使用方式。
注解
目前官方提供的SDK中,golang语言版本的功能最为全面,其他语言的功能弱一些,我们非常欢迎社区朋友一起建设SDK,参与贡献会获得开放网络的资源,可用于购买开放网络的服务。
1.5.1. RPC接口介绍¶
查看XuperChain的 proto文件 ,可以在service定义中获取所有支持的RPC接口
1.5.1.1. GetBalance¶
此接口用于查询指定地址中的余额
参数结构 |
AddressStatus |
返回结构 |
AddressStatus |
这里 AddressStatus 的定义如下
1 2 3 4 5 | message AddressStatus {
Header header = 1;
string address = 2;
repeated TokenDetail bcs = 3;
}
|
其中的 address 字段为需要查询的地址,传入string即可
其中的 bcs 字段为需要查询的链名,因为XuperChain支持平行链的功能,此字段为列表,亦可传入多个链名,
TokenDetail 定义如下:
1 2 3 4 5 | message TokenDetail {
string bcname = 1;
string balance = 2;
XChainErrorEnum error = 3;
}
|
请求时只需传入 bcname 字段,例如 “xuper”,其余字段为返回时携带的,balance即为对应平行链上的余额
其中的 Header 如下
1 2 3 4 5 | message Header {
string logid = 1;
string from_node = 2;
XChainErrorEnum error = 3;
}
|
Header中的logid是回复中也会携带的id,用来对应请求或追溯日志使用的,一般用 xupercore/lib/utils/utils.go 生成一个全局唯一id
Header中的from_node一般不需要填写,error字段也是返回中携带的错误内容,发请求时不需填写
以下为Golang示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | opts := make([]grpc.DialOption, 0)
opts = append(opts, grpc.WithInsecure())
opts = append(opts, grpc.WithMaxMsgSize(64<<20-1))
conn, _ := grpc.Dial("127.0.0.1:37101", opts...)
cli := pb.NewXchainClient(conn)
bc := &pb.TokenDetail{
Bcname: "xuper",
}
in := &pb.AddressStatus{
Header: utils.GenLogId(),
Address: "dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN",
Bcs: []*pb.TokenDetail{bc},
}
out, _ := cli.GetBalance(context.Background(), in)
|
1.5.1.2. GetBalanceDetail¶
此接口用于查询指定地址中的余额详细情况
参数结构 |
AddressBalanceStatus |
返回结构 |
AddressBalanceStatus |
AddressBalanceStatus 定义如下
1 2 3 4 5 | message AddressBalanceStatus {
Header header = 1;
string address = 2;
repeated TokenFrozenDetails tfds = 3;
}
|
address字段与GetBalance一样,tfds字段则多了是否冻结的内容,tfds在请求中只需要填充bcname,返回时会有TokenFrozenDetail数组给出正常余额和冻结余额的信息
以下为Golang示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | opts := make([]grpc.DialOption, 0)
opts = append(opts, grpc.WithInsecure())
opts = append(opts, grpc.WithMaxMsgSize(64<<20-1))
conn, _ := grpc.Dial("127.0.0.1:37101", opts...)
cli := pb.NewXchainClient(conn)
tfd := &pb.TokenFrozenDetails{
Bcname: "xuper",
}
in := &pb.AddressBalanceStatus{
Header: utils.GenLogId(),
Address: "dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN",
Tfds: []*pb.TokenFrozenDetails{bc},
}
out, _ := cli.GetBalanceDetail(context.Background(), in)
|
1.5.1.3. GetFrozenBalance¶
此接口用于查询指定地址中的冻结余额,请求方式与GetBalance完全一致,这里不再赘述
1.5.1.4. GetBlock¶
此接口用于查询指定id的区块内容
参数结构 |
BlockID |
返回结构 |
Block |
BlockID 定义如下
1 2 3 4 5 6 | message BlockID {
Header header = 4;
string bcname = 1;
bytes blockid = 2;
bool need_content = 3; //是否需要内容
}
|
header和bcname字段如上所述,blocked为要查询的区块id,注意是bytes类型,可能需要hex decode
need_content字段为布尔值,表明是否需要详细的区块内容(还是只查询区块是否在链和前驱后继)
以下为Golang示例
1 2 3 4 5 6 7 8 9 10 11 12 13 14 | opts := make([]grpc.DialOption, 0)
opts = append(opts, grpc.WithInsecure())
opts = append(opts, grpc.WithMaxMsgSize(64<<20-1))
conn, _ := grpc.Dial("127.0.0.1:37101", opts...)
cli := pb.NewXchainClient(conn)
id, _ := hex.DecodeString("ee0d6fd34df4a7e1540df309d47441af4fda6fdd9d841046f18e7680fe0cea8c")
in := &pb.BlockID{
Header: utils.GenLogId(),
Bcname: "xuper",
Blockid: id,
NeedContent: true,
}
out, _ := cli.GetBlock(context.Background(), in)
|
1.5.1.5. GetBlockByHeight¶
此接口用于查询指定高度的区块内容
参数结构 |
BlockHeight |
返回结构 |
Block |
BlockHeight定义如下
1 2 3 4 5 | message BlockHeight {
Header header = 3;
string bcname = 1;
int64 height = 2;
}
|
同GetBlock类似,id换成整型的高度即可,返回内容也是类似的
1.5.1.6. GetBlockChainStatus¶
此接口用于查询指定链的当前状态
参数结构 |
BCStatus |
返回结构 |
BCStatus |
BCStatus定义如下
1 2 3 4 5 6 7 8 | message BCStatus {
Header header = 1;
string bcname = 2;
LedgerMeta meta = 3;
InternalBlock block = 4;
UtxoMeta utxoMeta = 5;
repeated string branchBlockid = 6;
}
|
传入参数只需填充header,bcname即可
以下为Golang示例
1 2 3 4 5 6 7 8 9 10 11 | opts := make([]grpc.DialOption, 0)
opts = append(opts, grpc.WithInsecure())
opts = append(opts, grpc.WithMaxMsgSize(64<<20-1))
conn, _ := grpc.Dial("127.0.0.1:37101", opts...)
cli := pb.NewXchainClient(conn)
in := &pb.BCStatus{
Header: utils.GenLogId(),
Bcname: "xuper",
}
out, _ := cli.GetBlockChainStatus(context.Background(), in)
|
1.5.1.7. GetBlockChains¶
此接口用于查询当前节点上有哪些链
参数结构 |
CommonIn |
返回结构 |
BlockChains |
CommonIn结构很简单,只有header字段,返回的BlockChains也仅有一个链名的string数组
以下为Golang示例
1 2 3 4 5 6 7 8 9 10 | opts := make([]grpc.DialOption, 0)
opts = append(opts, grpc.WithInsecure())
opts = append(opts, grpc.WithMaxMsgSize(64<<20-1))
conn, _ := grpc.Dial("127.0.0.1:37101", opts...)
cli := pb.NewXchainClient(conn)
in := &pb.CommonIn{
Header: utils.GenLogId(),
}
out, _ := cli.GetBlockChains(context.Background(), in)
|
1.5.1.8. GetSystemStatus¶
此接口用于查询当前节点的运行状态
参数结构 |
CommonIn |
返回结构 |
SystemsStatusReply |
此接口相当于先查询了GetBlockChains,在用GetBlockChainStatus查询每个链的状态,不在赘述
1.5.1.9. GetNetURL¶
此接口用于查询当前节点的netUrl
参数结构 |
CommonIn |
返回结构 |
RawUrl |
RawUrl除了header字段外仅有一个string字段,表示返回的netURL
1.5.1.10. QueryACL¶
此接口用于查询指定合约账号的ACL内容
参数结构 |
AclStatus |
返回结构 |
AclStatus |
AclStatus定义如下
1 2 3 4 5 6 7 8 9 | message AclStatus {
Header header = 1;
string bcname = 2;
string accountName = 3;
string contractName = 4;
string methodName = 5;
bool confirmed = 6;
Acl acl = 7;
}
|
请求中仅需填充header,bcname,accountName即可,其余为返回内容
以下为Golang示例
1 2 3 4 5 6 | in := &pb.AclStatus{
Header: utils.GenLogId(),
Bcname: "xuper",
AccountName: "XC1111111111111111@xuper",
}
out, _ := cli.QueryACL(context.Background(), in)
|
1.5.1.11. QueryTx¶
此接口用于查询指定id的交易内容
参数结构 |
TxStatus |
返回结构 |
TxStatus |
TxStatus定义如下
1 2 3 4 5 6 7 8 | message TxStatus {
Header header = 1;
string bcname = 2;
bytes txid = 3;
TransactionStatus status = 4; //当前状态
int64 distance = 5; //离主干末端的距离(如果在主干上)
Transaction tx = 7;
}
|
请求中仅需填充header,bcname,txid字段
以下为Golang示例
1 2 3 4 5 6 7 | id, _ := hex.DecodeString("763ac8212c80b8789cefd049f1529eafe292f4d64eaffbc2d5fe19c79062a484")
in := &pb.AclStatus{
Header: utils.GenLogId(),
Bcname: "xuper",
Txid: id,
}
out, _ := cli.QueryTx(context.Background(), in)
|
1.5.1.12. SelectUTXO¶
此接口用于获取账号可用的utxo列表
参数结构 |
UtxoInput |
返回结构 |
UtxoOutput |
UtxoInput定义如下
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 | message UtxoInput {
Header header = 1;
// which bcname to select
string bcname = 2;
// address to select
string address = 3;
// publickey of the address
string publickey = 4;
// totalNeed refer the total need utxos to select
string totalNeed = 5;
// userSign of input
bytes userSign = 7;
// need lock
bool needLock = 8;
}
|
请求中只需填充header,bcname,address,totalNeed,needLock,其中needLock表示是否需要锁定utxo(适用于并发执行场景)
UtxoOutput中的返回即可在组装交易时使用,具体组装交易的过程可参考文档下方
1 2 3 4 5 6 7 8 | in := &pb.UtxoInput{
Header: utils.GenLogId(),
Bcname: "xuper",
Address: "dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN",
TotalNeed: "50",
NeedLock: true,
}
out, _ := cli.SelectUTXO(context.Background(), in)
|
1.5.1.13. SelectUTXOBySize¶
此接口用于获取账号中部分utxo,填满交易后便不在继续获取
参数结构 |
UtxoInput |
返回结构 |
UtxoOutput |
使用过程和SelectUTXO基本相同,仅少了totalNeed字段。适用拥有太多utxo,一次SelectUtxo内容超过交易容纳上限时使用
1.5.1.14. PreExec¶
此接口用于在节点上进行合约的预执行操作,返回预执行后的请求和回复
参数结构 |
InvokeRPCRequest |
返回结构 |
InvokeRPCResponse |
InvokeRPCRequest定义如下
1 2 3 4 5 6 7 | message InvokeRPCRequest {
Header header = 1;
string bcname = 2;
repeated InvokeRequest requests = 3;
string initiator = 4;
repeated string auth_require = 5;
}
|
其中的InvokeRequest定义如下
1 2 3 4 5 6 7 8 | message InvokeRequest {
string module_name = 1;
string contract_name = 2;
string method_name = 3;
map<string, bytes> args = 4;
repeated ResourceLimit resource_limits = 5;
string amount = 6;
}
|
其中必填字段有module_name,contract_name,method_name,args,具体示例可参见下一章节
1.5.1.15. PreExecWithSelectUTXO¶
此接口用于在节点上进行消耗资源的合约预执行操作,内部是由一个PreExec加上一个SelectUTXO实现的,预执行并选择出需要消耗数额的utxo
参数结构 |
PreExecWithSelectUTXORequest |
返回结构 |
PreExecWithSelectUTXOResponse |
PreExecWithSelectUTXORequest定义如下,实际上就是把预执行的请求结构放在了SelectUTXO结构中
1 2 3 4 5 6 7 8 9 | message PreExecWithSelectUTXORequest {
Header header = 1;
string bcname = 2;
string address = 3;
int64 totalAmount = 4;
SignatureInfo signInfo = 6;
bool needLock = 7;
InvokeRPCRequest request = 5;
}
|
具体填充方式可参考下一章节
1.5.1.16. PostTx¶
此接口用于提交交易,是大部分操作都需要的最终环节
参数结构 |
TxStatus |
返回结构 |
CommonReply |
请求结构TxStatus定义在QueryTx中已经给出,但提交交易时需要填充Transaction字段,定义如下
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 | message Transaction {
// txid is the id of this transaction
bytes txid = 1;
// the blockid the transaction belong to
bytes blockid = 2;
// Transaction input list
repeated TxInput tx_inputs = 3;
// Transaction output list
repeated TxOutput tx_outputs = 4;
// Transaction description or system contract
bytes desc = 6;
// Mining rewards
bool coinbase = 7;
// Random number used to avoid replay attacks
string nonce = 8;
// Timestamp to launch the transaction
int64 timestamp = 9;
// tx format version; tx格式版本号
int32 version = 10;
// auto generated tx
bool autogen = 11;
repeated TxInputExt tx_inputs_ext = 23;
repeated TxOutputExt tx_outputs_ext = 24;
repeated InvokeRequest contract_requests = 25;
// 权限系统新增字段
// 交易发起者, 可以是一个Address或者一个Account
string initiator = 26;
// 交易发起需要被收集签名的AddressURL集合信息,包括用于utxo转账和用于合约调用
repeated string auth_require = 27;
// 交易发起者对交易元数据签名,签名的内容包括auth_require字段
repeated SignatureInfo initiator_signs = 28;
// 收集到的签名
repeated SignatureInfo auth_require_signs = 29;
// 节点收到tx的时间戳,不参与签名
int64 received_timestamp = 30;
// 统一签名(支持多重签名/环签名等,与initiator_signs/auth_require_signs不同时使用)
XuperSignature xuper_sign = 31;
// 可修改区块链标记
ModifyBlock modify_block = 32;
// HD加解密相关信息
HDInfo HD_info = 33;
}
|
Transaction属于XuperChain中比较核心的结构了,下一章我们将介绍各种场景的交易如何构造并提交
1.5.2. RPC接口应用¶
本章节将以几个简单的场景为例描述RPC接口的使用方法,主要体现逻辑和步骤。代码中仅使用了原始的RPC接口,如果使用SDK则会简便很多。
1.5.2.1. 发起一次转账¶
这里我们演示如何使用RPC接口实现从账号Aclie向账号Bob的一次数额为10的转账,为了进行此操作,我们事先需要有以下信息(均为string)
Alice的地址 |
addr_alice |
Alice的公钥 |
pub_alice |
Alice的私钥 |
pri_alice |
Bob的地址 |
addr_bob |
发起转账交易的总体逻辑为,首先通过SelectUTXO获取Alice数额为10的资产,然后构造交易,最后通过PostTx提交
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 | // 获取Alice的utxo
utxoreq := &pb.UtxoInput{
Header: utils.GenLogId(),
Bcname: "xuper",
Address: addr_alice,
TotalNeed: "10",
NeedLock: true,
}
utxorsp, _ := cli.SelectUTXO(context.Background(), utxoreq)
// 声明一个交易,发起者为Alice地址,因为是转账,所以Desc字段什么都不填
// 如果是提案等操作,将客户端的 --desc 参数写进去即可
tx := &pb.Transaction{
Version: 1,
Coinbase: false,
Desc: []byte(""),
Nonce: global.GenNonce(),
Timestamp: time.Now().UnixNano(),
Initiator: addr_alice,
}
// 填充交易的输入,即Select出来的Alice的utxo
for _, utxo := range utxorsp.UtxoList {
txin := &pb.TxInput{
RefTxid: utxo.RefTxid,
RefOffset: utxo.RefOffset,
FromAddr: utxo.ToAddr,
Amount: utxo.Amount,
}
tx.TxInputs = append(tx.TxInputs, txin)
}
// 填充交易的输出,即给Bob的utxo,注意Amount字段的类型
amount, _ := big.NewInt(0).SetString("10", 10)
txout := &pb.TxOutput{
ToAddr: []byte(addr_bob),
Amount: amount.Bytes(),
}
tx.TxOutputs = append(tx.TxOutputs, txout)
// 如果Select出来的Alice的utxo多于10,需要构造一个给Alice的找零
total, _ := big.NewInt(0).SetString(utxorsp.TotalSelected, 10)
if total.Cmp(amount) > 0 {
delta := total.Sub(total, amount)
charge := &pb.TxOutput{
ToAddr: []byte(addr_alice),
Amount: delta.Bytes(),
}
tx.TxOutputs = append(tx.TxOutputs, charge)
}
// 接下来用Alice的私钥对交易进行签名,在此交易中,我们只需Alice签名确认即可
tx.AuthRequire = append(tx.AuthRequire, addr_alice)
// 签名需要的库在 github.com/xuperchain/xuperchain/core/crypto/client
// 和 github.com/xuperchain/xuperchain/core/crypto/hash
cryptoCli, _ := client.CreateCryptoClient("default")
sign, _ := txhash.ProcessSignTx(cryptoCli, tx, []byte(pri_alice))
signInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: sign,
}
// 将签名填充进交易
tx.InitiatorSigns = append(tx.InitiatorSigns, signInfo)
tx.AuthRequireSigns = append(tx.AuthRequireSigns, signInfo)
// 生成交易ID
tx.Txid, _ = txhash.MakeTransactionID(tx)
// 构造最终要Post的TxStatus
txs := &pb.TxStatus{
Bcname: "xuper",
Status: pb.TransactionStatus_UNCONFIRM,
Tx: tx,
Txid: tx.Txid,
}
// 最后一步,执行PostTx
rsp, err := cli.PostTx(context.Background(), txs)
// 这里的rsp即CommonReply,包含logid等内容
// 交易id我们已经生成在tx.Txid中,不过是bytes,输出可能需要hex.EncodeToString一下
|
1.5.2.2. 新建合约账号¶
这里我们演示创建一个合约账号 XC1234567812345678@xuper ,ACL如下
1 2 3 4 5 6 7 8 9 10 | {
"pm": {
"rule": 1,
"acceptValue": 1.0
},
"aksWeight": {
"XXXaddress-aliceXXX" : 0.6,
"XXXXaddress-bobXXXX" : 0.4
}
}
|
为了进行此操作,我们事先需要有以下信息
Alice的地址 |
addr_alice |
Alice的公钥 |
pub_alice |
Alice的私钥 |
pri_alice |
ACL的内容 |
acct_acl |
创建合约账号的总体逻辑为,首先进行创建合约账号的预执行,然后构造相应的交易内容(如果需要支付资源由Alice出),最后提交交易
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 | // 构造创建合约账号的请求
args := make(map[string][]byte)
args["account_name"] = []byte(1234567812345678)
args["acl"] = []byte(acct_acl)
invokereq := &pb.InvokeRequest{
ModuleName: "xkernel",
MethodName: "NewAccount",
Args: args,
}
invokereqs := []*pb.InvokeRequest{invokereq}
// 构造合约预执行的请求
authrequire := []string{addr_alice}
rpcreq := &pb.InvokeRPCRequest{
Header: utils.GenLogId(),
Bcname: "xuper",
Requests: invokereqs,
Initiator: addr_alice,
AuthRequire: authrequire,
}
// 花手续费需要出资的账号确认,填充一个验证的签名,才能正确的拿出utxo来
// 签名需要的库在 github.com/xuperchain/xuperchain/core/crypto/client
// 和 github.com/xuperchain/xuperchain/core/crypto/hash
content := hash.DoubleSha256([]byte("xuper" + addr_alice + "0" + "true"))
cryptoCli, _ := client.CreateCryptoClient("default")
prikey, _ := cryptoCli.GetEcdsaPrivateKeyFromJSON([]byte(pri_alice))
sign, _ := cryptoCli.SignECDSA(prikey, content)
signInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: sign,
}
// 组合一个PreExecWithSelectUTXORequest用来预执行同时拿出需要支付的Alice的utxo
prereq := &pb.PreExecWithSelectUTXORequest{
Header: utils.GenLogId(),
Bcname: "xuper",
Address: addr_alice,
TotalAmount: 0,
SignInfo: signInfo,
NeedLock: true,
Request: rpcreq,
}
prersp := cli.PreExecWithSelectUTXO(context.Background(), prereq)
// 构造一个Alice发起的交易
tx := &pb.Transaction{
Version: 1,
Coinbase: false,
Desc: []byte(""),
Nonce: global.GenNonce(),
Timestamp: time.Now().UnixNano(),
Initiator: addr_alice,
}
// 填充支付的手续费,手续费需要“转账”给地址“$”
amount := big.NewInt(prersp.Response.GasUsed)
fee := &pb.TxOutput{
ToAddr: []byte("$"),
Amount: amount.Bytes(),
}
tx.TxOutputs = append(tx.TxOutputs, fee)
// 填充select出来的Alice的utxo
for _, utxo := range prersp.UtxoOutput.UtxoList {
txin := &pb.TxInput{
RefTxid: utxo.RefTxid,
RefOffset: utxo.RefOffset,
FromAddr: utxo.ToAddr,
Amount: utxo.Amount,
}
tx.TxInputs = append(tx.TxInputs, txin)
}
// 处理找零的逻辑
total, _ := big.NewInt(0).SetString(prersp.UtxoOutput.TotalSelected, 10)
if total.Cmp(amount) > 0 {
delta := total.Sub(total, amount)
charge := &pb.TxOutput{
ToAddr: []byte(addr_alice),
Amount: delta,
}
}
// 填充预执行的结果
tx.ContractRequests = prersp.GetResponse().GetRequests()
tx.TxInputsExt = prersp.GetResponse().GetInputs()
tx.TxOutputsExt = prersp.GetResponse().GetOutputs()
// 给交易签名
tx.AuthRequire = append(tx.AuthRequire, addr_alice)
txsign, _ := txhash.ProcessSignTx(cryptoCli, tx, []byte(pri_alice))
txsignInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: txsign,
}
tx.InitiatorSigns = append(tx.InitiatorSigns, txsignInfo)
tx.AuthRequireSigns = append(tx.AuthRequireSigns, txsignInfo)
// 生成交易ID
tx.Txid, _ = txhash.MakeTransactionID(tx)
// 构造最终要Post的TxStatus
txs := &pb.TxStatus{
Bcname: "xuper",
Status: pb.TransactionStatus_UNCONFIRM,
Tx: tx,
Txid: tx.Txid,
}
// 最后一步,执行PostTx
rsp, err := cli.PostTx(context.Background(), txs)
|
1.5.2.3. 修改合约账号ACL¶
延续上一小节的例子,假设我们要把ACL修改成以下状态
1 2 3 4 5 6 7 8 9 10 | {
"pm": {
"rule": 1,
"acceptValue": 1.0
},
"aksWeight": {
"XXXaddress-aliceXXX" : 1.0,
"XXXXaddress-bobXXXX" : 1.0
}
}
|
为了进行此操作,我们事先需要有以下信息
Alice的地址 |
addr_alice |
Alice的公钥 |
pub_alice |
Alice的私钥 |
pri_alice |
Bob的地址 |
addr_bob |
Bob的公钥 |
pub_bob |
Bob的私钥 |
pri_bob |
新ACL的内容 |
new_acl |
修改ACL的总体逻辑为,首先进行修改的预执行,然后构造交易发送,这里需要注意的是,修改ACL操作需要满足现有的ACL要求才有权限,即Alice Bob都需要签名确认。简单起见,当中的手续费依然由Alice支付。
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 | // 构造修改ACL的请求
args := make(map[string][]byte)
args["account_name"] = []byte(1234567812345678)
args["acl"] = []byte(new_acl)
invokereq := &pb.InvokeRequest{
ModuleName: "xkernel",
MethodName: "SetAccountAcl",
Args: args,
}
invokereqs := []*pb.InvokeRequest{invokereq}
// 构造合约预执行的请求,和上一节一样,此处省略
///////////////////////////////////////////////
// 花手续费需要出资的账号确认,填充验证的签名,和上一节一样,此处省略
/////////////////////////////////////////////////////////////////////
// 按上一节逻辑一样,填充花费、找零,然后填充预执行的结果
tx.ContractRequests = prersp.GetResponse().GetRequests()
tx.TxInputsExt = prersp.GetResponse().GetInputs()
tx.TxOutputsExt = prersp.GetResponse().GetOutputs()
// 给交易签名需要原ACL里的多个账号了
tx.AuthRequire = append(tx.AuthRequire, addr_alice)
tx.AuthRequire = append(tx.AuthRequire, addr_bob)
alicesign, _ := txhash.ProcessSignTx(cryptoCli, tx, []byte(pri_alice))
alicesignInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: alicesign,
}
bobsign, _ := txhash.ProcessSignTx(cryptoCli, tx, []byte(pri_bob))
bobsignInfo := &pb.SignatureInfo{
PublicKey: pub_bob,
Sign: bobsign,
}
tx.InitiatorSigns = append(tx.InitiatorSigns, alicesignInfo)
tx.AuthRequireSigns = append(tx.AuthRequireSigns, alicesignInfo)
tx.AuthRequireSigns = append(tx.AuthRequireSigns, bobsignInfo)
// 然后和上一节一致了,生成交易ID
tx.Txid, _ = txhash.MakeTransactionID(tx)
// 构造最终要Post的TxStatus
txs := &pb.TxStatus{
Bcname: "xuper",
Status: pb.TransactionStatus_UNCONFIRM,
Tx: tx,
Txid: tx.Txid,
}
// 最后一步,执行PostTx
rsp, err := cli.PostTx(context.Background(), txs)
|
1.5.2.4. 部署一个合约¶
这里我们演示使用合约账号 XC1234567812345678@xuper 部署一个C++的counter合约,init参数为{“creator”:”xchain”},假设合约账号的ACL是修改过的版本
为了进行此操作,我们事先需要有以下信息
合约文件字节内容 |
contract_code |
Alice的地址 |
addr_alice |
Alice的公钥 |
pub_alice |
Alice的私钥 |
pri_alice |
部署合约的总体逻辑为,首先构造deploy操作预执行,部署需要的手续费由合约账号出,需要的签名由Alice提供(因为一个签名就满足ACL了)
1 2 3 4 5 6 7 8 9 10 11 12 13 14 15 16 17 18 19 20 21 22 23 24 25 26 27 28 29 30 31 32 33 34 35 36 37 38 39 40 41 42 43 44 45 46 47 48 49 50 51 52 53 54 55 56 57 58 59 60 61 62 63 64 65 66 67 68 69 70 71 72 73 74 75 76 77 78 79 80 81 82 83 84 85 86 87 88 89 90 91 92 93 94 95 96 97 98 99 100 101 102 103 104 105 106 107 | // 构造部署合约的请求,关注args的内容,基本上和使用xchain-cli一致
args := make(map[string][]byte)
args["account_name"] = []byte("XC1234567812345678@xuper")
args["contract_name"] = []byte("counter")
// github.com/golang/protobuf/proto
codedesc := desc := &pb.WasmCodeDesc{
Runtime: "c",
}
desc, _ := proto.Marshal(codedesc)
args["contract_desc"] = desc
args["contract_code"] = contract_code
initarg := `{"creator":"` + base64.StdEncoding.EncodeToString([]byte("xchain")) + `"}`
args["init_args"] = []byte(initarg)
invokereq := &pb.InvokeRequest{
ModuleName: "xkernel",
MethodName: "Deploy",
Args: args,
}
invokereqs := []*pb.InvokeRequest{invokereq}
// 这里预执行的authrequire格式为 XC1234567812345678@xuper/dpzuVdosQrF2kmzumhVeFQZa1aYcdgFpN,
// 表示是“某个合约账号的股东”,与直接写账号地址含义是不同的,ACL需求多个签名的时候即多个“股东”
authrequires := []string{"XC1234567812345678@xuper/XXXaddress-aliceXXX"}
rpcreq := &pb.InvokeRPCRequest{
Header: utils.GenLogId(),
Bcname: "xuper",
Requests: invokereqs,
Initiator: addr_alice,
AuthRequire: authrequires,
}
// SelectUTXO的目标是合约账号中的余额,出资账号签名中的地址变成了合约账号,与“创建账号”小节有区别
content := hash.DoubleSha256([]byte("xuper" + "XC1234567812345678@xuper" + "0" + "true"))
prikey, _ := cryptoCli.GetEcdsaPrivateKeyFromJSON([]byte(pri_alice))
sign, _ := cryptoCli.SignECDSA(prikey, content)
signInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: sign,
}
// 组合一个PreExecWithSelectUTXORequest用来预执行同时拿出需要支付的合约账号的utxo
prereq := &pb.PreExecWithSelectUTXORequest{
Header: utils.GenLogId(),
Bcname: "xuper",
Address: "XC1234567812345678@xuper",
TotalAmount: 0,
SignInfo: signInfo,
NeedLock: true,
Request: rpcreq,
}
prersp, _ := cli.PreExecWithSelectUTXO(context.Background(), prereq)
// 构造一个Alice发起的交易
tx := &pb.Transaction{
Version: 1,
Coinbase: false,
Desc: []byte(""),
Nonce: global.GenNonce(),
Timestamp: time.Now().UnixNano(),
Initiator: addr_alice,
}
// 填充支付的手续费,手续费需要“转账”给地址“$”
amount := big.NewInt(prersp.Response.GasUsed)
fee := &pb.TxOutput{
ToAddr: []byte("$"),
Amount: amount.Bytes(),
}
tx.TxOutputs = append(tx.TxOutputs, fee)
// 填充select出来的Alice的utxo
for _, utxo := range prersp.UtxoOutput.UtxoList {
txin := &pb.TxInput{
RefTxid: utxo.RefTxid,
RefOffset: utxo.RefOffset,
FromAddr: utxo.ToAddr,
Amount: utxo.Amount,
}
tx.TxInputs = append(tx.TxInputs, txin)
}
// 处理找零的逻辑
total, _ := big.NewInt(0).SetString(prersp.UtxoOutput.TotalSelected, 10)
if total.Cmp(amount) > 0 {
delta := total.Sub(total, amount)
charge := &pb.TxOutput{
ToAddr: []byte("XC1234567812345678@xuper"),
Amount: delta,
}
}
// 填充预执行的结果
tx.ContractRequests = prersp.GetResponse().GetRequests()
tx.TxInputsExt = prersp.GetResponse().GetInputs()
tx.TxOutputsExt = prersp.GetResponse().GetOutputs()
// 给交易签名,此处也是以“股东”身份签名
tx.AuthRequire = append(tx.AuthRequire, "XC1234567812345678@xuper/XXXaddress-aliceXXX")
txsign, _ := txhash.ProcessSignTx(cryptoCli, tx, []byte(pri_alice))
txsignInfo := &pb.SignatureInfo{
PublicKey: pub_alice,
Sign: txsign,
}
// 虽然Alice和“股东Alice”含义不同,但签名的私钥是一样的
tx.InitiatorSigns = append(tx.InitiatorSigns, signInfo)
tx.AuthRequireSigns = append(tx.AuthRequireSigns, signInfo)
tx.Txid, _ = txhash.MakeTransactionID(tx)
// 构造最终要Post的TxStatus
txs := &pb.TxStatus{
Bcname: "xuper",
Status: pb.TransactionStatus_UNCONFIRM,
Tx: tx,
Txid: tx.Txid,
}
// 最后一步,执行PostTx
rsp, err := cli.PostTx(context.Background(), txs)
|
1.5.2.5. 执行一个wasm合约¶
这里我们演示使用Alice账号调用上一节部署的counter合约,执行 increase 方法,参数为 {“key”: “example”}
为了进行此操作,我们事先需要有以下信息
Alice的地址 |
addr_alice |
Alice的公钥 |
pub_alice |
Alice的私钥 |
pri_alice |
执行合约的总体逻辑为,首先构造相应预执行请求并预执行,如果是查询,那么直接读预执行结果即可,如果是要调用上链的操作,使用预执行结果组建交易并发送
1 2 3 4 5 6 7 8 9 10 11 | // 构造执行合约的请求
args := make(map[string][]byte)
args["key"] = []byte("example")
invokereq := &pb.InvokeRequest{
ModuleName: "wasm",
MethodName: "increase",
ContractName: "counter",
Args: args,
}
invokereqs := []*pb.InvokeRequest{invokereq}
// 其他内容和“创建合约账号”一节完全一致
|