比原项目仓库:
Github 地址: https://github.com/Bytom/bytom
Gitee 地址: https://gitee.com/BytomBlockchain/bytom
该部分主要针对用户使用 bytom 自带的账户模式发送交易
API 接口 build-transaction,代码api/transact.go#L120
以标准的非 BTM 资产转账交易为例,资产 ID 为全 F 表示 BTM 资产,在该示例中 BTM 资产仅作为手续费,该交易表示花费 99 个特定的资产到指定地址中。其中构建交易的输入请求 json 格式如下:
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 20000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"account_id": "0ER7MEFGG0A02",
"amount": 99,
"asset_id": "42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f",
"type": "spend_account"
},
{
"amount": 99,
"asset_id": "42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f",
"address": "sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me",
"type": "control_address"
}
],
"ttl": 0,
"time_range": 0
}
对应源代码的请求对象如下:
// BuildRequest is main struct when building transactions
type BuildRequest struct {
Tx *types.TxData `json:"base_transaction"`
Actions []map[string]interface{} `json:"actions"`
TTL json.Duration `json:"ttl"`
TimeRange uint64 `json:"time_range"`
}
结构字段说明如下:
Tx
交易的TxData
部分,该字段为预留字段,为空即可TTL
构建交易的生存时间(单位为毫秒),意味着在该时间范围内,已经缓存的 utxo 不能用于再一次 build 交易,除非剩余的 utxo 足以构建一笔新的交易,否则会报错。当ttl
为 0 时会被默认设置为 600s,即 5 分钟TimeRange
时间戳,意味着该交易将在该时间戳(区块高度)之后不会被提交上链,为了防止交易在网络中传输延迟而等待太久时间,如果交易没有在特定的时间范围内被打包,该交易便会自动失效Actions
交易的actions
结构,所有的交易都是由 action 构成的,map
类型的interface{}
保证了 action 类型的可扩展性。其中 action 中必须包含 type 字段,用于区分不同的 action 类型,action
主要包含input
和output
两种类型,其详细介绍如下:
input action
类型:
output action
类型:
注意事项:
下面对构建交易时用到的各种action
类型进行详细说明:
issueAction
结构体源代码如下:
type issueAction struct {
assets *Registry
bc.AssetAmount
}
type AssetAmount struct {
AssetId *AssetID `protobuf:"bytes,1,opt,name=asset_id,json=assetId" json:"asset_id,omitempty"`
Amount uint64 `protobuf:"varint,2,opt,name=amount" json:"amount,omitempty"`
}
结构字段说明如下:
assets
主要用于资产的管理,无需用户设置参数AssetAmount
表示用户需要发行的资产 ID 和对应的资产数目,这里的AssetID
需要通过create-asset
创建,并且这里不能使用BTM
的资产 IDissueAction
的json
格式为:
{
"amount": 100000000,
"asset_id": "3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680",
"type": "issue"
}
例如发行一笔资产的交易示例如下:
(该交易表示发行数量为900000000
个assetID
的42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f
的资产到接收地址sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me
中, 其中手续费为20000000
neu 的 BTM 资产)
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 20000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"amount": 900000000,
"asset_id": "42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f",
"type": "issue"
},
{
"amount": 900000000,
"asset_id": "42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f",
"address": "sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me",
"type": "control_address"
}
],
"ttl": 0,
"time_range": 0
}
spendAction
结构体源代码如下:
type spendAction struct {
accounts *Manager
bc.AssetAmount
AccountID string `json:"account_id"`
ClientToken *string `json:"client_token"`
}
type AssetAmount struct {
AssetId *AssetID `protobuf:"bytes,1,opt,name=asset_id,json=assetId" json:"asset_id,omitempty"`
Amount uint64 `protobuf:"varint,2,opt,name=amount" json:"amount,omitempty"`
}
结构字段说明如下:
accounts
主要用于账户的管理,无需用户设置参数AccountID
表示需要花费资产的账户 IDAssetAmount
表示花费的资产 ID 和对应的资产数目ClientToken
表示 Reserve 用户 UTXO 的限制条件,目前不填或为空即可spendAction
的json
格式为:
{
"account_id": "0BF63M2U00A04",
"amount": 2000000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
}
例如转账一笔资产的交易示例如下:
(该交易表示通过账户的方式转账100000000
neu 的 BTM 资产到地址sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me
中, 其中手续费20000000
neu = 输入 BTM 资产数量 - 输出 BTM 资产数量)
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 120000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"address": "sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me",
"type": "control_address"
}
],
"ttl": 0,
"time_range": 0
}
spendUTXOAction
结构体源代码如下:
type spendUTXOAction struct {
accounts *Manager
OutputID *bc.Hash `json:"output_id"`
ClientToken *string `json:"client_token"`
}
结构字段说明如下:
accounts
主要用于账户的管理,无需用户设置参数OutputID
表示需要花费的 UTXO 的 ID,可以根据list-unspent-outputs
查询可用的 UTXO,其中OutputID
对应该 API 返回结果的id
字段ClientToken
表示 Reserve 用户 UTXO 的限制条件,目前不填或为空即可spendUTXOAction
的json
格式为:
{
"type": "spend_account_unspent_output",
"output_id": "58f29f0f85f7bd2a91088bcbe536dee41cd0642dfb1480d3a88589bdbfd642d9"
}
例如通过花费 UTXO 的方式转账一笔资产的交易示例如下:
(该交易表示通过直接花费 UTXO 的方式转账100000000
neu 的 BTM 资产到地址sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me
中, 其中手续费 = 输入 BTM 资产的 UTXO 值 - 输出 BTM 资产数量)
{
"base_transaction": null,
"actions": [
{
"output_id": "58f29f0f85f7bd2a91088bcbe536dee41cd0642dfb1480d3a88589bdbfd642d9",
"type": "spend_account_unspent_output"
},
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"address": "sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me",
"type": "control_address"
}
],
"ttl": 0,
"time_range": 0
}
controlAddressAction
结构体源代码如下:
type controlAddressAction struct {
bc.AssetAmount
Address string `json:"address"`
}
type AssetAmount struct {
AssetId *AssetID `protobuf:"bytes,1,opt,name=asset_id,json=assetId" json:"asset_id,omitempty"`
Amount uint64 `protobuf:"varint,2,opt,name=amount" json:"amount,omitempty"`
}
结构字段说明如下:
Address
表示接收资产的地址,可以根据 create-account-receiver
API 接口创建地址AssetAmount
表示接收的资产 ID 和对应的资产数目controlAddressAction
的json
格式为:
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"address": "bm1q50u3z8empm5ke0g3ngl2t3sqtr6sd7cepd3z68",
"type": "control_address"
}
例如转账一笔资产的交易示例如下:
(该交易表示通过账户的方式转账100000000
neu 的 BTM 资产到地址sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me
中, 其中control_address
类型表示以地址作为接收方式)
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 120000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"address": "sm1qxe4jwhkekgnxkezu7xutu5gqnnpmyc8ppq98me",
"type": "control_address"
}
],
"ttl": 0,
"time_range": 0
}
controlProgramAction
结构体源代码如下:
type controlProgramAction struct {
bc.AssetAmount
Program json.HexBytes `json:"control_program"`
}
type AssetAmount struct {
AssetId *AssetID `protobuf:"bytes,1,opt,name=asset_id,json=assetId" json:"asset_id,omitempty"`
Amount uint64 `protobuf:"varint,2,opt,name=amount" json:"amount,omitempty"`
}
结构字段说明如下:
Program
表示接收资产的合约脚本,可以根据 create-account-receiver
API 接口创建接收program
(返回结果的 program
和 address
是一一对应的)AssetAmount
表示接收的资产 ID 和对应的资产数目controlProgramAction
的json
格式为:
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"control_program":"0014a3f9111f3b0ee96cbd119a3ea5c60058f506fb19",
"type": "control_program"
}
例如转账一笔资产的交易示例如下:
(该交易表示通过账户的方式转账100000000
neu 的 BTM 资产到接收program
(跟address
是一一对应的)0014a3f9111f3b0ee96cbd119a3ea5c60058f506fb19
中, 其中control_program
类型表示以program
作为接收方式)
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 120000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"control_program": "0014a3f9111f3b0ee96cbd119a3ea5c60058f506fb19",
"type": "control_program"
}
],
"ttl": 0,
"time_range": 0
}
retireAction
结构体源代码如下:
type retireAction struct {
bc.AssetAmount
}
type AssetAmount struct {
AssetId *AssetID `protobuf:"bytes,1,opt,name=asset_id,json=assetId" json:"asset_id,omitempty"`
Amount uint64 `protobuf:"varint,2,opt,name=amount" json:"amount,omitempty"`
}
结构字段说明如下:
AssetAmount
表示销毁的资产 ID 和对应的资产数目retireAction
的json
格式为:
{
"amount": 900000000,
"asset_id": "3152a15da72be51b330e1c0f8e1c0db669269809da4f16443ff266e07cc43680",
"type": "retire"
}
例如销毁一笔资产的交易示例如下:
(该交易表示通过账户的方式将100000000
neu 的 BTM 资产销毁, retire
表示销毁指定数量的资产)
{
"base_transaction": null,
"actions": [
{
"account_id": "0ER7MEFGG0A02",
"amount": 120000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "spend_account"
},
{
"amount": 100000000,
"asset_id": "ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff",
"type": "retire"
}
],
"ttl": 0,
"time_range": 0
}
build-transaction
的输入构造完成之后,便可以通过 http 的调用方式进行发送交易,构建交易请求成功之后返回的 json 结果如下:
{
"allow_additional_actions": false,
"raw_transaction": "070100020161015f1190c60818b4aff485c865113c802942f29ce09088cae1b117fc4c8db2292212ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8099c4d599010001160014a86c83ee12e6d790fb388345cc2e2b87056a077301000161015fb018097c4040c8dd86d95611a13c24f90d4c9d9d06b25f5c9ed0556ac8abd73442275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f80a094a58d1d0101160014068840e56af74038571f223b1c99f1b60caaf456010003013effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80bfffcb9901011600140b946646626c55a52a325c8bb48de792284d9b7200013e42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f9d9f94a58d1d01160014c8b4391bab4923a83b955170d24ee4ca5b6ec3fb00013942275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f6301160014366b275ed9b2266b645cf1b8be51009cc3b260e100",
"signing_instructions": [
{
"position": 0,
"witness_components": [
{
"keys": [
{
"derivation_path": [
"010100000000000000",
"0100000000000000"
],
"xpub": "de0db655c091b2838ccb6cddb675779b0a9a4204b122e61699b339867dd10eb0dbdc926882ff6dd75c099c181c60d63eab0033a4b0a4d0a8c78079e39d7ad1d8"
}
],
"quorum": 1,
"signatures": null,
"type": "raw_tx_signature"
},
{
"type": "data",
"value": "d174db6506e35f2decb5be148c2984bfd0f6c67f043365bf642d1af387c04fd5"
}
]
},
{
"position": 1,
"witness_components": [
{
"keys": [
{
"derivation_path": [
"010100000000000000",
"0800000000000000"
],
"xpub": "de0db655c091b2838ccb6cddb675779b0a9a4204b122e61699b339867dd10eb0dbdc926882ff6dd75c099c181c60d63eab0033a4b0a4d0a8c78079e39d7ad1d8"
}
],
"quorum": 1,
"signatures": null,
"type": "raw_tx_signature"
},
{
"type": "data",
"value": "05cdbcc705f07ad87521835bbba226ad7b430cc24e5e3f008edbe61540535419"
}
]
}
]
}
对应响应对象的源代码如下:
// Template represents a partially- or fully-signed transaction.
type Template struct {
Transaction *types.Tx `json:"raw_transaction"`
SigningInstructions []*SigningInstruction `json:"signing_instructions"`
// AllowAdditional affects whether Sign commits to the tx sighash or
// to individual details of the tx so far. When true, signatures
// commit to tx details, and new details may be added but existing
// ones cannot be changed. When false, signatures commit to the tx
// as a whole, and any change to the tx invalidates the signature.
AllowAdditional bool `json:"allow_additional_actions"`
}
结构字段说明如下:
Transaction
交易相关信息,该字段包含TxData
和bc.Tx
两个部分:
TxData
表示给用户展示的交易数据部分,该部分对用户可见
Version
交易版本SerializedSize
交易序列化之后的 sizeTimeRange
交易提交上链的最大时间戳(区块高度)(主链区块高度到达该时间戳(区块高度)之后,如果交易没有被提交上链,该交易便会失效)Inputs
交易输入Outputs
交易输出bc.Tx
表示系统中处理交易用到的转换结构,该部分对用户不可见,故不做详细描述SigningInstructions
交易的签名信息
Position
对input action
签名的位置WitnessComponents
对input action
签名需要的数据信息,其中 build 交易的signatures
为null
,表示没有签名; 如果交易签名成功,则该字段会存在签名信息。该字段是一个 interface 接口,主要包含 3 种不同的类型:
SignatureWitness
对交易模板Template
中交易input action
位置的合约 program 进行哈希,然后对 hash 值进行签名
signatures
(数组类型)交易的签名,sign-transaction
执行完成之后才会有值存在keys
(数组类型)包含主公钥xpub
和派生路径derivation_path
,通过它们可以在签名阶段找到对应的派生私钥child_xprv
,然后使用派生私钥进行签名quorum
账户key
的个数,必须和上面的keys
的长度相等。如果quorum
等于 1,则表示单签账户,否则为多签账户program
签名的数据部分,program
的 hash 值作为签名数据。如果program
为空,则会根据当前交易 ID 和对应 action 位置的 InputID 两部分生成一个 hash,然后把它们作为指令数据自动构造一个program
RawTxSigWitness
对交易模板Template
的交易 ID 和对应input action
位置的 InputID(该字段位于 bc.Tx 中)进行哈希,然后对 hash 值进行签名
signatures
(数组类型)交易的签名,sign-transaction
执行完成之后才会有值存在keys
(数组类型)包含主公钥xpub
和派生路径derivation_path
,通过它们可以在签名阶段找到对应的派生私钥child_xprv
,然后使用派生私钥进行签名quorum
账户key
的个数,必须和上面的keys
的长度相等。如果quorum
等于 1,则表示单签账户,否则为多签账户DataWitness
该类型无需签名,验证合约 program 的附加数据AllowAdditional
是否允许交易的附加数据,如果为true
,则交易的附加数据会添加到交易中,但是不会影响交易的执行的program
脚本,对签名结果不会造成影响; 如果为false
,则整个交易作为一个整体进行签名,任何数据的改变将影响整个交易的签名估算手续费接口estimate-transaction-gas
是对build-transaction
的结果进行手续费的预估,估算的结果需要重新加到build-transaction
的结果中,然后对交易进行签名和提交。其主要流程如下:
build - estimate - build - sign - submit
估算手续费的输入请求 json 格式如下:
{
"transaction_template": {
"allow_additional_actions": false,
"raw_transaction": "070100020161015f1190c60818b4aff485c865113c802942f29ce09088cae1b117fc4c8db2292212ffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff8099c4d599010001160014a86c83ee12e6d790fb388345cc2e2b87056a077301000161015fb018097c4040c8dd86d95611a13c24f90d4c9d9d06b25f5c9ed0556ac8abd73442275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f80a094a58d1d0101160014068840e56af74038571f223b1c99f1b60caaf456010003013effffffffffffffffffffffffffffffffffffffffffffffffffffffffffffffff80bfffcb9901011600140b946646626c55a52a325c8bb48de792284d9b7200013e42275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f9d9f94a58d1d01160014c8b4391bab4923a83b955170d24ee4ca5b6ec3fb00013942275aacbeda1522cd41580f875c3c452daf5174b17ba062bf0ab71a568c123f6301160014366b275ed9b2266b645cf1b8be51009cc3b260e100",
"signing_instructions": [
{
"position": 0,
"witness_components": [
{
"keys": [
{
"derivation_path": [
"010100000000000000",
"0100000000000000"
],
"xpub": "de0db655c091b2838ccb6cddb675779b0a9a4204b122e61699b339867dd10eb0dbdc926882ff6dd75c099c181c60d63eab0033a4b0a4d0a8c78079e39d7ad1d8"
}
],
"quorum": 1,
"signatures": null,
"type": "raw_tx_signature"
},
{
"type": "data",
"value": "d174db6506e35f2decb5be148c2984bfd0f6c67f043365bf642d1af387c04fd5"
}
]
},
{
"position": 1,
"witness_components": [
{
"keys": [
{
"derivation_path": [
"010100000000000000",
"0800000000000000"
],
"xpub": "de0db655c091b2838ccb6cddb675779b0a9a4204b122e61699b339867dd10eb0dbdc926882ff6dd75c099c181c60d63eab0033a4b0a4d0a8c78079e39d7ad1d8"
}
],
"quorum": 1,
"signatures": null,
"type": "raw_tx_signature"
},
{
"type": "data",
"value": "05cdbcc705f07ad87521835bbba226ad7b430cc24e5e3f008edbe61540535419"
}
]
}
]
}
}
对应响应对象的源代码如下:
type request struct{
TxTemplate txbuilder.Template `json:"transaction_template"`
}
// Template represents a partially- or fully-signed transaction.
type Template struct {
Transaction *types.Tx `json:"raw_transaction"`
SigningInstructions []*SigningInstruction `json:"signing_instructions"`
// AllowAdditional affects whether Sign commits to the tx sighash or
// to individual details of the tx so far. When true, signatures
// commit to tx details, and new details may be added but existing
// ones cannot be changed. When false, signatures commit to the tx
// as a whole, and any change to the tx invalidates the signature.
AllowAdditional bool `json:"allow_additional_actions"`
}
其中TxTemplate
相关字段的说明见 build-transaction 的结果描述
调用estimate-transaction-gas
接口成功之后返回的 json 结果如下:
{
"total_neu": 5000000,
"storage_neu": 3840000,
"vm_neu": 1419000
}
对应响应对象的源代码如下:
// EstimateTxGasResp estimate transaction consumed gas
type EstimateTxGasResp struct {
TotalNeu int64 `json:"total_neu"`
StorageNeu int64 `json:"storage_neu"`
VMNeu int64 `json:"vm_neu"`
}
结构字段说明如下:
TotalNeu
预估的总手续费(单位为 neu ),该值直接加到 build-transaction 的 BTM 资产输入 action 中即可StorageNeu
存储交易的手续费VMNeu
运行虚拟机的手续费 1
Bytom OP |