Integrate MPC Wallets (User-Controlled Wallets)

This guide gets you started with using MPC Wallets (User-Controlled Wallets). For a high-level overview of what User-Controlled Wallets are, see Introduction to User-Controlled Wallets. By following this guide, you will be able to build a User-Controlled Wallet by using the Cobo Wallet-as-a-Service (WaaS) 2.0 API and UCW SDK to:

Complete the initial setup

Create projects with the Client Backend or Cobo Portal
Install the UCW SDK
Initialize the UCW SDK
Create a vault
Create a Main Group

Create a wallet and an address

Create a transaction

Back up and restore

Back up and restore your key shares with iCloud
Create a Recovery Group
Perform recovery from Recovery Group
Perform disaster recovery

You can choose between the 2-2, 2-3, or 3-3 signature scheme for your User-Controlled Wallets. For the purposes of this documentation, we will use the 2-2 signature scheme.

This guide uses the development environment in all its code samples. It is recommended that you use the development environment to test your new features first before deploying them to the production environment.

Technical architecture

The following diagram illustrates the components within a fully-functioning User-Controlled Wallet:

You only need to focus on implementing the Client Backend and Client App. The Cobo Backend, Cobo TSS Relay, and UCW SDK are managed and provided by Cobo.

Use the following tabs to learn more about each component in the technical architecture:

Client Backend
Client App
Cobo Backend
Cobo TSS Relay
UCW SDK
Server Co-Signer

Your server responsible for interacting with the Cobo Backend using the WaaS 2.0 API. Client Backend is also used to communicate with your Client Apps. To get started, you can download our Client Backend Demo here to set up a working example of a User-Controlled Wallet before developing your own implementation.

To learn about the general architecture of an MPC Wallet, see Organization-Controlled Wallet’s Technical architecture.

Data model

The following diagram presents an example of a User-Controlled Wallet data model that you can reference when developing your own implementation. It provides a clear representation of how users, vaults, wallets, transactions, addresses, TSS requests, groups, and TSS Nodes interact in a working User-Controlled Wallet. Use the tabs below to learn more about each entity and attribute in the data model.

User

Attributes:

user_id: Unique identifier for the user.
email: User’s email address.

Relationships:

Has a direct relationship with Vault, indicating that a user has exactly one vault and each vault corresponds to exactly one user.
Owns User TSS Node, where a user has zero or more TSS Nodes and each TSS Node is owned by exactly one user.

Vault

Attributes:

cobo_vault_id: Unique identifier for the vault in the Cobo system.
name: The name of the vault.
cobo_main_group_id: The currently active Main Group this vault owns that holds the authority to sign transactions.
- Even though a vault can own multiple Main Groups and Recovery Groups, only one Main Group can be active at any given time.
cobo_project_id: The project to which the vault belongs.
status: The vault’s current status.

Relationships:

Contains Wallet, meaning that a vault can hold one or more wallets, and a wallet belongs to exactly one vault.
Contains TSS Request, showing that a vault may have zero or more pending or processed TSS requests, and each TSS request corresponds to exactly one vault.
Owns Group, indicating that a vault owns multiple Main Groups and Recovery Groups.

Wallet

Attributes:

cobo_vault_id: Identifier linking the wallet to the vault that contains this wallet.
cobo_wallet_id: Unique identifier for the wallet.
name: The name of the wallet.

Relationships:

Contains Transaction, showing that a wallet can include zero or more transactions, and each transaction corresponds to exactly one wallet.
Contains Address, meaning a wallet can have zero or more blockchain addresses associated with it, and each address corresponds to exactly one wallet.

Transaction

Attributes:

cobo_transaction_id: Unique identifier for the transaction in the Cobo system.
request_id: The request ID associated with the transaction.
cobo_wallet_id: The wallet associated with the transaction.
address: The blockchain address involved in the transaction.
amount: The amount involved in the transaction.
type: Type of transaction (e.g., deposit, withdrawal).

Relationships:

Belongs to Wallet, indicating that each transaction is linked to exactly one wallet.

Address

Attributes:

address: The blockchain address associated with the wallet.
path: The derivation path of the address.
chain_id: The ID of the blockchain network associated with the address.
cobo_wallet_id: Identifier linking the address to its wallet.

Relationships:

Belongs to Wallet, indicating that each address is part of exactly one wallet.

TSS Request

Attributes:

cobo_tss_request_id: Unique identifier for the TSS request.
cobo_target_key_holder_group_id: The target key share holder group involved in the TSS request.

Relationships:

Belongs to Vault, showing that TSS requests are linked to exactly one vault, and each vault contains zero or more TSS requests.

Group

Attributes:

cobo_key_share_holder_group_id: Unique identifier for the key share holder group.
cobo_vault_id: Unique identifier for the vault that owns this key share holder group.
group_type: Type of key share holder group (i.e. Main Group or Recovery Group).

Relationships:

Contains User TSS Node, meaning that a group can hold multiple TSS Nodes, and each TSS Node corresponds to exactly one group.

User TSS Node

Attributes:

user_id: Unique identifier for the user of the TSS Node.
tss_node_id: Unique identifier for the TSS Node.
holder_name: The name of the holder.
status: The status of the TSS Node.

Relationships:

Belongs to Group, meaning that a key share holder group contains zero or more TSS Nodes, and each TSS Node belongs to exactly one key share holder group.
Owned by User. Each user owns to zero or more TSS Nodes, and each TSS Node is owned by exactly one user.

Prerequisites

Follow the instructions in Send your first request to set up your account and send your first API request to the WaaS 2.0 service.
If you choose to use a WaaS SDK instead of manually writing the API requests, refer to the SDK guide corresponding to the programming language of your choice (Python, Java, Go, JavaScript) to integrate the SDK into your Client Backend.
Prepare some test tokens as you will need them when testing the deposit feature. To know which test tokens you can use, refer to Query chain and token information. In most cases, you can use XTN as the test token.
It is highly recommended that you set up a callback endpoint to receive and approve withdrawal requests and a webhook endpoint to receive real-time notifications regarding transaction status updates and other events of your concern. To learn how to set up and register webhook and callback endpoints, refer to Introduction to webhooks and callbacks.

1. Complete the initial setup

Create projects with the Client Backend or Cobo Portal.

You can create projects with either the Client Backend or directly on Cobo Portal.

To create projects with the Client Backend, call the Create project operation.
To create projects with Cobo Portal, see our upcoming Product Manuals for User-Controlled Wallets.

Install UCW SDK

To install the UCW SDK, see our upcoming article on “Get started with UCW SDK”, which shows how you can download the UCW SDK, add it to your iOS app development environment, initialize the UCW SDK in your Client App, and invoke a UCW SDK operation.

Initialize UCW SDK

This section outlines the sequence of operations for initializing the UCW SDK from a Client App. The initialization process is straightforward, with a single interaction between the Client App and the UCW SDK to ensure that the UCW SDK is set up and ready for further operations.The UCW SDK needs to be initialized in the Client App to facilitate communication with the Cobo TSS Relay. This initialization also sets up the TSS Node ID, a unique identifier for the node participating in key generation.

Sequence of operations

Initialize UCW SDK
- Client App → UCW SDK
  1. Client App sends a request to initialize the UCW SDK by calling the Initialize Secrets operation.
- UCW SDK → Client App
  1. UCW SDK returns a success message indicating that the initialization has been completed successfully.

Create a vault

This section explains the sequence of operations involved in creating a vault. The process involves interactions between the Client App, Client Backend, and the Cobo Backend.

Sequence of operations

Send vault creation request to Client Backend
- Client App → Client Backend
  1. Client App sends a request to the Client Backend to create a vault.
Create the vault in Cobo Backend
- Client Backend → Cobo Backend
  1. Client Backend forwards the request to the Cobo Backend to create a new vault for the specified project by calling the Create vault operation.
- Cobo Backend → Client Backend
  1. Cobo Backend responds with the newly created vault ID.
Binding the vault to the user
- Client Backend
  1. Client Backend binds the newly created vault ID to an associated User ID.
Return vault information to Client App
- Client Backend → Client App
  1. Client Backend returns the vault information, including the vault ID and other metadata, to the Client App.

Create a Main Group

This section details the sequence of operations involved in creating a Main Group and performing a key generation process using the Client App, UCW SDK, Client Backend, Cobo Backend, and Cobo TSS Relay.

Sequence of operations

Open UCW SDK in the Client App
- Client App → UCW SDK
  1. Client App opens a UCW SDK instance by calling the Create UCW class and Create UCWPublic class operations.
- UCW SDK → Client App
  1. UCW SDK returns an instance of the UCWSDK and UCWSDKPublic class that is used for further interactions.
Retrieve TSS Node ID
- Client App → UCW SDK
  1. Client App calls the Get TSS Node ID operation on the UCWSDKPublic to retrieve the TSS Node ID.
- UCW SDK → Client App
  1. UCW SDK responds with the TSS Node ID.
Initialize Main Group creation
- Client App → Client Backend
  1. Client App sends a request to the Client Backend to generate the Main Group for the vault specified by vault ID, also passing the TSS Node ID.
- Client Backend → Cobo Backend
  1. Client Backend calls the Create key share holder group operation, instructing the Cobo Backend to create a Main Group.
- Cobo Backend → Client Backend
  1. Cobo Backend responds with a key share holder group ID, indicating that the Main Group has been successfully created.
- Client Backend
  1. Client Backend binds the key share holder group ID to the vault ID.
  2. Client Backend binds the TSS Node ID with the key share holder group ID.
Initialize key generation request
- Client Backend → Cobo Backend
  1. Client Backend calls the Create TSS request operation, instructing the Cobo Backend to initiate the key generation process.
- Cobo Backend → Client Backend
  1. Cobo Backend responds with a TSS request ID and a status of the TSS request.
- Client Backend → Client App
  1. Client Backend sends the TSS request ID and the TSS request status to the Client App, notifying the Client App that the TSS request is pending key share holder confirmations.
Cobo Backend risk controls and TSS request creation
- Cobo Backend
  1. Cobo Backend performs risk control checks before forwarding the request to the Cobo TSS Relay.
- Cobo Backend → Cobo TSS Relay
  1. Cobo Backend sends the request to the Cobo TSS Relay to create a TSS request.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay confirms the request creation with a 200 OK response.
Monitor the TSS request status on Client Backend
- Cobo Backend → Client Backend You can optionally monitor the status of the TSS request on the Client Backend through either webhook or polling.
  - Webhook option
    1. Cobo Backend sends a webhook to the Client Backend with the current status of the TSS request.
      To see the available webhook event types, see Webhook event types.
      
      To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option
    1. Client Backend polls the Cobo Backend to retrieve the status of the TSS request by calling the Get TSS request operation.
    2. Cobo Backend returns the status of the TSS request.
- (Optional) Monitor TSS request status on Client App
  - Client Backend → Client App You can optionally monitor the status of the TSS request on the Client App through either app notification or polling.
    - App notification option
      1. Client Backend pushes a notification to the Client App with the TSS request status.
    - Polling option
      1. Client App polls the Client Backend for the TSS request status.
      2. Client Backend returns the TSS request status.
Review and approval of TSS request in Client App
- Client App → UCW SDK
  1. Client App calls the UCW SDK to get the pending TSS requests by calling the Get TSS requests operation.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK forwards the request to the Cobo TSS Relay.
  2. Cobo TSS Relay returns the TSS request information to UCW SDK.
- UCW SDK → Client App
  1. The UCW SDK returns the TSS request information to the Client App.
- Client App
  1. User reviews the TSS request on the Client App.
- Client App → UCW SDK
  1. User uses the Client App to approve the TSS request. The Client App calls the Approve TSS requests operation and passes in the TSS request ID.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK participates in the key generation process by forwarding user’s approval to the Cobo TSS Relay.
  2. Cobo TSS Relay returns the key generation result to the UCW SDK.
- Client App → UCW SDK
  1. Client App checks the status of the TSS request with the UCW SDK by calling the Get TSS requests operation.
- UCW SDK → Client App
  1. UCW SDK returns the updated status of the TSS request.
Key generation result transmission
- Client App → Client Backend
  1. Client App sends the key generation result to the Client Backend.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay sends the key generation result to the Cobo Backend.
(Optional) Monitor key generation result on Client Backend
- Cobo Backend → Client Backend You can optionally monitor the key generation result on Client Backend through either webhook or polling.
  - Webhook option
    1. Cobo Backend sends the key generation result via a webhook event to the Client Backend.
      To see the available webhook event types, see Webhook event types.
      
      To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling Option
    1. Client Backend polls the Cobo Backend for the key generation result by calling the Get TSS request operation.
    2. Cobo Backend returns the key generation result.

2. Create a wallet and an address

This section details the sequence of operations involved in creating a wallet and generating an address within your User-Controlled Wallets. The process involves interactions between the Client App, Client Backend, and Cobo Backend.

Sequence of operations

Estimate transaction fee
- Client App → Client Backend
  1. Client App initiates a fee estimation request by sending transaction data to the Client Backend.
- Client Backend → Cobo Backend
  1. Client Backend forwards the request to the Cobo Backend to estimate the fee for the transaction by calling the Estimate transaction fee operation.
- Cobo Backend → Client Backend
  1. Cobo Backend processes the request and returns the estimated fee information.
- Client Backend → Client App
  1. Client Backend returns the estimated fee information to the Client App.
- Client App
  1. User reviews and selects the appropriate fee using the Client App.
Submit transaction
- Client App → Client Backend
  1. After selecting the fee, the Client App submits the transaction data to the Client Backend for processing.
- Client Backend → Cobo Backend
  1. Client Backend forwards the transaction data to the Cobo Backend to initiate the transaction by calling the Transfer token operation.
- Cobo Backend → Client Backend
  1. Cobo Backend processes the request and returns the transaction ID and other transaction information.
- Client Backend → Client App
  1. Client Backend returns the transaction information to the Client App.
Perform risk controls and TSS request processing
- Cobo Backend
  1. Cobo Backend performs internal risk control checks before proceeding with the transaction.
- Cobo Backend → Cobo TSS Relay
  1. Cobo Backend sends a request to the Cobo TSS Relay to create a TSS request for the transaction.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay confirms the creation of the TSS request with a 200 OK response.
Monitor transaction status on Client Backend
- Cobo Backend → Client Backend (13) You can monitor the status of the transaction on the Client Backend through either webhook or polling.
  - Webhook option Cobo Backend sends transaction updates to the Client Backend using webhooks.
    To see the available webhook event types, see Webhook event types.
    
    To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option Client Backend polls the Cobo Backend to get updates on the transaction status by calling the Get transaction information operation. Cobo Backend returns the transaction status to the Client Backend.
(Optional) Monitor transaction status on Client App
- Client Backend → Client App You can optionally send the transaction status to the Client App through push notifications or polling.
  - Push notification option
    1. Client Backend sends a push notification to the Client App with the transaction status.
  - Polling option
    1. Client App polls the Client Backend for the transaction status.
    2. Client Backend returns the transaction status to the Client App.
Review and approve the transaction
- Client App → UCW SDK
  1. Client App calls the UCW SDK to retrieve detailed transaction information by calling the Get transactions operation.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK forwards the request to the Cobo TSS Relay to retrieve the transaction information.
  2. Cobo TSS Relay returns the transaction information to the UCW SDK.
- UCW SDK → Client App
  1. UCW SDK returns the transaction information to the Client App.
- Client App
  1. User reviews the transaction information on the Client App.
- Client App → UCW SDK
  1. Client App approves the transaction using the UCW SDK by calling the Approve transactions operation, initiating the signing process.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK participates in the signing process by forwarding the transaction approval to the Cobo TSS Relay.
  2. Cobo TSS Relay returns the signature to the UCW SDK.
Update transaction status
- Client App → UCW SDK
  1. Client App checks the status of the transaction via the UCW SDK by calling the Get transactions operation.
- UCW SDK → Client App
  1. UCW SDK returns the current transaction status to the Client App.
- Client App → Client Backend
  1. Client App sends a transaction status update to the Client Backend.
Finalize the transaction
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay sends the final signature to the Cobo Backend.
- Cobo Backend → Client Backend
  1. You can get the final transaction information on the Client Backend via webhook or polling.
  - Webhook Option Cobo Backend sends the final transaction information via webhook to the Client Backend.
    To see the available webhook event types, see Webhook event types.
    
    To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option Client Backend polls the Cobo Backend for the final transaction information by calling the Get transaction information operation. Cobo Backend returns the transaction status to the Client Backend.

3. Create a transaction

This section details the process of estimating transaction fees, submitting a transaction, and participating in the signing process for a transaction in your User-Controlled Wallets. It outlines the sequence of interactions between the Client App, UCW SDK, Client Backend, Cobo Backend, and Cobo TSS Relay.

Sequence of operations

Estimate transaction fee
- Client App → Client Backend
  1. Client App initiates a fee estimation request by sending transaction data to the Client Backend.
- Client Backend → Cobo Backend
  1. Client Backend forwards the request to the Cobo Backend to estimate the fee for the transaction by calling the Estimate transaction fee operation.
- Cobo Backend → Client Backend
  1. Cobo Backend processes the request and returns the estimated fee information.
- Client Backend → Client App
  1. Client Backend returns the estimated fee information to the Client App.
- Client App
  1. User reviews and selects the appropriate fee using the Client App.
Submit transaction
- Client App → Client Backend
  1. After selecting the fee, the Client App submits the transaction data to the Client Backend for processing.
- Client Backend → Cobo Backend
  1. Client Backend forwards the transaction data to the Cobo Backend to initiate the transaction by calling the Transfer token operation.
- Cobo Backend → Client Backend
  1. Cobo Backend processes the request and returns the transaction ID and other transaction information.
- Client Backend → Client App
  1. Client Backend returns the transaction information to the Client App.
Perform risk controls and TSS request processing
- Cobo Backend
  1. Cobo Backend performs internal risk control checks before proceeding with the transaction.
- Cobo Backend → Cobo TSS Relay
  1. Cobo Backend sends a request to the Cobo TSS Relay to create a TSS request for the transaction.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay confirms the creation of the TSS request with a 200 OK response.
Monitor transaction status on Client Backend
- Cobo Backend → Client Backend (13) You can monitor the status of the transaction on the Client Backend through either webhook or polling.
  - Webhook option Cobo Backend sends transaction updates to the Client Backend using webhooks.
    To see the available webhook event types, see Webhook event types.
    
    To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option Client Backend polls the Cobo Backend to get updates on the transaction status by calling the Get transaction information operation. Cobo Backend returns the transaction status to the Client Backend.
(Optional) Monitor transaction status on Client App
- Client Backend → Client App You can optionally send the transaction status to the Client App through push notifications or polling.
  - Push notification option
    1. Client Backend sends a push notification to the Client App with the transaction status.
  - Polling option
    1. Client App polls the Client Backend for the transaction status.
    2. Client Backend returns the transaction status to the Client App.
Review and approve the transaction
- Client App → UCW SDK
  1. Client App calls the UCW SDK to retrieve detailed transaction information by calling the Get transactions operation.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK forwards the request to the Cobo TSS Relay to retrieve the transaction information.
  2. Cobo TSS Relay returns the transaction information to the UCW SDK.
- UCW SDK → Client App
  1. UCW SDK returns the transaction information to the Client App.
- Client App
  1. User reviews the transaction information on the Client App.
- Client App → UCW SDK
  1. Client App approves the transaction using the UCW SDK by calling the Approve transactions operation, initiating the signing process.
- UCW SDK → Cobo TSS Relay
  1. UCW SDK participates in the signing process by forwarding the transaction approval to the Cobo TSS Relay.
  2. Cobo TSS Relay returns the signature to the UCW SDK.
Update transaction status
- Client App → UCW SDK
  1. Client App checks the status of the transaction via the UCW SDK by calling the Get transactions operation.
- UCW SDK → Client App
  1. UCW SDK returns the current transaction status to the Client App.
- Client App → Client Backend
  1. Client App sends a transaction status update to the Client Backend.
Finalize the transaction
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay sends the final signature to the Cobo Backend.
- Cobo Backend → Client Backend
  1. You can get the final transaction information on the Client Backend via webhook or polling.
  - Webhook Option Cobo Backend sends the final transaction information via webhook to the Client Backend.
    To see the available webhook event types, see Webhook event types.
    
    To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option Client Backend polls the Cobo Backend for the final transaction information by calling the Get transaction information operation. Cobo Backend returns the transaction status to the Client Backend.

4. Backup and restore

Back up and restore your key shares with iCloud

This section describes the process of exporting encrypted Secrets from one instance of the UCW SDK in a Client App, saving it to an iCloud server, and subsequently importing the Secrets into another instance of the UCW SDK in a different Client App.

A Secrets file contains all essential information about the TSS Node, including your TSS Node ID and key shares.

The following sequence diagram details the interactions between the two Client Apps, their respective UCW SDK instances, and the iCloud server.

Sequence of operations

Open UCW SDK 1 in Client App 1
- Client App 1 → UCW SDK 1
  1. Client App 1 opens an instance of the UCW SDK 1 by calling the Create UCW class operation.
- UCW SDK 1 → Client App 1
  1. UCW SDK 1 returns an instance of itself to Client App 1, which can now be used to perform further operations.
Export Secrets
- Client App 1 → UCW SDK 1
  1. Client App 1 calls the Export Secrets operation on the UCW SDK 1 instance, providing a passphrase for encryption.
- UCW SDK 1 → Client App 1
  1. UCW SDK 1 encrypts the Secrets using the provided passphrase and returns the encrypted Secrets.
Save encrypted Secrets to iCloud
- Client App 1 → iCloud Server
  1. Client App 1 saves the encrypted Secrets to iCloud for secure storage.
Load encrypted Secrets from iCloud
- iCloud Server → Client App 2
  1. Client App 2 retrieves the encrypted Secrets from iCloud for use in its own UCW SDK 2 instance.
Import Secrets into UCW SDK 2
- Client App 2 → UCW SDK 2
  1. Client App 2 calls the Import Secrets operation and provides the passphrase and the encrypted Secrets, which allows UCW SDK 2 to import the Secrets.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 decrypts and imports the Secrets successfully, confirming the operation with Client App 2.

Create a Recovery Group

This section outlines the flow for creating a Recovery Group and performing a key generation process using the UCW SDK. The process involves multiple Client Apps, the Client Backend, the Cobo Backend, and the Cobo TSS Relay.

Sequence of operations

Initialize UCW SDKs 2 and 3 in Client Apps 2 and 3
- Client Apps 2, 3 → UCW SDK 2, 3
  1. Client Apps 2 and 3 initiate their respective UCW SDKs 2 and 3 instances by calling the Create UCW class operation.
- UCW SDK 2, 3 → Client Apps 2, 3
  1. UCW SDKs 2 and 3 return the UCW SDK 2 and 3 instances to Client Apps 2 and 3.
- Client Apps 2, 3 → UCW SDK 2, 3
  1. Client Apps 2 and 3 obtain the TSS Node IDs by calling the Get TSS Node ID operation.
- UCW SDK 2, 3 → Client Apps 2, 3
  1. UCW SDKs 2 and 3 return the TSS Node IDs to Client Apps 2 and 3.
Create Recovery Group
- Client App 1
  1. User provides Client App 1 with the TSS Node IDs from Client Apps 2 and 3.
- Client App 1 → Client Backend
  1. Client App 1, after receiving the TSS Node IDs from Client Apps 2 and 3, submits a request to the Client Backend to create a Recovery Group.
- Client Backend → Cobo Backend
  1. Client Backend forwards the request to the Cobo Backend by calling the Create key share holder group operation, specifying the Recovery Group details and key share holders.
- Cobo Backend → Client Backend
  1. The Cobo Backend returns the key share holder group ID to the Client Backend.
Initialize key generation request
- Client Backend → Cobo Backend
  1. Client Backend submits a request to the Cobo Backend to use the Main Group to create key shares for your Recovery Group by calling the Create TSS request operation and specifying KenGenFromKeyGroup as the type.
- Cobo Backend → Client Backend
  1. Cobo Backend processes the request and returns a TSS request ID.
- Cobo Backend
  1. Cobo Backend performs risk controls.
- Cobo Backend → Cobo TSS Relay
  1. Cobo Backend sends the request to the Cobo TSS Relay.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay confirms the request completion with a 200 OK message.
Monitor TSS request status on Client Backend
- Cobo Backend → Client Backend
  1. You can monitor the TSS request status through webhooks or polling.
  - Webhook option Cobo Backend sends updates to the Client Backend using webhooks.
    To see the available webhook event types, see Webhook event types.
    
    To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
  - Polling option The Client Backend polls the Cobo Backend for the status of the TSS request by calling the Get TSS request operation. The Cobo Backend returns the TSS request status to Client Backend.
(Optional) Monitor TSS request status on Client Apps 1, 2, and 3
- Client Backend → Client Apps 1, 2, and 3 You can optionally monitor the TSS request status on Client Apps 1, 2, and 3 through either push notification or polling.
  - Push notification option
    1. (15 & 18) Client Backend sends a push notification to Client Apps 1, 2, and 3.
  - Polling option
    1. (16 & 19) Client Apps 1, 2, and 3 send Client Backend requests for the TSS request status.
    2. (17 & 20) Client Backend sends Client Apps 1, 2, and 3 the TSS request status.
Review and approve TSS requests in Client Apps
- Client App 1 → UCW SDK 1
  1. Client App 1 retrieves the pending TSS request by calling the Get TSS requests operation.
- UCW SDK 1 → Client App 1
  1. UCW SDK 1 returns the TSS request information to Client App 1.
- Client App 1
  1. User reviews the TSS request information on Client App 1.
- Client App 1 → UCW SDK 1
  1. After review, Client App 1 approves the TSS request by calling the Approve TSS requests operation.
UCW SDK 1
1. UCW SDK 1 waits for the other TSS Nodes (Client Apps 2 and 3) to approve the request.
Client Apps 2, 3 → UCW SDK 2, 3
1. Client Apps 2 and 3 retrieve the pending TSS request by calling the Get TSS requests operation.
UCW SDK 2, 3 → Client Apps 2, 3
1. UCW SDK 2 and 3 return the TSS request information to Client Apps 2 and 3.
Client Apps 2, 3
1. Users review the TSS request information on Client Apps 2 and 3.
Client Apps 2, 3 → UCW SDK 2, 3
1. After review, Client Apps 2 and 3 approve the TSS request by calling the Approve TSS requests operation.
UCW SDK 2, 3
1. UCW SDK 2 and 3 wait for other TSS Node (Client App 1) to complete the approval process.
Participate in key generation
- UCW SDK 1, 2, 3 → Cobo TSS Relay
  1. (31 & 32) UCW SDKs 1, 2, and 3 participate in the key generation process by interacting with the Cobo TSS Relay.
  2. (33 & 34) The Cobo TSS Relay returns the key generation results to each UCW SDK instance.
Finalize the TSS request for key generation
- Client App 1 → UCW SDK 1
  1. Client App 1 retrieves the status of the TSS request by calling the Get TSS requests operation.
- UCW SDK 1 → Client App 1
  1. UCW SDK returns the TSS request status and key generation result.
- Client App 1 → Client Backend
  1. Client App 1 sends an update to the Client Backend to inform the TSS request result.
- Client Apps 2, 3 → UCW SDK 2, 3
  1. Client Apps 2 and 3 retrieve the status of the TSS request by calling the Get TSS requests operation.
- UCW SDK 2, 3 → Client Apps 2, 3
  1. UCW SDKs 2 and 3 return the TSS request status.
- Client Apps 2, 3 → Client Backend
  1. Client Apps 2 and 3 send updates to the Client Backend to inform the TSS request status.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay sends the TSS request result to the Cobo Backend.
Monitor the result in Cobo Backend
- Cobo Backend → Client Backend
  1. Client Backend receives the key generation result through webhook or polling.
    - Webhook option Cobo Backend sends the final key generation result via webhook to the Client Backend.
      To see the available webhook event types, see Webhook event types.
      
      To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
    - Polling option Client Backend polls the Cobo Backend to retrieve the final result by calling the Get TSS request operation. Cobo Backend sends the final result to Client Backend.

Perform recovery from Recovery Group

If the key shares have been lost in a Main Group, you can recover the key shares from a Recovery Group. This section describes the process of generating keys from a Recovery Group for a Main Group using the UCW SDK. The flow involves multiple Client Apps, the Client Backend, the Cobo Backend, and the Cobo TSS Relay.

Sequence of operations

Initialize UCW SDK 4 in Client App 4
- Client App 4 → UCW SDK 4
  1. Client App 4 initiates its UCW SDK instance by calling the Create UCW class operation.
- UCW SDK 4 → Client App 4
  1. UCW SDK 4 returns the UCW SDK 4 instance.
- Client App 4 → UCW SDK 4
  1. Client App 4 requests the TSS Node ID by calling the Get TSS Node ID operation.
- UCW SDK 4 → Client App 4
  1. UCW SDK 4 returns the TSS Node ID.
Fetch Recovery Groups
- Client App 4 → Client Backend
  1. Client App 4 requests the available Recovery Groups from the Client Backend.
- Client Backend → Client App 4
  1. Client Backend returns the available Recovery Groups.
Select and submit a Recovery Group
- Client App 4
  1. User selects a Recovery Group to use.
- Client App 4 → Client Backend
  1. After selecting a Recovery Group, Client App 4 submits a request to the Client Backend to recover the Main Group.
- Client Backend → Cobo Backend
  1. Client Backend forwards the request to the Cobo Backend by calling the Create key share holder group operation and creating a Main Group.
- Cobo Backend → Client Backend
  1. Cobo Backend returns the Main Group ID.
- Client Backend → Cobo Backend
  1. Client Backend submits a request to the Cobo Backend to initiate a key generation request by calling the Create TSS requests operation and specifying Recovery as the type.
- Cobo Backend → Client Backend
  1. Cobo Backend returns the TSS request ID.
- Cobo Backend
  1. Cobo Backend executes risk controls.
- Cobo Backend → Cobo TSS Relay
  1. Cobo Backend forwards the request to the Cobo TSS Relay.
- Cobo TSS Relay → Cobo Backend
  1. Cobo TSS Relay confirms the request with a 200 OK message.
Monitor TSS request status on Client Backend
- Cobo Backend → Client Backend
  1. Client Backend monitors the TSS request status through webhooks or polling.
    - Webhook option Cobo Backend sends a webhook to notify the Client Backend of the TSS request status.
      To see the available webhook event types, see Webhook event types.
      
      To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
    - Polling option Client Backend polls the TSS request status by calling the Get TSS request operation. Cobo Backend sends the TSS request status to Client Backend.
(Optional) Monitor TSS request status on Client Apps 2, 3, and 4
- Client Backend → Client Apps 2, 3, and 4 You can optionally monitor the TSS request status on Client Apps 2, 3, and 4 through push notifications or polling.
  - Push notification option
    1. (17 & 20) Client Backend sends TSS request status through push notifications to Client Apps 2, 3, and 4.
  - Polling option
    1. (18 & 21) Client Apps 2, 3, and 4 send a request to Client Backend requesting the TSS request status.
    2. (19 & 22) Client Backend returns the TSS request status to Client Apps 2, 3, and 4.
Review and approve TSS requests
- Client App 2, 3 → UCW SDK 2, 3
  1. Client Apps 2 and 3 retrieve the pending TSS request by calling the Get TSS requests operation.
- UCW SDK 2, 3 → Client App 2, 3
  1. UCW SDK 2 and 3 return the TSS request information.
- Client App 2, 3
  1. Users review the TSS request on Client Apps 2 and 3.
- Client App 2, 3 → UCW SDK 2, 3
  1. After reviewing the request, Client Apps 2 and 3 approve it by calling the Approve TSS request operation.
- UCW SDK 2, 3
  1. UCW SDK 2 and 3 wait for other TSS Nodes to complete their approval process.
- Client App 4 → UCW SDK 4
  1. Client Apps 4 retrieves the pending TSS request by calling the Get TSS requests operation.
- UCW SDK 4 → Client App 4
  1. UCW SDK 4 returns the TSS request information.
- Client App 4
  1. User reviews the pending TSS request on Client Apps 4.
- Client App 4 → UCW SDK 4
  1. After reviewing the request, Client App 4 approves it by calling the Approve TSS request operation.
- UCW SDK 4
  1. UCW SDK 4 waits for other TSS Nodes to complete their approval process.
Participate in key generation
- UCW SDK 2, 3, 4 → Cobo TSS Relay
  1. (33 & 34) UCW SDKs 2, 3, and 4 participate in the key generation process by communicating with the Cobo TSS Relay.
- Cobo TSS Relay → UCW SDK 2, 3, 4
  1. (35 & 36) The Cobo TSS Relay returns the key generation results to each UCW SDK instance.
Finalize the TSS request
- Client Apps 2, 3, 4 → UCW SDK 2, 3, 4
  1. (37 & 40) Client Apps 2, 3, and 4 retrieve the TSS request status by calling the Get TSS request operation.
- UCW SDK 2, 3, 4 → Client Apps 2, 3, 4
  1. (38 & 41) UCW SDK 2, 3, and 4 return the TSS request status to Client Apps 2, 3, and 4.
- Client Apps 2, 3, 4 → Client Backend
  1. (39 & 42) After receiving the TSS request result, Client Apps 2, 3, and 4 send updates to the Client Backend.
- Cobo TSS Relay → Cobo Backend
  1. The Cobo TSS Relay sends the final key generation result to the Cobo Backend.
Monitor the result in Cobo Backend
- Cobo Backend → Client Backend
  1. Client Backend receives TSS request result through webhooks or polling.
    - Webhook option Cobo Backend sends the final key generation result via webhooks.
      To see the available webhook event types, see Webhook event types.
      
      To see how to set up your Client Backend to receive webhook events, see Set up a callback or webhook endpoint.
    - Polling option Client Backend polls the final key generation result by calling the Get TSS requests operation. Cobo Backend sends Client Backend the key generation result.

Perform disaster recovery

In the unlikely event that Cobo is no longer in service, you can reconstruct the root extended private key that corresponds to your User-Controlled Wallets. All child private keys that correspond to the wallet addresses in this User-Controlled Wallets can then be derived from this root extended private key. The flow involves multiple Client Apps, UCW SDKs, and the Client Backend.

Sequence of operations

Fetch disaster recovery addresses
- Client App 2 → Client Backend
  1. Client App 2 requests disaster recovery information from the Client Backend.
- Client Backend → Client App 2
  1. Client Backend returns the relevant addresses and path for disaster recovery.
Export key shares of Client App 3
- Client App 3 → UCW SDK 3
  1. Client App 3 opens its UCW SDK 3 instance by calling the Create UCW class operation.
- UCW SDK 3 → Client App 3
  1. UCW SDK 3 returns the UCW SDK 3 instance.
- Client App 3 → UCW SDK 3
  1. Client App 3 exports its recovery key shares using a passphrase for encryption by calling the Export recovery key shares operation.
- UCW SDK 3 → Client App 3
  1. UCW SDK 3 returns the passphrase-encrypted JSON data of key shares.
Export key shares of Client App 2
- Client App 2 → UCW SDK 2
  1. Client App 2 opens its UCW SDK 2 instance by calling the Create UCW class operation.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns the UCW SDK 2 instance.
- Client App 2 → UCW SDK 2
  1. Client App 2 exports its recovery key shares using a passphrase for encryption by calling the Export recovery key shares operation.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns the passphrase-encrypted JSON data of key shares.
Initiate key recovery in Client App 2
- Client App 2 → UCW SDK 2
  1. Client App 2 opens a UCWRecoverKey instance in UCW SDK 2 by calling the Create UCW recover key operation.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns the UCWRecoverKey instance.
Import key shares from Client Apps 2 and 3
- Client App 2 → UCW SDK 2
  1. Client App 2 imports the recovery key shares from UCW SDK 2’s exported passphrase-encrypted JSON data of key shares by calling the Import recovery key share operation and passing in UCW SDK 2’s exported passphrase-encrypted JSON data of key shares.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns success.
- Client App 2 → UCW SDK 3
  1. Client App 2 imports the recovery key shares from UCW SDK 3’s exported passphrase-encrypted JSON data of key shares by calling the Import recovery key share operation and passing in UCW SDK 3’s exported passphrase-encrypted JSON data of key shares
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns success.
Recover the root extended private key
- Client App 2 → UCW SDK 2
  1. After importing the key shares, Client App 2 initiates the recovery of the full root extended private key for the specified address by calling the Recovery private key operation.
- UCW SDK 2 → Client App 2
  1. UCW SDK 2 returns the root extended private key and its child private keys.

Feel free to share your feedback to improve our documentation!

Overview

Get started

Webhooks and callbacks

Transactions

MPC Wallets

Resources

Integrate MPC Wallets (User-Controlled Wallets)

Technical architecture

Data model

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Prerequisites

1. Complete the initial setup

Sequence of operations

Sequence of operations

Sequence of operations

2. Create a wallet and an address

Sequence of operations

3. Create a transaction

Sequence of operations

4. Backup and restore

Sequence of operations

Sequence of operations

Sequence of operations

Sequence of operations

Overview

Get started

Webhooks and callbacks

Transactions

MPC Wallets

Resources

​Technical architecture

​Data model

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Attributes:

​Relationships:

​Prerequisites

​1. Complete the initial setup

​Sequence of operations

​Sequence of operations

​Sequence of operations

​2. Create a wallet and an address

​Sequence of operations

​3. Create a transaction

​Sequence of operations

​4. Backup and restore

​Sequence of operations

​Sequence of operations

​Sequence of operations

​Sequence of operations

Technical architecture

Data model

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Attributes:

Relationships:

Prerequisites

1. Complete the initial setup

Sequence of operations

Sequence of operations

Sequence of operations

2. Create a wallet and an address

Sequence of operations

3. Create a transaction

Sequence of operations

4. Backup and restore

Sequence of operations

Sequence of operations

Sequence of operations

Sequence of operations