Callback Server Requirements

HTTP API

The callback server is an HTTP server that supports the following endpoints:

• Path

  • /v1/check

• Method

  • POST

• Body

  • Encoded with x-www-form-urlencoded

HTTP Request Parsing

The TSS Node will follow the steps below to send the HTTP request:

• Generate CallbackRequest

• Serialize CallbackRequest to derive CallbackRequestJsonString

• Use CallbackRequestJsonString as the JWT payload and sign it using its RSA private key to create a JWT

• Submit the HTTP POST request via an HTML form with TSS_JWT_MSG as the key and JWT as the value

The callback server will follow the steps below once it receives the HTTP request:

• Retrieve the data in the HTTP POST request using TSS_JWT_MSG as the key and the JWT as the value

• Use the TSS Node’s RSA public key to validate the signed JWT

• Retrieve the payload in the JWT and deserialize it using CallbackRequest

• Deserialize the meta field to retrieve the information in the request

Risk Control

You'll need to perform a risk control for each CallbackRequest based on your organization’s business and security requirements to further validate the request.

HTTP Response

The callback server will send the HTTP response as follows:

• Generate CallbackResponse

• Serialize CallbackResponse to derive CallbackResponseJsonString

• Use CallbackResponseJsonString as the JWT payload and sign it using its RSA private key to create a JWT

• Use the JWT as the HTTP response and return it to the TSS Node

CallbackRequest Description

Parameter	Type	Description
request_id	string	Unique ID of the callback request
request_type	int	The types of callback requests, which will be an enum: TypeKeyGen = 1 TypeKeySign = 2 TypeKeyReshare = 3
request_detail	string	The details of the callback request; each type of the callback requests corresponds to a different request_detail structure; the format is a serialized JSON string
extra_info	string	Other information associated with the callback request; each type of the callback requests corresponds to a different extra_info structure; the format is a serialized JSON string

When request_type == TypeKeyGen, request_detail is as follows:

Parameter	Type	Description
threshold	int	Signature threshold
node_ids	[]string	Node IDs associated with the generation of all MPC key shares under the MPC wallet
curve	int	Signature algorithm that has been used; 0: SECP256K1 2: ED25519

extra_info:

Parameter	Type	Description
cobo_id	string	Unique ID of the key generation (KeyGen) request
api_request_id	string	Request ID passed in by the user using WaaS APIs; if the request is not sent via WaaS APIs, Cobo will automatically generate a Request ID

When request_type == TypeKeySign, request_detail is as follows:

Parameter	Type	Description
group_id	string	Group ID used during transaction signing
root_pub_key	string	MPC root extended public key
used_node_ids	[]string	Node IDs used during transaction signing
bip32_path_list	[]string	Address paths (BIP32)
msg_hash_list	[]string	Hashes to be signed

extra_info:

Parameter	Type	Description
cobo_id	string	Unique ID of the transaction signing (KeySign) request
api_request_id	string	Request ID of the withdrawal request; If the request is initialized via API, the value should be the same as request_id; If the request is initialized via Cobo Custody Web, Cobo will automatically generate a Request ID
transaction_type	TransactionTypeEnum	Please refer to TransactionTypeEnum
operation	TransactionOperationEnum	Please refer to TransactionOperationEnum
coin	string	Asset name
decimal	int	Decimal precision
from_address	string	Address from which assets are withdrawn
amount	string	(Optional) Transaction amount, which contains decimal places (e.g. one bitcoin is divisible to eight decimal places, and 100000000 represents 1 BTC)
to_address	string	Deposit address
to_address_details	json	(Optional) List of deposit addresses; applicable to the UTXO model; the value must meets the JSON structure of list[ToAddressDetail]
fee	int	(Optional) For BTC transaction, this field returns the transaction fees per byte; unit: satoshi
gas_price	int	(Optional) Gas fees; applicable to ETH; unit: GWei
gas_limit	int	(Optional) Gas limit; applicable to ETH
extra_parameters	json	Additional parameters for the transaction; for more information, please refer to the description of create_transaction
replace_cobo_id	string	(Optional) ID of a Cobo transaction that has been designated as RBF
api_key	string	(Optional) API_KEY of the withdrawal request initialized through API
spender	string	(Optional) Email information of the withdrawer; applicable to Cobo Custody Web
raw_tx	list[RawTx]	Raw transaction data
note	string	Transaction remarks
raw_tx_info	json	Raw information for constructing transaction to be signed

ToAddressDetail:

Parameter	Type	Description
to_address	string	Withdrawal address
amount	string	Transaction amount, which contains decimal places (e.g. one bitcoin is divisible to eight decimal places, and 100000000 represents 1 BTC)

extra_parameters:

Parameter	Type	Description
inputs_to_spend	list[Input]	Unspent Transaction Output (UTXO) to spend; this only applies in UTXO type of blockchains (e.g. bitcoin)
inputs_to_exclude	list[Input]	Unspent Transaction Output (UTXO) to exclude from spending; this only applies in UTXO type of blockchains (e.g bitcoin)

Input:

Parameter	Type	Description
tx_hash	string	Transaction hash
vout_n	int	Transaction index/no.

TransactionTypeEnum

Value	Name	Description
100	TRANSACTION_FROM_WEB	Transaction initiated via web
102	TRANSACTION_FROM_API	Transaction initiated via API
103	TRANSACTION_RBF_API_SPEEDUP	Transaction to speed up; initiated via API
104	TRANSACTION_RBF_WEB_SPEEDUP	Transaction to speed up; initiated via web
105	TRANSACTION_RBF_API_DROP	Transaction to cancel; initiated via API
106	TRANSACTION_RBF_WEB_DROP	Transaction to cancel; initiated via web

TransactionOperationEnum

Value	Name	Description
100	TRANSFER	Transfer
200	CONTRACT_CALL	Smart contract calls

RawTx

Parameter	Type	Description
raw_tx	string	Hex-encoded transaction information
derivation_path	string	Derivation path to be signed (e.g., "m/44/60/3/0/1")

When request_type == TypeKeyReshare, request_detail is as follows：

Parameter	Type	Description
old_group_id	string	Old Group ID
root_pub_key	string	MPC extended public key
curve	int	Signature algorithm that has been used; 0: SECP256K1 2: ED25519
used_node_ids	[]string	Selected Node IDs from the previous group that have been used for soft key recovery
old_threshold	int	Previous signature threshold
new_threshold	int	New Signature Threshold
new_node_ids	[]string	New Node IDs associated with the generation of all MPC key shares under the MPC wallet

extra_info:

Parameter	Type	Description
cobo_id	string	Unique ID of the soft key recovery (KeyReshare) request
api_request_id	string	Request ID passed in by the user using WaaS APIs; if the request is not sent via WaaS APIs, Cobo will automatically generate a Request ID

CallbackResponse Description

Parameter	Type	Description
status	int	Status; 0: callback server is normal; other values: callback server has an error
request_id	string	Request ID of the callback; the value must be the same as request_id in CallbackRequest
action	string	Instructions for task execution, which will be an enum: [APPROVE, REJECT] APPROVE: task should be executed; REJECT: task should be rejected, and the reason can be retrieved from the error field;
error	string	Error message; If the returned status is not 0, it indicates an error within the callback server If the returned status is 0 and action returns a “REJECT”, it indicates the reason for task rejection

Note: If the TSS Node fails to receive the HTTP response, it will continue to send requests to the callback server. In such cases, when the maximum number of retries is reached, the response will be categorized as REJECT.