> For the complete documentation index, see [llms.txt](https://docs.bitsafe.finance/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.bitsafe.finance/cbtc-1/get-started/install-and-validate-dars.md).

# Install and validate DARs

[CBTC environments and prerequisites](/cbtc-1/get-started/environments-and-prerequisites.md)

### Outcome

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

{% hint style="info" %}
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.
{% endhint %}

### 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](https://github.com/DLC-link/cbtc-lib/releases/tag/v0.6.4).
* The current compatibility row for the target Canton version, CBTC DAR release, and environment.

{% hint style="info" %}
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.
{% endhint %}

### 1. Get the pinned DAR release

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

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

```bash
chmod +x upload_dars.sh
./upload_dars.sh
```

The script uploads:

1. Dependency DARs from `dars/dependencies/`.
2. 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.

{% hint style="info" %}
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.
{% endhint %}

### 5. List the installed CBTC DARs

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

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

{% hint style="info" %}
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.
{% endhint %}

### 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

* [`cbtc-lib` `v0.6.4` DAR guidance](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/cbtc-dars/README.md)
* [Recommended gRPC upload script](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/cbtc-dars/upload_dars.sh)
* [CBTC DAR inventory script](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/cbtc-dars/00_ValidateDars.sc)
* [Alternative Canton upload script](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/cbtc-dars/00_UploadDars.sc)
* [Scala prerequisites](https://github.com/DLC-link/cbtc-lib/blob/v0.6.4/cbtc-dars/scala-prerequisites.md)

### Related pages

* [CBTC environments and prerequisites](/cbtc-1/get-started/environments-and-prerequisites.md)
* [CBTC authentication](/cbtc-1/get-started/authentication.md)
* [Mint CBTC](/cbtc-1/guides/mint-cbtc.md)
* [Redeem CBTC](/cbtc-1/guides/redeem-cbtc.md)
* [CBTC compatibility and release notes](/cbtc-1/concepts-and-reference/compatibility-and-release-notes.md)

### Next step

👉 **Configure access:** [CBTC authentication](/cbtc-1/get-started/authentication.md).


---

# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.

## Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.bitsafe.finance/cbtc-1/get-started/install-and-validate-dars.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.