Module 0 · Lesson 4 · ~20 min read + exploration

The Canton Codebase Tour

Now that you know the words, let's walk the map. This lesson orients you in the actual Canton source repository — where things live, what components talk to what, and where Go tooling plugs in.

The main repo

Primary source: github.com/digital-asset/canton (Apache 2.0). It's large. Don't try to read all of it. Use it as a reference — grep first, read selectively, follow types to their definitions.

Other repos you'll orbit:

• digital-asset/daml — the Daml compiler, Ledger API spec (protobuf), and SDK.
• digital-asset/daml-finance — reference Daml templates for financial instruments.
• The daml repo's ledger-api/grpc-definitions/ — the protobuf files you'll import in your Go client.

High-level layout of the canton repo

Canton uses a multi-module sbt build. At the top level, you'll see something like this (names and exact structure shift between versions — treat this as a guide, not a spec):

As a Go-side contributor, you almost never edit this code. You read it for two reasons:

1. To understand what a Ledger API call actually does (trace gRPC service → handler → command processor → …).
2. To find the canonical protobuf files your Go code needs to generate stubs from.

Where the protobufs live

These matter most for Go contributors. The Ledger API protobuf definitions are the contract between your Go client and any Canton participant. They live in the daml repo, not canton, though canton consumes them:

Those .proto files are what you'll feed protoc or buf to generate Go stubs. Exact path may shift with versions — find . -name '*.proto' | grep ledger from the daml repo root is your friend.

The Ledger API services — what you'll actually call

Four services cover 90% of integration code:

Service	What it does	Typical use
CommandService	Submit a command and wait for its outcome (success / completion details).	CLI that creates or transfers a contract and wants to block on result.
CommandSubmissionService	Submit a command; don't wait. Track outcome via CompletionService.	High-throughput integrators where blocking per-submission is wasteful.
UpdateService	Stream transaction updates (creates and archives) from a given offset.	Indexers, integrations, "what changed for my parties since X" queries.
StateService	Query current active contract set (ACS) and ledger offsets.	Bootstrapping an indexer, reconciliation, snapshotting.

Additional services — PartyManagementService, PackageService, VersionService — exist for admin tasks and discovery. You'll meet them incidentally.

The Admin API — operational endpoints

Beyond the Ledger API, Canton exposes an Admin API (gRPC) for node operations: topology management, DAR uploads, party provisioning, health checks. Also protobuf-defined, also a target for Go ops tooling. You'll see these live under community/admin-api/ in the Canton repo.

If you end up building a Canton-ops CLI in Go, you'll likely be calling both APIs: Ledger API for data plane, Admin API for control plane.

What gets deployed — the node processes

A Canton deployment is a set of JVM processes:

• Participant node — exposes Ledger API on one gRPC port, Admin API on another. Hosts parties. Every organization runs at least one.
• Synchronizer — depending on edition, one or multiple processes (sequencer, mediator, topology manager). Shared infrastructure between participants.
• Database — Postgres is the default. Each participant has its own DB. The synchronizer components also persist state.

For local development, the Canton sandbox bundles all of this into a single container. The capstone uses it.

Where Go code typically lives in this ecosystem

Digital Asset does not ship an official Go SDK for the Ledger API today — that's part of why "Go for Canton" is a real contribution area. Existing Go code in and around Canton lives in several places:

• Third-party or community Go clients that generate stubs from the canonical protobufs and talk to the Ledger API. These vary in maturity.
• Kubernetes operators and Helm tooling (Go-shaped ecosystem) for deploying Canton.
• Integration services and bridges — Kafka↔Canton bridges, Postgres exporters, audit/compliance services — often Go for operational reasons.
• CI/CD and ops tooling — CLI wrappers, monitoring exporters, log shippers, health probes.

A suggested reading order for the Canton repo

When you want to see real code, not just diagrams:

1. Start with a protobuf file — command_service.proto. The service definition is the cleanest form of the API surface.
2. Grep the Canton repo for the RPC name (e.g. SubmitAndWait). Find the Scala handler that implements it.
3. Trace from the handler into the command processor — that's where the interesting logic lives.
4. When you hit a phrase you don't know, search the docs/ directory or the official docs site.

Don't try to read top-down. Canton has too much code for that to work.

Takeaways

• Core Canton code = Scala, in digital-asset/canton.
• Ledger API protobufs = in digital-asset/daml, under ledger-api/grpc-definitions/.
• Four Ledger API services carry almost all traffic: CommandService, CommandSubmissionService, UpdateService, StateService.
• Go contribution targets: CLIs, integrations, operators, bridges. Not core protocol.
• Read the repo bottom-up from a protobuf, not top-down.

You're done with Module 0. Go play with the Daml playground exercise, then come back and start Module 1 to actually learn Go.

Mark as complete