Get Started

This page shows how to set up the Daml toolchain, build the OpenZeppelin packages, and use them in your own Daml project.

Prerequisites

• JDK 21 or newer. The Daml toolchain runs on Java. Set JAVA_HOME to the JDK.
• DPM (Daml Package Manager). DPM installs the Daml SDK and runs builds, tests, and the sandbox:

curl https://get.digitalasset.com/install/install.sh | sh

The packages target the Canton 3.4 baseline (SDK 3.4.11, Daml-LF target 2.1). Run dpm install in a project directory to install the SDK version that its daml.yaml or multi-package.yaml declares.

If you are new to Daml, read the Daml documentation and the Canton guide to building and packaging first.

Build the Packages

No DAR has a release yet, so build the packages from source:

git clone https://github.com/OpenZeppelin/canton-contracts.git
cd canton-contracts
dpm install
dpm build --all

To build one package, set DAML_PACKAGE to its directory. Build a package's dependencies first:

DAML_PACKAGE=packages/security/api-pausable-v1 dpm build
DAML_PACKAGE=packages/security/pausable-v1 dpm build

The packages are grouped by status and category:

Each build writes its DAR to the .daml/dist/ directory of the package, for example packages/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar.

Released DARs will go in dars/released/, with package IDs and SHA-256 digests in dars/manifest.yaml. Participant operators use these values to verify and vet the packages.

Add the Packages to Your Project

In the daml.yaml of your project, add each DAR under data-dependencies. The dependencies list is for SDK libraries only.

sdk-version: 3.4.11
name: my-app
source: daml
version: 0.1.0
dependencies:
  - daml-prim
  - daml-stdlib
data-dependencies:
  - ../canton-contracts/experiments/access/access-control-v1/.daml/dist/openzeppelin-access-control-v1-0.1.0.dar
  - ../canton-contracts/experiments/access/ownable-v1/.daml/dist/openzeppelin-ownable-v1-0.1.0.dar
  - ../canton-contracts/packages/security/api-pausable-v1/.daml/dist/openzeppelin-api-pausable-v1-0.1.0.dar
  - ../canton-contracts/packages/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar
build-options:
  - --target=2.1

Change the paths to match your clone. List only the DARs that you use, plus their dependencies: openzeppelin-pausable-v1 needs openzeppelin-api-pausable-v1.

The Token package also needs the Token Standard V2 DARs from dars/vendor/ in data-dependencies. The token page lists them.

Import the modules and build:

import OpenZeppelin.Api.PausableV1 (Pausable, PausableView (..))
import qualified OpenZeppelin.PausableV1 as Pausable

dpm build

Each package page gives its module name, templates, and choices.

Test Against a Local Ledger

dpm test runs Daml Script tests on an in-memory ledger. To check time behavior, party visibility, and DAR upload on a real ledger, run the same scripts against a local Canton sandbox over the Ledger API:

# start a sandbox with your DAR
dpm sandbox --static-time --ledger-api-port 6865 --dar .daml/dist/<your-package>.dar

# in a second terminal, run a script against it
dpm script --dar .daml/dist/<your-package>.dar \
  --script-name My.Module:myScript \
  --ledger-host localhost --ledger-port 6865 --static-time

Use --static-time on both commands if your scripts call setTime. A wall-clock ledger rejects setTime, and a static-time clock only moves forward.

A sandbox keeps its state between script runs. A second allocation of the same party hint fails, so give each script its own party hints.

Next Steps

• Read the Library overview for the package design rules.
• Read the Reference Implementations for complete application designs.
• See the Canton Improvement Proposals (CIPs) for the standards that the packages implement.