Developer onboarding — concept
From zero to a running ledger
in five minutes.
One install, two commands — and at every step you know what you should be seeing. This page is a working redesign of a typical SDK getting-started flow, demonstrated against a real, public example project.
Before you start ~2 min
Two prerequisites, checked before any project command appears:
1 A JDK, version 17 or newer
java -versionNo JDK? Get one from adoptium.net — the SDK runs on the JVM.
2 The SDK, pinned to the version this guide is written against
curl -sSL https://get.daml.com/ | sh -s 2.10.4Version-pinned on purpose: a guide "for whatever is current" is a guide that silently breaks.
Run something real ~2 min
Not a hello-world: an atomic delivery-versus-payment and a two-leg repo with a pre-commit risk gate, in 348 lines you can read afterwards.
git clone https://github.com/ThomasFelber/daml-two-leg-repo.git
cd daml-two-leg-repo
daml testWhat success looks like
Test Summary
daml/Main.daml:allocateParties: ok, 0 active contracts, 0 transactions.
daml/Main.daml:testDvp: ok, 2 active contracts, 4 transactions.
daml/Main.daml:testRepoRejectsBreachedHaircut: ok, 4 active contracts, 5 transactions.
daml/Main.daml:testRepoRejectsIneligibleCollateral: ok, 4 active contracts, 5 transactions.
daml/Main.daml:testRepoHappyPath: ok, 4 active contracts, 7 transactions.
daml/Main.daml:setup: ok, 14 active contracts, 21 transactions.Looks wrong, is right #1
ok on the two Rejects… scripts means the rejection happened. They assert with submitMustFail: an ineligible ISIN or a breached haircut must abort before anything commits. The failure is the feature under test.
Looks wrong, is right #2
Six lines, not four (and the order varies). The runner executes every top-level script — including the party-allocation helper and the setup script used by daml start.
See the point, not just the prompt ~2 min
The product's core promise here is need-to-know visibility. Don't assert it — let the reader click it:
daml start # sandbox + web UI on http://localhost:7500Log in as each of the three pre-created users and count what they see. The ledger holds 14 active contracts:
Collateral provider — think a bank's repo desk: pledges the bond, takes the cash.
Its bonds and cash, the open proposals, the eligibility lists — not the fund's undisclosed cash.
Cash provider and DvP bond buyer — the lender earning the minute-priced interest.
Its own holdings plus the same shared workflow contracts — not the dealer's other positions.
Three roles in one party: policy gate (eligibility & haircut floor), cash issuer, bond registrar.
Everything — not because it is an admin, but because each of those three roles is written into the contracts. Visibility follows role, never configuration.
When it breaks
The three failures a newcomer actually hits — not an FAQ dump:
- The web UI's login dropdown is empty
- The ledger has parties but no users — interactive tools authenticate via user management. This project's init script creates the three users for you; if you build your own, script createUser or the dropdown stays empty.
- java: command not found or a JVM version error
- Install a JDK ≥ 17 and re-run. On macOS: brew install temurin.
- Address already in use on start
- A previous sandbox is still running. Stop it (Ctrl-C in its terminal) or find it with lsof -i :6865.
Ongoing deep dive: from this lab to the token standard ~15 min
The example project ends with five deliberate simplifications. They are not shortcuts — they are the syllabus. Each one is exactly what an institutional registry formalizes, so each limit you just hit hands you one concept of the real token standard:
-
In the lab: the owner is the only signatory
In Assets.daml, Cash and Bond are signed by their owner alone — issuance control is explicitly out of scope.
In the standard: issuer-governed holdings
A registry makes the issuer/registrar a signatory, so supply, transfer rules and recovery become enforceable workflows instead of conventions.
Asset workflows → -
In the lab: a hand-rolled eligibility gate
EligibilityCriteria — an ISIN whitelist and a haircut floor — vetoes trades before they commit.
In the standard: allowlists & instrument rules
The same pre-commit idea, productized: credential-based allowlists and per-instrument compliance rules enforced natively.
Allowlist feature → -
In the lab: propose-accept settlement
The DvP moves both legs in one transaction because the proposal carries the signatories' authority into acceptance.
In the standard: transfer instructions (CIP-56)
The token standard generalizes exactly this two-step shape so any wallet and registry can settle atomically without trusting each other's code.
Token standard API → -
In the lab: closing the repo
RepoClose returns principal plus minute-priced interest — assets appear and disappear by contract choice.
In the standard: mint, burn & redemption
Supply changes become first-class, attested workflows with an auditable trail — the registry's version of "appear and disappear".
Redemption tutorial → -
In the lab: riskdesk sees 14/14 — through roles
The risk desk sees everything only because it holds three written-in roles: policy gate, cash issuer, bond registrar.
In the standard: role architecture
Registrar, operator, issuer and investor are distinct parties with distinct visibility — the production answer to "who may see what".
Role architecture →
Suggested reading order from here
- Role architecture — the concept layer first (~10 min).
- One tutorial arc end-to-end: issuance → transfer → redemption (the role/credential steps repeat — skim them the second and third time).
- Token standard (CIP-56) as the reference you keep open while coding.
- The primer, last — useful as positioning context once the concepts already sit.
The vocabulary, placed ~5 min
Words stick when they attach to something you did. Every term below is anchored to a moment on this page — and the picture shows where each cluster lives, bottom to top:
The four clusters
1 · Canton — network & runtime
Canton
The network protocol: many participant nodes synchronize privately — there is no global broadcast to subscribe to.
met it: `daml start` booted a one-node "canton sandbox"Participant
A node that hosts parties and their contracts, and exposes the APIs.
met it: dealer, mmf and riskdesk all lived on your sandbox participantLedger API · JSON API
The doors into a participant: gRPC (port 6865) and HTTP (7575).
met it: the 10/11/14 visibility counts came through port 7575DAR
The compiled, deployable package of Daml code you upload to a participant.
met it: `daml start` built and uploaded `.daml/dist/…dar`2 · Daml — the language
Party
An actor identity on the ledger; rights and visibility attach to parties, not accounts.
met it: Dealer, MMF, RiskDeskTemplate → Contract
Class → instance: a template stamped with data becomes an active contract on the ledger.
met it: `Cash with owner = mmf; amount = 98.0 …`Signatory · Observer
Who must authorize a contract vs who may see it — visibility is written into the contract itself.
met it: `observer issuer, disclosedTo` — and the 14/14 loginChoice
An operation a template offers; exercising one archives and creates contracts in a single atomic transaction.
met it: `DvpAccept`, `RepoClose`3 · Registry — the token standard
Registry
The issuer-side system of record for an asset class on Canton — where instruments are defined and governed.
met it: the production layer the deep dive maps intoInstrument
The asset definition — its rules and compliance profile — of which holdings are issued.
met it: your `Bond` template is a hand-rolled instrumentHolding
A party's concrete position in an instrument.
met it: one `Cash` contract = one naive holdingTransfer Instruction
The standard's two-step transfer: propose, then settle atomically — across wallets that don't trust each other's code.
met it: your propose-accept DvP, generalized (CIP-56)Allowlist · Blocklist
Credential-based pre-commit gates over who may hold or receive an instrument.
met it: `EligibilityCriteria`, productizedCIP
Canton Improvement Proposal — numbered specs the ecosystem builds against.
met it: CIP-56 = token standard; CIP-103 = wallet-based infra route4 · Reading the docs — the genres
Primer
An explanation genre: orientation and positioning, deliberately without steps. Useful context — read it after the concepts sit, not before.
met it: the registry primer, last stop of the reading orderQuickstart
Should be the shortest path to one verifiable success. If it opens with a commercial agreement, it's an onboarding checklist wearing the wrong name.
met it: the diagnosis in callout 6Tutorial vs Guide
Learning-oriented walkthrough vs task-oriented recipe — the core distinction of the Diátaxis framework.
met it: registry/tutorials vs registry/guidesReference
Precise lookup material you keep open while coding — never the place to learn a concept from.
met it: the CIP-56 API pagesThe four principles behind this redesign
Prerequisites first
Nothing a reader must install may appear after a command that needs it. Time estimates up front; version pinned.
Show success
Expected output verbatim, and an explanation wherever correct output looks like failure.
Prove the promise
The product's differentiator becomes a two-minute interactive tour, verified against the running system.
Fail with the reader
Troubleshooting covers the failures of this path, discovered by walking it, not imagined in a review meeting.