hie-core v1.4.0 Release Notes

Release Date: 2020-08-12 // over 2 years ago
  • Highlights

    • DAML on SQL is available as an Early Access standalone JAR, you can
      ๐Ÿš€ find it on the GH Release
      ๐Ÿš€ page
    • ๐Ÿ‘Œ Improvements to Ledger API and documentation for client application
      • This involves changes in the Ledger API in corner cases, but
        unless you are dealing with application failover, you are
        unlikely to be affected.
    • DAML REPL is stable and has gained new features, including the
      ability to run without being connected to a ledger
      • Module imports now need to be made explicit when starting DAML
    • daml codegen js is significantly faster when generating
      Javascript/TypeScript code
    • ๐Ÿ†• New Previous/Next buttons on
      ๐Ÿ“„ docs.daml.com. Thanks to Alex Mason for
      ๐Ÿ“š suggestion

    Impact and Migration

    Migration from SDK 1.3 to 1.4 should require no action for almost all
    ๐Ÿ‘‰ users.

    • If you were using the Early Access version of DAML REPL, you need to
      ๐Ÿ‘‰ make a minor adjustment to the CLI parameters to start it.
    • If you are working on application failover, you need to incorporate
      some API improvements.

    ๐Ÿš€ Standalone Early Access release of DAML on SQL


    The DAML Sandbox's primary purpose is to serve as an in-memory
    ๐Ÿ‘ development tool, but has had support for SQL backing for a long time.
    โœ… This made it a popular choice as a prototyping ledger and test tool, but
    lacking a separate distribution, required an entire SDK installation to
    ๐Ÿš€ run. To add clarity and ease deployment, the developer tool "Sandbox",
    and the Ledger "DAML on SQL" are now being separated. As a first step,
    DAML on SQL is now available as a standalone JAR file on GitHub
    ๐Ÿš€ releases. Some minor changes to functionality and CLI are planned for
    ๐Ÿš€ upcoming releases to further differentiate developer tooling and actual
    Ledger. The standalone JAR will remain in Early Access until those
    ๐Ÿ”„ changes have been made.

    Specific Changes

    ๐Ÿš€ DAML on SQL is now available with every release from the GitHub
    ๐Ÿš€ Releases page

    Impact and Migration

    For now, this is a purely additive change, but at the same time DAML on
    ๐Ÿ—„ SQL will become stable,, persistence mode in Sandbox will be deprecated,
    ๐Ÿ‘ and after a transition period, both support for persistence in Sandbox,
    ๐Ÿšš and the already deprecated Sandbox-classic will be removed from the SDK.
    ๐Ÿ‘‰ Users of Sandbox-classic or Sandbox with SQL backing are advised to
    start migrating over to the new DAML on SQL distribution.

    Client Application Failover


    Client applications have to be able to deal with the possibility that
    participant nodes become unavailable, for example due to network or
    hardware failure. For such cases, some DAML Ledgers offer the
    possibility to run hot (or cold) standbys of participant nodes. When a
    failover from a primary to a standby node occurs, the client application
    ๐Ÿšค has to handle the possibility that due to latency or initialization, the
    standby is not yet fully caught up with the Ledger. Improvements to
    ๐Ÿ“š Ledger API and documentation makes this significantly easier.

    Specific Changes

    • The error code for requesting a transaction stream with an offset
      beyond the ledger end changed from INVALID_ARGUMENT to
    • The command completion service now validates the offset and returns
      the OUT_OF_RANGE error if the request offset is beyond the ledger
    • โž• Added a documentation
      ๐Ÿ“„ section

      on how to write DAML applications that can fail over between
      eventually consistent Ledger API endpoints.

    Impact and Migration

    The behaviour of the transaction and command completion services have
    ๐Ÿ”„ changed in cases where an offset beyond ledger end are given. This
    should only happen if a client application re-connects to a different
    node which is not fully caught up, so you are only likely to be affected
    if your application fails over.

    If you were relying on the old behaviors (returning INVALID_ARGUMENT,
    or accepting the argument, respectively), you now need to handle the
    OUT_OF_RANGE error and implement retry logic.

    REPL is now Stable


    DAML REPL, a developer tool to interactively evaluate DAML and interact
    with DAML Ledgers has been in Early Access since SDK 0.13.55. With this
    ๐Ÿš€ release, it becomes stable, meaning its developer facing APIs are final
    and won't break outside of major SDK versions. In addition, it has
    gained a number of new useful features including the ability to run
    โœ… without being connected to a DAML Ledger, allowing interactive testing
    of pure functions, for example.

    Specific Changes

    • โš™ Run DAML REPL without connecting to a ledger by omitting the
      --ledger-host and --ledger-port parameters.
    • List the currently imported modules using the REPL command
      :show imports.
    • ๐Ÿ‘€ Type :help at the REPL prompt to see a list of possible REPL
    • โž• Add and remove module imports using :module [+-] Some.Module.
    • ๐Ÿ‘‰ Use let bindings to bind pure expressions
    • The list of DARs passed to DAML REPL can now be empty.
    • ๐Ÿ‘ The REPL now supports loading multiple DARs specified at the command
      line. The DARs are loaded as data-dependencies.
    • 0๏ธโƒฃ The REPL no longer loads modules by default to avoid collisions when
      multiple DARs are loaded.

    Impact and Migration

    You now need to either explicitly import all modules of your DAR file
    using the --import flag, or use :module + โ€ฆ inside the REPL. For
    example, if you previously started the REPL with

    daml repl .daml/dist/script-example-0.0.1.dar``

    you now need to either run

    daml repl .daml/dist/script-example-0.0.1.dar --import script-example``

    or import modules individually with

    :module + ScriptExample

    Faster JavaScript codegen


    The TypeScript/JavaScript codegen daml codegen js used to generate
    TypeScript files and then use yarn to compile these to JavaScript and
    declaration files. The codegen now generates JavaScript and declarations
    directly, significantly improving speed, and removing the dependency on

    Specific Changes

    • daml codegen js no longer requires yarn and is significantly

    Impact and Migration

    No action is required to consume this improvement.

    Minor Improvements

    • The DAML compiler will now compile type synonyms (type X = Y) into
      the DAR,whenever possible, and will expose these synonyms via
      0๏ธโƒฃ data-dependencies. This works for DAML-LF 1.8 (the current default)
      and upwards.
    • ๐Ÿ–จ DAML Ledgers now print detailed log messages whenever a request was
      rejected due to a failed JWT authentication/authorization, allowing
      for easier debugging.
    • You can now use daml new project-name --template=template-name
      instead of daml new project-name template-name. The positional
      arguments led to confusion so the named version is now preferred,
      but both continue to work.
    • ๐Ÿ“ฆ Successful package uploads to the Sandbox are now logged on the
      ๐Ÿ‘€ server. See #6144.
    • Sandbox now allows the user to specify the participant ID with the
      --participant-id switch.
    • โฑ The daml ledger commands now accept a --timeout option which can
      0๏ธโƒฃ be used to change the timeout for API requests from the default of
    • You can now specify the version of Sandbox and the JSON API
      independently of your SDK version by setting platform-version in
      ๐Ÿš€ your daml.yaml. This is useful if you are deploying to a ledger
      ๐Ÿ‘€ that is running components from a different SDK version. See
      ๐Ÿ“„ https://docs.daml.com/1.4.0/tools/assistant.html#project-config-file-daml-yaml
      for details.
    • daml new foobar --template=create-daml-app now properly respects
      the project name and creates a project called foobar in
      ๐Ÿ“ฆ daml.yaml and package.json instead of hardcoding the name to
    • ๐Ÿ‘€ Scala codegen has gained support for exercise-by-key commands. See
      Issue #6466.

    ๐Ÿ› Bug and Security fixes

    • ๐Ÿ›  Fix an issue in the JavaScript Client Libraries where some recursive
      types resulted in a stack overflow.
    • The ActiveContractService now only sets the offset in the last
      response, as intended, instead of in every response element.
    • A bug relating to how Fetch nodes are validated in some DAML ledgers
      ๐Ÿ›  was fixed.

    Integration Kit

    • ๐ŸŽ The performance test names have been changed. To learn more about
      ๐Ÿ“š the available tests, consult the documentation for the Ledger API
      โœ… Test Tool and run it with --list. Docs:
      โœ… https://docs.daml.com/tools/ledger-api-test-tool/index.html
    • ๐Ÿ›  Fixed a bug in the Ledger API test tool that caused the full
      ๐ŸŽ conformance test suite to be run when trying to run performance
      ๐Ÿ‘€ tests but using a wrong name. See
    • Truncate GRPC error messages at 4 KB. This ensures that we won't
      trigger a protocol error when sending errors to the client.
    • ๐Ÿ”„ Change the callback for contract keys from
      GlobalKey => Option[ContractId] to
      GlobalKeyWithMaintainers => Option[ContractId] in DAML Engine
    • โœ‚ Removed Sandbox specific code from the API intended to be used by
      ledger integrations. Use the maven coordinates
      com.daml:participant-integration-api:VERSION instead of
      com.daml:ledger-api-server or com.daml:sandbox.
    • StandaloneApiServer can now be run in a read-only mode
      • The type of the constructor parameter writeService of
        StandaloneApiServer changed to Option[WriteService]. Passing
        None will not start any of the admin services, the command
        service, and the command submission service.
      • The constructor parameter readService of StandaloneApiServer
        ๐Ÿšš has been removed.
      • A new constructor parameter ledgerId has been added to
        StandaloneApiServer. It is used to verify that
        StandaloneApiServer is run against an index storage for the
        same ledgerId. Initialization is aborted if this is not the
    • ๐Ÿ”ง The LedgerConfigurationService now properly streams configuration
      ๐Ÿ”„ changes.
    • 0๏ธโƒฃ Default new Engine constructor to Engine.StableConfig so it does
      not need to be overridden unless you specifically want to run in
      Engine.DevConfig mode
    • โœ… The LotsOfPartiesIT and TransactionScaleIT test suite have been
      ๐Ÿšฆ deemed not providing relevant signal to DAML ledger implementers and
      โœ… have been retired. The tests will be nominally kept in but will be
      ๐Ÿ—„ skipped while they are in a deprecation period. You are advised to
      โœ‚ remove explicit references to those tests before they are fully
      โœ‚ removed.
    • โœ… All tests are now run by default. The --all-tests option is now
      ๐Ÿšš ineffective and deprecated. You are advised to remove its usages
      ๐Ÿ— from your build scripts. Non-isolated tests that could affect the
      โœ… global state of the ledger and interfere with other tests are now
      โฑ automatically scheduled by the test tool to run sequentially at the
      end of the run.
    • ๐Ÿ—„ The --load-scale-factor option is now unused and deprecated. You
      ๐Ÿ— are advised to remove its usages from your build scripts.