Distribute and upload earlier versions of SCU-compatible DARs?

App Development
1

If I have this:

  • an older lib-1.0.0.dar with the org.lib.v1 package
  • a newer, lib-1.1.0.dar which is SCU-compatible
  • existing contracts on-ledger, still using the 1.0.0 models

My questions are:

  1. Should new app users upload/vet both DARs to their nodes?
  2. Must new app users upload/vet the DARs in oldest-to-newest order?
2

@WallaceKelly Yes, new participants should generally upload/vet both lib-1.0.0.dar and lib-1.1.0.dar if contracts created from 1.0.0 still exist on-ledger.

Even with SCU compatibility, Canton/Daml contracts are tied to the exact package ID they were created from. So participants that need to interpret, validate, or process transactions involving older contracts must still have the 1.0.0 package available and vetted. The 1.1.0.dar is then needed for newly created or upgraded contracts.

As for ordering, i know:

  • There is usually no hard protocol requirement to upload DARs strictly oldest->newest.

  • However, in practice it’s the recommended operational approach, especially with SCU, because the newer package may need the older one present for compatibility validation and smoother rollout behavior.

So operationally the safest flow is:

  1. Upload/vet lib-1.0.0.dar

  2. Upload/vet lib-1.1.0.dar

  3. Keep 1.0.0 available until all legacy contracts are archived or migrated

That way the participant can safely process both old and upgraded contract states.

3

I believe this is no longer the case starting with Canton 3.4.

One can un-vet 1.0.0 and still use contracts created with 1.0.0 in choices exercised via 1.1.0.

Not sure about the ordering of operations.

cc @tudor_voicu

4

Yes, @Matteo_Limberto is right. Users generally only need the latest DAR uploaded and vetted even if a contract’s original package is not vetted/uploaded anymore.

Must new app users upload/vet the DARs in oldest-to-newest order?

When you need multiple versions of the same package-name uploaded/vetted (e.g. to satisfy different vetting states of counterparties in an application), you can upload and vet them in any order, provided they are pair-wise upgrade-compatible.

5

@tudor_voicu, when you say “Users generally only need the latest…” (emphasis mine) and “(e.g., to satisfy different vetting states of counterparties…)” do I understand correctly that…

In a subtransaction, all counterparties must have the same package version vetted?