Install and validate DARs

Outcome

Upload the CBTC DAR packages required for minting and redemption to a Canton participant, then confirm that the expected CBTC packages are present.

CBTC DAR packages are required for minting and redemption. They are not required for sending or receiving CBTC or for UTXO management, according to the cbtc-lib v0.6.4 DAR guidance.

Before you start

You need:

Administrative access to the target Canton participant.
An approved connection to the participant Admin API. The repository examples use localhost:5002; use the endpoint and connection method documented for the target environment.
A participant administrator JWT if the Admin API requires authentication.
grpcurl, jq, and a compatible base64 command for the recommended upload path.
The pinned cbtc-lib v0.6.4 release.
The current compatibility row for the target Canton version, CBTC DAR release, and environment.

Treat administrator tokens as secrets. Retrieve them through the approved secret-management process. Do not commit tokens, add them to documentation, or leave them in a modified copy of the upload script.

1. Get the pinned DAR release

git clone <https://github.com/DLC-link/cbtc-lib.git>
cd cbtc-lib
git checkout v0.6.4
cd cbtc-dars

Confirm that the directory contains upload_dars.sh, 00_ValidateDars.sc, dars/dependencies/, and dars/cbtc/.

2. Confirm the Admin API connection

Establish the approved port-forward or network path to the participant Admin API. If the target differs from the repository default, update canton_admin_api_url in a local working copy of upload_dars.sh.

Do not proceed until the endpoint is confirmed to belong to the intended participant and environment.

3. Configure authentication

If the Admin API requires authentication, expose the administrator token to the script through the jwt_token environment variable:

export jwt_token="<participant-admin-jwt>"

If the Admin API does not require authentication, leave jwt_token empty. Follow the authentication flow documented for the target environment.

4. Upload the DARs

The recommended repository path uses the gRPC upload script:

chmod +x upload_dars.sh
./upload_dars.sh

The script uploads:

Dependency DARs from dars/dependencies/.
CBTC DARs from dars/cbtc/.

For every upload, the script requests package vetting and synchronized vetting. Canton skips a DAR that is already present, so the repository guidance describes the script as safe to run again.

Confirm that the local base64 command matches the syntax used by the script. The repository calls out a difference between GNU and BSD implementations. Also verify the upload response itself. Do not treat the script's printed success line as sufficient proof that the Admin API accepted every package.

5. List the installed CBTC DARs

The repository includes a Canton script that lists installed DARs whose names contain cbtc:

canton run 00_ValidateDars.sc -c ./misc/connect.conf

For each matching DAR, the script prints:

Name.
Version.
Main package ID.
Description.

Record this output with the environment and release tag used for the installation. Remove tokens and other sensitive values before sharing diagnostic output.

6. Verify the result

A successful installation should meet all of these checks:

Every expected dependency upload returned an accepted or already-present result.
Every expected CBTC upload returned an accepted or already-present result.
00_ValidateDars.sc lists the expected CBTC names, versions, and main package IDs.
The recorded package set matches the Engineering-approved release manifest for the target environment.
A read-only CBTC preflight succeeds before any mint or redemption is attempted.

The included validation script is an inventory check, not a complete compatibility test. It filters for DAR names containing cbtc and does not verify dependency completeness, application behavior, or compatibility with the participant version. Complete the release-specific acceptance test after checking the maintained package manifest.

Expected result

The target participant contains the approved CBTC and dependency DAR set for the selected environment. The CBTC inventory shows the expected versions and package IDs, and the environment passes the approved read-only preflight.

Troubleshooting

Symptom

Check

Next action

Connection refused or unavailable

Port-forward, host, port, participant identity, and Admin API availability.

Restore the approved Admin API connection. Do not switch environments or ports by trial and error.

Unauthenticated or permission denied

Whether the Admin API requires a token and whether the token has participant administrator permissions.

Obtain a new token through the approved process. Do not paste the token into a support ticket.

base64 reports an unsupported option

Whether the workstation uses GNU or BSD base64.

Adapt the local script to the installed implementation, then review the change before retrying.

The CBTC validation list is empty

Target participant, upload responses, DAR names, and Canton connection configuration.

Stop before minting or redemption. Collect redacted logs and escalate with the release tag and environment.

Some packages appear but the release set is incomplete

Dependency and CBTC upload responses, release manifest, and package vetting status.

Do not mix releases. Reconcile against the approved manifest before retrying.

Alternative Canton upload path

The repository also includes 00_UploadDars.sc. In v0.6.4, this script uploads CBTC DARs before dependency DARs, while the README and recommended gRPC script specify dependencies first. Use the recommended gRPC path unless the supported release explicitly documents the alternative ordering.

Technical sources

Next step

👉 Configure access: CBTC authentication.

PreviousDeveloper quick start

NextAuthentication

Last updated 21 days ago