开发回调服务器
HTTP 接口说明
回调服务器是一个 HTTP 服务器，需要支持如下接口的请求：
Path
/v1/check
Method
POST
Body
采用 x-www-form-urlencoded 编码的数据
解析 HTTP 请求
TSS Node 采用如下步骤构建 HTTP 请求，供对接参考：
根据任务类型，生成对应的 CallbackRequest 结构体
将 CallbackRequest 结构体进行 JSON 序列化，得到 CallbackRequestJsonString
使用 CallbackRequestJsonString 作为 JWT 的 payload，使用自身的 RSA 私钥对其进行签名，构造 JWT
使用 form 表单的形式进行 HTTP POST 提交，form 表单的 Key 是 TSS_JWT_MSG，Value 为上一步构造的 JWT
回调服务器接收到 HTTP 请求后，需要按照如下步骤进行解析：
提取 HTTP POST 请求中提交的表单数据，Key 为 TSS_JWT_MSG，Value 即为 JWT
使用本地保存的 TSS Node 的 RSA 公钥，对 JWT 进行签名检查
提取 JWT 中的 payload，并对 payload 按照 CallbackRequest 结构体进行 JSON 反序列化
根据 CallbackRequest 的类型，对其中的 meta 字段进行进一步的 JSON 反序列化，得到本请求的详细信息
开发风控检查相关逻辑
回调服务器内，需要结合自身业务上的需求，针对 CallbackRequest 的内容进行风控检查，确保本次请求的任务是合法的动用私钥分片的任务。
构建 HTTP 响应
回调服务器构建 HTTP 响应的步骤如下：
根据风控检查结构，生成对应的 CallbackResponse 结构体
将 CallbackResponse 结构体进行 JSON 序列化，得到 CallbackResponseJsonString
使用 CallbackResponseJsonString 作为 JWT 的 payload，使用自身的 RSA 私钥对其进行签名，构造 JWT
将上一步构造的 JWT 作为 HTTP 响应的内容，直接返回给 TSS Node
CallbackRequest 定义
参数
类型
描述
request_id
string
回调请求唯一 ID
request_type
int
回调请求的类型，是一个枚举值，包括以下几种： TypePing = 0
TypeKeyGen = 1
TypeKeySign = 2
TypeKeyReshare = 3
request_detail
string
回调请求详细信息，包括请求的一系列关键信息。不同的回调请求类型对应不同的 request_detail 结构；
格式为 JSON 序列化后的字符串
extra_info
string
回调请求辅助信息，包括请求的一些额外相关信息；
不同的回调请求类型对应不同的 extra_info 结构；
格式为 JSON 序列化后的字符串
当request_type == TypeKeyGen时，request_detail 的结构定义如下：
参数
类型
描述
threshold
int
签名阈值
node_ids
[]string
参与生成私钥的节点 ID 集合
curve
int
支持的签名曲线。
0: SECP256K1
2: ED25519
task_id
string
任务 ID
extra_info 的结构定义如下：
参数
类型
描述
cobo_id
string
Cobo 内部 KeyGen 请求唯一 ID
api_request_id
string
用户通过 WaaS 接口传入的请求 ID，如果请求非 WaaS 接口，Cobo 内部会自动生成
当 request_type == TypeKeySign 时，request_detail 的结构定义如下：
参数
类型
描述
group_id
string
签名时使用的 GroupID
root_pub_key
string
根公钥
used_node_ids
[]string
签名时所使用的 nodeID 列表
bip32_path_list
[]string
使用的 bip32path 列表
msg_hash_list
[]string
待签名的消息 Hash 列表
tweak_list
[]string
待签名的 tweak 列表
signature_type
int32
使用的签名算法。 1: ecdsa 2: eddsa 3: schnorr
tss_protocol
int32
使用的TSS签名协议。 0: Unknown 1: GG18 2: Lindell 3: EDDSATss
task_id
string
任务 ID
extra_info 的结构定义如下：
参数
类型
描述
cobo_id
string
Cobo 内部 KeySign 请求唯一 ID
api_request_id
string
提币请求的请求 ID。如果是通过 API 提交的提币请求，则该字段与用户通过接口传入的 request_id 一致；如果是通过 Web 发起的提币，Cobo 内部会自动生成
transaction_type
TransactionTypeEnum
参考 TransactionTypeEnum 定义
operation
TransactionOperationEnum
参考TransactionOperationEnum定义
coin
string
资产名称
decimal
int
币种精度
from_address
string
资产出账地址
amount
string
（非必需）交易数额，请注意，这里的数值包含小数位，例如 BTC decimal 为8位，则这里的 100000000 实际为 1 个 BTC
to_address
string
提币到账地址
to_address_details
json
（非必需）资产接收信息列表，用于 UTXO 模型资产转账时使用，此处参数值需满足结构 list[ToAddressDetail] 的 json 字符串
fee
int
（非必需）对于 BTC 交易，该字段表示每字节对应的手续费，单位为 satoshi
gas_price
int
（非必需）燃料价格，ETH 类型账号模型适用，单位为 GWei
gas_limit
int
（非必需）燃料上限，ETH 类型账号模型适用
extra_parameters
json
交易的额外参数，详情请参考 API 文档 create_transaction 接口参数定义
replace_cobo_id
string
（非必需）RBF 覆盖的交易 Cobo ID
api_key
string
（非必需）通过 API 发起的提币所使用的 API_KEY
spender
string
（非必需） Custody Web 收发币钱包的提币员 email 信息
operator
string
（非必需） Custody Web web3 钱包的操作员 email 信息
custody_wallet_name
string
钱包名称
gas_station_child_id
string
gas station 交易的 Cobo ID
raw_tx_hex
string
交易 hash
note
string
交易备注信息
raw_tx_info
json
构造待签名消息的原始信息
ToAddressDetail
参数
类型
描述
to_address
string
提币到账地址
amount
string
交易数额，请注意，这里的数值包含小数位，例如 BTC decimal 为 8 位，则这里的 100000000 实际为 1 个 BTC
extra_parameters
参数
类型
描述
inputs_to_spend
list[Input]
指定需要作为交易输入的 Input 列表
inputs_to_exclude
list[Input]
指定不能作为交易输入的 Input 列表
Input
参数
类型
描述
tx_hash
string
交易 hash
vout_n
int
在交易中的索引号
TransactionTypeEnum
值
值名称
描述
100
TRANSACTION_FROM_WEB
web端发起的交易
102
TRANSACTION_FROM_API
api发起的交易
103
TRANSACTION_RBF_API_SPEEDUP
api发起的加速交易
104
TRANSACTION_RBF_WEB_SPEEDUP
web端发起的加速交易
105
TRANSACTION_RBF_API_DROP
api发起的废弃交易
106
TRANSACTION_RBF_WEB_DROP
web端发起的废弃交易
TransactionOperationEnum
值
值名称
描述
100
TRANSFER
资产转账
200
CONTRACT_CALL
合约调用
当 request_type == TypeKeyReshare 时，request_detail 的结构定义如下：
参数
类型
描述
old_group_id
string
老的 GroupID
root_pub_key
string
根公钥
curve
int
支持的签名曲线。
0: SECP256K1
2: ED25519
used_node_ids
[]string
参与私钥恢复（Reshare）的老节点 NodeID 列表
old_threshold
int
老的签名阈值
new_threshold
int
新的签名阈值
new_node_ids
[]string
参与私钥恢复（Reshare）的新节点 NodeID 列表；
私钥恢复成功后，这些节点会分别持有新的私钥分片
task_id
string
任务 ID
extra_info 的结构定义如下：
参数
类型
描述
cobo_id
string
Cobo 内部 Reshare 请求唯一 ID
api_request_id
string
用户通过 WaaS 接口传入的请求 ID，如果请求非 WaaS 接口，Cobo 内部会自动生成
CallbackResponse 定义
参数
类型
描述
status
int
状态码，当状态码为 0 时，表明回调服务器正常执行；当状态码为其他值时，表明回调服务器执行过程中出现了一些异常情况
request_id
string
回调请求 ID，与本次请求的 CallbackRequest 对象的request_id 保持一致
action
string
枚举值，代表后续的执行指令： [APPROVE, REJECT]
APPROVE 表示同意继续执行任务； REJECT 表示拒绝执行任务，具体的拒绝信息可以在 error 字段中输出
error
string
错误信息；
当 status 返回值不是 0 时，代表回调服务器内部出现的错误信息；
当 status 为 0，且风控结果为 REJECT 时，代表具体的风控拒绝信息。
注：当 TSS Node 无法接收到 HTTP 响应时，会持续重试请求回调服务器。当超过最大重试次数后，风控结果为 REJECT
Last updated
