Integration Patterns

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

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

Key Considerations

Consideration	Approach
Authentication	Integrate with your auth system; map users to parties
Balance display	Query via Wallet SDK; cache appropriately
Transfers	Submit via Ledger API; handle async confirmation
Error handling	Handle insufficient balance, network errors

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

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

Consideration	Approach
Interoperability	Follow CIP-0056 for wallet compatibility
Authorization	Define clear signatory/controller roles
Privacy	Token balances visible only to holders

Application Integration Pattern

Use Case

Integrate with other Canton Network applications, such as:

DeFi protocols
Identity services
Data feeds

Architecture

Integration Approaches

Approach	When to Use
On-ledger	Multi-party workflows requiring atomic execution
Off-ledger API	Read-only queries, non-transactional operations
Hybrid	Combine both for complete integration

Key Considerations

Consideration	Approach
Interface compatibility	Use published Daml interfaces
Authorization	Understand party requirements
Privacy	Know what data is shared through composition
Versioning	Handle contract upgrades

Data Access Pattern

Use Case

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

Options

Method	Use Case	Performance
Ledger API	Real-time queries, streaming	Good
PQS	Complex queries, analytics	Best for reads
Transaction trees	Historical data, audit	Depends on volume

Architecture with PQS

PQS connects to the validator node via the Ledger API to receive transaction updates, then stores the data in its own PostgreSQL database for querying.

Key Considerations

Consideration	Approach
Query complexity	Simple: Ledger API; Complex: PQS
Latency requirements	Real-time: Ledger API; Batch: PQS
Data volume	High volume: PQS with indexing
Privacy scope	Only query data for authorized parties

Privacy-Aware Design

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

Design Principles

Principle	Application
Minimal visibility	Request only necessary observer rights
Party design	Don’t create parties unnecessarily
Divulgence awareness	Understand what composing contracts reveals
Audit consideration	Plan for audit visibility from the start

Common Mistakes

Mistake	Impact	Solution
Over-observing	Unnecessary data exposure	Minimize observers
Public queries	Expecting global state	Query party-scoped data
Ignoring divulgence	Unintended data sharing	Map transaction composition

Error Handling Patterns

Integrations should handle common error scenarios:

Error	Cause	Handling
Insufficient traffic	Not enough CC for fees	Prompt for top-up
Authorization failure	Party not authorized	Check party setup
Timeout	Network or validator issues	Retry with backoff
Contract not found	Archived or never existed	Refresh state

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");
}

Pattern Overview

Wallet Integration Pattern

Use Case

Architecture

Key Considerations

Privacy Implications

Token Operations Pattern

Use Case

Architecture

Implementation Approach

Key Considerations

Application Integration Pattern

Use Case

Architecture

Integration Approaches

Key Considerations

Data Access Pattern

Use Case

Options

Architecture with PQS

Key Considerations

Privacy-Aware Design

Design Principles

Common Mistakes

Error Handling Patterns

Retry Strategy

Next Steps

Wallet for Developers

Token Standard

​Pattern Overview

​Wallet Integration Pattern

​Use Case

​Architecture

​Key Considerations

​Privacy Implications

​Token Operations Pattern

​Use Case

​Architecture

​Implementation Approach

​Key Considerations

​Application Integration Pattern

​Use Case

​Architecture

​Integration Approaches

​Key Considerations

​Data Access Pattern

​Use Case

​Options

​Architecture with PQS

​Key Considerations

​Privacy-Aware Design

​Design Principles

​Common Mistakes

​Error Handling Patterns

​Retry Strategy

​Next Steps

Wallet for Developers

Token Standard

Pattern Overview

Wallet Integration Pattern

Use Case

Architecture

Key Considerations

Privacy Implications

Token Operations Pattern

Use Case

Architecture

Implementation Approach

Key Considerations

Application Integration Pattern

Use Case

Architecture

Integration Approaches

Key Considerations

Data Access Pattern

Use Case

Options

Architecture with PQS

Key Considerations

Privacy-Aware Design

Design Principles

Common Mistakes

Error Handling Patterns

Retry Strategy

Next Steps