Skip to content

docs(canton): document Scoped Authorization Grant and sync with current sources #252

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
pepebndc wants to merge 5 commits into
base: main
Choose a base branch
from
+529 −376
Open

docs(canton): document Scoped Authorization Grant and sync with current sources #252

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
bbbbf88
docs(canton): sync with canton-contracts and canton-specs, tighten prose
pepebndc Sep 25, 2026
4a96672
docs(canton): link the Pausable and Access Control replacement PRs
pepebndc Sep 25, 2026
012b9ae
docs(canton): document the merged Pausable packages
pepebndc Sep 25, 2026
60bc000
Merge remote-tracking branch 'origin/main' into docs/canton-current-s…
pepebndc Oct 20, 2026
e15d848
docs(canton): document Scoped Authorization Grant and sync with curre…
pepebndc Oct 20, 2026
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
105 changes: 58 additions & 47 deletions content/canton/get-started.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,41 +2,30 @@
title: Get Started
---

This guide covers the prerequisites and the basic project wiring for building on Canton with OpenZeppelin's Daml packages.
This page shows how to set up the Daml toolchain, build the OpenZeppelin packages, and use them in your own Daml project.

<Callout type="info">
These packages target the Canton 3.4.x baseline and are under active
development. Pin exact versions from the package manifests in
<Callout type="warn">
The packages are unaudited and have no release yet. Pin a source commit of
[`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts)
rather than copying version numbers from this page.
and take version numbers from its package manifests, not from this page.
</Callout>

## Prerequisites

- **JDK 21+**: the Daml toolchain runs on Java. Install any JDK 21 or newer - e.g. OpenJDK or Eclipse Adoptium both work - and make sure `JAVA_HOME` points at it.
- **DPM (Daml Package Manager)**: Digital Asset's package manager and SDK installer. Install it, then use it to provision the Daml SDK / Canton baseline:
- **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:

```bash
curl https://get.digitalasset.com/install/install.sh | sh
dpm install 3.4.11 # or the baseline pinned in your project's daml.yaml
```

- **A Daml project**: a directory with a `daml.yaml` (single package) or a `multi-package.yaml` (workspace of packages). New to Daml? Start with the [Daml documentation](https://docs.digitalasset.com/) and the [Canton Network overview](https://www.canton.network/).

## Add OpenZeppelin Packages
The packages target the Canton 3.5 baseline (SDK `3.5.8`, 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.

OpenZeppelin's Canton library is distributed as Daml packages: each primitive is its own DAR, so you add only the ones you need.
If you are new to Daml, read the [Daml documentation](https://docs.digitalasset.com/) and the [Canton guide to building and packaging](https://docs.canton.network/appdev/modules/m3-building-packaging) first.

<Callout type="warn">
Experimental and work in progress. All library packages are version 0.x,
unaudited, and not yet a stable public API: interfaces may change before a
1.0 release, and they are not intended for production use. They live under
[`experiments/`](https://github.com/OpenZeppelin/canton-contracts/tree/main/experiments)
in `OpenZeppelin/canton-contracts` and move to `packages/` when they are
released.
</Callout>
## Build the Packages

**1. Get the DARs.** The source of truth for production DARs is the [`dars/released/`](https://github.com/OpenZeppelin/canton-contracts/tree/main/dars) directory in `OpenZeppelin/canton-contracts`: it holds immutable DARs copied from tagged GitHub Releases, indexed in `dars/manifest.yaml` with the package IDs and SHA-256 digests operators need for verification and vetting. No production releases have been published yet, so for now build the library packages from source:
No DAR has a release yet, so build the packages from source:

```bash
git clone https://github.com/OpenZeppelin/canton-contracts.git
Expand All @@ -45,63 +34,85 @@ dpm install
dpm build --all
```

Library packages live under `experiments/` until their first release, grouped by category (`experiments/access/` for authorization and ownership, `experiments/security/` for operational security, `experiments/token/` for the Token Standard V2 (CIP-112) token and settlement package); released packages will live under `packages/`. Each package's DAR lands in its own `.daml/dist/` directory (for example `experiments/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar`).
To build one package, set `DAML_PACKAGE` to its directory. Build a package's dependencies first:

```bash
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:

**2. Declare them as data-dependencies.** In your project's `daml.yaml`, reference the built DARs under `data-dependencies` (not `dependencies`, which is for the SDK's own libraries):
| Directory | Contents |
| --- | --- |
| `packages/access/` | Scoped Authorization Grant (pre-release) |
| `packages/security/` | Pausable (pre-release) |
| `test/` | Test packages for `packages/` |
| `experiments/token/` | Token (CIP-0112) (experimental) |
| `experiments/test/` | Test packages for `experiments/` |
| `examples/` | Runnable projects that use the packages: licensing, treasury RBAC, and Pausable vault, registry, and retrofit |

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/`](https://github.com/OpenZeppelin/canton-contracts/tree/main/dars), 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.

```yaml
sdk-version: 3.4.11
sdk-version: 3.5.8
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/experiments/security/pausable-v1/.daml/dist/openzeppelin-pausable-v1-0.1.0.dar
- ../canton-contracts/packages/access/scoped-authorization-grant-v1/.daml/dist/openzeppelin-scoped-authorization-grant-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
```

Adjust the paths to wherever you cloned the repo, and pin the exact versions from its package manifests. If you only need one primitive, list only that DAR.
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`.

**3. Import and build.** Import the modules you declared and build your project:
The [Token](/canton/library/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:

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

```bash
# from your project root, with DPM on PATH
dpm build
```

Refer to each component's page for the module path to import and the templates and interfaces it exposes:

- [Access Control](/canton/library/access-control)
- [Ownable](/canton/library/ownable)
- [Pausable](/canton/library/pausable)
Each package page gives its module name, templates, and choices.

## Test Against a Local Canton Ledger
## Test Against a Local Ledger

Daml Script tests run in-memory by default, but you can point the same scripts at a real local Canton ledger over gRPC, which is useful for validating time semantics, party visibility, and DAR uploads before targeting a shared network:
`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:

@laurenmxv laurenmxv Oct 22, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Following the page as written, the first test won't build, because the daml.yaml above doesn't include daml-script. Adding it to the app package works but makes damlc warn that templates depend on Daml Script, so a separate test package is the cleaner pattern. That's also how the library does it under test/.

Suggested change
`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:
Keep your Daml Script tests in a separate test package: list `daml-script` under `dependencies`, and your application DAR (plus any library DARs the tests import) under `data-dependencies`. Adding `daml-script` to the application package itself makes `damlc` warn that its templates depend on Daml Script. In the commands below, start the sandbox with your application DAR and pass the test package's DAR to `dpm script`.
`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:


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

# run a script against it over the Ledger API
# 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
--ledger-host localhost --ledger-port 6865 --static-time
```

If your scripts control ledger time with `setTime`, start the sandbox with `--static-time` and pass `--static-time` to `dpm script` as well: both default to wall-clock time, and ledger time only moves forward.
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.

## Explore Further
## Next Steps

- The **[Settlement (CIP-112)](/canton/settlement)** primitive shows how to compose the library into an atomic, value-moving settlement flow.
- The **[Reference Implementations](/canton/reference-implementations)** walk through complete application blueprints built on these pieces.
- The [Canton Improvement Proposals (CIPs)](https://github.com/canton-foundation/cips) repository holds the ecosystem standards these packages align with.
- Read the [Library overview](/canton/library) for the package design rules.
- Read the [Reference Implementations](/canton/reference-implementations) for complete application designs.
- See the [Canton Improvement Proposals (CIPs)](https://github.com/canton-foundation/cips) for the standards that the packages implement.
31 changes: 14 additions & 17 deletions content/canton/index.mdx
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -2,34 +2,31 @@
title: OpenZeppelin for Canton
---

OpenZeppelin is building a suite of secure, reusable building blocks for the [Canton Network](https://www.canton.network/), the privacy-enabled network of applications built on [Daml](https://docs.digitalasset.com/). This section is the home for OpenZeppelin's Canton documentation: the general-purpose library, the settlement primitive, and the Reference Implementations that show how they fit together.

<Callout type="info">
The Canton ecosystem stack is under active development. Components are labelled
by maturity throughout these docs. Treat everything marked *experimental* as
a preview surface: interfaces may change, and it is not yet audited or intended
for production use.
OpenZeppelin builds reusable, security-focused [Daml](https://docs.digitalasset.com/) packages for applications on the [Canton Network](https://www.canton.network/). This section documents the library packages and the Reference Implementations that use them.

<Callout type="warn">
No package has a release or an audit yet. Do not use the packages in
production. Scoped Authorization Grant and Pausable are pre-release
packages. Token is an experiment: it will be redesigned before its first
release, and the redesign will change module names, choice signatures, and
package IDs.
</Callout>

## Library

Foundational Daml modules that other packages and applications compose on top of. See the [Library overview](/canton/library) for the design philosophy. These live in [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts).

- **[Access Control](/canton/library/access-control)**: Role-based authorization for Daml workflows, with an admin role that grants and revokes other roles.
- **[Ownable](/canton/library/ownable)**: A single-owner authorization primitive for privileged actions, with ownership transfer.
- **[Pausable](/canton/library/pausable)**: An emergency stop mechanism that lets an authorized party halt and resume sensitive choices.

## Settlement
The packages live in [`OpenZeppelin/canton-contracts`](https://github.com/OpenZeppelin/canton-contracts). Each package is an independent DAR. See the [Library overview](/canton/library) for the design rules.

- **[Settlement (CIP-112)](/canton/settlement)**: An experimental, interface-shaped settlement engine for atomic multi-leg, value-moving delivery-versus-payment, built on the Token Standard V2 (CIP-112) interfaces. Implemented as the [`openzeppelin-tokenCIP112-v1`](https://github.com/OpenZeppelin/canton-contracts/tree/main/experiments/token/tokenCIP112-v1) package in `OpenZeppelin/canton-contracts`, with executable research and live-ledger evidence in [`OpenZeppelin/canton-specs`](https://github.com/OpenZeppelin/canton-specs).
- **[Scoped Authorization Grant](/canton/library/scoped-authorization-grant)**: resource-scoped, revocable, time-bounded grants. Protected choices check the grant that the caller presents. Role-based access control builds on it.
- **[Pausable](/canton/library/pausable)**: an emergency stop. Your template holds the flag, and gated choices refuse to run while it is set.
- **[Token (CIP-0112)](/canton/library/token)**: a token that implements the Token Standard V2 interfaces, with batch settlement, compliance hooks, and CIP-86 allowances.

## Reference Implementations

- **[Reference Implementations](/canton/reference-implementations)**: End-to-end application blueprints (DEX, Lending, Cross-Chain Stablecoin, Confidential Auction) that demonstrate how the library and settlement primitives compose into real applications.
The [Reference Implementations](/canton/reference-implementations) are target architectures for complete applications: a DEX, a lending protocol, a cross-chain stablecoin bridge, and a confidential auction.

## Where to Start

New to the Canton stack? Head to **[Get Started](/canton/get-started)** for prerequisites, toolchain setup, and how to add OpenZeppelin packages to a Daml project.
Go to [Get Started](/canton/get-started) to install the toolchain and add OpenZeppelin packages to a Daml project.

---

Expand Down
Loading
Loading