DAR Backup

DAR File Backup System

The repo dars/ tree preserves versioned DAR (DAML Archive) files for OpenCapTable uploads. Since package identity is determined by the compiled package ID, we store the exact bytes of deployed packages and one mutable candidate per package line.

As of #217, dars/ and dars.lock keep only OpenCapTable-vNN backups. 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

The exact set of backed-up artifacts is defined by dars/dars.lock (and the matching paths under dars/). Example layout:

dars/
├── dars.lock                          # Hash manifest for CI verification
├── OpenCapTable-vNN/
│   ├── 0.0.1/
│   │   └── OpenCapTable-vNN.dar       # Deployed history, immutable
│   └── 0.0.2/
│       └── OpenCapTable-vNN.dar       # Current networks:[] candidate, replaceable
└── …                                  # Additional deployed OpenCapTable-vNN rows per dars.lock

There is no dars/README.md in the repo — this wiki page and dars.lock are the references.

Related archives: Historical DAR backups for packages that are no longer stored under this repo’s dars/ tree may also be maintained in Fairmint/daml alongside its lockfile.

Using the Backup System

Preparing a Candidate

Back up the current candidate before upload:

npm run backup-dar -- --package OpenCapTable-vNN --version 0.0.2

This will:

1. Copy the DAR from .daml/dist/ to dars/{package}/{version}/
2. Compute and store the SHA256 hash in dars.lock
3. Replace the existing networks: [] candidate atomically when its bytes change
4. Refuse to replace any backup recorded on a network or proven live on DevNet

DevNet-Anchored Version Policy

The preferred packages reported live by both DevNet providers (intellect and 5n) are the only authority for selecting a candidate version. Version calculation never queries Mainnet or uses Mainnet state.

• If neither provider has the package line, use 0.0.1.
• Otherwise, a changed DAR must be exactly one patch above the highest preferred DevNet version. A DAR counts as already deployed only when every configured provider prefers its exact package ID and version; one provider present and one absent still requires the next patch and does not justify a devnet marker.
• Run dpm upgrade-check --both from every distinct preferred DevNet DAR to the candidate. If the providers prefer different versions, the higher version controls the patch calculation, but both predecessors must be compatible.
• If providers report different package IDs for the same package name and version, stop and reconcile the conflict. Semantic version equality is not package-ID equality.
• Keep one mutable networks: [] candidate per package line. Deployed or live-confirmed backups are immutable.
• Prune a superseded networks: [] backup only after a live query proves that its exact package ID is not preferred by either configured DevNet provider. Preserve all deployed history, including recorded Mainnet artifacts.

Recovery and partial uploads

• If CI reports that an exact preferred DevNet predecessor is missing, stop. Recover that exact DAR from the deployment branch, release artifact, or historical commit and verify its package ID before adding it to dars.lock. Never overwrite a different recorded DAR that reused the same semantic version; retain both under distinct backup filenames.
• A partial upload can leave the providers on different preferred versions. Preserve both exact predecessors, choose the next candidate one patch above the higher version, and run compatibility from both.
• If providers report different package IDs for the same name/version, do not upload another candidate. Reconcile DevNet first.
• Network markers are additive evidence. A new devnet marker requires the exact locked package ID and version to be preferred by every configured DevNet provider.
• A new mainnet marker is accepted only when an immutable GitHub Actions artifact binds the exact marker commit to its trusted release run, package, and lock entry, after DevNet evidence; an automation/ocp-release-* branch name alone is not provenance. Mainnet markers are retained as history but never affect candidate-version calculation.
• Removing a marker or a recorded DAR is never pruning. Historical same-version/different-ID artifacts remain immutable under distinct backup filenames; only a live provider collision for the same version blocks new work.

Verifying DAR Integrity

Check that all DAR files match their recorded hashes:

npm run verify-dars

CI Integration

• check-dars.yml — runs on pushes that change dars/** (or the workflow file). Executes npm run verify-dars to ensure hashes match dars.lock.
• release.yml — the package tag release workflow runs npm run backup-dar during build, then npm run verify-dars before publish; it commits updated dars/ and dars.lock back to main when they change.

PRs that modify DAR files without a matching dars.lock update will fail verification.

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 source changes alter the compiled DAR:

1. Update the DAML source code
2. Query both preferred DevNet packages and select the candidate version by the policy above
3. Build the candidate and run upgrade compatibility from every distinct DevNet predecessor
4. Refresh its mutable backup with npm run backup-dar, then upload the exact backed-up bytes

CI rejects changes to deployed backups, candidate versions that do not match DevNet, and build-versus-backup mismatches.

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 backup is immutable" error

This means the version is recorded on a network or its package ID is live on DevNet. Keep that exact backup and use the candidate version derived from the preferred DevNet high-water mark. Only an unuploaded networks: [] candidate can be replaced.

"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. For an unuploaded candidate only, recreate the backup with npm run backup-dar

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