开发回调服务器

HTTP 接口说明

回调服务器是一个 HTTP 服务器，需要支持如下接口的请求：

• Path

  • /v1/check

• Method

  • POST

• Body

  • 采用 x-www-form-urlencoded 编码的数据

解析 HTTP 请求

TSS Node 采用如下步骤构建 HTTP 请求，供对接参考：

1. 根据任务类型，生成对应的 CallbackRequest 结构体

2. 将 CallbackRequest 结构体进行 JSON 序列化，得到 CallbackRequestJsonString

3. 使用 CallbackRequestJsonString 作为 JWT 的 payload，使用自身的 RSA 私钥对其进行签名，构造 JWT

4. 使用 form 表单的形式进行 HTTP POST 提交，form 表单的 Key 是 TSS_JWT_MSG，Value 为上一步构造的 JWT

回调服务器接收到 HTTP 请求后，需要按照如下步骤进行解析：

1. 提取 HTTP POST 请求中提交的表单数据，Key 为 TSS_JWT_MSG，Value 即为 JWT

2. 使用本地保存的 TSS Node 的 RSA 公钥，对 JWT 进行签名检查

3. 提取 JWT 中的 payload，并对 payload 按照 CallbackRequest 结构体进行 JSON 反序列化

4. 根据 CallbackRequest 的类型，对其中的 meta 字段进行进一步的 JSON 反序列化，得到本请求的详细信息

开发风控检查相关逻辑

回调服务器内，需要结合自身业务上的需求，针对 CallbackRequest 的内容进行风控检查，确保本次请求的任务是合法的动用私钥分片的任务。

构建 HTTP 响应

回调服务器构建 HTTP 响应的步骤如下：

1. 根据风控检查结构，生成对应的 CallbackResponse 结构体

2. 将 CallbackResponse 结构体进行 JSON 序列化，得到 CallbackResponseJsonString

3. 使用 CallbackResponseJsonString 作为 JWT 的 payload，使用自身的 RSA 私钥对其进行签名，构造 JWT

4. 将上一步构造的 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