search

digital-asset / daml

The Daml smart contract language
https://www.digitalasset.com/developers
797 stars 199 forks source link

Add a ledger-api-version field to daml.yaml #8973

Open cocreature opened 3 years ago

cocreature commented 3 years ago

Problem

Currently, your only option to target a specific ledger API version (which includes the LF version) is to add a --target flag in the build-options section of your daml.yaml. This works but it has some shortcomings:

  1. Ledgers report the Ledger API version they support but they don’t directly report the list of supported LF versions. You can sometimes see it from log output but that’s rather crude so users have to figure out which version they should chose when deploying to a particular ledger.
  2. Other tools might also need changes depending on the ledger API version. Most manage to avoid having to depend on it explicitly since the ledger API is backwards compatible (at least within minor versions) but in general, changes might be required.
  3. It is easy to accidentally depend on a feature that is not supported in your target Ledger API version.

Proposed changes

  1. Add a ledger-api-version field to daml.yaml.
  2. damlc will pick up this field and chose the target LF version as the newest stable (but possibly not default) LF version compatible with that Ledger API version. If the field is not present, behavior is as it is now.
  3. Other tools will pick up this field when they need to.
  4. Sandbox/Sandbox classic will be chosen to be the latest version that supports this ledger API version and no newer version (i.e., it reports this version on the ledger API endpoint)
  5. Somewhat separate but related: Introduce a connect-version field to control the version of json API, triggers, daml script, …. and deprecate platform-version.

Implementation

  1. Add a machine-readable table of ledger API versions and supported LF versions to our repo.
  2. Based on that table generate Haskell & Scala code that allows you to access this table.
  3. Make damlc pick up the field and use the table to select an LF version.

Other tools can follow later.

bame-da commented 3 years ago

Why not just use a Sandbox version that exposes the right Ledger API version? Ie split platform-version into connect-version which selects JSON API and trigger versions, and ledger-api-version which selects language, compiler, and sandbox versions.

cocreature commented 3 years ago

Why not just use a Sandbox version that exposes the right Ledger API version? Ie split platform-version into connect-version which selects JSON API and trigger versions, and ledger-api-version which selects language, compiler, and sandbox versions.

Because there are other improvements in newer implementations. Performance, bugfixes, better errors, …. Selecting an inferior (assuming we improve our software over time) implementation of the same API just to make sure I don’t accidentally depend on the wrong API is kind of crappy.

cocreature commented 3 years ago

You also pay for two SDK downloads and installations in that case.

bame-da commented 3 years ago

Because there are other improvements in newer implementations. Performance, bugfixes, better errors, …. Selecting an inferior (assuming we improve our software over time) implementation of the same API just to make sure I don’t accidentally depend on the wrong API is kind of crappy.

I don't really buy this. The Sandbox is 95% the integration kit. Ie a. Sandbox which exposes Ledger API version X will behave like a ledger that exposes Ledger API version X in most of the respects you list: Performance, bugfixes, better errors. So I think "Use the latest Sandbox that exposes the given API version" does make sense.

My worry is primarily that uses use unsupported features on the client side. Like you said, multi-party submission via ledger-bindings is a good example. I would like a least a way to be warned that I'm doing so.

cocreature commented 3 years ago

Fair enough, I think there is still value in getting better errors during development even if I can’t get them in my live ledger but that can definitely also be confusing. I don’t feel too strongly about this so fine to go with your proposal. I’ve updated the text.

As for connect-version, this seems a bit confusing once we have a canon-based sandbox.

bame-da commented 3 years ago

I think we could spew out a warning if you start the Canton Sandbox in a project which has ledger-api-version set. It makes no sense since the Connect Node and thus Ledger API version move into app-space.

basvangijzel-DA commented 1 year ago

We are currently looking at adding a general flag for dev version across the stack, this work is related.

moisesackerman-da commented 1 year ago

https://github.com/DACH-NY/canton/issues/11420