Daml Connect 1.14.0 has been marked stable and released on Thursday June 17th. You can install it using:
daml install latest
Impact and Migration
There are no backwards-incompatible changes that require immediate action. However, Daml application developers should take note of the deprecation mentioned above, as well as the phased change in Ledger behavior and the reasons behind this change, both elaborated further below.
The arbitrary precision numeric type BigNumeric in GA and Daml Exceptions in Beta are introduced in new Daml Ledger API and Daml-LF versions:
BigNumeric.Impact and Migration
To stay on an older Daml-LF version or enable a newer non-default version,
you can manually set the Daml-LF version of your Daml project by adding the below stanza to your daml.yaml file:
build-options:
- --target=1.XXBackground
Daml’s inbuilt Decimal and Numeric data types are fixed point numbers with a fixed precision of 38 decimals. In some numeric applications, they can require careful management of scale, or pre-condition checking to preserve the required precision in calculations.
The new BigNumeric removes this burden from the developer by allowing them to specify an arbitrary precision that is used for any intermediary results.
Specific Changes
BigNumeric. BigNumeric represents any positive or negative decimal number with up to 2^15 digits before the decimal point, and up to 2^15 digits after the decimal point.BigNumeric to a fixed-width 128-bit decimal Numeric n in order to store it in a template.BigNumeric is used via conversion functions fromNumeric and fromBigNumeric to convert between BigNumeric and Numeric n, which includes the alias Decimal == Numeric 10.DA.BigNumeric provides functions for division and rounding.DA.BigNumeric.shift has been split into DA.BigNumeric.shiftLeft and DA.BigNumeric.shiftRight for clarity.DA.BigNumeric.roundToNumeric is introduced, for rounding and converting a BigNumeric to a Numeric in a single move.Background
Daml, like most smart contract or transactional languages, has all-or-nothing semantics by default. A transaction either executes atomically as a whole, or not at all. This is key for security in a multi-party context, but requires careful handling of expected business exceptions. The new try/catch exception handling feature in Daml makes this a whole lot easier without compromising safety.
Developers can now wrap entire subtransactions in a try/catch block. Should a handleable exception be encountered in the try block, the partial transaction from the start of try to the exception is rolled back and the exception can be processed in the catch block.
These operations are fully validated by Daml Ledgers retaining the security and determinism guarantees of Daml transactions.
Specific Changes
exception to define a new exception typetry to start a subtransaction that may be rolled backcatch to handle an exception from a try blockthrow in module DA.Exception to throw an exception.GeneralError, ArithmeticError, PreconditionFailed, and AssertionFailed.Details on their use and an example can be found on the reference documentation page and a new chapter in the Introduction to Daml.
Impact and Migration
We encourage you to try out this feature, prepare your project for the stable version of this feature in an upcoming release and invite you to provide feedback.
Background
The JSON API service, like most Daml components, is designed for multi-tenancy in the sense that it is intended as a shared service between users and downstream services and applications. The log output of the service has now been improved to make it easier for its operator to associate log messages with specific users and downstream consumers, as well as to correlate log messages that belong to the same request. This aids identification, tracking and debugging of runtime issues.
10:07Specific Changes
--log-encoder json or via setting the env var LOG_FORMAT_JSON=true.--log-level cli argument. Valid values are error, warn, info (default), debug, trace.As an example of the new context information:
Before:
11:15:58.707 [http-json-ledger-api-akka.actor.default-dispatcher-9] ERROR com.daml.http.CommandService - ’create failure
io.grpc.StatusRuntimeException: INVALID_ARGUMENT: Command interpretation error in LF-DAMLe: Interpretation error: Error: node NodeId(0) (0bc3b795bd41e4c3c047310be5fcc1446da01bfb874cf81f7469b01f4c0828ef:Main:T) has no signatories. Details: Last location: [DA.Internal.Template.Functions:219], partial transaction: root node NodeId(0):
After:
11:14:07.952 [http-json-ledger-api-akka.actor.default-dispatcher-4] ERROR com.daml.http.CommandService - Symbol(create) failure , context: {instance_uuid=6f13ec78-3ae9-4cea-8ccf-911e4dfc13fe, request_id=5aec3810-6279-4b8e-afc1-e9b6d6012e92}
io.grpc.StatusRuntimeException: INVALID_ARGUMENT: Command interpretation error in LF-DAMLe: Interpretation error: Error: node NodeId(0) (0bc3b795bd41e4c3c047310be5fcc1446da01bfb874cf81f7469b01f4c0828ef:Main:T) has no signatories. Details: Last location: [DA.Internal.Template.Functions:219], partial transaction: root node NodeId(0):
Impact and Migration
This is an additive change.
Background
Divulgence is a concept in the Daml Ledger Model. It’s a mechanism by which the submitter of a transaction shares just enough contract information with the witnesses of a (sub-)transaction so that they can validate their views of the ledger. It’s the key enabler for Daml’s unique blend of need-to-know subtransaction privacy and guaranteed consistency and auditability.
For historic reasons, a party that receives a contract via the divulgence mechanism can use that contract when submitting their own transactions. While this is fine according to the Daml Ledger Model, fully secure, and adds some flexibility in the use of Daml, it is at odds with some operational concerns of running a Daml participant node or application.
If a party A is a stakeholder on a contract C, they are guaranteed to be informed of both the creation and archival of C. That means both their participant node as well as the application know when the contract is only retained for auditability purposes and can be removed from the active state of the application without affecting operation. With divulged contracts this is not the case. If A learned of a contract D via divulgence, they may never be notified of the archival of D. That means neither their participant node nor application have an automatic way of determining when it is safe to remove D. Yet not removing such contracts would lead to an ever-growing active state.
The operational concern outweighs usability and backwards compatibility so the use of divulged contracts during transaction interpretation(/submission) is being deprecated and removed in a phased manner.
Specific Changes
Impact and Migration
There is no need to take action yet other than to avoid relying on this behaviour for newly developed applications which may later run on pruned participants.
sqrt and ** functions in DA.Math have been extended to zero with sqrt(0.0) == 0 and 0 ** 0 == 1.parties component of the argument to the generated export script now takes a mapping from old party name to new party name.