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: TypePing = 0

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

task_id

string

Task ID

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

tweak_list

[]string

Tweaks to be signed

signature_type

int32

Signature algorithms used

1: ECDSA

2: EdDSA

3: Schnorr

tss_protocol

int32

TSS signature protocols used

0: Unknown

1: GG18

2: Lindell

3: EDDSA

task_id

string

Task ID

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 address of the withdrawer; applicable to Cobo Custody Web

operator

string

(Optional) Email address of the operator; applicable to Cobo Custody Web

custody_wallet_name

string

Wallet name

gas_station_child_id

string

Cobo ID for Fee Station transaction

raw_tx_hex

string

Transaction hash

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

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

task_id

string

Task ID

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.

Last updated