« Changelog History


hie-core v1.0.0 Release Notes

Release Date: 2020-04-15 // about 4 years ago

  • Summary

    • 🆕 New JavaScript/TypeScript client-side tooling is now stable and the
      🏗 recommended way to build DAML applications. A new Getting Started
      📄 Guide       based
      on these tools has replaced the Quickstart guide.
    • The Time Model has been improved so that it works seamlessly without
      ⚡️ user input to the Ledger API. Action needed when you update to the
      ✅ latest version of API bindings or recompile gRPC clients.
    • 🔧 More TLS configuration options for DAML Ledgers.
    • 0️⃣ The next generation Sandbox is now the default, bringing an
      experience closer to a distributed ledger. Immediate action is
      needed if your project is relying on scenarios for ledger
      🎉 initialization.
    • 🗄 Cleanup of names, deprecated features and language versions.
      Immediate action needed if you use any Java dependencies with
      📦 com.digitalasset packages or Maven coordinates.

    Known issues

    • The new Sandbox has a known issue where some false negative contract
      key lookups are only correctly validated on the read path, not on
      the write path. The net effect is that with carefully constructed
      DAML models, non-conformant transactions can be recorded in the
      underlying storage, which may lead to data continuity issues when
      🛠 this issue is fixed. Full details can be found on GitHub issue
      #5563      .

    What's New

    🆕 New Client Tooling

    Background

    Distributed applications are much more than smart contracts running on a
    distributed ledger, and in 2019 we set out to make it significantly
    🏗 easier to build that part of applications which lives off-ledger:
    Automations, Integrations, and UIs. The new tooling is focused on giving
    application developers an easy-to-consume, real-time ledger state, which
    🚚 moves the development experience away from event sourcing and makes it
    similar to working with a database.

    • The HTTP JSON API: giving a queryable view of the ledger state and
      endpoints to submit transactions, all using an easy-to-consume JSON
      format.
    • 📦 A JavaScript/TypeScript code generator: turning a DAML package into
      a (typed) library to interact with the HTTP JSON API.
    • A set of JavaScript/TypeScript client libraries: working hand in
      hand with the code generator to interact with the HTTP JSON API, and
      bind ledger data to React components.
    • A new Getting Started Guide shows how all these pieces fit together
      🏗 to build a complete distributed end-to-end application with a custom
      💻 UI.

    The HTTP JSON API is designed to be consumable from any language
    ecosystem. The choice of JavaScript (and React) for the rest of the
    tooling was driven by the desire to aid application development all the
    way up to UIs, using the most widely adopted technologies.

    Specific Changes

    • 📚 The documentation has a new Getting Started
      📄 Guide      . The
      🚚 previous Quickstart guide has moved under the Java Bindings section.
    • There is a new SDK template with a skeleton for an end-to-end
      application using the new tooling. It's documented and used in the
      🆕 new Getting Started Guide. Use
      daml new create-daml-app create-daml-app to get started.
    • The /v1 endpoints of the HTTP JSON API and the JavaScript Code
      👍 Generator and Support Libraries are now stable.
      • The JSON API has gained an endpoint to allocate parties:
        /v1/parties/allocate.
    • 👌 Support for maps and lists has been removed from the query language.
    • Note that the WebSockets streaming endpoint of the HTTP JSON API is
      still under development.

    Impact and Migration

    The new client tooling is almost purely additive so for most, no action
    is needed. For new applications, we recommend this tooling as it makes a
    lot of things quicker and easier. However, direct use of the Ledger API
    and HTTP JSON API continues to be a good option for anyone needing
    lower-level control or wanting to use a different language for their
    applications.

    The only non-backwards compatible change compared to previous versions
    is the removal of queries on lists and maps in the HTTP JSON API. There
    is no trivial migration for this. If you were relying on these
    capabilities please get in touch with us via [email protected] or on
    Slack. We'd like to hear how you were making use of the feature so that
    👍 we can replace it with something better, and we will make some
    ↪ suggestions to work around the removal.

    👌 Improved Time Model

    Background

    🚀 SDK Release 0.13.55 introduced a new method for command deduplication
    and deprecated the command field maximum_record_time. SDK Release 1.0
    further improves the Ledger Time model so that users no longer need to
    pass in any time related information to the Ledger API. The new time
    model is designed to work under almost all circumstances without user
    intervention, making developing applications against DAML Ledgers easier
    in practice.

    Specific Changes

    • The Sandbox no longer emits Checkpoints at regular intervals in wall
      clock mode.
    • The ledger_effective_time and maximum_record_time fields have
      🚚 been removed from the Ledger API, and corresponding fields have been
      ✂ removed from the  HTTP JSON API and Ledger API language bindings.
    • 0️⃣ The --default-ttl command line argument of the HTTP JSON API is
      gone.
    • Ledger Time is no longer strictly monotonically increasing, but only
      follows causal monotonicity: Ledger Time of transactions is greater
      than or equal to the Ledger Time of any input contract.
    • The Command Service is no longer idempotent with respect to
      duplicate submissions. Duplicate submissions now instead return an
      ALREADY_EXISTS error, consistent with the new deduplication
      mechanism of the Command Submission Service.

    Impact and Migration

    Old applications will continue running against new ledgers, but ledger
    effective time and maximum record time set on submissions will be
    ignored. As soon as the client-side language bindings or compiled gRPC
    ⚡️ services are updated, the fields will need to be removed as they are no
    longer part of the API specification.

    👍 Better TLS Support

    Background

    👍 DAML Ledgers have always supported exposing the Ledger API via TLS, but
    👌 support on consuming applications was inconsistent and often required
    🚀 client certificates. From this release onward, more client components
    👌 support consuming the Ledger API via TLS without client authentication.

    Specific Changes

    • 🔧 When Sandbox is run with TLS enabled, you can now configure the
      👀 requirement for client authentication via  --client-auth. See the
      📚 documentation
      for more information.
    • 🚀 The daml deploy and daml ledger commands now support connecting
      👀 to the Ledger API via TLS. See their
      📚 documentation
      for more information.
    • 👍 DAML Script and DAML Triggers now support TLS by passing the --tls
      flag. You can set certificates for client authentication via --pem
      and --crt and a custom root CA for validating the server
      certificate via --cacrt.
    • Navigator, DAML Script, DAML REPL, DAML Triggers, and Extractor can
      now run against a TLS-enabled ledger without client authentication.
      You can enable TLS without any special certificates by passing
      --tls.
    • 🔧 DAML Script and DAML Triggers have the option to configure
      certificates for client authentication via --pem and --crt and a
      custom root CA for validating the server certificate via --cacrt.

    Impact and Migration

    This is a new capability, so no action is needed. These new features are
    👉 useful in production environments where client to ledger connections may
    need to be secured.

    Next Generation Sandbox

    Background

    The DAML Sandbox has had a major architectural overhaul to bring it and
    its user experience even closer in line with other DAML Ledgers. The new
    0️⃣ Sandbox is now the default, but the "classic" Sandbox is included as a
    🚀 deprecated version in this release. The classic Sandbox will be removed
    🚀 from the SDK in a future release and will not be actively developed
    further.

    Specific Changes

    • daml sandbox and daml start start the new Sandbox. The classic
      sandbox can be invoked via daml sandbox-classic and
      daml start --sandbox-classic.
    • 0️⃣ Wall Clock Time mode (--wall-clock-time) is now the default.
    • 👍 Scenarios are no longer supported for ledger initialization.
    • Contract identifiers are hashes instead of longer sequence numbers.
      • A new static contract identifier seeding scheme has been added
        to enable reproducible contract identifiers in combination with
        👀 --static-time. Set flag --contract-id-seeding=static to use
        it.
    • Ledger API Offsets are no longer guaranteed to be a parsable number.
      They are an opaque string that can be compared lexicographically.
    • 💻 The command line flags --auth-jwt-ec256-crt and
      --auth-jwt-ec512-crt were renamed to --auth-jwt-es256-crt and
      --auth-jwt-es512-crt, respectively, to align them with the
      cryptographic algorithms used.

    Impact and Migration

    The impact is primarily on demo applications running in static time mode
    and/or using scenarios for ledger initialization. Since both the
    classic  and new Sandbox are compliant DAML Ledgers, there is no
    difference in behavior apart from these fringes.

    If you rely on static time mode, set it explicitly using
    --static-time.

    • If you rely on reproducible contract identifiers, also set
      👀 --contract-id-seeding=static.

    If you use a scenario for ledger initialization, migrate to DAML
    📄 Script    .
    📜 If you were parsing ledger offsets, you need to find a way to stop doing
    so. This is not guaranteed to be possible on DAML Ledgers other than the
    classic Sandbox. If you were relying on doing so, get in touch with us
    on [email protected]. We'd like to help with migration and want to
    👍 understand how you were using this so we can better support your use
    case. If you were using ES256 or ES512 signing for authentication,
    💻 adjust your command line flags. If you were running the now classic
    sandbox with persistence in a SQL database, you need to recreate
    contracts in the ledger run with the new sandbox. There is no automatic
    ⏪ data migration available. To ease transition, you can revert back to the
    classic Sandbox using daml sandbox-classic and
    daml start --sandbox-classic=yes. Note that the classic Sandbox is
    🚀 deprecated and will be removed in a future release.

    Cleanup for DAML SDK 1.0

    Background

    🚀 As we are moving into the 1.0 release line, we have done some cleanup
    🗄 work, aligning names of artifacts, removing deprecated language
    🔖 versions, streamlining the release process, and finishing a few language
    ⚠ tweaks by turning select warnings into errors. 

    Specific Changes

    📦 All Java and Scala packages starting with com.digitalasset.daml
    and com.digitalasset are now consolidated under com.daml. 

    • Impact: Changing the version of some artifacts to 1.0 will
      cause a resolution error.
    • Migration: Changing Maven coordinates and imports using a
      find and replace should be enough to migrate your code.

    📦 Ledger API services are now under the com.daml package. A
    compatibility layer has been added to also expose the services under
    📦 the com.digitalasset package.

    • Impact: grpcurl does not work with the compatibility layer.
    • Migration: Scripts using grpcurl need to change the service
      name from com.digitalasset to com.daml.

    < DAML SDK 1.0: com.digitalasset.ledger.api.v1.TransactionService

    ≥ DAML SDK 1.0: com.daml.ledger.api.v1.TransactionService)

    0️⃣ The default DAML-LF target version is now 1.8.

    • Impact: Projects will not run against old DAML Ledgers that
      👍 do not support DAML-LF 1.8.
    • Migration: You can target 1.7 by specifying --target=1.7
      🏗 in the build-options field in your daml.yaml.

    🗄 All DAML-LF versions <1.6 are deprecated and will not be supported
    on DAML Ledgers.

    • Impact: The new Sandbox will not run DAML code compiled to
      DAML-LF 1.5 or earlier.

    - Migration : Use classic Sandbox to run older DAML models.

    🚀 We no longer release the SDK to Bintray.

    • Impact: If you were relying on artifacts on Bintray, you
      ⚡️ will not be able to update to version 1.0 without changing the
      repository.
    • Migration: The new locations are as follows:
      • SDK Releases and Protobuf files are released to GitHub
        🚀 Releases.
      • Java/Scala artifacts are on Maven Central.

      - JavaScript artifacts are on NPM.

    File names must now match up with module names. This already
    🚀 produced a warning in previous releases

    • Impact: Projects in which there are mismatches will no
      🏗 longer build.
    • Migration: Change your .daml filenames to match module
      names.

    It is now an error to define a record with a single constructor
    where the constructor does not match the type name. This restriction
    only applies to single-constructor records. Variants and enums are
    ⚠ not affected. This already produced a warning in SDK 0.13.55.

    • Impact: Projects with now illegal type declarations will no
      🏗 longer build.
    • Migration: In declarations of the type data X = Y with ..,
      you have to change the type name (X) to match data constructor
      name (Y) or vice versa.

    The compiler name collision check has been extended to also count
    the case as a collision where you have a type B in module A and
    a module A.B.C (but no module A.B).

    • Impact: Projects with such module names will produce
      🚀 warnings and stop compiling in a future release. The JavaScript
      📦 Code Generator is not usable on packages that don't uphold this
      restriction.
    • Migration: You have to rename your modules to avoid such
      name clashes.

    Impact and Migration

    Impacts and migrations are covered item by item in Specific Changes
    above.

    Progress on Features Under Development

    Background

    Work is progressing on two features that are currently under active
    development.

    1. The DAML REPL, introduced with SDK 0.13.55 is becoming richer in its
      abilities, getting ever closer in capabilities to DAML Script.
    2. Work on a Websockets streaming version of the HTTP JSON API's
      querying endpoints is progressing. The aim with this streaming
      service is to combine the ease of consumption of the HTTP JSON API
      with the liveness provided by a streaming API.

    Specific Changes

    • DAML REPL
      • You can now use import declarations at the REPL prompt to bring
        ➕ additional modules into scope.
      • You can now use more complex patterns in statements, e.g.,
        (x,y) <- pure (1,2).
      • You can now connect to a ledger with authentication using
        daml repl --access-token-file=path/to/tokenfile option.
    • Websockets on the HTTP JSON API
      • The error format has changed to match the synchronous API:
        {"status": <400 \| 401 \| 404 \| 500>, "errors": <JSON array of strings> }.
      • The streaming version of the query and fetch-by-key endpoints
        👀 now emit the last seen ledger offset. These offsets can be fed
        back to new requests to start the stream at said offset. Such
        offset messages are also used for heartbeating instead of the
        previous explicit heartbeat messages.

    Impact and Migration

    The only impacts are on consumers of the Websocket streaming APIs. Those
    consumers will have to make some minor adjustments to include the API
    🔄 changes around error handling and ledger offsets.

    🛠 Minor Changes and Fixes

    • 🚀  Better support for snapshot releases in the DAML Assistant.
      • daml version can now list the available snapshot versions by
        passing the flag --snapshots=yes.
      • daml install latest can now include the latest snapshot
        🔖 version by passing the flag --snapshots=yes.
      • DAML Script can now be run over the HTTP JSON API, which means
        it now runs against project:DABL. Take a look at the
        📚 documentation
        for instructions and limitations.
    • Party strings are now restricted to 255 characters.
      • Impact: If you used the Sandbox with very long Party strings
        they'll be rejected by the new Sandbox and other DAML Ledgers.
      • Migration: Shorten your Party strings. Note that in ledgers
        other than Sandbox, you may not be able to choose them entirely
        freely anyway.
    • You can now disable starting Navigator as part of daml start in
      your daml.yaml file by adding start-navigator: false.
    • Calls to the GetParties API function with an empty list of parties
      no longer results in an error, but in an empty response.