SDK v0 to v1 Migration Guide

Wallet SDK v1 is not backwards compatible with v0. Quick links

Configuration — Detailed configuration guide
Preparing and signing a transaction — Preparing and signing transactions
Migration cheat sheet — Full v0 → v1 method lookup

We have removed the configure() and connect() pattern in favor of passing in a static configuration or a provider with ledger api capabilities. Static configuration initialization where we supply an auth config and a ledgerClientUrl:

import { SDK, localNetStaticConfig } from '@canton-network/wallet-sdk'

export default async function () {
    const sdk = await SDK.create({
        auth: {
            method: 'self_signed',
            issuer: 'unsafe-auth',
            credentials: {
                clientId: 'ledger-api-user',
                clientSecret: 'unsafe',
                audience: 'https://canton.network.global',
                scope: '',
            },
        },
        ledgerClientUrl: new URL('http://localhost:2975'),
        token: {
            validatorUrl: new URL('http://localhost:2000/api/validator'),
            registries: [
                new URL('http://localhost:2000/api/validator/v0/scan-proxy'),
            ],
            auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
        },
        amulet: {
            validatorUrl: localNetStaticConfig.LOCALNET_APP_VALIDATOR_URL,
            scanApiUrl: localNetStaticConfig.LOCALNET_SCAN_API_URL,
            auth: TOKEN_PROVIDER_CONFIG_DEFAULT,
            registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL,
        },
        asset: {
            registries: [localNetStaticConfig.LOCALNET_REGISTRY_API_URL],
            auth: TOKEN_PROVIDER_CONFIG_DEFAULT,
        },
    })

    const myParty = global.EXISTING_PARTY_1

    await sdk.token.utxos.list({ partyId: myParty })

    await sdk.amulet.traffic.status()

    // OR, you can defer loading config by calling .extend()

    const basicSDK = await SDK.create({
        auth: {
            method: 'self_signed',
            issuer: 'unsafe-auth',
            credentials: {
                clientId: 'ledger-api-user',
                clientSecret: 'unsafe',
                audience: 'https://canton.network.global',
                scope: '',
            },
        },
        ledgerClientUrl: new URL('http://localhost:2975'),
    })

    // Extend with token namespace
    const tokenExtendedSDK = await basicSDK.extend({
        token: {
            validatorUrl: new URL('http://localhost:2000/api/validator'),
            registries: [
                new URL('http://localhost:2000/api/validator/v0/scan-proxy'),
            ],
            auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
        },
    })

    // Now token namespace is available
    await tokenExtendedSDK.token.utxos.list({ partyId: myParty })

    // Can extend further with more namespaces
    const fullyExtendedSDK = await tokenExtendedSDK.extend({
        amulet: {
            validatorUrl: localNetStaticConfig.LOCALNET_APP_VALIDATOR_URL,
            scanApiUrl: localNetStaticConfig.LOCALNET_SCAN_API_URL,
            auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
            registryUrl: localNetStaticConfig.LOCALNET_REGISTRY_API_URL,
        },
    })

    // Now both token and amulet are available
    await fullyExtendedSDK.token.utxos.list({ partyId: myParty })
    await fullyExtendedSDK.amulet.traffic.status()
}

Provider intialization: The provider is an abstraction that ultimately interacts with the Ledger (JSON LAPI). This can be implemented for either a dApp consumer, direct ledger user, or alternative transport channels such as Wallet Connect.

// Notice that `auth` and `ledgerClientUrl` are no longer needed
// when supplying sdk with custom provider
const sdk = await SDK.create(config, provider)

Namespace changes

We have removed the controllers and replaced them with namespaces to appropriately segregate the service layer in terms of business context. When the sdk is initialized, it has access to the users, keys, ledger, and party namespaces. The amulet, token, asset, and events namespaces can be initialized with a separate config via the .extend() method.

Find your migration path

Jump to the page that matches the work you are migrating:

Allocate or list parties

Internal and external parties, offline signing, and replacing setPartyId.

Transfers, holdings, UTXOs, allocations

Replace tokenStandard transfer, holding, UTXO, and allocation APIs.

Users and rights

Create users and grant rights without separate admin/user ledger controllers.

Canton Coin, traffic, preapprovals, tap

Migrate amulet-specific traffic, preapproval, featured-app, and tap flows.

Prepare, sign, execute, ACS, DARs

Replace prepareSignExecuteAndWaitFor with the prepare/sign/execute chain.

Discover assets and instruments

List and find instruments through the dedicated asset namespace.

Keys and events

Key generation and ledger update/completion subscriptions.

Full method cheat sheet

Searchable v0 controller → v1 namespace method mapping table.

Removed functionality

The following methods have been removed: sdk.connect() No longer needed, SDK is connected on creation sdk.connectAdmin() No longer needed, admin operations are available in the ledger namespace and rights are extracted from the token. sdk.connectTopology() No longer needed, the grpc endpoints have been removed and replaced with ledger api endpoints. sdk.setPartyId() Pass partyId explicitly to each operation

sdk.setPartyId(myPartyId)
const holdingTransactionsmyPartyId = await sdk.tokenStandard?.listHoldingTransactions()
sdk.setPartyId(myPartyId2)
const holdingTransactionsmyPartyId2 = await sdk.tokenStandard?.listHoldingTransactions()

const holdingTransactionsmyPartyId = await token.holdings(myPartyId)
const holdingTransactionsmyPartyId2 = await token.holdings(myPartyId2)

In v0, the controllers and sdk were stateful. In v1, party information should be passed explicitly to each function. This enables acting as multiple parties and allows for thread safety in concurrent use.

Keys and events

The keys namespace is always available on the basic SDK. Use it instead of standalone key-pair helpers:

v0	v1
`createKeyPair()`	`sdk.keys.generate()`

The events namespace replaces ledger update and completion subscriptions from userLedger. Like amulet, token, and asset, it is an extended namespace that you configure at creation time or via .extend():

v0	v1
`sdk.userLedger.subscribeToUpdates`	`sdk.events.updates`
`sdk.userLedger.subscribeToCompletions`	`sdk.events.completions`

For the complete method map across all namespaces, see the migration cheat sheet.

Overview

SDKs

Language Bindings

CLI Tools

Development Tools

API Overview

Reference Projects

Namespace changes

Find your migration path

Allocate or list parties

Transfers, holdings, UTXOs, allocations

Users and rights

Canton Coin, traffic, preapprovals, tap

Prepare, sign, execute, ACS, DARs

Discover assets and instruments

Keys and events

Full method cheat sheet

Removed functionality

Keys and events

See also

​Namespace changes

​Find your migration path

Allocate or list parties

Transfers, holdings, UTXOs, allocations

Users and rights

Canton Coin, traffic, preapprovals, tap

Prepare, sign, execute, ACS, DARs

Discover assets and instruments

Keys and events

Full method cheat sheet

​Removed functionality

​Keys and events

​See also

Namespace changes

Find your migration path

Removed functionality

Keys and events

See also