hie-core v1.3.0 Release Notes

Release Date: 2020-07-16 // over 1 year ago
  • Summary

    • The Websocket query and fetch APIs are now stable.
    • ๐Ÿš€ The JSON API Server is now released as a standalone JAR file to
      ๐Ÿš€ GitHub Releases.
    • DAML Script and REPL now work in Static Time mode and can query
      parties.
    • DAML Studio exposes more details on how contracts were disclosed.
    • The Trigger Service, a solution to host and manage DAML Triggers is
      now available in Early Access.

    Known Issues

    The DAML Studio VSCode extension is affected by a known and recently
    ๐Ÿ›  fixed bug in recent VSCode versions:
    microsoft/vscode#89038

    For some users this may lead to the Scenario View in VSCode not
    โฌ†๏ธ rendering correctly. If you are affected by this issue upgrading to
    VSCode 1.47 should resolve it.

    What's New

    Websocket API is stable

    Background

    The JSON API Server exposes several Websocket endpoints which allow
    clients to maintain a live view of contract data without polling. These
    endpoints have been available since before SDK 1.0 in early access, and
    are now considered stable.

    Specific Changes

    • The API specification for the /v1/stream/query and
      /v1/stream/fetch endpoints are finalized and fully implemented. 

    Impact and Migration

    The final version of these endpoints is backwards compatible with SDK
    1.0 in the sense that clients of these endpoints from SDK 1.0 work with
    SDK 1.3. Thus no action needs to be taken.

    Standalone JSON API Server

    Background

    The JSON API Server is a component intended to be run in production
    environments to supplement the lower level Ledger API with an
    easy-to-use queryable ledger state consumable by any HTTP 1.1 client,
    ๐Ÿ’ป including web browsers. Despite this intended use case, the JSON API
    Server was only distributed as part of the SDK, which meant that the
    DAML SDK had to be installed on production servers in order to run the
    JSON API Server. Providing a stand-alone JAR distribution gives
    ๐Ÿš€ application operators a much leaner deployment option.

    Specific Changes

    Impact and Migration

    This is purely additive to the distribution via the SDK so no action is
    โœ… needed. However, if you do run the JSON API Server in a test or
    production environment, this gives you a leaner and more portable way of
    doing so.

    More functionality in DAML Script and REPL

    Background

    โœ… DAML Script and REPL had some limitations in key test and production use
    cases. Firstly, neither exposed the Time Service, which made them hard
    to use in static time mode. Secondly, they only exposed functions to
    allocate parties, not to query existing parties, which required existing
    parties to be passed in via a file, or to be obtained using unsafe
    functions like partyFromText. By exposing the relevant functions of
    the Ledger API in DAML Script and REPL, Ledger Time can now be queried
    and set in Static Time mode, and existing parties can be queried.

    In addition, it is now possible to use DAML Script and REPL with
    multiple JWTs, which in particular, means they can be used with multiple
    parties on DABL.

    Specific Changes

    • DAML Script and REPL's getTime now correctly handles time changes
      in static time mode and returns the current time by querying the
      0๏ธโƒฃ time service rather than defaulting to the Unix epoch. This only
      works in static time mode and via gRPC. In wallclock mode, getTime
      continues to return the system time in UTC. When run against the
      JSON API in static time mode, it continues returning Unix epoch.
    • โž• Add setTime to DAML Script and REPL which sets the ledger time via
      the Ledger API time service. This only works in static time mode and
      via gRPC.
    • โž• Add listKnownParties and listKnownPartiesOn to query the
      corresponding ListKnownParties endpoint in the Party Management
      service.
    • The time mode for DAML REPL can now be specified using
      the--static-time and --wall-clock-time flags.
    • You can now use DAML Script with multiple auth tokens. This is
      particularly useful if you are working with the JSON API where you
      can only have one party per token or with an IAM that only provides
      single-party tokens. The tokens are specified in the participant
      ๐Ÿ”ง configuration passed via --participant-config in a new
      access_token field. The existing --access-token-file flag is
      ๐Ÿ‘ still supported if you want to use the same token for all
      connections. Take a look at the
      ๐Ÿ“š documentation
      for more details.

    Impact and Migration

    This functionality is purely additive so no action needs to be taken.

    More Privacy Information in DAML Studio

    Background

    DAML Studio's Scenario view allows developers to explore the
    transactions resulting from their DAML models in real time. One of the
    main uses of doing so is to verify that privacy is preserved as
    expected. Until now, the available views only gave information on who
    ๐Ÿ‘€ got to see a contract and through which transaction. SDK 1.3 adds
    information on the mechanism through which a party learned about a
    contract. This saves the developer the work of inferring this from the
    detailed transaction view.

    Specific Changes

    • When displaying scenario results in table view in DAML Studio,
      there's now a new checkbox "Show Detailed Disclosure" which shows
      indications why a party knows about the existence of a contract:
      • S means the party is a signatory.
      • O means the party is an observer.
      • W means the party has witnessed the creation of the contract.
      • D means the party has learned about the contract via
        divulgence.

    Impact and Migration

    This functionality is purely additive so no action needs to be taken.

    Early Access Trigger Service

    Background

    DAML Triggers give developers the ability to write automation of DAML
    ๐Ÿ’… applications in the style of database triggers using the DAML language
    itself, aiding code reuse and allowing contract definitions and basic
    ๐Ÿ“ฆ automation to be packaged and shipped together. These triggers need to
    be managed at runtime, which until now required developers to manage
    ๐Ÿš€ individual JVM processes, raising the bar to actually deploying DAML
    Triggers in production. The Trigger Service provides a way to manage
    DAML Triggers via a simple REST API.

    The Trigger Service is currently in Alpha, meaning API changes are still
    ๐Ÿ‘ likely, and it notably doesn't support authentication yet.

    Specific Changes

    • โž• Added the daml trigger-service command to the SDK to start the
      Trigger Service. More information in the
      ๐Ÿ“š documentation.

    Impact and Migration

    This functionality is purely additive so no action needs to be taken. If
    you are already evaluating Triggers for your application, we highly
    recommend trying out the Trigger Service as it should ease their use
    considerably. We welcome your feedback.

    Minor Improvements

    • The Java Binding's Bot.wire and Bot.wireSimple now return a
      Disposable, which can be used to shut down the flows. You are
      encouraged to call .dispose() before terminating the client.
    • โž• Added a CLI option for specifying the initial skew parameter for the
      time model. You can control the allowed difference between the
      Ledger Effective Time and the Record time using the
      --max-ledger-time-skew flag.
    • When run with persistence, the Sandbox used to crash if the database
      wasn't running during startup. It now instead waits for the database
      to start up.
    • โž• Additional CLI options to configure the write pipeline in Sandbox,
      ๐Ÿ‘ allowing operators to determine at what point back pressure is
      ๐Ÿ‘€ applied. See daml sandbox --help for details.
    • ๐ŸŽ‰ Initialize the loading indicators in @daml/react of useQuery,
      useFetchByKey and their streaming variants with true. This
      โœ‚ removes a glitch where the loading indicator was false for a very
      brief moment when components using these hooks were mounted although
      no data had been loaded yet. Code using these hooks does not need to
      be adapted in response to this change.
    • The create-daml-app example can now be run against a HTTP JSON API
      port specified in the environment variable
      REACT_APP_HTTP_JSON_PORT
    • ๐Ÿ‘Œ Improved error messages on unsuccessful key lookups.

    ๐Ÿ› Bug and Security Fixes

    • โœ… damlc test --project-root now works with relative paths as well.
    • ๐Ÿ“ฆ The Package Management Service's ListKnownParties response's
      PartyDetails now properly reflects where a party is non-local on
      distributed, multi-participant ledgers that expose parties to remote
      participants.
    • The application identifier in a command submission request is now
      ๐Ÿ‘€ checked against the authorization token. See
      #4409.
    • In scenarios, fetches and exercises of contract keys associated with
      contracts not visible to the submitter are now handled properly
      instead of showing a low-level error.
    • โšก๏ธ Some libraries in the DAML Studio VS Code Extension were updated to
      ๐Ÿ›  fix security issues. DAML Studio now requires VSCode 1.39 or newer.
    • ๐Ÿ›  Fix an issue in DAML Script where the port was ignored for
      non-empty paths in the url when running DAML Script over the JSON
      API.
    • ๐Ÿ›  Fix an issue in the Ledger API indexer that could have caused a
      crash in the presence of divulged contracts. Exclusively affects
      DAML ledger implementations where distributed participants each only
      ๐Ÿ‘€ see a portion of the ledger. The sandbox is not affected. See
      #6607.

    Ledger Integration Kit

    • โœ… The Ledger API Test Tool --exclude and --include flags now match
      โœ… the full test name as a prefix, rather than just suite names. Test
      โœ… name is built by combining the suite name with a test identifier, so
      this change should be fully backwards compatible. Run with
      โœ… --list-all to list all tests (as opposed to just the test suites
      with --list).
    • ๐ŸŒ LfValueTranslation.Cache now requires separate configuration of
      ๐ŸŒ lfValueTranslationEventCache and lfValueTranslationContractCache
    • โฌ†๏ธ Upgrade auth0 jwks-rsa version to 0.11.0
    • KVUtils does not commit output keys whose value is identical to
      input anymore
    • The Ledger API Server + Sandbox now accepts a new time model if none
      is set. Previously, it would erroneously be rejected because the
      generation number submitted to was incorrectly set to 2 rather
      than 1. This would not affect most users of Sandbox or other
      ๐Ÿ”ง kvutils-based ledgers, as if a configuration is set automatically on
      startup when creating a new ledger. This affects users who
      ๐Ÿ”ง explicitly override the initial ledger configuration submit delay to
      something longer than a few milliseconds.
    • โž• Add 8 new  timer metrics to track database performance when storing
      transactions. The overall time is measured by
      daml.index.db.store_ledger_entry.
      • Timer daml.index.db.store_ledger_entry.prepare_batches:
        measures the time for preparing batch insert/delete statements
      • Timer daml.index.db.store_ledger_entry.events_batch: measures
        the time for inserting events
      • Timer
        daml.index.db.store_ledger_entry.delete_contract_witnesses_batch
        measures the time for deleting contract witnesses
      • Timer daml.index.db.store_ledger_entry.delete_contracts_batch:
        measures the time for deleting contracts
      • Timer daml.index.db.store_ledger_entry.insert_contracts_batch:
        measures the time for inserting contracts
      • Timer
        daml.index.db.store_ledger_entry.insert_contract_witnesses_batch:
        measures the time for inserting contract witnesses
      • Timer daml.index.db.store_ledger_entry.insert_completion:
        measures the time for inserting the completion
      • Timer daml.index.db.store_ledger_entry.update_ledger_end:
        โšก๏ธ measures the time for updating the ledger end
    • โž• Added 4 new timer metrics to track DAML execution performance The
      overall time is measured by daml.execution.total
      • Timer daml.execution.lookup_active_contract_per_execution:
        measures the accumulated time spent for looking up active
        contracts per execution
      • Histogram
        daml.execution.lookup_active_contract_count_per_execution:
        measures the number of active contract lookups per execution
      • Timer daml.execution.lookup_contract_key_per_execution:
        measures the accumulated time spent for looking up contract keys
        per execution
      • Histogram
        daml.execution.lookup_contract_key_count_per_execution:
        measures the number of contract key lookups per execution