Integration Architecture

High-Level Overview

If you have integrated your exchange with other BTC and other UTXO-based chains, the architecture presented here will be familiar and you will be able to reuse existing components and patterns. Before jumping into the discussion, it is important to map your preexisting concepts using the following mapping:

  • Transactions are identified in Canton using their globally unique update-id.

  • Each transaction is committed at specific record time that is assigned by the synchronizer used to commit the transaction.

  • Blockheight in BTC can be mapped to the record time of the Global Synchronizer in Canton Network.

  • BTC UTXOs map to what are usually called active contracts in Canton. Every Canton contract carries data of a specific Daml template type. For ease of understanding, we often refer to active contracts as “UTXOs” in this guide.

  • BTC addresses map to parties in Canton.

  • Validator nodes host parties and store their private data. Validator nodes also expose the Ledger API (LAPI), which can be used by an owner of a party to read their party’s state and transactions.

  • Canton is designed as a network-of-networks where each network is a separate synchronizer that is distinct and separate from other synchronizers. For example, the Global Synchronizer is a synchronizer that connects validators in its network.

  • Validator nodes can be connected to multiple synchronizers. Validator nodes merge the data streams from all connected synchronizers into a single logical stream, which is why they assign a local Ledger API offset to every transaction. These offsets are not comparable across validator nodes, but update-ids and record times are.

  • Transactions in Canton have a hierarchical structure that reflects the nested execution and visibility of Daml choices. This hierarchical structure guarantees privacy between parties in the same transaction. Different validator nodes may see different sub-trees of the same transaction depending on which parties they host.

  • Memos are stored in the transfer metadata using the splice.lfdecentralizedtrust.org/reason key. The Canton Network Token Standard defines this key and a way to parse these memo tags and other transfer information from transactions.

This guide provides a sample architecture and workflows for integrating an exchange with Canton. The expectation is that the integration components are reasonably thin wrappers over the functionality provided by the wallet SDK. The guide expects you to provide these components since they are mostly concerned integrating with your exchange’s internal systems and its requirements.

Component Overview

The following diagram shows the components to integrate an exchange’s internal systems with Canton Network. We explain the components in the subsections below.

Integration architecture component overview

Exchange Components

This guide assumes that there are Exchange Internal Systems that manage, among other things, the exchange’s internal ledger of Customer balances. These systems serve data to the Exchange UI, which is used by exchange customers to trade, observe their deposits, and request withdrawals of funds to their wallets.

The guide’s assumptions might not perfectly match your exchange’s actual architecture. We encourage you to consider them in spirit and map the diagram as best as possible.

Canton Integration Components

There are five Canton integration components:

  • The Exchange Validator Node is a Splice validator node that hosts your treasuryParty, which is the party you setup to control funds, receive deposits, and execute transfers for withdrawals. See Setup Exchange Parties for details on how to setup the treasuryParty. You can deploy and operate a validator yourself or use a node-as-a-service provider to operate it for you.

  • The Canton Integration DB is used to keep track of the state of withdrawals and the customer-attribution of the funds held by the treasuryParty. It is shown as a separate component in the diagram, but it could be part of an existing databases.

  • The Tx History Ingestion service uses the JSON Ledger API exposed by the Exchange Validator Node to read Daml transactions affecting the treasuryParty. It parses these transactions and updates the Canton Integration DB with the effect of these transactions (e.g. a successful deposit to a customer account).

  • The Withdrawal Automation service is responsible for executing withdrawals requested by the Exchange Internal Systems via the Canton Integration DB.

  • The Multi-Step Deposit Automation service is responsible for accepting or rejecting transfers from customers to their exchange accounts for CN tokens that do not support direct transfers. It is not necessary for an integration with Canton Coin, which does support direct, 1-step transfers.

You are expected to provide the three services and DBs listed above in a way that is accessible for querying by the Exchange Internal Systems. As explained in the High-Level Overview, you should be able to build these services as thin wrappers over the functionality provided by the wallet SDK and reuse the DB schemas from your existing UTXO-based integrations. We explain the expected functionality of the services and the state they store in the Canton Integration DB in the Integration Workflows section.

Third-Party Components

The purpose of the third-party components in the diagram above (in gray) is:

  • The Global Synchronizer serves the validator nodes to commit Daml transactions in a decentralized and fault-tolerant manner.

  • The Customer Validator Node is the validator node that hosts the customerParty which is used by the Customer to hold and transfer their funds.

  • The Customer Wallet is the wallet used by the customer to manage their funds and make transactions.

  • The Admin Validator Node is the validator node used by the token administrator to track the ownership records of the token and validate changes to them. We use the adminParty to refer to the party that represents them on ledger. Note that the adminParty for a decentralized token is hosted on multiple validator nodes. For example the adminParty for Canton Coin is hosted on every SV node.

  • The Registry API Server provides access to extra context to execute token transfers. This context is often only known to the token administrator, which is why access is provided to it off-ledger. The OpenAPI specification of the Registry API is maintained as part the Canton Network Token Standard definitions in the Splice repository.

Information Flows

The following diagram shows the information flows between the components. The main information flows of the Canton integration are highlighted using bold arrows. We explain them below.

Information flow diagram

There are three main information flows:

  1. Tx History Ingestion: ingests the transactions (tx) affecting the treasuryParty from the Exchange Validator Node into the Canton Integration DB. Arrow 1.a represents the transaction data being read using the /v2/updates/flats Ledger API endpoint using either plain HTTP or websockets. It is parsed by the Tx History Ingestion service to update the status of funds, deposits, and withdrawals in the Canton Integration DB (Arrow 1.b).

    This data is queried by Exchange Internal Systems (Arrow 1.c), for example to serve the Exchange UI. For brevity, the diagram shows direct access to the Canton Integration DB by the Exchange Internal Systems. However using a micro-services architecture, the Exchange Internal Systems would typically access the Canton Integration DB through a dedicated API layer. Choose whatever architecture best fits your exchange’s needs.

  2. Withdrawal Automation: starts with the Exchange Internal Systems writing a withdrawal request to the Canton Integration DB (Arrow 2.a). The Withdrawal Automation service reads the request from the DB (Arrow 2.b), and prepares, signs, and executes a Canton Network Token standard transfer corresponding to the withdrawal request using the Ledger API (Arrow 2.c).

    Note that the status of transfers becomes visible in the transaction history ingested by the Tx History Ingestion service; and is communicated to both the Exchange Internal Systems and the Withdrawal Automation service via the Canton Integration DB. This routing of information through the Canton Integration DB is intentional to simplify disaster recovery.

    Note also that the Withdrawal Automation may write back to the Canton Integration DB to mark a withdrawal as failed.

  3. Multi-Step Deposit Automation: is required to support offer-and-accept style transfers for tokens that do not support direct transfers. It relies on the Tx Ingestion Service to ingest transfer offers as part of Arrow 1.c.

    The workflow starts with the Multi-Step Deposit Automation service querying the Canton Integration DB to see whether there are pending transfers for deposits from customers (Arrow 3.a). The service then checks whether the deposit address specified in the transfer is known. If yes, it prepares, signs, and executes an accept transaction using the Ledger API (Arrow 3.b). If no, then it takes no action, and lets the transfer offer expire or be withdrawn by the sender.

    Note that there is an arrow from Multi-Step Deposit Automation back to the Canton Integration DB, as the Multi-Step Deposit Automation may write back to the Canton Integration DB to store that the transaction to accept the deposit could not be committed even after retrying multiple times.

The other information flows interact with the main flows as part of a deposit or withdrawal. We explain them in the Integration Workflows section.