2d511b449d
* Make choice observers mandatory when available. This is an invariant of the DAML-LF proto. The haskell AST allows missing choice observers for any version, because the AST represents what was written in the syntax. However, if we are targeting a new DAML-LF version (>= `featureChoiceObservers`) then `Nothing` is converted to `Just (ENil TParty)` by the haskell encoder (`EncodeV1.hs`) to satisfy the proto invariant. On the scala side, the decoder (`DecodeV1.scala`) now insists that choice observers are present when_ the version is new. (>= `LV.Features.choiceObservers`). changelog_begin changelog_end * LF: LF encoder generate always choice observer if lf >= 1.dev (#8318) This is a follow up of #8316. This advances the state of #7709 CHANGELOG_BEGIN CHANGELOG_END Co-authored-by: Remy <remy.haemmerle@daml.com> |
||
|---|---|---|
| .. | ||
| src | ||
| archive.bzl | ||
| BUILD.bazel | ||
| README.md | ||
DAML-LF archive
This component contains the .proto definitions specifying the format
in which DAML-LF packages are stored -- the DAML-LF archive. All the
proto definitions are kept in the directory
src/protobuf/com/daml/daml_lf_dev/
The entry point definition is Archive in
src/protobuf/com/daml/daml_lf_dev/daml_lf.proto. Archive
contains some metadata about the actual archive (currently the hashing
function and the hash), and then a binary blob containing the
archive. The binary blob must be an ArchivePayload -- we keep it in
binary form to facilitate hashing, signing, etc. The encoding and
decoding of the payload is handled by Haskell and Java libraries in
daml-core-package, so that consumers and producers do not really
need to worry about it.
ArchivePayload is a sum type containing the various DAML-LF versions
supported by the DAML-LF archive. Currently we have two major versions:
DAML-LF-0, which is the deprecated legacy DAML core;DAML-LF-1, which is the first version of DAML-LF as specified by https://github.com/digital-asset/daml/blob/master/daml-lf/spec/daml-lf-1.rst.
Snapshot versions
The component contains also an arbitrary number of snapshots of the
protobuf definitions as they were as the time a particular version of
DAML-LF was frozen. For versions <= 1.8, those snapshots are kept in the directories
src/protobuf/com/digitalasset/daml_lf_x_y/, where x.y is a
already frozen DAML-LF version. For newer versions, the directory is
src/protobuf/com/daml/daml_lf_x_y/. A snapshot for version x.y can be
used to read any DAML-LF version from 1.0 to x.y without suffering
breaking changes (at the generated code level) often introduced in the
current version.
Building
It produces several libraries containing code to encode / decode such definition, a Haskell one, and several Java ones:
$ bazel build //daml-lf/archive:daml_lf_archive_haskell_proto
$ bazel build //daml-lf/archive:daml_lf_dev_archive_proto_java
$ bazel build //daml-lf/archive:daml_lf_1_6_archive_proto_java
Editing the .proto definitions
When editing the proto definitions, you must make sure to not change them in a backwards-incompatible way. To make sure this doesn't happen:
- DO NOT delete message fields;
- DO NOT change the number of a message field or an enum value;
- DO NOT change the type of a message field;
Note that "fields" include oneof fields. Also note that the "don't
delete fields" rule is there not because they introduce a backwards
incompatible change, but rather because after a field has been deleted
another commiter might redefine it with a different type without
realizing.
What is OK is renaming message fields while keeping the number and semantics unchanged. For example, if you have
message Foo {
bytes blah = 1;
}
it's OK to change it to
message Foo {
// this field is deprecated -- use baz instead!
bytes blah_deprecated = 1;
string baz = 2;
}
Conversion from the .proto to AST
The .proto definitions contain the serialized format for DAML-LF
packages, however the code to convert from the .proto definitions to
the actual AST lives elsewhere.