Token¶

The token namespace provides methods to manage token operations including transfers, holdings, UTXOs, and allocations on the Canton Network. In v1, the token namespace replaces the tokenStandard controller from v0.

Availability and extensibility¶

The token namespace is an extended namespace that requires configuration. You can initialize it either during SDK creation or later using the extend() method.

Option 1: Initialize during SDK creation

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

export default async function () {
    const sdk = await SDK.create({
        auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
        ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL,
        token: global.TOKEN_NAMESPACE_CONFIG,
    })

    const partyId = EXISTING_PARTY_1

    // token namespace is now available
    await sdk.token.utxos.list({ partyId })
}

Option 2: Add token namespace later using extend()

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

export default async function () {
    // Create basic SDK first
    const basicSDK = await SDK.create({
        auth: global.TOKEN_PROVIDER_CONFIG_DEFAULT,
        ledgerClientUrl: localNetStaticConfig.LOCALNET_APP_USER_LEDGER_URL,
    })

    // Extend with token namespace when needed
    const extendedSDK = await basicSDK.extend({
        token: global.TOKEN_NAMESPACE_CONFIG,
    })

    const partyId = EXISTING_PARTY_1

    // Now token namespace is available
    await extendedSDK.token.utxos.list({ partyId })
}

Key changes from v0 to v1¶

v0 used the tokenStandard controller with implicit party context set via sdk.setPartyId().

v1 uses the token namespace where you:

Pass partyId explicitly to each operation
Initialize the namespace with configuration
Access operations through logical groupings (transfer, utxos, allocation)

This enables thread-safe concurrent operations and clearer code organization.

Transfers¶

Creating transfers

Accepting, rejecting, or withdrawing transfers

Listing pending transfers

Holdings¶

Holdings represent the transaction history of token ownership for a party.

You can also specify offsets for pagination:

const holdings = await sdk.token.holdings({
    partyId,
    afterOffset: 10,
    beforeOffset: 100,
})

UTXOs¶

UTXOs (Unspent Transaction Outputs) are the actual holding contracts that represent token balances.

Listing UTXOs

You can specify additional parameters for pagination and limits:

const utxos = await sdk.token.utxos.list({
    partyId,
    includeLocked: false,
    limit: 100,
    offset: 0,
    continueUntilCompletion: false,
})

Merging UTXOs

Merging consolidates multiple small UTXOs into larger ones to improve performance.

The merge operation groups UTXOs by instrument and creates self-transfers to consolidate them. You can optionally provide specific UTXOs to merge:

const [commands, disclosedContracts] = await sdk.token.utxos.merge({
    partyId,
    inputUtxos,
    memo: 'custom merge',
})

Allocation¶

Allocations handle the issuance and distribution of new tokens.

Listing pending allocations

The pending method accepts an optional interface ID to filter by allocation type:

import {
    ALLOCATION_REQUEST_INTERFACE_ID,
    ALLOCATION_INSTRUCTION_INTERFACE_ID,
    ALLOCATION_INTERFACE_ID,
} from '@canton-network/core-token-standard'

// Filter by specific type
const requests = await sdk.token.allocation.pending(
    myPartyId,
    ALLOCATION_REQUEST_INTERFACE_ID
)

Executing, withdrawing or cancelling allocations

Migration reference¶

Token-related method migration¶
v0 method	v1 method
`sdk.tokenStandard.createTransfer`	`sdk.token.transfer.create`
`sdk.tokenStandard.exerciseTransferInstructionChoice`	`sdk.token.transfer.accept` / `sdk.token.transfer.reject` / `sdk.token.transfer.withdraw`
`sdk.tokenStandard.fetchPendingTransferInstructionView`	`sdk.token.transfer.pending`
`sdk.tokenStandard.listHoldingTransactions({partyId})`	`sdk.token.holdings({partyId})`
`sdk.tokenStandard.listHoldingUtxos()`	`sdk.token.utxos.list({partyId})`
`sdk.tokenStandard.mergeHoldingUtxos`	`sdk.token.utxos.merge`
`sdk.tokenStandard.fetchPendingAllocationRequestView`	`sdk.token.allocation.pending(partyId, ALLOCATION_REQUEST_INTERFACE_ID)`
`sdk.tokenStandard.fetchPendingAllocationInstructionView`	`sdk.token.allocation.pending(partyId, ALLOCATION_INSTRUCTION_INTERFACE_ID)`
`sdk.tokenStandard.fetchPendingAllocationView`	`sdk.token.allocation.pending(partyId)`