Usage

Using the dApp SDK from a Canton Network dApp

There are two ways to interact with the dApp API:

1. dApp SDK - A high-level SDK that wraps the Provider API with convenient methods and event handlers. This is the recommended approach for most applications.

2. Provider API - The low-level interface that follows the EIP-1193 pattern. Use this when you need direct control over the API or are integrating with existing provider-based infrastructure.

The examples below show both approaches side by side.

Setup

dApp SDK:

Import the dApp SDK:

import * as sdk from '@canton-network/dapp-sdk'

Initialize the SDK (recommended)

Call init() once early (e.g. on app mount). This registers adapters and attempts to restore a previously connected session without opening the wallet picker.

await sdk.init()

If you want to add or replace wallets (e.g. WalletConnect), see Adapter registration & wallet discovery (picker).

Provider API:

Import and create a provider instance:

const provider = window.canton

Request-Response Methods

Connecting to a Wallet

Establish a connection to the Wallet. This initiates the authentication flow if the user is not already authenticated.

dApp SDK:

await sdk.init() // optional if already called
const result = await sdk.connect()
console.log(result.isConnected) // true if connected

Provider API:

const result = await provider.request<ConnectResult>({
    method: 'connect',
})
console.log(result.isConnected) // true if connected

Disconnecting from a Wallet

Close the session between the client and the Wallet.

dApp SDK:

await sdk.disconnect()

Provider API:

await provider.request({ method: 'disconnect' })

Checking the Connection Status

Check the connection status of the Wallet. The status returns an object containing network connection- and session-related information.

dApp SDK:

sdk.status()
    .then((result) => {
        setStatus(
            `${result.connection.isConnected ? 'connected' : 'disconnected'}`
        )
    })
    .catch(() => setStatus('disconnected'))

Provider API:

provider
    .request<StatusEvent>({ method: 'status' })
    .then((result) => {
        setStatus(
            `${result.connection.isConnected ? 'connected' : 'disconnected'}`
        )
    })
    .catch(() => setStatus('disconnected'))

Checking if Connected (without login)

Check if the user is connected without triggering the login flow.

dApp SDK:

const result = await sdk.isConnected()
console.log(result.isConnected)

Provider API:

const result = await provider.request<ConnectResult>({
    method: 'isConnected',
})
console.log(result.isConnected)

Getting the Active Network

Retrieve details about the network the user is connected to.

dApp SDK:

const network = await sdk.getActiveNetwork()
console.log(network.networkId) // e.g., 'canton:da-mainnet'

Provider API:

const network = await provider.request<Network>({
    method: 'getActiveNetwork',
})
console.log(network.networkId)

Listing Accounts

List all accounts (parties) the user has access to in the Wallet.

dApp SDK:

const accounts = await sdk.listAccounts()
console.log(accounts)

Provider API:

const accounts = await provider.request<Account[]>({
    method: 'listAccounts',
})
console.log(accounts)

Getting the Primary Account

Get the account currently set as primary by the user.

dApp SDK:

const account = await sdk.getPrimaryAccount()
console.log(account.partyId)

Provider API:

const account = await provider.request<Account>({
    method: 'getPrimaryAccount',
})
console.log(account.partyId)

Signing a Message

Sign an arbitrary string message using the primary account’s private key.

dApp SDK:

const signature = await sdk.signMessage('Hello, Canton!')
console.log(signature)

Provider API:

const signature = await provider.request<string>({
    method: 'signMessage',
    params: { message: 'Hello, Canton!' },
})
console.log(signature)

Executing a Transaction

Prepare, sign, and execute a Daml transaction. This method handles the full lifecycle: preparing the commands, requesting user approval/signature, and submitting to the ledger.

dApp SDK:

const createPingCommand = (party: string) => ({
    commands: [
        {
            CreateCommand: {
                templateId: '#AdminWorkflows:Canton.Internal.Ping:Ping',
                createArguments: {
                    id: `my-test-${new Date().getTime()}`,
                    initiator: party,
                    responder: party,
                },
            },
        },
    ],
})

// Get the primary party the user selected in the Wallet
const primaryParty = (await sdk.listAccounts()).find((w) => w.primary)?.partyId

// Request user's signature and execute the transaction
await sdk.prepareExecute(createPingCommand(primaryParty!))

Provider API:

const createPingCommand = (party: string) => ({
    commands: [
        {
            CreateCommand: {
                templateId: '#AdminWorkflows:Canton.Internal.Ping:Ping',
                createArguments: {
                    id: `my-test-${new Date().getTime()}`,
                    initiator: party,
                    responder: party,
                },
            },
        },
    ],
})

// Get the primary party the user selected in the Wallet
const accounts = await provider.request<Account[]>({ method: 'listAccounts' })
const primaryParty = accounts.find((w) => w.primary)?.partyId

// Request user's signature and execute the transaction
await provider.request({
    method: 'prepareExecute',
    params: createPingCommand(primaryParty!),
})

Calling the Ledger API

Proxy requests to the Canton JSON Ledger API. The request is authenticated using the user’s session.

dApp SDK:

const response = await sdk.ledgerApi({
    requestMethod: 'GET',
    resource: '/v2/version',
})
console.log(JSON.parse(response.response))

Provider API:

const response = await provider.request<LedgerApiResponse>({
    method: 'ledgerApi',
    params: {
        requestMethod: 'GET',
        resource: '/v2/version',
    },
})
console.log(JSON.parse(response.response))

Events

The dApp API emits events to notify your application of state changes. Subscribe to these events to keep your UI in sync with the Wallet state.

Listening for Connection Status Changes

Receive notifications when the connection status or session state changes.

dApp SDK:

sdk.onStatusChanged((status) => {
    console.log('Status changed:', status)
    console.log('Connected:', status.connection.isConnected)
})

Provider API:

provider.on('statusChanged', (status: StatusEvent) => {
    console.log('Status changed:', status)
    console.log('Connected:', status.connection.isConnected)
})

Listening for Account Changes

Receive notifications when accounts are added, removed, or when the primary account changes.

dApp SDK:

sdk.onAccountsChanged((accounts) => {
    console.log('Accounts changed:', accounts)
    const primary = accounts.find((a) => a.primary)
    console.log('Primary account:', primary?.partyId)
})

Provider API:

provider.on('accountsChanged', (accounts: Account[]) => {
    console.log('Accounts changed:', accounts)
    const primary = accounts.find((a) => a.primary)
    console.log('Primary account:', primary?.partyId)
})

Listening for Transaction Changes

Receive notifications about the lifecycle of transactions initiated via prepareExecute. The event payload includes the transaction status (pending, signed, executed, failed) and relevant details.

dApp SDK:

sdk.onTxChanged((tx) => {
    console.log('Transaction status:', tx.status)
    if (tx.status === 'executed') {
        console.log('Update ID:', tx.payload.updateId)
    }
})

Provider API:

provider.on('txChanged', (tx: TxChangedEvent) => {
    console.log('Transaction status:', tx.status)
    if (tx.status === 'executed') {
        console.log('Update ID:', tx.payload.updateId)
    }
})

Removing Event Listeners

When your component unmounts or you no longer need to listen for events, remove the listeners to prevent memory leaks.

dApp SDK:

const handleStatus = (status) => console.log(status)

// Subscribe
sdk.onStatusChanged(handleStatus)

// Unsubscribe (when cleaning up)
sdk.offStatusChanged(handleStatus)

Provider API:

const handleStatus = (status: StatusEvent) => console.log(status)

// Subscribe
provider.on('statusChanged', handleStatus)

// Unsubscribe (when cleaning up)
provider.removeListener('statusChanged', handleStatus)

Adapter / Provider information

Get the current provider

sdk.getConnectedProvider() returns the raw CIP-103 provider for the currently active discovery session, or null if you are not connected. Use this when you need direct access to provider.request(...), to subscribe to provider-level events, or to instantiate the Wallet SDK (upcoming feature).

const provider = sdk.getConnectedProvider()
if (!provider) {
    // Not connected yet
    return
}

const status = await provider.request({ method: 'status' })
console.log(status.connection.isConnected)

Adapter registration & wallet discovery (picker)

See Adapter registration & wallet discovery (picker) for multiple ways to register adapters and what appears in the wallet picker.