Canton Transactions

Overview

Mirador correlates Canton (Daml Ledger API v2) transactions to a trace by ledger updateId — the unique identifier of an on-ledger update, returned when you submit a command to a participant. The Web3Plugin exposes this under its web3.canton namespace.

trace.web3.canton.addTxHint(updateId);

Like Solana, Canton hints take no chain argument. The chain identity is implicit — Canton lives outside the EVM Chain enum, and the hint is emitted on the wire as chain_name = "canton". On the platform side, the canton-hint processor resolves the full transaction server-side from the updateId and emits its events into the trace waterfall, alongside any other on-chain or off-chain activity.

Canton methods require the Web3Plugin. See Plugins for setup.

Adding a Canton Transaction Hint

Pass the updateId your participant’s Ledger API returns after a successful command — e.g. submit-and-wait-for-transaction on the JSON Ledger API, or CommandService.SubmitAndWaitForTransaction over gRPC. Use whatever Canton client you already have; the SDK only needs the resulting id.

// `submit` is your own participant client (JSON Ledger API, gRPC, @daml/ledger, …)
const { updateId } = await submit(createOrExerciseCommand);
trace.web3.canton.addTxHint(updateId);

Scoping to a Party

partyId is optional. Include it to scope the update to a specific party, or omit it when the participant only co-hosts the contract as an observer — the backend can resolve the update from the updateId alone.

trace.web3.canton.addTxHint(updateId, 'Alice::1220...');  // scope to a party
trace.web3.canton.addTxHint(updateId);                     // observer co-host — no party

With Details

Attach a free-form note for downstream debugging:

trace.web3.canton.addTxHint(updateId, 'Alice::1220...', 'IOU transfer');

Method Signature

trace.web3.canton.addTxHint(updateId: string, partyId?: string, details?: string): Trace

Parameter	Type	Required	Description
`updateId`	`string`	Yes	Canton ledger update id (the transaction’s unique identifier)
`partyId`	`string`	No	Party to scope the update to; omit for observer co-hosts
`details`	`string`	No	Free-form note attached to the hint for debugging context

End-to-End Example

import { Client, Web3Plugin } from '@miradorlabs/nodejs-sdk';

const client = new Client('your-api-key', { plugins: [Web3Plugin()] });

async function transferIou(params: TransferParams) {
  const trace = client.trace({ name: 'CantonTransfer' })
    .addAttributes({
      party: params.owner,
      templateId: params.templateId,
      contractId: params.contractId,
    })
    .addTags(['canton', 'iou']);

  try {
    // Exercise the Transfer choice via your participant's Ledger API.
    const { updateId } = await ledger.exercise(params.contractId, 'Transfer', {
      newOwner: params.recipient,
    });

    trace.web3.canton.addTxHint(updateId, params.owner, 'IOU transfer');
    trace.addEvent('confirmed');
  } catch (err) {
    trace.error('transfer_failed', { message: (err as Error).message });
  }
}

For a complete, runnable example — submitting Canton commands and tracing them end-to-end — see the canton-example repo.

Why No Chain Argument?

EVM tx hints carry a numeric chain ID so the backend knows which chain to resolve the tx hash on. Canton has no such enum — a Canton network is a set of synchronizers reached through a participant node, not an id-keyed chain. So the API omits the chain parameter and emits chain_name = "canton" on the wire:

// EVM — chain is required
trace.web3.evm.addTxHint('0x123...', 'ethereum');

// Canton — no chain; the updateId is the identifier
trace.web3.canton.addTxHint('1220...');

Observer Co-Hosts

Canton’s privacy model means a participant only sees updates for the parties it hosts. If your trace runs on a participant that co-hosts a contract as an observer — rather than acting as a signatory — you may not have a party to act as. Pass just the updateId and omit partyId; the backend resolves the update from the id alone.

trace.web3.canton.addTxHint(updateId); // observer — no party needed

Best Practices

Add the Hint as Soon as You Have the updateId

Record it the moment the submission returns — Canton assigns the updateId on commit, so there’s nothing to wait for.

Label Each Step in a Multi-Command Flow

When one user action produces several commands (e.g. mint then transfer), use the optional details arg to label each leg so the waterfall is self-explanatory:

trace.web3.canton.addTxHint(mintUpdateId, owner, 'Mint');
trace.web3.canton.addTxHint(xferUpdateId, owner, 'Transfer');

Next Steps

Solana Transactions

The other chain-implicit hint

EVM Transaction Hints

EVM tx correlation and the supported chain list

Plugins

Web3Plugin setup and namespaces

Getting Started

Core Concepts

Web3 Integration

OpenTelemetry

Automations

AI & Agents

Advanced

Best Practices

Overview

Adding a Canton Transaction Hint

Scoping to a Party

With Details

Method Signature

End-to-End Example

Why No Chain Argument?

Observer Co-Hosts

Best Practices

Add the Hint as Soon as You Have the updateId

Label Each Step in a Multi-Command Flow

Next Steps

Solana Transactions

EVM Transaction Hints

Plugins

​Overview

​Adding a Canton Transaction Hint

​Scoping to a Party

​With Details

​Method Signature

​End-to-End Example

​Why No Chain Argument?

​Observer Co-Hosts

​Best Practices

​Add the Hint as Soon as You Have the updateId

​Label Each Step in a Multi-Command Flow

​Next Steps

Solana Transactions

EVM Transaction Hints

Plugins

Overview

Adding a Canton Transaction Hint

Scoping to a Party

With Details

Method Signature

End-to-End Example

Why No Chain Argument?

Observer Co-Hosts

Best Practices

Add the Hint as Soon as You Have the updateId

Label Each Step in a Multi-Command Flow

Next Steps