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.
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" ); }
Next Steps
Wallet for Developers Detailed wallet integration guide.
Token Standard Implement the Canton Token Standard.
