DAR Backup

DAR File Backup System

The repo dars/ tree preserves versioned DAR (DAML Archive) files for OpenCapTable uploads. Since DAML builds are only deterministic when using the exact same compiler version, we store the exact bytes of published packages here.

As of #217, dars/ and dars.lock keep only OpenCapTable-vNN backups (currently v34). Older OCP DARs and packages maintained in fairmint/daml are not backed up in this tree—use that repo (and its lockfiles / release process) for those artifacts. #216 moved non-OCP sources out of this repo; #217 aligns checked-in backups with the OCP-only layout.

Not the same as the npm DAR: The published JS package @fairmint/open-captable-protocol-daml-js also ships a copy of the current OpenCapTable DAR under a stable export path (opencaptable.dar → published-dars/OpenCapTable.dar; see the NPM Publishing section on Home, including getOpenCapTableDarPath() / resolveOpenCapTableDarPath(), env var OPEN_CAP_TABLE_DAR_PATH, and sibling overrides). That artifact is for downstream tooling tied to the npm release, while dars/ is the canonical backup of deployed OpenCapTable package/version pairs for verification and rollback.

Why We Need This

1. Package verification - Canton validates package hashes; rebuilt packages have different hashes
2. Reproducibility - Ensures we can always redeploy the exact same artifact
3. Rollback safety - Allows redeploying a known-good version if needed

Directory Structure

dars/
├── README.md                          # Human overview (see also this wiki page)
├── dars.lock                          # Hash manifest for CI verification
└── OpenCapTable-v34/
    └── 0.0.1/
        └── OpenCapTable-v34.dar       # Current OpenCapTable backup path

Using the Backup System

After a Successful Upload

Back up the DAR file after uploading to mainnet:

npm run backup-dar -- --package OpenCapTable-v34 --version 0.0.1

This will:

1. Copy the DAR from .daml/dist/ to dars/{package}/{version}/
2. Compute and store the SHA256 hash in dars.lock
3. Fail if the DAR already exists (prevents accidental overwrites)

Verifying DAR Integrity

Check that all DAR files match their recorded hashes:

npm run verify-dars

CI Integration

The CI workflow automatically:

1. Verifies all DAR hashes match dars.lock
2. Fails PRs that modify DAR files without updating dars.lock

dars.lock Format

The dars.lock file contains SHA256 hashes and metadata for all backed-up DARs:

{
  "version": 1,
  "packages": {
    "OpenCapTable-v34/0.0.1/OpenCapTable-v34.dar": {
      "sha256": "abc123...",
      "size": 12345,
      "sdkVersion": "3.4.10",
      "uploadedAt": "2026-01-09T12:00:00Z",
      "networks": ["mainnet", "devnet"]
    }
  }
}

Git LFS

DAR files are stored using Git LFS to keep the repository performant. The .gitattributes file configures this automatically.

Modifying DARs

Never modify a DAR file directly. If you need to deploy a new version:

1. Update the DAML source code
2. Bump the version in daml.yaml
3. Build and upload the new version
4. Back up the new DAR with npm run backup-dar

The CI will reject any PR that modifies existing DAR files without a corresponding version bump.

Troubleshooting

Mainnet upload: NOT_VALID_UPGRADE_PACKAGE (Splice / lineage)

Canton’s default upload path vets new packages immediately. If the new DAR is not an LF-valid upgrade of an already-vetted same package name (often because embedded splice-amulet changed between builds), upload fails with NOT_VALID_UPGRADE_PACKAGE.

Sketch of the escape hatch: upload with --no-vet, then vet the new package id via POST /v2/package-vetting with operator force flags when your topology allows it. Regenerate JS (npm run codegen) after any splice-amulet data-dependency change so bundled imports match the built DAR. For CantonPayments and other multi-package lineages, follow the playbooks documented with fairmint/daml. In this repo, npm run vet-package-allow-incompatible-upgrade is a thin helper around forced vetting (see script header in scripts/vet-package-allow-incompatible-upgrade.ts).

"DAR already exists" error

If you see this error when running backup-dar, it means the DAR for that package/version already exists. This is intentional—we never overwrite backed-up DARs. If you need to deploy changes, bump the version number.

"Hash mismatch" error in CI

This means a DAR file has been modified without updating dars.lock. Either:

1. Restore the original DAR file
2. If intentional, update dars.lock with npm run verify-dars -- --update

Git LFS not working

Make sure Git LFS is installed and initialized:

git lfs install
git lfs pull

References

• Splice DAR storage - Inspiration for this system
• Git LFS documentation