Integration Patterns

Documentation Index

Fetch the complete documentation index at: https://docs.canton.network/llms.txt Use this file to discover all available pages before exploring further.

Integration Patterns

Common patterns for integrating Canton Network building blocks into your applications

This page describes common patterns for integrating Canton Network building blocks into applications. These patterns help you design effective integrations while respecting Canton’s privacy model.

Pattern Overview

flowchart TB
    subgraph Patterns[Integration Patterns]
        WAL[Wallet Integration<br>CC management]
        TOKEN[Token Operations<br>Standard tokens]
        APP[App Integration<br>Third-party apps]
        DATA[Data Access<br>Ledger queries]
    end

    subgraph Your App[Your Application]
        FE[Frontend]
        BE[Backend]
        SC[Smart Contracts]
    end

    WAL --> FE
    TOKEN --> SC
    APP --> BE
    DATA --> BE

Wallet Integration Pattern

Use Case

Add Canton Coin management to your application, allowing users to:

• View their CC balance
• Transfer CC to other parties
• Top up traffic for transactions

Architecture

flowchart LR
    subgraph YourApp[Your Application]
        UI[User Interface]
        AUTH[Auth Service]
        API[Your API]
    end

    subgraph Wallet[Wallet Integration]
        SDK[Wallet SDK]
        LAPI[Ledger API]
    end

    UI --> AUTH
    UI --> API
    API --> SDK
    SDK --> LAPI

Key Considerations

Privacy Implications

• Users see only their own balance
• Transfer details visible only to sender and receiver
• Your application backend sees what it’s authorized to see

Token Operations Pattern

Use Case

Create, manage, and transfer tokens following the Canton Token Standard (CIP-0056).

Architecture

flowchart TB
    subgraph Contracts[Smart Contracts]
        TOKEN[Your Token Template]
        HOLDING[Holding Interface]
        TRANSFER[Transfer Interface]
    end

    subgraph Standard[Token Standard]
        CIP[CIP-0056 Interfaces]
    end

    TOKEN --> CIP
    HOLDING --> CIP
    TRANSFER --> CIP

Implementation Approach

-- Implement token standard interfaces
template MyToken
  with
    issuer : Party
    holder : Party
    amount : Decimal
  where
    signatory issuer
    observer holder

    -- Implement standard holding interface
    interface instance HoldingInterface for MyToken where
      view = HoldingView with
        custodian = issuer
        owner = holder
        amount = amount

    -- Standard transfer choice
    choice Transfer : ContractId MyToken
      with
        newHolder : Party
      controller holder
      do
        create this with holder = newHolder

Key Considerations

Application Integration Pattern

Use Case

Integrate with other Canton Network applications, such as:

• DeFi protocols
• Identity services
• Data feeds

Architecture

flowchart LR
    subgraph YourApp[Your Application]
        SC1[Your Contracts]
        BE1[Your Backend]
    end

    subgraph ThirdParty[Third-Party App]
        SC2[Their Contracts]
        API2[Their API]
    end

    SC1 <--> |Daml interfaces| SC2
    BE1 <--> |REST/gRPC| API2

Integration Approaches

Key Considerations

Data Access Pattern

Use Case

Query ledger data for reporting, analytics, or application state.

Options

Architecture with PQS

flowchart TB
    subgraph YourApp[Your Application]
        API[Your API]
        REPORT[Reporting]
    end

    subgraph Canton[Canton Infrastructure]
        PART[Validator Node]
        LAPI[Ledger API]
        PQS[PQS]
        PQSDB[(PQS PostgreSQL)]
    end

    API --> LAPI
    LAPI --> PART
    PART --> PQS
    REPORT --> PQSDB
    PQS --> PQSDB

Key Considerations

Privacy-Aware Design

All integration patterns must account for Canton’s privacy model:

Design Principles

Common Mistakes

Error Handling Patterns

Integrations should handle common error scenarios:

Retry Strategy

async function submitWithRetry<T>(command: Command, maxRetries = 3): Promise<T> {
  for (let attempt = 0; attempt < maxRetries; attempt++) {
    try {
      return await ledgerApi.submit(command);
    } catch (error) {
      if (isRetryable(error) && attempt < maxRetries - 1) {
        await sleep(Math.pow(2, attempt) * 1000);
        continue;
      }
      throw error;
    }
  }
  throw new Error("Max retries exceeded");
}

Next Steps

Mirrored from Canton Network official documentation (CC-BY-4.0) by CC Privacy Club for learning purposes.