cn-quickstart - Canton Network Docs

The cn-quickstart repository is a complete example application that demonstrates how to build, test, and run a Canton Network application. It includes Daml smart contracts, a Java backend, a React frontend, and a LocalNet environment for local development.

Repository Overview

Clone the repository:

git clone https://github.com/digital-asset/cn-quickstart
cd cn-quickstart
direnv allow
cd quickstart

The repository uses Nix and Direnv for reproducible development dependencies. If you prefer not to use Nix, work directly in the quickstart/ directory and manage dependencies (JDK, Node.js, dpm) manually.

Project Structure

cn-quickstart/
  .envrc                    # Nix/Direnv activation
  nix/                      # Nix development dependencies
  quickstart/
    Makefile                # Build and run commands
    compose.yaml            # Docker Compose configuration
    .env                    # Environment variables
    daml/                   # Daml smart contracts
      Licensing/
        AppInstall.daml     # User onboarding workflow
        License.daml        # License management
        Util.daml           # Helper functions
      dars/                 # Splice DAR dependencies
    backend/                # Java Spring Boot backend
      src/main/java/...
        ledger/             # Ledger API client
        repository/         # PQS queries
        pqs/                # SQL generation
        service/            # REST endpoints
        security/           # OAuth2 auth
    frontend/               # React TypeScript frontend
      src/
        components/         # UI components
        api/                # Generated API client
    common/
      openapi.yaml          # Shared API definition
    docker/                 # Docker image definitions
      modules/
        localnet/           # LocalNet configuration
    config/                 # Service configuration files

The Reference Application

cn-quickstart implements a software licensing workflow with four parties:

App Provider — Creates and sells licenses
App User — Purchases and holds licenses
Super Validator (SV) — Operates the payment infrastructure
DSO Party — The decentralized synchronizer operator for Canton Coin

The Provider and User each run on their own validator. License purchases involve Canton Coin payments processed through the Splice wallet system.

Running the Application

cd quickstart
make install-daml-sdk    # Install the Daml SDK
make setup               # Select deployment profile
make build               # Compile contracts, backend, frontend
make start               # Launch LocalNet and all services

Once running, the frontend is accessible in your browser. See the QuickStart walkthrough for a step-by-step guide.

Extending the Example

Adding Your Own Templates

Create new .daml files in the daml/ directory. After writing your templates:

dpm build                # Compile
dpm test                 # Run tests
make build               # Rebuild everything including codegen
make restart             # Restart services

The build system regenerates Java bindings from the updated DAR file, so your backend can reference the new templates immediately.

Modifying the Backend

The backend follows a standard Spring Boot layout. To add a new endpoint:

Define the endpoint in common/openapi.yaml
Add the service implementation in backend/src/main/java/.../service/
Add PQS queries in repository/ if you need to read contract data
Add Ledger API commands in ledger/ if you need to submit transactions
Rebuild with make build-backend

Custom Frontend

The React frontend consumes the backend’s REST API. To modify it:

Update or add components in frontend/src/components/
Regenerate the API client if you changed openapi.yaml
Rebuild with make build-frontend

The frontend never interacts with the Ledger API directly — all ledger access goes through the backend.

Switching Architectures

cn-quickstart uses a fully mediated architecture (backend handles all ledger access). You can switch to a CQRS pattern where the frontend submits commands directly to the Ledger API using TypeScript bindings generated by dpm codegen-js. See SDKs and APIs for a comparison of both approaches.

QuickStart walkthrough — Step-by-step guide to running the demo
Project structure — Detailed breakdown of every directory and file
LocalNet — The Docker Compose environment powering local development
Backend development — Patterns from the cn-quickstart backend

​Repository Overview

​Project Structure

​The Reference Application

​Running the Application

​Extending the Example

​Adding Your Own Templates

​Modifying the Backend

​Custom Frontend

​Switching Architectures

​Related Pages