Console Overview

Accessing and using the Canton Console for validator and SV node operations

The Canton Console provides direct, interactive access to Canton node internals. It’s a Scala-based REPL that connects to participant, sequencer, and mediator nodes for debugging, diagnostics, and advanced operations that aren’t exposed through the standard APIs.

When You Need the Console

Most day-to-day operations happen through the Ledger API, Admin API, or web UIs. The Canton Console is for situations that require deeper access:

• Debugging stuck transactions or unexpected behavior
• Inspecting topology state (party-to-participant mappings, package vetting)
• Managing parties and packages at a low level
• Disaster recovery or repair operations
• Advanced key management and rotation

Starting the Console

This section was adapted from existing reviewed documentation. Source: deployment/console_access.rst Reviewers: Skip this section. Remove markers after final approval.

To access the Canton Console, you need:

• Direct network access to the Canton node process (participant, sequencer, or mediator)
• The Canton binary (typically via the Canton Docker image)

Participant Console

1. Obtain an authentication token (see the Canton authentication docs for JWT setup)
2. Ensure you can access the participant’s ports 5001 (Ledger API) and 5002 (Admin API)
3. Create a configuration file console.conf:

canton {
  remote-participants {
    participant {
      admin-api {
        port = 5002
        address = localhost
      }
      ledger-api {
        port = 5001
        address = localhost
      }
      token = "<auth token>"
    }
  }
  features.enable-preview-commands = yes
  features.enable-testing-commands = yes
  features.enable-repair-commands = yes
}

4. Run the Canton Console via Docker:

docker run -it --rm --network host \
  -v $(pwd)/console.conf:/app/app.conf \
  digitalasset/canton:3.3.0 --console

Replace 3.3.0 with the Canton version matching your deployment. Check available versions at Docker Hub.

If you run the participant using Docker Compose, use the Docker network used by the participant (e.g., --network splice-validator) and adjust the address in the config to the container name (e.g., address = participant).

Sequencer Console

1. Ensure you can access the sequencer’s ports 5008 (public API) and 5009 (Admin API)
2. Create console.conf:

canton {
  remote-sequencers {
    sequencer {
      public-api {
        port = 5008
        address = localhost
      }
      admin-api {
        port = 5009
        address = localhost
      }
    }
  }
  features.enable-preview-commands = yes
  features.enable-testing-commands = yes
  features.enable-repair-commands = yes
}

3. Run the Docker command as shown above for the participant.

Mediator Console

1. Ensure you can access the mediator’s port 5007 (Admin API)
2. Create console.conf:

canton {
  remote-mediators {
    mediator {
      admin-api {
        port = 5007
        address = localhost
      }
    }
  }
  features.enable-preview-commands = yes
  features.enable-testing-commands = yes
  features.enable-repair-commands = yes
}

3. Run the Docker command as shown above.

K8s Cluster Access

In a Kubernetes cluster, use a debug pod to access the console directly:

kubectl debug "${POD_NAME}" \
  --image "$(kubectl get pod "${POD_NAME}" -o json | jq -re '.spec.containers[0].image')" \
  -i -t -- bash

Where POD_NAME is the name of the participant, sequencer, or mediator pod. Inside the pod:

apt-get update && apt-get install -y vim
vim console.conf  # paste in the appropriate config from above
/app/bin/canton -v -c console.conf

Console Structure

Once connected, the console provides access to node-specific objects:

• participant — For participant consoles: party management, package management, ledger operations
• sequencer — For sequencer consoles: synchronizer status, sequencing operations
• mediator — For mediator consoles: mediator state inspection

Each object exposes a hierarchy of commands organized by domain: health, topology, parties, packages, domains (on participants), and more.

Help System

Use the built-in help to discover available commands:

// List top-level command groups
participant.help()

// Get help for a specific group
participant.topology.help()

// Get help for a specific command
participant.parties.help("hosted")

Next Steps

• Essential Commands — Key commands for health checks, party and package management
• Debugging Workflows — Step-by-step diagnostic procedures