This article is targeted at WaaS 1.0 users who are considering upgrading to WaaS 2.0. It introduces the benefits of the upgrade and provides step-by-step instructions to successfully complete the upgrade process.
Key enhancements in WaaS 2.0
WaaS 2.0 is a major upgrade from WaaS 1.0, designed to support diverse Web3 scenarios such as payments, tokenization, and automated fund management. It enables enterprises and developers to build Web3 applications more efficiently and cost-effectively.
The three core benefits of upgrading to WaaS 2.0 are:
- Enhanced capabilities: Introduces new modules including Payment Solutions, Tokenization, Fee Station, Auto-sweep, Travel Rule, and more.
- More efficient development: A unified API architecture reduces the number of API calls required to accomplish the same functionality, lowering integration and maintenance complexity.
- Improved operations: Upgraded webhook functionality supports more event types and provides built-in tools such as logs, retries, and simulated testing, enhancing observability and debugging efficiency.
For a complete introduction to WaaS 2.0, see Introduction to WaaS 2.0.
The following table summarizes the key enhancements introduced in WaaS 2.0 compared with WaaS 1.0:
| Dimension | WaaS 1.0 | WaaS 2.0 |
|---|
| API Architecture | Wallet-type-based structure: The same business functionality required different API operations depending on wallet type. For example: - Withdrawals for Custodial Wallets and MPC Wallets required separate API operations.
- Querying a transaction by different IDs (such as transaction hash, transaction ID, internal ID) also required separate API operations.
| Scenario-driven structure: The same business functionality can now be completed with a single API operation. For example: - The token transfer operation can handle deposits and withdrawals for all wallet types.
- Transaction queries are unified under a single API operation and support any type of ID.
|
| New Feature Modules | N/A | - Payment: A complete cryptocurrency payment solution.
- Tokenization: Issue and manage tokenized on-chain assets.
- Fee Station: Handle gas fees and manage unified cost settlements.
- Auto-sweep: Automatically consolidate token balances.
- Travel Rule: Meet more comprehensive regulatory compliance requirements.
- Cobo Portal Apps: Develop and manage apps within the Cobo Portal ecosystem.
|
| Webhook Mechanism | Only supported transaction status notifications. | - Support for more event types: Includes transaction, wallet, address, balance, and TSS-related events.
- Built-in debugging tools: Provides logs, automatic retries, and simulated event testing.
|
| Developer Tools | Provided basic SDKs. | Expands the developer ecosystem with additional tools: - Cobo CLI: A command-line tool for rapid testing and debugging.
- UI Toolkit: Pre-built UI components to accelerate app development.
|
Technical changes and migration reference
This section is intended for developers. It explains the key technical changes between WaaS 1.0 and WaaS 2.0 in areas such as API design, authentication, and callback mechanisms, and provides a comparison table of common API operations to help you migrate quickly.
Technical changes
The following table summarizes the key technical changes between WaaS 1.0 and WaaS 2.0, including API design, authentication, and callback mechanisms.
| WaaS 1.0 | WaaS 2.0 |
|---|
| API design | HTTP endpoints supporting the GET and POST methods. | RESTful API structured into distinct domains, such as wallets, transactions, and webhooks. The API follows resource-oriented design principles for endpoint definition and supports standard HTTP methods including GET, POST, PUT, and DELETE. |
| API key and authentication | - The API key is wallet-specific, meaning it can only be used to access the associated wallet.
- An SECP256k1 signature is used for authenticating an API request.
| - The API key is organization-specific and can be used to access multiple wallets. For more information, refer to Register an API key.
- An ED25519 signature is used for authenticating an API request.
|
| Transaction notification | Supports transaction status-related events only. | |
| Withdrawal confirmation | A mechanism used for confirming withdrawals initiated through WaaS API. | - This feature is called “Callback” in 2.0.
- The data structure of the callback message differs from 1.0.
|
| Supported wallet types | - Custodial Wallets
- MPC Wallets
| |
| Asset model | - A coin is considered a unique asset type.
- A coin represents a specific pairing of a chain and a cryptocurrency, such as ETH_USDT.
| - A token is considered a unique asset type, except for Exchange Wallets, which consider an “asset” to be a unique asset type.
- A token represents a specific pairing of a chain and a cryptocurrency, such as ETH_USDT.
- An asset represents a cryptocurrency stored in your linked exchange account, such as USDT.
|
| Balance model | - [Custodial Wallets] Coin balances can be calculated for an entire wallet but not for each address.
- [MPC Wallets] Coin balances can be calculated for each address within the wallet, but not for an entire wallet.
| - [Custodial Wallets] Token balances can be calculated for the entire wallet but not for each address.
- [MPC Wallets] Token balances can be calculated for the entire wallet or each address.
|
| Balances and amounts | - Balances and amounts are denominated in the smallest units of the cryptocurrency. For example, Bitcoin balances and amounts are denominated in Satoshis.
- The parameters
abs_balance and abs_amount are denominated in the primary unit of the cryptocurrency, such as BTC for Bitcoin.
| - Balances and amounts are denominated in the primary unit of the cryptocurrency, such as BTC for Bitcoin.
- As an example, for a deposit of 1.2 BTC, the deposit amount is recorded as
120,000,000 in 1.0 and 1.2 in 2.0.
|
| Address generation | - [Custodial Wallets] Addresses are generated based on a specified coin, such as ETH_USDT, and can then be used by all coins on the same chain.
- [MPC Wallets] Addresses are generated based on a specified chain, such as ETH, and can then be used by all coins on the same chain.
| [Custodial Wallets / MPC Wallets] Addresses are generated based on a specified chain, such as ETH, and can then be used by all tokens on the same chain. |
| Transaction ID | The unique ID of a transaction. | - The transaction ID in 2.0 follows the UUID format which differs from the format used in 1.0.
- The transaction ID in 1.0 is termed as “Cobo ID” in 2.0. You can continue to use Cobo ID to query a transaction.
|
API operation comparison
The following table lists the API operations needed for common wallet operations in WaaS 1.0 and 2.0 respectively. You can refer to this table when migrating your code from 1.0 to 2.0.
Upgrade to 2.0
This section introduces the detailed steps to upgrade from WaaS 1.0 to 2.0.
Prerequisites
Reach out to our support team at help@cobo.com to migrate from Cobo Custody to Cobo Portal.
Get started with WaaS 2.0
Follow the instructions in Send your first request to set up your account, create and register your API key, integrate a WaaS SDK if necessary, and send your first API request to the WaaS 2.0 service.
Rewrite your code
Once you complete the initial setup, it is time to rewrite your code by replacing the 1.0 API operations with 2.0 operations. Refer to API operation comparison for a detailed comparison between 1.0 and 2.0 API operations.
You can also refer to Get started with Custodial Wallets (Asset Wallets) for a step-by-step guide on how to create a Custodial Wallet (Asset Wallet), generate wallet addresses, and receive and withdraw tokens. Guides for other wallet types will be available in the future.
Set up webhook and callback endpoints
Set up the webhook and callback endpoints and register them in Cobo Portal.
To understand webhook events, callback messages, and the differences in webhook/callback mechanisms between WaaS 1.0 and WaaS 2.0, refer to Introduction to webhooks and callbacks.
To learn the detailed steps of the setup, see Set up a callback or webhook endpoint. To register the endpoint, see Register a webhook endpoint and Register a callback endpoint.
The endpoints you set up for WaaS 1.0 will not receive any messages from the WaaS 2.0 service.
