@canton-network/core-provider-dapp

CIP-103 Provider implementations for Canton dApps. Extends @canton-network/core-splice-provider with wallet-mediated access to the dApp API (and proxied ledger calls).

Most applications should use @canton-network/dapp-sdk, which picks and wraps these providers. Use this package directly when building lower-level integrations or custom discovery / transport wiring.

Published on npm under Apache-2.0.

Install

npm install @canton-network/core-provider-dapp

Providers

flowchart LR
    dApp["dApp / dApp SDK"] --> Sync["DappSyncProvider"]
    dApp --> Async["DappAsyncProvider"]
    Sync -->|"postMessage"| Ext["Extension / desktop wallet"]
    Async -->|"HTTPS + SSE"| Gw["Remote wallet gateway"]
    Ext --> LAPI["JSON Ledger API"]
    Gw --> LAPI

Both implement the same Provider surface (request, on, emit, removeListener). Method and event types come from the generated OpenRPC clients (@canton-network/core-wallet-dapp-rpc-client and @canton-network/core-wallet-dapp-remote-rpc-client).

Sync vs Async

Sync — user interaction is in-process (popup / extension). Methods return results directly.

Async — user interaction cannot block. Methods that need approval return a userUrl (or similar) for the user to complete the action; the outcome arrives later as an event (for example connected, txChanged, messageSignature).

Usage

DappSyncProvider

Defaults to a WindowTransport bound to window. Pass a custom RpcTransport when testing or bridging a non-browser host.

import { DappSyncProvider } from '@canton-network/core-provider-dapp'

const provider = new DappSyncProvider()

provider.on('statusChanged', (status) => {
    console.log('connected:', status.connection.isConnected)
})

const { isConnected } = await provider.request({ method: 'isConnected' })
if (!isConnected) {
    await provider.request({ method: 'connect' })
}

const accounts = await provider.request({ method: 'listAccounts' })

DappAsyncProvider

Point at the remote gateway base URL. An optional session token opens the SSE event stream immediately; after IDP auth in a popup, the provider updates the token and reconnects SSE.

import { DappAsyncProvider } from '@canton-network/core-provider-dapp'

const provider = new DappAsyncProvider('https://wallet-gateway.example.com')

provider.on('connected', (status) => {
    console.log('session ready', status)
})

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

const connect = await provider.request({ method: 'connect' })
// If not already authenticated, open connect.userUrl for the user to log in.

Events

Subscribe with provider.on / provider.removeListener. Payloads follow CIP-103 / the OpenRPC event schemas.

DappSyncProvider bridges wallet-pushed notifications from WindowTransport into the provider listener map. DappAsyncProvider multiplexes a shared EventSource across instances for the same gateway URL + token.

window.canton

This package augments Window with an optional injected provider:

window.canton?: Provider<DappLedgerRpc>

DappLedgerRpc is the Sync dApp RPC map combined with Ledger ledgerApi operation types, matching a full browser wallet injection that can both speak CIP-103 and proxy ledger calls.

Related

Specs

• Sync OpenRPC: openrpc-dapp-api.json
• Async OpenRPC: openrpc-dapp-remote-api.json
• CIP-103