digital-asset/daml
1
1
Fork 0
mirror of https://github.com/digital-asset/daml.git synced 2024-09-20 01:07:18 +03:00
Code Issues Projects Releases Wiki Activity

Updating Titles and Headings (#13592)

Browse Source 
* Updating Titles and Headings

Conforming titles and headings to best practices:

- Making them descriptive and non-repetitive
- Title case for first two levels of headings on a given page, sentence case for lower levels (in keeping with DA style guide)
- Typo fixes

[CHANGELOG_BEGIN]

[CHANGELOG_END]

* Updating Titles and Headings 2

Incorporating Stefano's comments throughout.

[CHANGELOG_BEGIN]

[CHANGELOG_END]

* Update docs/source/daml/intro/10_Functional101.rst

* Update docs/source/daml/intro/10_Functional101.rst

* Update docs/source/daml/intro/10_Functional101.rst

* Update docs/source/daml/reference/contract-keys.rst

fixing the 'Specify Maintainers' link

[CHANGELOG_BEGIN]

[CHANGELOG_END]

Co-authored-by: carrie-laben <91496516+carrie-laben@users.noreply.github.com>
This commit is contained in:
carrielaben-da 2022-05-02 15:22:51 -04:00 committed by GitHub
parent d3280ac87d
commit 58c615a251
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
96 changed files with 687 additions and 685 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

22
docs/source/app-dev/app-arch.rst
View File

@ -3,8 +3,8 @@
.. _recommended-architecture:
Application architecture
########################
Daml Application Architecture
#############################
This section describes our recommended design of a full-stack Daml application.
@ -104,7 +104,7 @@ with a Daml ledger that validates authorization of incoming requests. Simply ini
``DamlLedger`` object with the token obtained by the respective token issuer. How authorization works and the
form of the required tokens is described in the :ref:`Authorization <authorization>` section.
Developer workflow
Developer Workflow
******************
The SDK enables a local development environment with fast iteration cycles:
@ -126,7 +126,7 @@ Together, these features can provide you with very tight feedback loops while de
See :doc:`Your First Feature </getting-started/first-feature>` for a more detailed walkthrough of these steps.
Command deduplication
Command Deduplication
=====================
The interaction of a Daml application with the ledger is inherently asynchronous: applications send commands to the ledger, and some time later they see the effect of that command on the ledger.
@ -145,12 +145,12 @@ For details on how to use command deduplication, see the :doc:`Command Deduplica
.. _dealing-with-failures:
Dealing with failures
=====================
Deal With Failures
==================
.. _crash-recovery:
Crash recovery
Crash Recovery
--------------
In order to restart your application from a previously known ledger state,
@ -163,8 +163,8 @@ atomic operation, your application can resume from where it left off.
.. _failing-over-between-ledger-api-endpoints:
Failing over between Ledger API endpoints
-----------------------------------------
Fail Over Between Ledger API Endpoints
--------------------------------------
Some Daml Ledgers support exposing multiple eventually consistent Ledger API
endpoints where command deduplication works across these Ledger API endpoints.
@ -197,8 +197,8 @@ new endpoint, it will resume normal operation.
.. _dealing-with-time:
Dealing with time
=================
Deal With Time
==============
The Daml language contains a function :ref:`getTime <daml-ref-gettime>` which returns a rough estimate of “current time” called *Ledger Time*. The notion of time comes with a lot of problems in a distributed setting: different participants might run different clocks, there may be latencies due to calculation and network, clocks may drift against each other over time, etc.

12
docs/source/app-dev/authorization.rst
View File

@ -37,8 +37,8 @@ whether the request is valid according to the :ref:`Daml Ledger Model <da-ledger
Whether a participant node *will* serve such a request to a Daml application depends on whether the
request includes an access token that is valid and sufficient to authorize the request for this participant node.
Acquiring and using access tokens
*********************************
Acquire and Use Access Tokens
*****************************
How an application should acquire access tokens depends on the participant node it talks to and is ultimately setup by the participant node operator.
Many setups use a flow in the style of `OAuth 2.0 <https://oauth.net/2/>`_:
@ -64,7 +64,7 @@ and the :ref:`JSON API <json-api-access-tokens>`.
.. _authorization-claims:
Access tokens and rights
Access Tokens and Rights
************************
Access tokens contain information about the rights granted to the bearer of the token. These rights are specific to the API being accessed.
@ -129,7 +129,7 @@ The following table summarizes the rights required to access each Ledger API end
.. _access-token-formats:
Access token formats
Access Token Formats
********************
Applications should treat access tokens as opaque blobs.
@ -141,7 +141,7 @@ and there are two formats of the JSON payload in use by Daml ledgers.
.. note:: To generate access tokens for testing purposes, you can use the `jwt.io <https://jwt.io/>`__ web site.
User access tokens
User Access Tokens
==================
Daml ledgers that support participant :ref:`user management <user-management-service>` also accept user access tokens.
@ -177,7 +177,7 @@ The above notations are explained below:
that must contain the ``"daml_ledger_api"`` scope
Custom Daml claims access tokens
Custom Daml Claims Access Tokens
================================
This format represents the :ref:`rights <authorization-claims>` granted by the access token as custom claims in the JWT's payload, like so:

30
docs/source/app-dev/bindings-java/codegen.rst
View File

@ -3,7 +3,9 @@
.. _daml-codegen-java:
Generate Java code from Daml
Generate Java Code from Daml
############################
Introduction
@ -15,14 +17,14 @@ The :doc:`Daml assistant documentation </tools/codegen>` describes how to run an
The rest of this page describes Java-specific topics.
Understand the generated Java model
===================================
Understand the Generated Java Model
======================================
The Java codegen generates source files in a directory tree under the output directory specified on the command line.
.. _daml-codegen-java-primitive-types:
Map Daml primitives to Java types
Map Daml Primitives to Java Types
---------------------------------
Daml built-in types are translated to the following equivalent types in Java:
@ -63,7 +65,7 @@ Daml built-in types are translated to the following equivalent types in Java:
+--------------------------------+--------------------------------------------+------------------------+
Understand escaping rules
Understand Escaping Rules
-------------------------
To avoid clashes with Java keywords, the Java codegen applies escaping rules to the following Daml identifiers:
@ -76,7 +78,7 @@ To avoid clashes with Java keywords, the Java codegen applies escaping rules to
If any of these identifiers match one of the `Java reserved keywords <https://docs.oracle.com/javase/specs/jls/se12/html/jls-3.html#jls-3.9>`__, the Java codegen appends a dollar sign ``$`` to the name. For example, a field with the name ``import`` will be generated as a Java field with the name ``import$``.
Understand the generated classes
Understand the Generated Classes
--------------------------------
Every user-defined data type in Daml (template, record, and variant) is represented by one or more Java classes as described in this section.
@ -93,7 +95,7 @@ The Java package for the generated classes is the equivalent of the lowercase Da
package foo.bar.baz;
Records (a.k.a product types)
Records (a.k.a Product Types)
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
A :ref:`Daml record <daml-ref-record-types>` is represented by a Java class with fields that have the same name as the Daml record fields. A Daml field having the type of another record is represented as a field having the type of the generated class for that record.
@ -208,7 +210,7 @@ A file is generated that defines three Java classes:
Note that the static methods returning an ``ExerciseByKeyCommand`` will only be generated for templates that define a key.
Variants (a.k.a sum types)
Variants (a.k.a Sum Types)
^^^^^^^^^^^^^^^^^^^^^^^^^^
A :ref:`variant or sum type <daml-ref-sum-types>` is a type with multiple constructors, where each constructor wraps a value of another type. The generated code is comprised of an abstract class for the variant type itself and a subclass thereof for each constructor. Classes for variant constructors are similar to classes for records.
@ -291,7 +293,7 @@ The Java code generated for this variant is:
public DamlRecord toValue() { /* ... */ }
}
Parameterized types
Parameterized Types
^^^^^^^^^^^^^^^^^^^
.. note::
@ -381,7 +383,7 @@ The Java code generated for this variant is:
}
Convert a value of a generated type to a Java Bindings value
Convert a Value of a Generated Type to a Java Bindings Value
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
To convert an instance of the generic type ``Attribute<a>`` to a Java Bindings `Value`_, call the ``toValue`` method and pass a function as the ``toValuea`` argument for converting the field of type ``a`` to the respective Java Bindings `Value`_. The name of the parameter consists of ``toValue`` and the name of the type parameter, in this case ``a``, to form the name ``toValuea``.
@ -398,7 +400,7 @@ See :ref:`Daml To Java Type Mapping <daml-codegen-java-primitive-types>` for an
Note: If the Daml type is a record or variant with more than one type parameter, you need to pass a conversion function to the ``toValue`` method for each type parameter.
Create a value of a generated type from a Java Bindings value
Create a Value of a Generated Type from a Java Bindings Value
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
Analogous to the ``toValue`` method, to create a value of a generated type, call the method ``fromValue`` and pass conversion functions from a Java Bindings `Value`_ type to the expected Java type.
@ -411,13 +413,13 @@ Analogous to the ``toValue`` method, to create a value of a generated type, call
See Java Bindings `Value`_ class for the methods to transform the Java Bindings types into corresponding Java types.
Non-exposed parameterized types
Non-exposed Parameterized Types
"""""""""""""""""""""""""""""""
If the parameterized type is contained in a type where the *actual* type is specified (as in the ``BookAttributes`` type above), then the conversion methods of the enclosing type provides the required conversion function parameters automatically.
Convert Optional values
Convert Optional Values
"""""""""""""""""""""""
The conversion of the Java ``Optional`` requires two steps. The
@ -439,7 +441,7 @@ convert back the value possibly contains in the container.
Attribute<Optional<Long>> idAttribute2 =
serializedId.toOptional(v -> v.asInt64().orElseThrow(() -> new IllegalArgumentException("Expected Int64 element")));
Convert Collection values
Convert Collection Values
"""""""""""""""""""""""""
`DamlCollectors`_ provides collectors to converted Java collection

10
docs/source/app-dev/bindings-java/example.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Example project
###############
Java Bindings Example Project
#############################
To try out the Java bindings library, use the `examples on GitHub <https://github.com/digital-asset/ex-java-bindings>`__: ``PingPongReactive``.
@ -18,14 +18,14 @@ The logic of the application goes like this:
#. ``Bob`` sees this contract and exercises the consuming choice ``RespondPing`` to create a contract of type ``Ping`` for ``Alice``.
#. Points 2 and 3 are repeated until the maximum number of contracts defined in the Daml is reached.
Setting up the example projects
*******************************
Set Up the Example Projects
***************************
To set up the example projects, clone the public GitHub repository at `github.com/digital-asset/ex-java-bindings <https://github.com/digital-asset/ex-java-bindings>`__ and follow the setup instruction in the `README file <https://github.com/digital-asset/ex-java-bindings/blob/master/README.rst#setting-up-the-example-projects>`__.
This project contains two examples of the PingPong application, built directly with gRPC and using the RxJava2-based Java bindings.
Example project
Example Project
***************
PingPongMain.java

44
docs/source/app-dev/bindings-java/index.rst
View File

@ -3,7 +3,7 @@
.. _java-bindings:
Java bindings
Java Bindings
#############
.. toctree::
@ -51,8 +51,8 @@ The Java bindings library is composed of:
Can be found in the java package ``com.daml.ledger.rxjava.components``.
Code generation
===============
Generate Code
=============
When writing applications for the ledger in Java, you want to work with a representation of Daml templates and data types in Java that closely resemble the original Daml code while still being as true to the native types in Java as possible.
@ -60,26 +60,26 @@ To achieve this, you can use Daml to Java code generator ("Java codegen") to gen
For more information on Java code generation, see :doc:`/app-dev/bindings-java/codegen`.
Connecting to the ledger: LedgerClient
======================================
Connect to the Ledger: ``LedgerClient``
=======================================
Connections to the ledger are made by creating instance of classes that implement the interface ``LedgerClient``. The class ``DamlLedgerClient`` implements this interface, and is used to connect to a Daml ledger.
This class provides access to the ledgerId, and all clients that give access to the various ledger services, such as the active contract set, the transaction service, the time service, etc. This is described :ref:`below <ledger-api-java-binding-connecting>`. Consult the `JavaDoc for DamlLedgerClient <javadocs/com/daml/ledger/rxjava/DamlLedgerClient.html>`_ for full details.
Reference documentation
Reference Documentation
***********************
`Click here for the JavaDoc reference documentation <javadocs/index.html>`_.
Getting started
***************
Get Started
***********
The Java bindings library can be added to a `Maven <https://maven.apache.org/>`_ project.
.. _bindings-java-setup-maven:
Set up a Maven project
Set Up a Maven Project
======================
To use the Java bindings library, add the following dependencies to your project's ``pom.xml``:
@ -97,15 +97,15 @@ You can also take a look at the ``pom.xml`` file from the :ref:`quickstart proje
.. _ledger-api-java-binding-connecting:
Connecting to the ledger
========================
Connect to the Ledger
=====================
Before any ledger services can be accessed, a connection to the ledger must be established. This is done by creating a instance of a ``DamlLedgerClient`` using one of the factory methods ``DamlLedgerClient.forLedgerIdAndHost`` and ``DamlLedgerClient.forHostWithLedgerIdDiscovery``. This instance can then be used to access service clients directly, or passed to a call to ``Bot.wire`` to connect a ``Bot`` instance to the ledger.
.. _ledger-api-java-bindings-authorization:
Authorizing
===========
Perform Authorization
=====================
Some ledgers will require you to send an access token along with each request.
@ -124,8 +124,8 @@ If you're communicating with a ledger that verifies authorization it's very impo
.. _ledger-api-java-binding-connecting-securely:
Connecting securely
===================
Connect Securely
================
The Java bindings library lets you connect to a Daml Ledger via a secure connection. The builders created by
``DamlLedgerClient.newBuilder`` default to a plaintext connection, but you can invoke ``withSslContext`` to pass an ``SslContext``.
@ -137,7 +137,7 @@ For information on how to set up an ``SslContext`` with the provided certificate
`TLS with OpenSSL <https://github.com/grpc/grpc-java/blob/master/SECURITY.md#tls-with-openssl>`_ as well as the
`HelloWorldClientTls <https://github.com/grpc/grpc-java/blob/70b1b1696a258ffe042c7124217e3a7894821444/examples/src/main/java/io/grpc/examples/helloworldtls/HelloWorldClientTls.java#L46-L57>`_ example of the ``grpc-java`` project.
Advanced connection settings
Advanced Connection Settings
============================
Sometimes the default settings for gRPC connections/channels are not suitable for a given situation. These use cases are supported by creating a custom `NettyChannelBuilder <https://grpc.github.io/grpc-java/javadoc/io/grpc/netty/NettyChannelBuilder.html>`_ object and passing the it to the ``newBuilder`` static method defined over `DamlLedgerClient <javadocs/com/daml/ledger/rxjava/DamlLedgerClient.html>`_.
@ -147,8 +147,8 @@ Reactive Components
The Reactive Components are deprecated as of 2020-10-14.
Accessing data on the ledger: LedgerView
----------------------------------------
Access Data on the Ledger: LedgerView
-------------------------------------
The ``LedgerView`` of an application is the "copy" of the ledger that the application has locally. You can query it to obtain the contracts that are active on the Ledger and not pending.
@ -167,8 +167,8 @@ The ``LedgerView`` is updated every time:
For instance, if an incoming transaction is received with a create event for a contract that is relevant
for the application, the application ``LedgerView`` is updated to contain that contract too.
Writing automations: Bot
------------------------
Write Automations: Bot
----------------------
The ``Bot`` is an abstraction used to write automation for a Daml Ledger. It is conceptually
defined by two aspects:
@ -214,8 +214,8 @@ In the above:
contains the ``templateId``, the arguments of the contract created and the context of
the created contract. The context contains the ``workflowId``.
Example project
***************
Example Projects
****************
Example projects using the Java bindings are available on `GitHub <https://github.com/digital-asset/ex-java-bindings>`__. :doc:`Read more about them here </app-dev/bindings-java/example>`.

28
docs/source/app-dev/bindings-java/quickstart.rst
View File

@ -3,8 +3,8 @@
.. _quickstart:
IOU Quickstart Tutorial
#######################
Daml IOU Quickstart Tutorial
############################
In this guide, you will learn about developer tools and Daml applications by:
@ -18,7 +18,7 @@ Prerequisites:
.. _quickstart-download:
Download the quickstart application
Download the Quickstart Application
***********************************
You can get the quickstart application using the Daml assistant (``daml``):
@ -28,7 +28,7 @@ You can get the quickstart application using the Daml assistant (``daml``):
This creates the ``quickstart-java`` application into a new folder called ``quickstart``.
#. Run ``cd quickstart`` to change into the new directory.
Folder structure
Folder Structure
================
The project contains the following files:
@ -68,8 +68,8 @@ You will explore these in more detail through the rest of this guide.
.. _tutorials-iou-overview:
Overview of what an IOU is
**************************
Understand IOUs
***************
To run through this guide, you will need to understand what an IOU is. This section describes the properties of an IOU like a bank bill that make it useful as a representation and transfer of value.
@ -107,7 +107,7 @@ The note itself is printed on paper, and its legal owner is the person holding i
.. _quickstart-start:
Run the application using prototyping tools
Run the Application Using Prototyping Tools
*******************************************
In this section, you will run the quickstart application and get introduced to the main tools for prototyping Daml:
@ -151,8 +151,8 @@ In this section, you will run the quickstart application and get introduced to t
.. _quickstart-work:
Try out the application
***********************
Try the Application
*******************
Now everything is running, you can try out the quickstart application:
@ -252,7 +252,7 @@ Now everything is running, you can try out the quickstart application:
.. _quickstart-daml:
Get started with Daml
Get Started with Daml
*********************
The *contract model* specifies the possible contracts, as well as the allowed transactions on the ledger, and is written in Daml.
@ -360,7 +360,7 @@ For a deeper introduction to Daml, consult the :doc:`Daml Reference </daml/refer
.. _quickstart-scripts:
Test using Daml Script
Test Using Daml Script
======================
You can check the correct authorization and privacy of a contract model using *scripts*: tests that are written in Daml.
@ -480,7 +480,7 @@ In the transaction view, transaction ``6`` is of particular interest, as it show
The ``submit`` function used in this script tries to perform a transaction and fails if any of the ledger integrity rules are violated. There is also a ``submitMustFail`` function, which checks that certain transactions are not possible. This is used in ``daml/Tests/Iou.daml``, for example, to confirm that the ledger model prevents double spends.
.. Interact with the ledger through the command line
.. Interact With the Ledger Through the Command Line
*************************************************
All interaction with a Daml ledger, be it sandbox or any other implementation, happens via the :doc:`Ledger API </app-dev/ledger-api>`. It is based on `gRPC <https://grpc.io/>`_.
@ -497,7 +497,7 @@ The ``submit`` function used in this script tries to perform a transaction and f
.. _quickstart-application:
Integrate with the ledger
Integrate With the Ledger
*************************
A distributed ledger only forms the core of a full Daml application.
@ -609,7 +609,7 @@ The rest of the application sets up the REST services using `Spark Java <http://
For a discussion of ledger application design and architecture, take a look at :doc:`Application Architecture Guide </app-dev/app-arch>`.
Next steps
Next Steps
**********
Great - you've completed the quickstart guide!

14
docs/source/app-dev/bindings-ts/daml2js.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
JavaScript Code Generator
#########################
Use the JavaScript Code Generator
#################################
The command ``daml codegen js`` generates JavaScript (and TypeScript) that can be used in conjunction with the `JavaScript Client Libraries <../index>`_ for interacting with a Daml ledger via the `HTTP JSON API <../json-api/index.html>`_.
@ -10,8 +10,8 @@ Inputs to the command are DAR files. Outputs are JavaScript packages with TypeSc
The generated packages use the library `@daml/types <https://github.com/digital-asset/daml/tree/main/language-support/ts/daml-types>`_.
Usage
*****
Generate and Use Code
*********************
In outline, the command to generate JavaScript and TypeScript typings from Daml is ``daml codegen js -o OUTDIR DAR`` where ``DAR`` is the path to a DAR file (generated via ``daml build``) and ``OUTDIR`` is a directory where you want the artifacts to be written.
@ -36,7 +36,7 @@ Here's a complete example on a project built from the standard "skeleton" templa
To get a quickstart idea of how to use what has been generated, you may wish to jump to the `Templates and choices`_ section and return to the reference material that follows as needed.
Primitive Daml types: @daml/types
Primitive Daml Types: @daml/types
*********************************
To understand the TypeScript typings produced by the code generator, it is helpful to keep in mind this quick review of the TypeScript equivalents of the primitive Daml types provided by @daml/types.
@ -93,7 +93,7 @@ To understand the TypeScript typings produced by the code generator, it is helpf
.. note::
The TypeScript definition of type ``Optional<τ>`` in the above table might look complicated. It accounts for differences in the encoding of optional values when nested versus when they are not (i.e. "top-level"). For example, ``null`` and ``"foo"`` are two possible values of ``Optional<Text>`` whereas, ``[]`` and ``["foo"]`` are two possible values of type ``Optional<Optional<Text>>`` (``null`` is another possible value, ``[null]`` is **not**).
Daml to TypeScript mappings
Daml to TypeScript Mappings
***************************
The mappings from Daml to TypeScript are best explained by example.
@ -202,7 +202,7 @@ the generated TypeScript will consist of a type declaration and the definition o
keys: ['Red','Blue','Yellow'],
} as const;
Templates and choices
Templates and Choices
=====================
Here is a Daml template of a basic 'IOU' contract.

4
docs/source/app-dev/bindings-ts/index.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
JavaScript Client Libraries
###########################
Using JavaScript Client Libraries with Daml
###########################################
.. _typescript:

8
docs/source/app-dev/bindings-x-lang/index.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Creating your own bindings
##########################
Create Your Own Bindings
########################
This page gets you started with creating custom bindings for a Daml Ledger.
@ -22,8 +22,8 @@ Note that for different reasons we chose codegen, but that is not the only optio
- `Template Haskell <https://wiki.haskell.org/Template_Haskell>`_
Building Ledger Commands
========================
Build Ledger Commands
=====================
No matter what approach you take, either manually building commands or writing a codegen to do this, you need to understand how ledger commands are structured. This section demonstrates how to build create and exercise commands manually and how it can be done using contract classes.

18
docs/source/app-dev/command-deduplication.rst
View File

@ -3,7 +3,7 @@
.. _command-deduplication:
Command deduplication
Command Deduplication
#####################
The interaction of a Daml application with the ledger is inherently asynchronous: applications send commands to the ledger, and some time later they see the effect of that command on the ledger.
@ -23,7 +23,7 @@ This guide covers the following topics:
.. _command-dedup-workings:
How command deduplication works
How Command Deduplication Works
*******************************
The following fields in a command submissions are relevant for command deduplication.
@ -94,7 +94,7 @@ At this time, only `Daml driver for VMware Blockchain <https://www.digitalasset.
.. _command-dedup-usage:
How to use command deduplication
How to Use Command Deduplication
********************************
To effectuate a ledger change exactly once, the application must resubmit a command if an earlier submission was lost.
@ -110,7 +110,7 @@ Similarly, an :ref:`Exercise command <com.daml.ledger.api.v1.ExerciseCommand>` o
With command deduplication, applications can ensure such intended ledger changes are executed only once within the deduplication period, even if the application resubmits, say because it considers the earlier submissions to be lost or forgot during a crash that it had already submitted the command.
Known processing time bounds
Known Processing Time Bounds
============================
For this strategy, you must estimate a bound ``B`` on the processing time and forward clock drifts in the Daml ledger with respect to the application’s clock.
@ -183,7 +183,7 @@ Under this caveat, the following strategy works for applications that use the :r
.. _dedup-bounded-error-handling:
Error handling
Error Handling
--------------
Error handling is needed when the status code of the command submission RPC call or in the :ref:`completion event <com.daml.ledger.api.v1.Completion.status>` is not ``OK``.
@ -273,7 +273,7 @@ Fields in the error metadata are written as ``field`` in lowercase letters.
In particular, you must not draw any conclusions from not having received a :ref:`SUBMISSION_ALREADY_IN_FLIGHT <error_code_SUBMISSION_ALREADY_IN_FLIGHT>` error, because the outstanding submission may be queued somewhere and will reach the relevant processing point only later.
Failure scenarios
Failure Scenarios
-----------------
The above strategy can fail in the following scenarios:
@ -298,7 +298,7 @@ The above strategy can fail in the following scenarios:
Of course, you can always stop retrying and accept that you do not know the outcome for sure.
Unknown processing time bounds
Unknown Processing Time Bounds
==============================
Finding a good bound ``B`` on the processing time is hard, and there may still be unforeseen circumstances that delay processing beyond the chosen bound ``B``.
@ -360,13 +360,13 @@ We recommend the following strategy for using deduplication offsets:
.. _dedup-unbounded-error-handling:
Error handling
Error Handling
--------------
The same as :ref:`for known bounds <dedup-bounded-error-handling>`, except that the former retry from :ref:`Step 2 <dedup-bounded-step-offset>` becomes retry from :ref:`Step 3 <dedup-unbounded-step-offset>`.
Failure scenarios
Failure Scenarios
-----------------
The above strategy can fail in the following scenarios:

26
docs/source/app-dev/daml-lf-translation.rst
View File

@ -1,14 +1,14 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
How Daml types are translated to Daml-LF
How Daml Types are Translated to Daml-LF
########################################
This page shows how types in Daml are translated into Daml-LF. It should help you understand and predict the generated client interfaces, which is useful when you're building a Daml-based application that uses the Ledger API or client bindings in other languages.
For an introduction to Daml-LF, see :ref:`daml-lf-intro`.
Primitive types
Primitive Types
***************
:ref:`Built-in data types <daml-ref-built-in-types>` in Daml have straightforward mappings to Daml-LF.
@ -46,7 +46,7 @@ Most built-in types have the same name in Daml-LF as in Daml. These are the exac
Be aware that only the Daml primitive types exported by the :ref:`Prelude <module-prelude-72703>` module map to the Daml-LF primitive types above. That means that, if you define your own type named ``Party``, it will not translate to the Daml-LF primitive ``Party``.
Tuple types
Tuple Types
***********
Daml tuple type constructors take types ``T1, T2, …, TN`` to the type ``(T1, T2, …, TN)``. These are exposed in the Daml surface language through the :ref:`Prelude <module-prelude-72703>` module.
@ -55,7 +55,7 @@ The equivalent Daml-LF type constructors are ``daml-prim:DA.Types:TupleN``, for
For example: the Daml pair type ``(Int, Text)`` is translated to ``daml-prim:DA.Types:Tuple2 Int64 Text``.
Data types
Data Types
**********
Daml-LF has three kinds of data declarations:
@ -68,7 +68,7 @@ Daml-LF has three kinds of data declarations:
.. In the tables below, the left column uses Daml 1.2 syntax and the right column uses the notation from the `Daml-LF specification <https://github.com/digital-asset/daml/blob/main/daml-lf/spec/daml-lf-1.rst>`_.
Record declarations
Record Declarations
===================
This section uses the syntax for Daml :ref:`records <daml-ref-record-types>` with curly braces.
@ -92,7 +92,7 @@ This section uses the syntax for Daml :ref:`records <daml-ref-record-types>` wit
* - ``data Foo = Bar {}``
- ``record Foo ↦ {}``
Variant declarations
Variant Declarations
====================
.. list-table::
@ -128,7 +128,7 @@ Variant declarations
* - ``data Foo = Bar { bar1: Int; bar2: Decimal } | Baz { baz1: Text; baz2: Date }``
- ``data Foo ↦ Bar Foo.Bar | Baz Foo.Baz``, ``record Foo.Bar ↦ { bar1: Int64; bar2: Decimal }``, ``record Foo.Baz ↦ { baz1: Text; baz2: Date }``
Enum declarations
Enum Declarations
=================
.. list-table::
@ -142,7 +142,7 @@ Enum declarations
* - ``data Color = Red | Green | Blue``
- ``enum Color ↦ Red | Green | Blue``
Banned declarations
Banned Declarations
===================
There are two gotchas to be aware of: things you might expect to be able to do in Daml that you can't because of Daml-LF.
@ -170,7 +170,7 @@ The second gotcha is that a constructor in a data type declaration can have at m
* - ``data Foo = Bar | Baz Int Text``
- Name arguments to the Baz constructor, for example ``data Foo = Bar | Baz { x: Int; y: Text }``
Type synonyms
Type Synonyms
*************
:ref:`Type synonyms <daml-ref-type-synonyms>` (starting with the ``type`` keyword) are eliminated during conversion to Daml-LF. The body of the type synonym is inlined for all occurrences of the type synonym name.
@ -188,7 +188,7 @@ The ``Username`` type is eliminated in the Daml-LF translation, as follows:
record User ↦ { name: Text }
Template types
Template Types
**************
A :ref:`template declaration <daml-ref-template-name>` in Daml results in one or more data type declarations behind the scenes. These data types, detailed in this section, are not written explicitly in the Daml program but are created by the compiler.
@ -197,7 +197,7 @@ They are translated to Daml-LF using the same rules as for record declarations a
These declarations are all at the top level of the module in which the template is defined.
Template data types
Template Data Types
===================
Every contract template defines a record type for the parameters of the contract. For example, the template declaration:
@ -220,7 +220,7 @@ This translates to the Daml-LF record declaration:
record Iou ↦ { issuer: Party; owner: Party; currency: Text; amount: Decimal }
Choice data types
Choice Data Types
=================
Every choice within a contract template results in a record type for the parameters of that choice. For example, let’s suppose the earlier ``Iou`` template has the following choices:
@ -246,7 +246,7 @@ These translate to the Daml-LF record declarations:
record DoNothing ↦ {}
record Transfer ↦ { newOwner: Party }
Names with special characters
Names with Special Characters
*****************************
All names in Daml—of types, templates, choices, fields, and variant data constructors—are translated to the more restrictive rules of Daml-LF. ASCII letters, digits, and ``_`` underscore are unchanged in Daml-LF; all other characters must be mangled in some way, as follows:

18
docs/source/app-dev/grpc/daml-to-ledger-api.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
How Daml types are translated to protobuf
How Daml Types are Translated to Protobuf
#########################################
This page gives an overview and reference on how Daml types and contracts are represented by the Ledger API as protobuf messages, most notably:
@ -27,7 +27,7 @@ A particular value of ``Foo`` is then represented by the Ledger API in this way:
The name of messages is added as a comment after the opening curly brace.
Records and primitive types
Records and Primitive Types
***************************
Records or product types are translated to :ref:`com.daml.ledger.api.v1.record`. Here's an example Daml record type that contains a field for each primitive type:
@ -73,7 +73,7 @@ The snippets below shows the value of ``mySum1`` and ``mySum2`` respectively as
:lines: 14-38
:caption: mySum2
Contract templates
Contract Templates
******************
Contract templates are represented as records with the same identifier as the template.
@ -85,22 +85,22 @@ This first example template below contains only the signatory party and a simple
:start-after: -- BEGIN_SIMPLE_TEMPLATE
:end-before: -- END_SIMPLE_TEMPLATE
Creating a contract
===================
Create a Contract
=================
Creating contracts is done by sending a :ref:`com.daml.ledger.api.v1.createcommand` to the :ref:`com.daml.ledger.api.v1.commandsubmissionservice` or the :ref:`com.daml.ledger.api.v1.commandservice`. The message to create a `MySimpleTemplate` contract with *Alice* being the owner is shown below:
.. literalinclude:: ../code-snippets/CreateMySimpleTemplate.payload
Receiving a contract
====================
Receive a Contract
==================
Contracts are received from the :ref:`com.daml.ledger.api.v1.transactionservice` in the form of a :ref:`com.daml.ledger.api.v1.createdevent`. The data contained in the event corresponds to the data that was used to create the contract.
.. literalinclude:: ../code-snippets/CreatedEventMySimpleTemplate.payload
Exercising a choice
===================
Exercise a Choice
=================
A choice is exercised by sending an :ref:`com.daml.ledger.api.v1.exercisecommand`. Taking the same contract template again, exercising the choice ``MyChoice`` would result in a command similar to the following:

20
docs/source/app-dev/grpc/error-codes.rst
View File

@ -12,7 +12,7 @@ Error Codes
###########
Overview
*********
********
.. _gRPC status codes: https://grpc.github.io/grpc/core/md_doc_statuscodes.html
@ -42,7 +42,7 @@ errors in a self-service manner, either in an automated-way or manually.
Glossary
*********************************************
********
Error
Represents an occurrence of a failure.
@ -82,7 +82,7 @@ Correlation id
Anatomy of an Error
*********************************************
*******************
Errors returned to users contain a `gRPC status code`_, a description and additional machine readable information
@ -90,7 +90,7 @@ represented in the `rich gRPC error model`_.
Error Description
=============================================
=================
We use the `standard gRPC description`_ that additionally adheres to our custom message format:
@ -126,7 +126,7 @@ In a concrete example an error description might look like this:
Additional Machine Readable Information
=============================================
=======================================
We use following error details:
@ -145,16 +145,16 @@ Many errors will include more information,
but there is no guarantee given that additional information will be preserved across versions.
Preventing Security Leaks in Error Codes
=============================================
Prevent Security Leaks in Error Codes
=====================================
For any error that could leak information to an attacker, the system will return an error message via the API that
will not leak any valuable information. The log file will contain the full error message.
Working with Error Codes
*********************************************
Work With Error Codes
*********************
This example shows how a user can extract the relevant error information.
@ -231,7 +231,7 @@ This example shows how a user can extract the relevant error information.
Error Categories Inventory
*********************************************
**************************
The error categories allow to group errors such that application logic can be built
in a sensible way to automatically deal with errors and decide whether to retry

18
docs/source/app-dev/grpc/index.rst
View File

@ -3,25 +3,25 @@
.. _grpc:
gRPC
####
Use the Ledger API With gRPC
############################
If you want to write an application for the ledger API in other languages, you'll need to use `gRPC <https://grpc.io>`__ directly.
If you're not familiar with gRPC and protobuf, we strongly recommend following the `gRPC quickstart <https://grpc.io/docs/quickstart/>`__ and `gRPC tutorials <https://grpc.io/docs/tutorials/>`__. This documentation is written assuming you already have an understanding of gRPC.
Getting started
***************
Get Started
***********
You can get the protobufs from a `GitHub release <protobufs_>`_, or from the ``daml`` repository `here <https://github.com/digital-asset/daml/tree/main/ledger-api/grpc-definitions>`__.
Protobuf reference documentation
Protobuf Reference Documentation
********************************
For full details of all of the Ledger API services and their RPC methods, see :doc:`/app-dev/grpc/proto-docs`.
Example project
Example Project
***************
We have an example project demonstrating the use of the Ledger API with gRPC. To get the example project, ``PingPongGrpc``:
@ -30,7 +30,7 @@ We have an example project demonstrating the use of the Ledger API with gRPC. To
#. Clone the `repository from GitHub <https://github.com/digital-asset/ex-java-bindings>`__.
#. Follow the `setup instructions in the README <https://github.com/digital-asset/ex-java-bindings/blob/master/README.rst#setting-up-the-example-projects>`__. Use ``examples.pingpong.grpc.PingPongGrpcMain`` as the main class.
About the example project
About the Example Project
=========================
The example shows very simply how two parties can interact via a ledger, using two Daml contract templates, ``Ping`` and ``Pong``.
@ -59,12 +59,12 @@ The first line shows:
This example subscribes to transactions for a single party, as different parties typically live on different participant nodes. However, if you have multiple parties registered on the same node, or are running an application against the Sandbox, you can subscribe to transactions for multiple parties in a single subscription by putting multiple entries into the ``filters_by_party`` field of the ``TransactionFilter`` message. Subscribing to transactions for an unknown party will result in an error.
Daml types and protobuf
Daml Types and Protobuf
***********************
For information on how Daml types and contracts are represented by the Ledger API as protobuf messages, see :doc:`/app-dev/grpc/daml-to-ledger-api`.
Error handling
Error Handling
**************
The Ledger API generally uses the gRPC standard status codes for signaling response failures to client applications.

2
docs/source/app-dev/ledger-api.rst
View File

@ -82,7 +82,7 @@ As a user, you don't need to interact with Daml-LF directly. But internally, it'
.. Daml-LF content appears in the package service interactions. It is represented as opaque blobs that require a secondary decoding phase.
When you need to know about Daml-LF
When You Need to Know About Daml-LF
===================================
Daml-LF is only really relevant when you're dealing with the objects you send to or receive from the ledger. If you use any of the provided language bindings for the Ledger API, you don't need to know about Daml-LF at all, because this generates idiomatic representations of Daml for you.

52
docs/source/app-dev/services.rst
View File

@ -3,7 +3,7 @@
.. _ledger-api-services:
The Ledger API services
The Ledger API Services
#######################
The Ledger API is structured as a set of services. The core services are implemented using `gRPC <https://grpc.io/>`__ and `Protobuf <https://developers.google.com/protocol-buffers/>`__, but most applications access this API through the mediation of the language bindings.
@ -42,12 +42,12 @@ Glossary
.. _ledger-api-submission-services:
Submitting commands to the ledger
*********************************
Submit Commands to the Ledger
*****************************
.. _command-submission-service:
Command submission service
Command Submission Service
==========================
Use the **command submission service** to submit commands to the ledger. Commands either create a new contract, or exercise a choice on an existing contract.
@ -80,7 +80,7 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _command-submission-service-deduplication:
Command deduplication
Command Deduplication
---------------------
The command submission service deduplicates submitted commands based on their :ref:`change ID <change-id>`.
@ -94,7 +94,7 @@ For details on how to use command deduplication, see the :doc:`Command Deduplica
.. _command-completion-service:
Command completion service
Command Completion Service
==========================
Use the **command completion service** to find out the completion status of commands you have submitted.
@ -105,7 +105,7 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _command-service:
Command service
Command Service
===============
Use the **command service** when you want to submit a command and wait for it to be executed. This service is similar to the command submission service, but also receives completions and waits until it knows whether or not the submitted command has completed. It returns the completion status of the command execution.
@ -114,12 +114,12 @@ You can use either the command or command submission services to submit commands
For full details, see :ref:`the proto documentation for the service <com.daml.ledger.api.v1.CommandService>`.
Reading from the ledger
***********************
Read From the Ledger
********************
.. _transaction-service:
Transaction service
Transaction Service
===================
Use the **transaction service** to listen to changes in the ledger state, reported via a stream of transactions.
@ -132,7 +132,7 @@ Subscribe to the transaction service to read events from an arbitrary point on t
For full details, see :ref:`the proto documentation for the service <com.daml.ledger.api.v1.TransactionService>`.
Transaction and transaction trees
Transaction and transaction Trees
---------------------------------
``TransactionService`` offers several different subscriptions. The most commonly used is ``GetTransactions``. If you need more details, you can use ``GetTransactionTrees`` instead, which returns transactions as flattened trees, represented as a map of event IDs to events and a list of root event IDs.
@ -152,7 +152,7 @@ You can get these included in requests related to Transactions by setting the ``
.. _active-contract-service:
Active contracts service
Active Contracts Service
========================
Use the **active contracts service** to obtain a party-specific view of all contracts that are active on the ledger at the time of the request.
@ -183,12 +183,12 @@ See :ref:`verbosity` above.
.. _ledger-api-utility-services:
Utility services
Utility Services
****************
.. _party-service:
Party management service
Party Management Service
========================
Use the **party management service** to allocate parties on the ledger and retrieve information about allocated parties.
@ -201,7 +201,7 @@ For more information, refer to the pages on :doc:`Identity Management</concepts/
.. _user-management-service:
User management service
User Management Service
=======================
Use the **user management service** to manage the set of users on a participant node and
@ -223,7 +223,7 @@ User management is available in Canton-enabled drivers and not yet available in
.. _package-service:
Package service
Package Service
===============
Use the **package service** to obtain information about Daml packages available on the ledger.
@ -234,7 +234,7 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _ledger-identity-service:
Ledger identity service (DEPRECATED)
Ledger Identity Service (DEPRECATED)
=====================================
Use the **ledger identity service** to get the identity string of the ledger that your application is connected to.
@ -246,7 +246,7 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _ledger-configuration-service:
Ledger configuration service
Ledger Configuration Service
============================
Use the **ledger configuration service** to subscribe to changes in ledger configuration.
@ -257,8 +257,8 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _version-service:
Version service
============================
Version Service
===============
Use the **version service** to retrieve information about the Ledger API version and what optional features are supported by the ledger server.
@ -266,8 +266,8 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _pruning-service:
Pruning service
============================
Pruning Service
===============
Use the **pruning service** to prune archived contracts and transactions before or at a given offset.
@ -275,8 +275,8 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _metering-report-service:
Metering Report service
============================
Metering Report Service
=======================
Use the **metering report service** to retrieve a participant metering report.
@ -284,14 +284,14 @@ For full details, see :ref:`the proto documentation for the service <com.daml.le
.. _ledger-api-testing-services:
Testing services
Testing Services
****************
**These are only for use for testing with the Sandbox, not for on production ledgers.**
.. _time-service:
Time service
Time Service
============
Use the **time service** to obtain the time as known by the ledger server.

54
docs/source/concepts/glossary.rst
View File

@ -65,7 +65,7 @@ A **contract** is an item on a `ledger <#daml-ledger>`__. They are created from
Contracts are immutable: once they are created on the ledger, the information in the contract cannot be changed. The only thing that can happen to it is that the contract can be `archived <#active-contract-archived-contract>`__.
Active contract, archived contract
Active Contract, Archived Contract
----------------------------------
When a `contract <#contract>`__ is created on a `ledger <#daml-ledger>`__, it becomes **active**. But that doesn't mean it will stay active forever: it can be **archived**. This can happen:
@ -93,29 +93,29 @@ A choice can only be exercised by its `controller <#controller>`__. Within the c
For full documentation on choices, see :doc:`/daml/reference/choices`.
Consuming choice
Consuming Choice
----------------
A **consuming choice** means that, when the choices is exercised, the `contract <#contract>`__ it is on will be `archived <#active-contract-archived-contract>`__. The alternative is a `nonconsuming choice <#nonconsuming-choice>`__.
Consuming choices can be `preconsuming <#preconsuming-choice>`__ or `postconsuming <#postconsuming-choice>`__.
Preconsuming choice
Preconsuming Choice
~~~~~~~~~~~~~~~~~~~
A `choice <#choice>`__ marked **preconsuming** will be `archived <#active-contract-archived-contract>`__ at the start of that `exercise <#exercise>`__.
Postconsuming choice
Postconsuming Choice
~~~~~~~~~~~~~~~~~~~~
A `choice <#choice>`__ marked **postconsuming** will not be `archived <#active-contract-archived-contract>`__ until the end of the `exercise <#exercise>`__ choice body.
Nonconsuming choice
Nonconsuming Choice
--------------------
A **nonconsuming choice** does NOT `archive <#active-contract-archived-contract>`__ the `contract <#contract>`__ it is on when `exercised <#exercise>`__. This means the choice can be exercised more than once on the same `contract <#contract>`__.
Disjunction choice, flexible controllers
Disjunction Choice, Flexible Controllers
----------------------------------------
A **disjunction choice** has more than one `controller <#controller>`__.
@ -177,7 +177,7 @@ It's not possible for keys to be globally unique, because there is no party that
For documentation on contract keys, see :doc:`/daml/reference/contract-keys`.
Authorization, signing
Authorization, Signing
======================
The Daml runtime checks that every submitted transaction is **well-authorized**, according to the :doc:`authorization rules of the ledger model </concepts/ledger-model/ledger-integrity>`, which guarantee the integrity of the underlying ledger.
@ -215,7 +215,7 @@ Only if all required parties have given their authorization to an update action,
It is noteworthy, that authorizing parties are always determined only from the local context of a choice in question, that is, its controllers and the contract's signatories. Authorization is never inherited from earlier execution contexts.
Standard library
Standard Library
================
The **Daml standard library** is a set of `Daml` functions, classes and more that make developing with Daml easier.
@ -273,7 +273,7 @@ See :ref:`testing-using-script`.
.. The **Daml runtime** (sometimes also called the Daml execution engine or Damle)...
Contract key
Contract Key
============
A **contract key** allows you to uniquely identify a `contract <#contract>`__ of a particular `template <#template>`__, similarly to a primary key in a database table.
@ -284,7 +284,7 @@ See :doc:`/daml/reference/contract-keys`.
.. _dar-file-dalf-file:
DAR file, DALF file
DAR File, DALF File
===================
A Daml Archive file, known as a ``.dar`` file is the result of compiling Daml code using the `Assistant <#assistant>`__ which can be interpreted using a Daml interpreter.
@ -298,7 +298,7 @@ A ``.dar`` contains multiple ``.dalf`` files. A ``.dalf`` file is the output of
.. TODO ask Robin
Developer tools
Developer Tools
***************
Assistant
@ -336,10 +336,10 @@ This is the version of Navigator that runs as a web app.
See :doc:`/tools/navigator/index`.
Building applications
Building Applications
*********************
Application, ledger client, integration
Application, Ledger Client, Integration
=======================================
**Application**, **ledger client** and **integration** are all terms for an application that sits on top of the `ledger <#daml-ledger>`__. These usually `read from the ledger <#reading-from-the-ledger>`_, `send commands <#submitting-commands-writing-to-the-ledger>`__ to the ledger, or both.
@ -354,62 +354,62 @@ An alternative name for the Ledger API is the **gRPC Ledger API** if disambiguat
See :doc:`/app-dev/ledger-api` page.
It includes the following :doc:`services </app-dev/services>`.
Command submission service
Command Submission Service
--------------------------
Use the **command submission service** to `submit commands <#submitting-commands-writing-to-the-ledger>`__ - either create commands or exercise commands - to the `ledger <#daml-ledger>`__. See :ref:`command-submission-service`.
Command completion service
Command Completion Service
--------------------------
Use the **command completion service** to find out whether or not `commands you have submitted <#submitting-commands-writing-to-the-ledger>`__ have completed, and what their status was. See :ref:`command-completion-service`.
Command service
Command Service
---------------
Use the **command service** when you want to `submit a command <#submitting-commands-writing-to-the-ledger>`__ and wait for it to be executed. See :ref:`command-service`.
Transaction service
Transaction Service
-------------------
Use the **transaction service** to listen to changes in the `ledger <#daml-ledger>`__, reported as a stream of `transactions <#transactions>`__. See :ref:`transaction-service`.
Active contract service
Active Contract Service
-----------------------
Use the **active contract service** to obtain a party-specific view of all `contracts <#contract>`__ currently `active <#active-contract-archived-contract>`__ on the `ledger <#daml-ledger>`__. See :ref:`active-contract-service`.
Package service
Package Service
---------------
Use the **package service** to obtain information about Daml packages available on the `ledger <#daml-ledger>`__. See :ref:`package-service`.
Ledger identity service
Ledger Identity Service
-----------------------
Use the **ledger identity service** to get the identity string of the `ledger <#daml-ledger>`__ that your application is connected to. See :ref:`ledger-identity-service`.
Ledger configuration service
Ledger Configuration Service
----------------------------
Use the **ledger configuration service** to subscribe to changes in `ledger <#daml-ledger>`__ configuration. See :ref:`ledger-configuration-service`.
Ledger API libraries
Ledger API Libraries
====================
The following libraries wrap the `ledger API <#ledger-api>`__ for more native experience applications development.
Java bindings
Java Bindings
-------------
An idiomatic Java library for writing `ledger applications <#application-ledger-client-integration>`__. See :doc:`/app-dev/bindings-java/index`.
Reading from the ledger
Reading From the Ledger
=======================
`Applications <#application-ledger-client-integration>`__ get information about the `ledger <#daml-ledger>`__ by **reading** from it. You can't query the ledger, but you can subscribe to the transaction stream to get the events, or the more sophisticated active contract service.
Submitting commands, writing to the ledger
Submitting Commands, Writing To the Ledger
==========================================
`Applications <#application-ledger-client-integration>`__ make changes to the `ledger <#daml-ledger>`__ by **submitting commands**. You can't change it directly: an application submits a command of `transactions <#transactions>`__. The command gets evaluated by the runtime, and will only be accepted if it's valid.
@ -436,7 +436,7 @@ Participant Node
The participant node is a server that provides users a consistent programmatic access to a ledger through the `Ledger API <#ledger-api>`__. The participant nodes handles transaction signing and
validation, such that users don't have to deal with cryptographic primitives but can trust the participant node that the data they are observing has been properly verified to be correct.
Sub-Transaction Privacy
Sub-transaction Privacy
=======================
Sub-transaction privacy is where participants to a transaction only `learn about the subset of the transaction <https://docs.daml.com/concepts/ledger-model/ledger-privacy.html>`__ they are
@ -461,7 +461,7 @@ directly involved participants who wish to be part of the new application functi
.. _trust-domain:
Trust domain
Trust Domain
============
A trust domain encompasses a part of the system (in particular, a Daml ledger) operated by a single real-world entity. This subsystem may consist of one or more physical nodes. A single physical machine is always assumed to be controlled by exactly one real-world entity.

22
docs/source/concepts/interoperability.rst
View File

@ -3,8 +3,8 @@
.. _interoperable-ledgers:
Ledger Interoperability
#######################
Daml Ledger Interoperability
############################
Certain Daml ledgers can interoperate with other Daml ledgers.
That is, the contracts created on one ledger can be used and archived in transactions on other ledgers.
@ -32,7 +32,7 @@ The presentation assumes that you are familiar with the following concepts:
.. _interop-limitation-examples:
Interoperability examples
Interoperability Examples
*************************
.. _interoperable-topology:
@ -70,7 +70,7 @@ The components in this diagram are the following:
.. _interoperable-aggregation:
Aggregation at the participant
Aggregation at the Participant
==============================
The Participant Node assembles the updates from these ledgers and outputs them via the party's Transaction Service and Active Contract Service.
@ -83,7 +83,7 @@ then `P1`\ 's transaction stream for Alice will emit this transaction and report
.. _enter-leave-event:
Enter and Leave events
Enter and Leave Events
======================
With interoperability, a transaction can use a contract whose creation was recorded on a different ledger.
@ -128,7 +128,7 @@ In contrast, `P1` need not output the **Enter** and **Leave** actions at all in
.. _cross-ledger-transaction:
Cross-ledger transactions
Cross-ledger Transactions
=========================
With interoperability, a cross-ledger transaction can be committed on several interoperable Daml ledgers simultaneously.
@ -157,7 +157,7 @@ Accordingly, it does not report the contract as active nor can Alice use the con
.. _interop-causality-graph:
Multi-ledger causality graphs
Multi-ledger Causality Graphs
*****************************
This section generalizes :ref:`causality graphs <causality-graph>` to the interoperability setting.
@ -323,7 +323,7 @@ In particular all maximal chains of actions on a contract are ledger traces:
| `PaintAgree P A` | **Create** |
+-------------------------+-----------------------------------------+
Minimality and reduction
Minimality and Reduction
========================
When edges are added to an `X`-multi-ledger consistent causality graph such that it remains acyclic and transitively closed,
@ -343,7 +343,7 @@ Since multi-ledger causality graphs are acyclic, their vertices can be sorted to
If the original causality graph is `X`\ -consistent, then so is the topological sort, as topological sorting merely adds edges.
From multi-ledger causality graphs to ledgers
From Multi-ledger Causality Graphs to Ledgers
=============================================
Multi-Ledger causality graphs `G` are linked to ledgers `L` in the Daml Ledger Model via topological sort and reduction.
@ -364,7 +364,7 @@ Conversely, a consistent ledger does not talk about the incoming and outgoing le
.. _ledger-aware-projection:
Ledger-aware projection
Ledger-aware Projection
***********************
A Participant Node maintains a local ledger for each party it hosts and the Transaction Service outputs a topological sort of this local ledger.
@ -456,7 +456,7 @@ That is, a **Leave** action is white on the right hand side and an **Enter** act
.. _interop-ordering-guarantees:
Ledger API ordering guarantees
Ledger API Ordering Guarantees
******************************
The Transaction Service and the Active Contract Service are derived from the local ledger that the Participant Node maintains for the party.

4
docs/source/concepts/ledger-model/ledger-daml.rst
View File

@ -3,8 +3,8 @@
.. _da-model-daml:
Daml: Defining Contract Models Compactly
########################################
Daml: Define Contract Models Compactly
######################################
As described in preceding sections, both the integrity and privacy notions depend on
a contract model, and such a model must specify:

8
docs/source/concepts/ledger-model/ledger-integrity.rst
View File

@ -65,7 +65,7 @@ Then, `act'` happens after `act`.
.. _da-model-contract-consistency:
Contract consistency
Contract Consistency
====================
Contract consistency ensures that contracts are used after they have been created and before they are consumed.
@ -136,7 +136,7 @@ of contracts `Iou Bank P` and `PaintAgree P A`.
.. _da-model-key-consistency:
Key consistency
Key Consistency
===============
Contract keys introduce a key uniqueness constraint for the ledger.
@ -203,14 +203,14 @@ Key consistency extends to actions, transactions and lists of transactions just
.. _da-model-ledger-consistency:
Ledger consistency
Ledger Consistency
==================
Definition »ledger consistency«
A ledger is **consistent** if it is consistent for all contracts and for all keys.
Internal consistency
Internal Consistency
====================
The above consistency requirement is too strong for actions and transactions
in isolation.

2
docs/source/concepts/ledger-model/ledger-privacy.rst
View File

@ -184,7 +184,7 @@ projections.
.. _da-model-privacy-authorization:
Privacy through authorization
Privacy Through Authorization
*****************************
Setting the maintainers as required authorizers for a **NoSuchKey** assertion ensures

44
docs/source/concepts/local-ledger.rst
View File

@ -3,8 +3,8 @@
.. _local-ledger:
Causality and Local Ledgers
###########################
Causality and Local Daml Ledgers
################################
Daml ledgers do not totally order all transactions.
So different parties may observe two transactions on different Participant Nodes in different orders via the :ref:`Ledger API <ledger-api-services>`.
@ -19,7 +19,7 @@ The presentation assumes that you are familiar with the following concepts:
.. _causality-examples:
Causality examples
Causality Examples
******************
A Daml Ledger need not totally order all transaction, unlike ledgers in the Daml Ledger Model.
@ -37,8 +37,8 @@ Recall that :ref:`the party projections <da-paint-counteroffer-example>` are as
.. _causality-example-create-archive:
Stakeholders of a contract see creation and archival in the same order.
=======================================================================
Stakeholders of a Contract See Creation and Archival in the Same Order
======================================================================
Every Daml Ledger orders the creation of the `CounterOffer A P Bank` before the painter exercising the consuming choice on the `CounterOffer`.
(If the **Create** was ordered after the **Exercise**, the resulting shared ledger would be inconsistent, which violates the validity guarantee of Daml ledgers.)
@ -47,8 +47,8 @@ This does not depend on whether they are hosted on the same Participant Node.
.. _causality-example-create-use-archive:
Signatories of a contract and stakeholder actors see usages after the creation and before the archival.
=======================================================================================================
Signatories of a Contract and Stakeholder Actors See Usages After the Creation and Before the Archival
======================================================================================================
The `Fetch A (Iou Bank A)` action comes after the creation of the `Iou Bank A` and before its archival,
for both Alice and the Bank,
@ -56,8 +56,8 @@ because the Bank is a signatory of the `Iou Bank A` contract and Alice is a stak
.. _causality-example-commit-atomic:
Commits are atomic.
===================
Commits Are Atomic
==================
Alice sees the **Create** of her `Iou` before the creation of the `CounterOffer`,
because the `CounterOffer` is created in the same commit as the **Fetch** of the `Iou`
@ -65,8 +65,8 @@ and the **Fetch** commit comes after the **Create** of the `Iou`.
.. _causality-example-non-consuming:
Non-consuming usages in different commits may appear in different orders.
=========================================================================
Non-Consuming Usages in Different Commits May Appear in Different Orders
========================================================================
Suppose that the Bank exercises a non-consuming choice on the `Iou Bank A` without consequences while Alice creates the `CounterOffer`.
In the ledger shown below, the Bank's commit comes before Alice's commit.
@ -83,8 +83,8 @@ Yet, the **Fetch** may come before the non-consuming **Exercise** in the Bank's
.. _causality-example-out-of-band:
Out-of-band causality is not respected.
=======================================
Out-of-Band Causality Is Not Respected
======================================
The following examples assume that Alice splits up her commit into two as follows:
@ -114,8 +114,8 @@ Daml ledgers therefore do not capture data flow through applications.
.. _causality-divulgence-example:
Divulged actions do not induce order.
=====================================
Divulged Actions Do Not Induce Order
====================================
The painter witnesses the fetching of Alice's `Iou` when the `ShowIou` contract is consumed.
The painter also witnesses the **Exercise** of the `Iou` when Alice exercises the transfer choice as a consequence of the painter accepting the `CounterOffer`.
@ -139,8 +139,8 @@ Analogously, choice observers of an **Exercise** action benefit from the orderin
.. _causality-example-depend-on-party:
The ordering guarantees depend on the party.
============================================
The Ordering Guarantees Depend on the Party
===========================================
By the previous example, for the painter, fetching the `Iou` is not ordered before transferring the `Iou`.
For Alice, however, the **Fetch** must appear before the **Exercise**
@ -150,7 +150,7 @@ This shows that the ordering guarantees depend on the party.
.. _causality-graph:
Causality graphs
Causality Graphs
****************
The above examples indicate that Daml ledgers order transactions only partially.
@ -299,7 +299,7 @@ For this set of transactions, consistency allows only one such order: `tx5` come
.. _causality-consistency-ledger-model:
From causality graphs to ledgers
From Causality Graphs to Ledgers
================================
Since causality graphs are acyclic, their vertices can be sorted topologically and the resulting list is again a causality graph, where every vertex has an outgoing edge to all later vertices.
@ -344,7 +344,7 @@ Conversely, if the sequence of commits `L` is ledger consistent, `G`:sub:`L` is
.. _local-ledger-structure:
Local ledgers
Local Ledgers
*************
As explained in the Daml Ledger Model, parties see only a :ref:`projection <da-model-projections>` of the shared ledger for privacy reasons.
@ -398,7 +398,7 @@ This difference explains the :ref:`divulgence causality example <causality-divul
.. _ordering-guarantees:
Ledger API ordering guarantees
Ledger API Ordering Guarantees
==============================
The :ref:`Transaction Service <transaction-service>` provides the updates as a stream of Daml transactions
@ -432,7 +432,7 @@ These guarantees are subject to the deployed Daml ledger's trust assumptions.
That is, all the local ledgers can in theory be combined into a consistent single causality graph of which they are projections.
Explaining the causality examples
Explaining the Causality Examples
=================================
The :ref:`causality examples <causality-examples>` can be explained in terms of causality graphs and local ledgers as follows:

14
docs/source/concepts/time.rst
View File

@ -3,8 +3,8 @@
.. _time:
Time
####
Time on Daml Ledgers
####################
The Daml language contains a function :ref:`getTime <daml-ref-gettime>` which returns the “current time”.
However, the notion of time comes with a lot of problems in a distributed setting.
@ -16,7 +16,7 @@ the *ledger time* ``lt_TX`` and the *record time* ``rt_TX``.
.. _ledger_time:
Ledger time
Ledger Time
***********
The *ledger time* ``lt_TX`` is a property of a transaction.
@ -27,7 +27,7 @@ The ledger time is assigned by the submitting participant as part of the Daml co
.. _record-time:
Record time
Record Time
***********
The *record time* ``rt_TX`` is another property of a transaction.
@ -63,7 +63,7 @@ Daml applications should not interpret the value returned by :ref:`getTime <daml
.. _ledger-time-model:
Ledger time model
Ledger Time Model
*****************
The *ledger time model* is the set of parameters used in the assignment and validation of ledger time.
@ -82,8 +82,8 @@ The ledger time model is part of the ledger configuration and can be changed by
.. _assigning-ledger-time:
Assigning ledger time
*********************
Assign Ledger Time
******************
The ledger time is assigned automatically by the participant.
In most cases, Daml applications will not need to worry about ledger time and record time at all.

10
docs/source/daml-repl/index.rst
View File

@ -2,7 +2,7 @@
.. SPDX-License-Identifier: Apache-2.0
Daml REPL
###########
#########
The Daml REPL allows you to use the :doc:`/daml-script/index` API
interactively. This is useful for debugging and for interactively
@ -125,7 +125,7 @@ Using the ``query`` function we can now verify that there is one
To exit ``daml repl`` press ``Control-D``.
What is in scope at the prompt?
What Is in Scope at the Prompt?
===============================
In the prompt, all modules from DALFs specified in ``--import`` are
@ -144,7 +144,7 @@ The command ``:show imports`` lists the currently active imports.
.. _repl-no-ledger:
Using Daml REPL without a Ledger
Using Daml REPL Without a Ledger
================================
If you are only interested in pure expressions, e.g., because you want
@ -167,13 +167,13 @@ authentication by passing ``--pem client.key --crt client.crt``. If
``--cacrt`` or ``--pem`` and ``--crt`` are passed TLS is automatically
enabled so ``--tls`` is redundant.
Connection to a Ledger with Authorization
Connection to a Ledger With Authorization
=========================================
If your ledger requires an authorization token you can pass it via
``--access-token-file``.
Using Daml REPL to convert to JSON
Using Daml REPL to Convert to JSON
==================================
Using the ``:json`` command you can encode serializable Daml expressions as

26
docs/source/daml-script/index.rst
View File

@ -124,7 +124,7 @@ the type ``Script ()``.
:start-after: -- INITIALIZE_PURE_BEGIN
:end-before: -- INITIALIZE_PURE_END
Party management
Party Management
----------------
We have now defined a way to initialize the ledger so we can write a
@ -177,8 +177,8 @@ them away using ``map snd``.
:start-after: -- TEST_QUERIES_BEGIN
:end-before: -- TEST_QUERIES_END
Running a Script
----------------
Run a Script
------------
To run our script, we first build it with ``daml build`` and then run
it by pointing to the DAR, the name of our script, and the host and
@ -225,8 +225,8 @@ initialize our ledger as follows:
.. _script-ledger-initialization:
Using Daml Script for Ledger Initialization
===========================================
Use Daml Script for Ledger Initialization
=========================================
You can use Daml script to initialize a ledger on startup. To do so,
specify an ``init-script: ScriptExample:initializeUser`` field in your
@ -242,8 +242,8 @@ instead of party ids.
:start-after: -- INITIALIZE_USER_BEGIN
:end-before: -- INITIALIZE_USER_END
Migrating from Scenarios
------------------------
Migrate From Scenarios
----------------------
Existing scenarios that you used for ledger initialization can be
translated to Daml script but there are a few things to keep in mind:
@ -298,8 +298,8 @@ translated to Daml script but there are a few things to keep in mind:
.. _daml-script-distributed:
Using Daml Script in Distributed Topologies
===========================================
Use Daml Script in Distributed Topologies
=========================================
So far, we have run Daml script against a single participant node. It
is also more possible to run it in a setting where different parties
@ -324,8 +324,8 @@ argument.
.. _daml-script-auth:
Running Daml Script against Ledgers with Authorization
======================================================
Run Daml Script Against Ledgers with Authorization
==================================================
To run Daml Script against a ledger that verifies authorization,
you need to specify an access token. There are two ways of doing that:
@ -348,8 +348,8 @@ have a token specified in the config.
.. _daml-script-json-api:
Running Daml Script against the HTTP JSON API
=============================================
Run Daml Script Against the HTTP JSON API
=========================================
In some cases, you only have access to the
:doc:`HTTP JSON API </json-api/index>` but not to the gRPC of a ledger, e.g., on

36
docs/source/daml/daml-studio.rst
View File

@ -6,13 +6,13 @@ Daml Studio
Daml Studio is an integrated development environment (IDE) for Daml. It is an extension on top of `Visual Studio Code <https://code.visualstudio.com>`__ (VS Code), a cross-platform, open-source editor providing a `rich code editing experience <https://code.visualstudio.com/docs/editor/editingevolved>`__.
Installing
**********
Install
*******
Daml Studio is included in :doc:`the Daml SDK </getting-started/installation>`.
Creating your first Daml file
*****************************
Create Your First Daml File
***************************
1. Start Daml Studio by running ``daml studio`` in the current project.
@ -50,14 +50,14 @@ We recommend reviewing the
to learn more about how to use it.
To learn more about Daml, see :doc:`reference/index`.
Supported features
Supported Features
******************
Visual Studio Code provides many helpful features for editing Daml files and we recommend reviewing
`Visual Studio Code Basics <https://code.visualstudio.com/docs/editor/codebasics>`__ and `Visual Studio Code Keyboard Shortcuts for OS X <https://code.visualstudio.com/shortcuts/keyboard-shortcuts-macos.pdf>`_.
The Daml Studio extension for Visual Studio Code provides the following Daml-specific features:
Symbols and problem reporting
Symbols and Problem Reporting
=============================
Use the commands listed below to navigate between symbols, rename them, and inspect any problems detected in your Daml files. Symbols are identifiers such as template names,
@ -93,7 +93,7 @@ Command Shortcut (OS X)
.. _Go to Symbol in Workspace: https://code.visualstudio.com/docs/editor/editingevolved#_open-symbol-by-name
.. _Problems Panel: https://code.visualstudio.com/docs/editor/editingevolved#_errors-warnings
Hover tooltips
Hover Tooltips
==============
You can `hover`_ over most symbols in the code to display additional information such as its type.
@ -102,8 +102,8 @@ You can `hover`_ over most symbols in the code to display additional information
.. _script-results:
Daml Script results
================================
Daml Script Results
===================
Top-level declarations of type ``Script`` are decorated with
a ``Script results`` code lens.
@ -180,7 +180,7 @@ You can navigate to the corresponding source code by clicking on the location
shown in parenthesis (e.g. ``Iou:25:12``, which means the ``Iou`` module, line 25 and column 1).
You can also navigate between transactions by clicking on the transaction and contract ids (e.g. ``#1:0``).
Daml snippets
Daml Snippets
=============
You can automatically complete a number of "snippets" when editing a Daml
@ -209,8 +209,8 @@ snippet file.
.. _Creating your own Snippets: https://code.visualstudio.com/docs/editor/userdefinedsnippets
Common script errors
**********************
Common Script Errors
********************
During Daml execution, errors can occur due to exceptions (e.g. use of "abort", or division by zero), or
due to authorization failures. You can expect to run into the following errors when writing Daml.
@ -233,7 +233,7 @@ Committed transaction
Trace
Any messages produced by calls to ``trace`` and ``debug``.
Abort, assert, and debug
Abort, Assert, and Debug
========================
The ``abort``, ``assert`` and ``debug`` inbuilt functions can be used in updates and scripts. All three can be used to output messages, but ``abort`` and ``assert`` can additionally halt the execution:
@ -255,7 +255,7 @@ The ``abort``, ``assert`` and ``debug`` inbuilt functions can be used in updates
"hello, world!"
Missing authorization on create
Missing Authorization on Create
===============================
If a contract is being created without approval from all authorizing
@ -289,7 +289,7 @@ authorize the creation via a choice, for example 'Alice' could create a contract
giving 'Bob' the choice to create the 'Example' contract.
Missing authorization on exercise
Missing Authorization on Exercise
=================================
Similarly to creates, exercises can also fail due to missing authorizations when a
@ -332,7 +332,7 @@ choice 'Consume' of which he is not a controller
From the error we can see that the parties authorizing the exercise ('Bob')
is not a subset of the required controlling parties.
Contract not visible
Contract Not Visible
====================
Contract not being visible is another common error that can occur when a contract
@ -373,8 +373,8 @@ To fix this issue the party 'Bob' should be made a controlling party in one of t
.. _daml-studio-packages:
Working with multiple packages
******************************
Work with Multiple Packages
***************************
Often a Daml project consists of multiple packages, e.g., one
containing your templates and one containing a Daml trigger so that

2
docs/source/daml/intro/0_Intro.rst
View File

@ -3,7 +3,7 @@
.. _intro-to-daml:
An introduction to Daml
An Introduction to Daml
=======================
Daml is a smart contract language designed to build composable applications on an abstract :ref:`da-ledgers`.

6
docs/source/daml/intro/10_Functional101.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
10 Functional Programming 101
=============================
Functional Programming 101
==========================
In this chapter, you will learn more about expressing complex logic in a functional language like Daml. Specifically, you'll learn about
@ -497,7 +497,7 @@ Have a go at implementing ``foldlA`` in terms of ``foldl`` and ``sequence`` and
Lastly, you'll have noticed that in some cases we used ``mapA_``, not ``mapA``. The underscore indicates that the result is not used. ``mapA_ fn xs fn = void (mapA fn xs)``. The Daml Linter will alert you if you could use ``mapA_`` instead of ``mapA``, and similarly for ``forA_``.
Next up
Next Up
-------
You now know the basics of functions and control flow, both in pure and Action contexts. The Chapter 8 example shows just how much can be done with just the tools you have encountered here, but there are many more tools at your disposal in the Daml Standard Library. It provides functions and typeclasses for many common circumstances and in :doc:`11_StdLib`, you'll get an overview of the library and learn how to search and browse it.

22
docs/source/daml/intro/11_StdLib.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
11 Intro to the Daml Standard Library
=====================================
Introduction to the Daml Standard Library
=========================================
In chapters :doc:`3_Data` and :doc:`10_Functional101` you learnt how to define your own data types and functions. But of course you don't have to implement everything from scratch. Daml comes with the Daml Standard Library which contains types, functions, and typeclasses that cover a large range of use-cases. In this chapter, you'll get an overview of the essentials, but also learn how to browse and search this library to find functions. Being proficient with the Standard Library will make you considerably more efficient writing Daml code. Specifically, this chapter covers:
@ -23,7 +23,7 @@ The Prelude
You've already used a lot of functions, types, and typeclasses without importing anything. Functions like ``create``, ``exercise``, and ``(==)``, types like ``[]``, ``(,)``, ``Optional``, and typeclasses like ``Eq``, ``Show``, and ``Ord``. These all come from the :doc:`Prelude </daml/stdlib/Prelude>`. The Prelude is module that gets implicitly imported into every other Daml module and contains both Daml specific machinery as well as the essentials needed to work with the inbuilt types and typeclasses.
Important Types from the Prelude
Important Types From the Prelude
--------------------------------
In addition to the :ref:`native-types`, the Prelude defines a number of common types:
@ -116,7 +116,7 @@ This is akin to an interface declaration of an interface with a getter and sette
Typeclasses can have constraints like functions. For example: ``class Eq a => Ord a`` means "everything that is orderable can also be compared for equality". And that's almost all there's to it.
Important Typeclasses from the Prelude
Important Typeclasses From the Prelude
--------------------------------------
Eq
@ -185,15 +185,15 @@ You get the idea, the names are fairly descriptive.
Other than the typeclasses defined in Prelude, there are two modules generalizing concepts you've already learnt about, which are worth knowing about: ``Foldable`` and ``Traversable``. In :ref:`looping` you learned all about folds and their Action equivalents. All the examples there were based on lists, but there are many other possible iterators. This is expressed in two additional typeclasses: :doc:`/daml/stdlib/DA-Traversable`, and :doc:`/daml/stdlib/DA-Foldable`. For more detail on these concepts, please refer to the literature in :ref:`haskell-connection`, or `https://wiki.haskell.org/Foldable_and_Traversable <https://wiki.haskell.org/Foldable_and_Traversable>`__.
Searching the Standard Library
------------------------------
Search the Standard Library
---------------------------
Being able to browse the Standard Library starting from :doc:`/daml/stdlib/index` is a start, and the module naming helps, but it's not an efficient process for finding out what a function you've encountered does, or even less so to find a function that does a thing you need to do.
Daml has it's own version of the `Hoogle <https://hoogle.haskell.org/>`__ search engine, which offers search both by name and by signature. It's fully integrated into the search bar on `https://docs.daml.com/ <https://docs.daml.com/>`__, but for those wanting a pure Standard Library search, it's also available on `<https://hoogle.daml.com>`__.
Searching for functions by Name
...............................
Search for Functions by Name
............................
Say you come across some functions you haven't seen before, like the ones in the ``ensure`` clause of the ``MultiTrade``.
@ -214,8 +214,8 @@ You may be able to guess what ``not`` and ``null`` do, but try searching those n
Signature (including type constraints) and description usually give a pretty clear picture of what a function does.
Searching for functions by Signature
....................................
Search for Functions by Signature
.................................
The other very common use-case for the search is that you have some values that you want to do something with, but don't know the standard library function you need. On the ``MultiTrade`` template we have a list ``baseAssets``, and thanks to your ensure clause we know it's non-empty. In the original ``Trade`` we used ``baseAsset.owner`` as the signatory. How do you get the first element of this list to extract the ``owner`` without going through the motions of a complete pattern match using ``case``?
@ -237,7 +237,7 @@ The reason is that there is an instance for ``Foldable [a]``.
Let's try another search. Suppose you didn't want the first element, but the one at index ``n``. Remember that ``(!!)`` operator from :doc:`10_Functional101`? There are now two possible signatures we could search for: ``[a] -> Int -> a`` and ``Int -> [a] -> a``. Try searching for both. You'll see that the search returns ``(!!)`` in both cases. You don't have to worry about the order of arguments.
Next up
Next Up
-------
There's little more to learn about writing Daml at this point that isn't best learnt by practice and consulting reference material for both Daml and Haskell. To finish off this course, you'll learn a little more about your options for testing and interacting with Daml code in :doc:`12_Testing`, and about the operational semantics of some keywords and common associated failures.

18
docs/source/daml/intro/12_Testing.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
12 Testing Daml Contracts
=========================
Test Daml Contracts
===================
This chapter is all about testing and debugging the Daml contracts you've built using the tools from chapters 1-10. You've already met Daml Script as a way of testing your code inside the IDE. In this chapter you'll learn about more ways to test with Daml Script and its other uses, as well as other tools you can use for testing and debugging. You'll also learn about a few error cases that are most likely to crop up only in actual distributed testing, and which need some care to avoid. Specifically we will cover:
@ -59,8 +59,8 @@ If in doubt, use ``debug``. It's the easier of the two to interpret the results
The thing in the square brackets is the last location. It'll tell you the Daml file and line number that triggered the printing, but often no more than that because full stacktraces could violate subtransaction privacy quite easily. If you want to enable stacktraces for some purely functional code in your modules, you can use the machinery in :doc:`/daml/stdlib/DA-Stack` to do so, but we won't cover that any further here.
Diagnosing Contention Errors
----------------------------
Diagnose Contention Errors
--------------------------
The above tools and functions allow you to diagnose most problems with Daml code, but they are all synchronous. The sequence of commands is determined by the sequence of inputs. That means one of the main pitfalls of distributed applications doesn't come into play: Contention.
@ -99,7 +99,7 @@ ContractId Not Found During Validation
Disputed: dependency error: couldn't find contract ContractId (00c06fa370f8858b20fd100423d928b1d200d8e3c9975600b9c038307ed6e25d6f).
fetchByKey Error during Interpretation
fetchByKey Error During Interpretation
......................................
.. code-block:: none
@ -120,8 +120,8 @@ lookupByKey Dispute During Validation
Disputed: recreated and original transaction mismatch VersionedTransaction(...) expected, but VersionedTransaction(...) is recreated.
Avoiding Race Conditions and Stale References
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Avoid Race Conditions and Stale References
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The first thing to avoid is write-write or write-read contention on contracts. In other words, one requester submitting a transaction with a consuming exercise on a contract while another requester submits another exercise or fetch on the same contract. This type of contention cannot be eliminated entirely, for there will always be some latency between a client submitting a command to a participant, and other clients learning of the committed transaction.
@ -136,7 +136,7 @@ Here are a few scenarios and measures you can take to reduce this type of collis
3. Avoid workflows that encourage multiple parties to simultaneously try to exercise a consuming choice on the same contract. For example, imagine an ``Auction`` contract containing a field ``highestBid : (Party, Decimal)``. If Alice tries to bid $100 at the same time that Bob tries to bid $90, it doesn't matter that Alice's bid is higher. The second transaction to be sequenced will be rejected as it has a write collision with the first. It's better to record the bids in separate ``Bid`` contracts, which can be written to independently. Again, think about how you would structure this data in a relational database to avoid data loss due to race conditions.
4. Think carefully about storing ContractIds. Imagine you had created a sharded user directory according to 1. Each user has a ``User`` contract that store their display name and party. Now you write a chat application where each ``Message`` contract refers to the sender by ``ContractId User``. If the user changes their display name, that reference goes stale. You either have to modify all messages that user ever sent, or become unable to use the sender contract in Daml. If you need to be able to make this link inside Daml, Contract Keys help here. If the only place you need to link ``Party`` to ``User`` is the UI, it might be best to not store contract references in Daml at all.
Collisions due to Ignorance
Collisions Due to Ignorance
~~~~~~~~~~~~~~~~~~~~~~~~~~~
The :doc:`Daml Ledger Model </concepts/ledger-model/index>` specifies authorization rules, and privacy rules. Ie it specifies what makes a transaction conformant, and who gets to see which parts of a committed transaction. It does *not* specify how a command is translated to a transaction. This may seem strange at first since the commands - create, exercise, exerciseByKey, createAndExercise - correspond so closely to actions in the ledger model. But the subtlety comes in on the read side. What happens when the participant, during interpretation, encounters a ``fetch``, ``fetchByKey``, or ``lookupByKey``?
@ -158,7 +158,7 @@ Let's illustrate how collisions and operational semantics and interleave:
As you can see, the behavior of ``fetch``, ``fetchByKey`` and ``lookupByKey`` at interpretation time depend on what information is available to the requester at that time. That's something to keep in mind when writing Daml contracts, and something to think about when encountering frequent "Disputed" errors.
Next up
Next Up
-------
You've reached the end of the Introduction to Daml. Congratulations. If you think you understand all this material, you could test yourself by getting Daml certified at `https://academy.daml.com <https://academy.daml.com>`__. Or put your skills to good use by developing a Daml application. There are plenty of examples to inspire you on the `Examples <https://daml.com/examples>`_ page.

10
docs/source/daml/intro/1_Token.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
1 Basic contracts
=================
Basic Contracts
===============
To begin with, you're going to write a very small Daml template, which represents a self-issued, non-transferable token. Because it's a minimal template, it isn't actually useful on its own - you'll make it more useful later - but it's enough that it can show you the most basic concepts:
@ -16,7 +16,7 @@ To begin with, you're going to write a very small Daml template, which represent
Remember that you can load all the code for this section into a folder ``1_Token`` by running ``daml new intro1 --template daml-intro-1``
Daml ledger basics
Daml Ledger Basics
------------------
Like most structures called ledgers, a Daml Ledger is just a list of *commits*. When we say *commit*, we mean the final result of when a *party* successfully *submits* a *transaction* to the ledger.
@ -31,7 +31,7 @@ Individual contracts are *immutable* in the sense that an active contract can no
Daml specifies what transactions are legal on a Daml Ledger. The rules the Daml code specifies are collectively called a *Daml model* or *contract model*.
Daml files and modules
Daml Files and Modules
----------------------
Each ``.daml`` file defines a *Daml Module* at the top:
@ -71,7 +71,7 @@ The ``signatory`` keyword specifies the *signatories* of a contract. These are t
Furthermore, Daml ledgers *guarantee* that parties see all transactions where their authority is used. This means that signatories of a contract are guaranteed to see the creation and archival of that contract.
Next up
Next Up
-------
In :doc:`2_DamlScript`, you'll learn about how to try out the ``Token`` contract template in Daml's inbuilt Daml Script testing language.

26
docs/source/daml/intro/2_DamlScript.rst
View File

@ -3,8 +3,8 @@
.. _testing-using-script:
2 Testing templates using Daml Script
=====================================
Test Templates using Daml Script
================================
In this section you will test the ``Token`` model from :doc:`1_Token` using the :doc:`Daml Script </daml-script/index>` integration in :ref:`Daml Studio <script-results>`. You'll learn about the basic features of :
@ -21,8 +21,8 @@ In this section you will test the ``Token`` model from :doc:`1_Token` using the
.. script_basics:
Script basics
---------------
Script Basics
-------------
A ``Script`` is like a recipe for a test, where you can script different parties submitting a series of transactions, to check that your templates behave as you'd expect. You can also script some external information like party identities, and ledger time.
@ -55,7 +55,7 @@ You'll learn all about the syntax ``Token with owner = alice`` in :doc:`3_Data`.
You could write this as ``submit alice (createCmd Token with owner = alice)``, but just like scripts, you can assemble commands using ``do`` blocks. A ``do`` block always takes the value of the last statement within it so the syntax shown in the commands above gives the same result, whilst being easier to read. Note however, that the commands submitted as part of a transaction are not allowed to depend on each other.
Running scripts
Run the Scripts
---------------
There are a few ways to run Daml Scripts:
@ -91,8 +91,8 @@ To run the same test from the command line, save your module in a file ``Token_T
.. _intro_2_failure:
Testing for failure
-------------------
Test for Failure
----------------
In :doc:`1_Token` you learned that creating a ``Token`` requires the authority of its owner. In other words, it should not be possible for Alice to create a Token for another party and vice versa. A reasonable attempt to test that would be:
@ -119,8 +119,8 @@ To test for failing submits and keep the script running thereafter, or fail if t
.. _archiving:
Archiving contracts
-------------------
Archive Contracts
-----------------
Archiving contracts works just like creating them, but using ``archiveCmd`` instead of ``createCmd``. Where ``createCmd`` takes an instance of a template, ``archiveCmd`` takes a reference to a contract.
@ -135,8 +135,8 @@ This script first checks that Bob cannot archive Alice's Token and then Alice su
:start-after: -- TOKEN_TEST_3_BEGIN
:end-before: -- TOKEN_TEST_3_END
Exploring the ledger
--------------------
Explore the Ledger
------------------
The resulting script view is empty, because there are no contracts left on the ledger. However, if you want to see the history of the ledger, e.g. to see how you got to that state, tick the "Show archived" box at the top of the ledger view:
@ -174,7 +174,7 @@ To get a better understanding of script, try the following exercises:
Remember that in :ref:`intro_2_failure` we saw a proper error message for a failing submit.
Next up
----------
Next Up
-------
In :doc:`3_Data` you will learn about Daml's type system, and how you can think of templates as tables and contracts as database rows.

20
docs/source/daml/intro/3_Data.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
3 Data types
============
Data Types
==========
In :doc:`1_Token`, you learnt about contract templates, which specify the types of contracts that can be created on the ledger, and what data those contracts hold in their arguments.
@ -31,7 +31,7 @@ After this section, you should be able to use a Daml ledger as a simple database
.. _native-types:
Native types
Native Types
------------
You have already encountered a few native Daml types: ``Party`` in :doc:`1_Token`, and ``Text`` and ``ContractId`` in :doc:`2_DamlScript`. Here are those native types and more:
@ -87,8 +87,8 @@ With templates and these native types, it's already possible to write a schema a
:start-after: -- CASH_BALANCE_BEGIN
:end-before: -- CASH_BALANCE_END
Assembling types
----------------
Assemble Types
--------------
There's quite a lot of information on the ``CashBalance`` above and it would be nice to be able to give that data more structure. Fortunately, Daml's type system has a number of ways to assemble these native types into much more expressive structures.
@ -159,7 +159,7 @@ Records can give the data on ``CashBalance`` a bit more structure:
If you look at the resulting script view, you'll see that this still gives rise to one table. The records are expanded out into columns using dot notation.
Variants and pattern matching
Variants and Pattern Matching
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Suppose now that you also wanted to keep track of cash in hand. Cash in hand doesn't have a bank, but you can't just leave ``bank`` empty. Daml doesn't have an equivalent to ``null``. Variants can express that cash can either be in hand or at a bank.
@ -194,8 +194,8 @@ To do this, you can use *pattern matching* and either throw errors or return com
:start-after: -- VARIANT_ACCESS_BEGIN
:end-before: -- VARIANT_ACCESS_END
Manipulating data
-----------------
Manipulate Data
---------------
You've got all the ingredients to build rich types expressing the data you want to be able to write to the ledger, and you have seen how to create new values and read fields from values. But how do you manipulate values once created?
@ -212,7 +212,7 @@ Throughout the script, ``eq_record`` never changes. The expression ``"Zero" :: e
.. _contract_keys:
Contract keys
Contract Keys
-------------
Daml's type system lets you store richly structured data on Daml templates, but just like most database schemas have more than one table, Daml contract models often have multiple templates that reference each other. For example, you may not want to store your bank and account information on each individual cash balance contract, but instead store those on separate contracts.
@ -243,7 +243,7 @@ via ``createAndExerciseCmd``. We will learn more about choices in the :doc:`next
Since a single type could be used as the key for multiple templates, you need to tell the compiler what type of contract is being fetched by using the ``@Account`` notation.
Next up
Next Up
-------
You can now define data schemas for the ledger, read, write and delete data from the ledger, and use keys to reference and look up data in a stable fashion.

16
docs/source/daml/intro/4_Transformations.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
4 Transforming data using choices
=================================
Transform Data Using Choices
============================
In the example in :ref:`contract_keys` the accountant party wanted to change some data on a contract. They did so by archiving the contract and re-creating it with the updated data. That works because the accountant is the sole signatory on the ``Account`` contract defined there.
@ -14,7 +14,7 @@ In this section you will learn about how to define simple data transformations u
Remember that you can load all the code for this section into a folder called ``intro4`` by running ``daml new intro4 --template daml-intro-4``
Choices as methods
Choices as Methods
------------------
If you think of templates as classes and contracts as objects, where are the methods?
@ -77,7 +77,7 @@ contract with the given arguments and immediately exercise a choice on
it. For a consuming choice, this archives the contract so the contract
is created and archived within the same transaction.
Choices as delegation
Choices as Delegation
---------------------
Up to this point all the contracts only involved one party. ``party`` may have been stored as ``Party`` field in the above, which suggests they are actors on the ledger, but they couldn't see the contracts, nor change them in any way. It would be reasonable for the party for which a ``Contact`` is stored to be able to update their own address and telephone number. In other words, the ``owner`` of a ``Contact`` should be able to *delegate* the right to perform a certain kind of data transformation to ``party``.
@ -98,7 +98,7 @@ If you open the script view in the IDE, you will notice that Bob sees the ``Cont
.. _choices:
Choices in the Ledger Model
Choices In the Ledger Model
---------------------------
In :doc:`1_Token` you learned about the high-level structure of a Daml ledger. With choices and the `exercise` function, you have the next important ingredient to understand the structure of the ledger and transactions.
@ -166,14 +166,14 @@ There are four commits corresponding to the four ``submit`` statements in the sc
So commits ``#2`` and ``#3`` contain ``exercise`` actions with IDs ``#2:0`` and ``#3:0``. The ``create`` actions of the updated ``Contact`` contracts, ``#2:1`` and ``#3:1``, are indented and found below a line reading ``children:``, making the tree structure apparent.
The Archive choice
The Archive Choice
~~~~~~~~~~~~~~~~~~
You may have noticed that there is no archive action. That's because ``archive cid`` is just shorthand for ``exercise cid Archive``, where ``Archive`` is a choice implicitly added to every template, with the signatories as controllers.
.. _simple_iou:
A simple cash model
A Simple Cash Model
-------------------
With the power of choices, you can build your first interesting model: issuance of cash IOUs (I owe you). The model presented here is simpler than the one in :doc:`3_Data` as it's not concerned with the location of the physical cash, but merely with liabilities:
@ -183,7 +183,7 @@ With the power of choices, you can build your first interesting model: issuance
The above model is fine as long as everyone trusts Dora. Dora could revoke the `SimpleIou` at any point by archiving it. However, the provenance of all transactions would be on the ledger so the owner could *prove* that Dora was dishonest and cancelled her debt.
Next up
Next Up
-------
You can now store and transform data on the ledger, even giving other parties specific write access through choices.

32
docs/source/daml/intro/5_Restrictions.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
5 Adding constraints to a contract
==================================
Add Constraints to a Contract
=============================
You will often want to constrain the data stored or the allowed data transformations in your contract models. In this section, you will learn about the two main mechanisms provided in Daml:
@ -17,7 +17,7 @@ Lastly, you will learn about time on the ledger and in Daml Script.
Remember that you can load all the code for this section into a folder called ``intro5`` by running ``daml new intro5 --template daml-intro-5``
Template preconditions
Template Preconditions
----------------------
The first kind of restriction you may want to put on the contract model are called *template pre-conditions*. These are simply restrictions on the data that can be stored on a contract from that template.
@ -82,7 +82,7 @@ There are quite a few new time-related functions from the ``DA.Time`` and ``DA.D
There's also quite a lot going on inside the ``do`` block of the ``Redeem`` choice, with several uses of the ``<-`` operator. ``do`` blocks and ``<-`` deserve a proper explanation at this point.
Time on Daml ledgers
Time on Daml Ledgers
--------------------
Each transaction on a Daml ledger has two timestamps called the *ledger time (LT)* and the *record time (RT)*. The ledger time is set by the participant, the record time is set by the ledger.
@ -97,7 +97,7 @@ Time therefore has to be considered slightly fuzzy in Daml, with the fuzziness d
For details, see :ref:`Background concepts - time <time>`.
Time in test scripts
Time in Test Scripts
~~~~~~~~~~~~~~~~~~~~
For tests, you can set time using the following functions:
@ -105,7 +105,7 @@ For tests, you can set time using the following functions:
- ``setTime``, which sets the ledger time to the given time.
- ``passTime``, which takes a ``RelTime`` (a relative time) and moves the ledger by that much.
Time on ledgers
Time on Ledgers
~~~~~~~~~~~~~~~~~
On a distributed Daml ledger, there are no guarantees that ledger time or record time are strictly increasing. The only guarantee is that ledger time is increasing with causality. That is, if a transaction ``TX2`` depends on a transaction ``TX1``, then the ledger enforces that the LT of ``TX2`` is greater than or equal to that of ``TX1``:
@ -115,14 +115,14 @@ On a distributed Daml ledger, there are no guarantees that ledger time or record
:start-after: -- CAUSALITY_TEST_BEGIN
:end-before: -- CAUSALITY_TEST_END
Actions and ``do`` blocks
Actions and ``do`` Blocks
-------------------------
You have come across ``do`` blocks and ``<-`` notations in two contexts by now: ``Script`` and ``Update``. Both of these are examples of an ``Action``, also called a *Monad* in functional programming. You can construct ``Actions`` conveniently using ``do`` notation.
Understanding ``Actions`` and ``do`` blocks is therefore crucial to being able to construct correct contract models and test them, so this section will explain them in some detail.
Pure expressions compared to Actions
Pure Expressions Compared to Actions
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Expressions in Daml are pure in the sense that they have no side-effects: they neither read nor modify any external state. If you know the value of all variables in scope and write an expression, you can work out the value of that expression on pen and paper.
@ -137,7 +137,7 @@ You cannot work out the value of ``now`` based on any variable in scope. To put
Similarly, you've come across ``fetch``. If you have ``cid : ContractId Account`` in scope and you come across the expression ``fetch cid``, you can't evaluate that to an ``Account`` so you can't write ``account = fetch cid``. To do so, you'd have to have a ledger you can look that contract ID up on.
Actions and impurity
Actions and Impurity
~~~~~~~~~~~~~~~~~~~~~
Actions are a way to handle such "impure" expressions. ``Action a`` is a type class with a single parameter ``a``, and ``Update`` and ``Script`` are instances of ``Action``. A value of such a type ``m a`` where ``m`` is an instance of ``Action`` can be interpreted as "a recipe for an action of type ``m``, which, when executed, returns a value ``a``".
@ -174,8 +174,8 @@ same transaction, you can make multiple calls to ``submit``.
:start-after: -- BEGIN_EXT
:end-before: -- END_EXT
Chaining up actions with do blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Chain Actions With ``do`` Blocks
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
An action followed by another action, possibly depending on the result of the first action, is just another action. Specifically:
@ -191,12 +191,12 @@ This is where ``do`` blocks come in. ``do`` blocks allow you to build complex ac
Above, we see ``do`` blocks in action for both ``Script`` and ``Update``.
Wrapping values in actions
~~~~~~~~~~~~~~~~~~~~~~~~~~
Wrap Values in Actions
~~~~~~~~~~~~~~~~~~~~~~
You may already have noticed the use of ``return`` in the redeem choice. ``return x`` is a no-op action which returns value ``x`` so ``return 42 : Update Int``. Since ``do`` blocks always return the value of their last action, ``sub_script2 : Script Int``.
Failing actions
Failing Actions
---------------
Not only are ``Update`` and ``Script`` examples of ``Action``, they are both examples of actions that can fail, e.g. because a transaction is illegal or the party retrieved via ``allocateParty`` doesn't exist on the ledger.
@ -207,7 +207,7 @@ Transactions succeed or fail *atomically* as a whole. Scripts on the other hand
The last expression in the ``do`` block of the ``Redeem`` choice is a pattern matching expression on ``dow``. It has type ``Update ()`` and is either an ``abort`` or ``return`` depending on the day of week. So during the week, it's a no-op and on weekends, it's the special failure action. Thanks to the atomicity of transactions, no transaction can ever make use of the ``Redeem`` choice on weekends, because it fails the entire transaction.
A sample Action
A Sample Action
---------------
If the above didn't make complete sense, here's another example to explain what actions are more generally, by creating a new type that is also an action. ``CoinGame a`` is an ``Action a`` in which a ``Coin`` is flipped. The ``Coin`` is a pseudo-random number generator and each flip has the effect of changing the random number generator's state. Based on the ``Heads`` and ``Tails`` results, a return value of type ``a`` is calculated.
@ -271,7 +271,7 @@ The big downside to this is that even unused errors cause failures. The followin
``error`` should therefore only be used in cases where the error case is unlikely to be encountered, and where explicit partiality would unduly impact usability of the function.
Next up
Next Up
-------
You can now specify a precise data and data-transformation model for Daml ledgers. In :doc:`6_Parties`, you will learn how to properly involve multiple parties in contracts, how authority works in Daml, and how to build contract models with strong guarantees in contexts with mutually distrusting entities.

16
docs/source/daml/intro/6_Parties.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
6 Parties and authority
=======================
Parties and Authority
=====================
Daml is designed for distributed applications involving mutually distrusting parties. In a well-constructed contract model, all parties have strong guarantees that nobody cheats or circumvents the rules laid out by templates and choices.
@ -16,7 +16,7 @@ In this section you will learn about Daml's authorization rules and how to devel
Remember that you can load all the code for this section into a folder called ``intro6`` by running ``daml new intro6 --template daml-intro-6``
Preventing IOU revocation
Preventing IOU Revocation
-------------------------
The ``SimpleIou`` contract from :doc:`4_Transformations` and :doc:`5_Restrictions` has one major problem: The contract is only signed by the ``issuer``. The signatories are the parties with the power to create and archive contracts. If Alice gave Bob a ``SimpleIou`` for $100 in exchange for some goods, she could just archive it after receiving the goods. Bob would have a record of such actions, but would have to resort to off-ledger means to get his money back.
@ -52,7 +52,7 @@ You'll now learn a couple of common ways of building issuance and transfer workf
.. _intro propose accept:
Use propose-accept workflows for one-off authorization
Use Propose-accept Workflows for One-off Authorization
------------------------------------------------------
If there is no standing relationship between Alice and Bob, Alice can propose the issuance of an Iou to Bob, giving him the choice to accept. You can do so by introducing a proposal contract ``IouProposal``:
@ -98,7 +98,7 @@ Bob can now transfer his ``Iou``. The transfer workflow can even be used for iss
:start-after: -- IOU_TRANSFER_SCENARIO_BEGIN
:end-before: -- IOU_TRANSFER_SCENARIO_END
Use role contracts for ongoing authorization
Use Role Contracts for Ongoing Authorization
--------------------------------------------
Many actions, like the issuance of assets or their transfer, can be pre-agreed. You can represent this succinctly in Daml through relationship or role contracts.
@ -128,7 +128,7 @@ Here it is in action:
:start-after: -- SENDER_SCENARIO_BEGIN
:end-before: -- SENDER_SCENARIO_END
Daml's authorization model
Daml's Authorization Model
--------------------------
Hopefully, the above will have given you a good intuition for how authority is passed around in Daml. In this section you'll learn about the formal authorization model to allow you to reason through your contract models. This will allow you to construct them in such a way that you don't run into authorization errors at runtime, or, worse still, allow malicious transactions.
@ -150,7 +150,7 @@ The authorizers of transactions are:
- The root transaction of a commit is authorized by the submitting party.
- The consequences of an exercise action are authorized by the actors of that action plus the signatories of the contract on which the action was taken.
An authorization example
An Authorization Example
~~~~~~~~~~~~~~~~~~~~~~~~
Consider the transaction from the script above where Bob sends an ``Iou`` to Charlie using a ``Send_Iou`` contract.
@ -210,7 +210,7 @@ The consequences of ``TryB`` are authorized by both Alice and Bob, but the actio
Therefore, the consequences of ``TryA`` are only authorized by Alice. Bob's authority is now missing to create the flipped ``NonTransitive`` so the transaction fails.
Next up
Next Up
-------
In :doc:`7_Composing` you will put everything you have learned together to build a simple asset holding and trading model akin to that in the :doc:`/app-dev/bindings-java/quickstart`. In that context you'll learn a bit more about the ``Update`` action and how to use it to compose transactions, as well as about privacy on Daml ledgers.

18
docs/source/daml/intro/7_Composing.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
7 Composing choices
===================
Composing Choices
=================
It's time to put everything you've learnt so far together into a complete and secure Daml model for asset issuance, management, transfer, and trading. This application will have capabilities similar to the one in :doc:`/app-dev/bindings-java/quickstart`. In the process you will learn about a few more concepts:
@ -18,7 +18,7 @@ The model in this section is not a single Daml file, but a Daml project consisti
Remember that you can load all the code for this section into a folder called ``intro7`` by running ``daml new intro7 --template daml-intro-7``
Daml projects
Daml Projects
-------------
Daml is organized in projects, packages and modules. A Daml project is specified using a single ``daml.yaml`` file, and compiles into a package in Daml's intermediate language, or bytecode equivalent, Daml-LF. Each Daml file within a project becomes a Daml module, which is a bit like a namespace. Each Daml project has a source root specified in the ``source`` parameter in the project's ``daml.yaml`` file. The package will include all modules specified in ``*.daml`` files beneath that source directory.
@ -34,7 +34,7 @@ You can generally set ``name`` and ``version`` freely to describe your project.
You compile a Daml project by running ``daml build`` from the project root directory. This creates a ``dar`` file in ``.daml/dist/dist/${project_name}-${project_version}.dar``. A ``dar`` file is Daml's equivalent of a ``JAR`` file in Java: it's the artifact that gets deployed to a ledger to load the package and its dependencies. ``dar`` files are fully self-contained in that they contain all dependencies of the main package. More on all of this in :doc:`9_Dependencies`.
Project structure
Project Structure
-----------------
This project contains an asset holding model for transferable, fungible assets and a separate trade workflow. The templates are structured in three modules: ``Intro.Asset``, ``Intro.Asset.Role``, and ``Intro.Asset.Trade``.
@ -89,7 +89,7 @@ corresponding functionality:
import Daml.Script
Project overview
Project Overview
----------------
The project both changes and adds to the ``Iou`` model presented in :doc:`6_Parties`:
@ -100,8 +100,8 @@ The project both changes and adds to the ``Iou`` model presented in :doc:`6_Part
With the ``Iou`` model, an ``issuer`` could end up owing cash to anyone as transfers were authorized by just ``owner`` and ``newOwner``. In this project, only parties having an ``AssetHolder`` contract can end up owning assets. This allows the ``issuer`` to determine which parties may own their assets.
- The ``Trade`` template adds a swap of two assets to the model.
Composed choices and scripts
------------------------------
Composed Choices and Scripts
----------------------------
This project showcases how you can put the ``Update`` and ``Script`` actions you learnt about in :doc:`6_Parties` to good use. For example, the ``Merge`` and ``Split`` choices each perform several actions in their consequences.
@ -212,7 +212,7 @@ Just writing ``(alice, bob, bank, aha, ahb) <- setupRoles`` would also be legal,
.. _execution_model:
Daml's execution model
Daml's Execution Model
----------------------
Daml's execution model is fairly easy to understand, but has some important consequences. You can imagine the life of a transaction as follows:
@ -306,7 +306,7 @@ Note that Principle 2 of the privacy model means that sometimes parties see cont
This is because the ``create`` action of these contracts are in the transitive consequences of the ``Trade_Settle`` action both of them have a stake in. This kind of disclosure is often called "divulgence" and needs to be considered when designing Daml models for privacy sensitive applications.
Next up
Next Up
-------
In :doc:`8_Exceptions`, we will learn about how errors in your model can be handled in Daml.

6
docs/source/daml/intro/8_Exceptions.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
8 Exception Handling
====================
Exception Handling
==================
The default behavior in Daml is to abort the transaction on any error
and roll back all changes that have happened until then. However, this
@ -154,7 +154,7 @@ For more information on exceptions, take a look at the
:ref:`language reference <exceptions>`.
Next up
Next Up
-------
We have now seen how to develop safe models and how we can handle

6
docs/source/daml/intro/9_Dependencies.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
9 Working with Dependencies
===========================
Work with Dependencies
======================
The application from Chapter 7 is a complete and secure model for atomic swaps of assets, but there is plenty of room for improvement. However, one can't implement all feature before going live with an application so it's important to understand way to change already running code. There are fundamentally two types of change one may want to make:
@ -85,7 +85,7 @@ For example, in all our projects in this intro, including this chapter, our scri
Similarly, we included ``Trade`` in the same project as ``Asset`` in chapter 7, even though ``Trade`` is a pure extension to the core ``Asset`` model. If we expect ``Trade`` to need more frequent changes, it may be a good idea to split it out into a separate project from the start.
Next up
Next Up
-------
The ``MultiTrade`` model has more complex control flow and data handling than previous models. In :doc:`10_Functional101` you'll learn how to write more advanced logic: control flow, folds, common typeclasses, custom functions, and the Standard Library. We'll be using the same projects so don't delete your chapter 7 and 8 folders just yet.

2
docs/source/daml/patterns.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Good design patterns
Good Design Patterns
####################
Patterns have been useful in the programming world, as both a source of design inspiration, and a document of good design practices. This document is a catalog of Daml patterns intended to provide the same facility in the Daml application world.

4
docs/source/daml/patterns/authorization.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Authorization
#############
The Authorization Pattern
#########################
The Authorization pattern demonstrates how to make sure a controlling party is authorized before they take certain actions.

4
docs/source/daml/patterns/delegation.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Delegation
##########
The Delegation Pattern
######################
The Delegation pattern gives one party the right to exercise a choice on behalf of another party. The agent can control a contract on the ledger without the principal explicitly committing the action.

4
docs/source/daml/patterns/initaccept.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Initiate and Accept
###################
The Initiate and Accept Pattern
###############################
The Initiate and Accept pattern demonstrates how to start a bilateral workflow. One party initiates by creating a proposal or an invite contract. This gives another party the chance to accept, reject or renegotiate.

4
docs/source/daml/patterns/legends.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Diagram legends
################
Diagram Legends
###############
.. figure:: images/legends.png

4
docs/source/daml/patterns/locking.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Locking
#######
The Locking Pattern
###################
The Locking pattern exhibits how to achieve locking safely and efficiently in Daml. Only the specified locking party can lock the asset through an active and authorized action. When a contract is locked, some or all choices specified on that contract may not be exercised.

8
docs/source/daml/patterns/locking/locking-by-archiving.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Locking by archiving
####################
Lock by Archiving
#################
**Pre-condition**: there exists a contract that needs to be locked and unlocked. In this section, *Coin* is used as the original contract to demonstrate locking and unlocking.
@ -25,7 +25,7 @@ Archiving is a straightforward choice for locking because once a contract is arc
.. _lockingbyConsumingChoice:
Consuming choice
Consuming Choice
****************
The steps below show how to use a consuming choice in the original contract to achieve locking:
@ -63,7 +63,7 @@ The steps below show how to use a consuming choice in the original contract to a
Locking By Consuming Choice Diagram
Archiving contract
Archiving Contract
******************
In the event that changing the original contract is not desirable and assuming the original contract already has an *Archive* choice, you can introduce another contract, *CoinCommitment*, to archive *Coin* and create *LockedCoin*.

4
docs/source/daml/patterns/locking/locking-by-safekeeping.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Locking by safekeeping
######################
Lock by Safekeeping
###################
Safekeeping is a realistic way to model locking as it is a common practice in many industries. For example, during a real estate transaction, purchase funds are transferred to the sellers lawyer’s escrow account after the contract is signed and before closing. To understand its implementation, review the original *Coin* template first.

4
docs/source/daml/patterns/locking/locking-by-state.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Locking by state
################
Lock by State
#############
The original *Coin* template is shown below. This is the basis on which to implement locking by state

4
docs/source/daml/patterns/multiparty-agreement.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Multiple party agreement
########################
The Multiple Party Agreement Pattern
####################################
The Multiple Party Agreement pattern uses a Pending contract as a wrapper for the Agreement contract. Any one of the signatory parties can kick off the workflow by creating a Pending contract on the ledger, filling in themselves in all the signatory fields. The Agreement contract is not created on the ledger until all parties have agreed to the Pending contract, and replaced the initiator's signature with their own.

20
docs/source/daml/reference/choices.rst
View File

@ -1,12 +1,12 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: choices
Reference: Choices
##################
This page gives reference information on choices. For information on the high-level structure of a choice, see :doc:`structure`.
``choice`` first or ``controller`` first
``choice`` First or ``controller`` First
****************************************
There are two ways you can start a choice:
@ -34,7 +34,7 @@ A secondary difference is that starting with ``choice`` allows *choice observers
.. _daml-ref-choice-name:
Choice name
Choice Name
***********
.. literalinclude:: ../code-snippets/Reference.daml
@ -79,12 +79,12 @@ Controllers
.. _daml-ref-consumability:
Contract consumption
Contract Consumption
====================
If no qualifier is present, choices are *consuming*: the contract is archived before the evaluation of the choice body and both the controllers and all contract stakeholders see all consequences of the action.
Preconsuming choices
Preconsuming Choices
********************
.. literalinclude:: ../code-snippets/Reference.daml
@ -106,7 +106,7 @@ Preconsuming choices
- Only the controllers and signatories of the contract see all consequences of the action. Other stakeholders merely see an archive action.
- Can be thought as a non-consuming choice that implicitly archives the contract before anything else happens
Postconsuming choices
Postconsuming Choices
*********************
.. literalinclude:: ../code-snippets/Reference.daml
@ -127,7 +127,7 @@ Postconsuming choices
- Only the controllers and signatories of the contract see all consequences of the action. Other stakeholders merely see an archive action.
- Can be thought as a non-consuming choice that implicitly archives the contract after the choice has been exercised
Non-consuming choices
Non-consuming Choices
*********************
.. literalinclude:: ../code-snippets/Reference.daml
@ -149,7 +149,7 @@ Non-consuming choices
.. _daml-ref-return-type:
Return type
Return Type
===========
- Return type is written immediately after choice name.
@ -158,7 +158,7 @@ Return type
.. _daml-ref-choice-arguments:
Choice arguments
Choice Arguments
****************
.. literalinclude:: ../code-snippets/Reference.daml
@ -173,7 +173,7 @@ Choice arguments
.. _daml-ref-choice-body:
Choice body
Choice Body
***********
- Introduced with ``do``

10
docs/source/daml/reference/contract-keys.rst
View File

@ -3,7 +3,7 @@
.. _contractkeys:
Reference: Contract keys
Reference: Contract Keys
########################
Contract keys are an optional addition to templates. They let you specify a way of uniquely identifying contracts, using the parameters to the template - similar to a primary key for a database.
@ -17,15 +17,15 @@ Here's an example of setting up a contract key for a bank account, to act as a b
:start-after: -- start contract key setup snippet
:end-before: -- end contract key setup snippet
What can be a contract key
What Can Be a Contract Key
**************************
The key can be an arbitrary serializable expression that does **not** contain contract IDs. However, it **must** include every party that you want to use as a ``maintainer`` (see `Specifying maintainers`_ below).
The key can be an arbitrary serializable expression that does **not** contain contract IDs. However, it **must** include every party that you want to use as a ``maintainer`` (see `Specify Maintainers`_ below).
It's best to use simple types for your keys like ``Text`` or ``Int``, rather than a list or more complex type.
Specifying maintainers
**********************
Specify Maintainers
*******************
If you specify a contract key for a template, you must also specify a ``maintainer`` or maintainers, in a similar way to specifying signatories or observers. The maintainers "own" the key in the same way the signatories "own" a contract. Just like signatories of contracts prevent double spends or use of false contract data, maintainers of keys prevent double allocation or incorrect lookups. Since the key is part of the contract, the maintainers **must** be signatories of the contract. However, maintainers are computed from the ``key`` instead of the template arguments. In the example above, the ``bank`` is ultimately the maintainer of the key.

36
docs/source/daml/reference/data-types.rst
View File

@ -1,14 +1,14 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: data types
Reference: Data Types
#####################
This page gives reference information on Daml's data types.
.. _daml-ref-built-in-types:
Built-in types
Built-in Types
**************
Table of built-in primitive types
@ -64,7 +64,7 @@ Table of built-in primitive types
- ``RelTime`` values have microsecond precision with allowed range from `-9,223,372,036,854,775,808ms` to `9,223,372,036,854,775,807ms`
There are no literals for ``RelTime``. Instead they are created using one of ``days``, ``hours``, ``minutes``, ``seconds``, ``miliseconds`` and ``microseconds`` (to get these functions, import ``DA.Time``).
Escaping characters
Escaping Characters
===================
``Text`` literals support backslash escapes to include their delimiter (``\"``) and a backslash itself (``\\``).
@ -87,8 +87,8 @@ list) and ``::`` (which is an operator that appends an element to the front of a
:start-after: -- BEGIN_LISTS_EXAMPLE
:end-before: -- END_LISTS_EXAMPLE
Summing a list
==============
Sum a List
==========
To sum a list, use a *fold* (because there are no loops in Daml). See :ref:`daml-ref-folding` for details.
@ -96,7 +96,7 @@ To sum a list, use a *fold* (because there are no loops in Daml). See :ref:`daml
.. _daml-ref-record-types:
Records and record types
Records and Record Types
************************
You declare a new record type using the ``data`` and ``with`` keyword:
@ -146,7 +146,7 @@ For example:
.. _daml-ref-data-constructors:
Data constructors
Data Constructors
=================
You can use ``data`` keyword to define a new data type, for example ``data Floor a = Floor a`` for some type ``a``.
@ -162,8 +162,8 @@ An example of a data constructor with zero arguments is ``data Empty = Empty {}`
In ``data Confusing = Int``, the ``Int`` is a data constructor with no arguments. It has nothing to do with the built-in ``Int`` type.
Accessing record fields
=======================
Access Record Fields
====================
To access the fields of a record type, use dot notation. For example:
@ -175,8 +175,8 @@ To access the fields of a record type, use dot notation. For example:
-- Access the value of the field `second`
val.second
Updating record fields
======================
Update Record Fields
====================
You can also use the ``with`` keyword to create a new record on the basis of an existing replacing select fields.
@ -213,7 +213,7 @@ If you have a variable with the same name as the label, Daml lets you use this w
.. _daml-ref-parameterized-types:
Parameterized data types
Parameterized Data Types
========================
Daml supports parameterized data types.
@ -230,7 +230,7 @@ An example of a type that can be constructed with ``Coordinate`` is ``Coordinate
.. _daml-ref-type-synonyms:
Type synonyms
Type Synonyms
*************
To declare a synonym for a type, use the ``type`` keyword.
@ -245,19 +245,19 @@ This makes ``IntegerTuple`` and ``(Int, Int)`` synonyms: they have the same typ
You can use the ``type`` keyword for any type, including :ref:`daml-ref-built-in-types`.
Function types
Function Types
==============
A function's type includes its parameter and result types. A function ``foo`` with two parameters has type ``ParamType1 -> ParamType2 -> ReturnType``.
Note that this can be treated as any other type. You could for instance give it a synonym using ``type FooType = ParamType1 -> ParamType2 -> ReturnType``.
Algebraic data types
Algebraic Data Types
********************
An algebraic data type is a composite type: a type formed by a combination of other types. The enumeration data type is an example. This section introduces more powerful algebraic data types.
Product types
Product Types
=============
The following data constructor is not valid in Daml: ``data AlternativeCoordinate a b = AlternativeCoordinate a b``. This is because data constructors can only have one argument.
@ -271,7 +271,7 @@ A way of thinking about this is that the ``Coordinate Int Int`` type has a first
.. _daml-ref-sum-types:
Sum types
Sum Types
=========
Sum types capture the notion of being of one kind or another.
@ -289,7 +289,7 @@ the :doc:`Daml standard library </daml/stdlib/index>`.
The ``Some`` data constructor takes one argument, and it expects a value of type ``a`` as a parameter.
Pattern matching
Pattern Matching
================
You can match a value to a specific pattern using the ``case`` keyword.

10
docs/source/daml/reference/exceptions.rst
View File

@ -34,7 +34,7 @@ Note that other errors cannot be handled via exceptions, e.g., an
exercise on an inactive contract will still result in a transaction
abort.
User-Defined Exceptions
User-defined Exceptions
.......................
Users can define their own exception types which can be thrown and
@ -50,8 +50,8 @@ In addition to the record fields, exceptions also need to define a
:start-after: -- BEGIN_EXCEPTION
:end-before: -- END_EXCEPTION
Throwing Exceptions
...................
Throw Exceptions
................
There are two ways to throw exceptions:
@ -64,8 +64,8 @@ If both are an option, it is generally preferable to use ``throw``
since it is easier to reason about when exactly the exception will get
thrown.
Catching Exceptions
...................
Catch Exceptions
................
Exceptions are caught in try-catch blocks similar to those found in
languages like Java. The ``try`` block defines the scope within which

8
docs/source/daml/reference/expressions.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: expressions
Reference: Expressions
######################
This page gives reference information for Daml expressions that are not :doc:`updates <updates>`.
@ -45,7 +45,7 @@ Here you see:
This means it takes two Decimals and returns another Decimal.
- the definition ``= 2.0 * pi * r * h`` (which uses the previously defined ``pi``)
Arithmetic operators
Arithmetic Operators
********************
.. list-table::
@ -76,7 +76,7 @@ The result of the modulo operation has the same sign as the dividend:
To write infix expressions in prefix form, wrap the operators in parentheses. For example, ``(+) 1 2`` is another way of writing ``1 + 2``.
Comparison operators
Comparison Operators
********************
.. list-table::
@ -90,7 +90,7 @@ Comparison operators
* - ``==``, ``/=``
- ``Bool``, ``Text``, ``Int``, ``Decimal``, ``Party``, ``Time``, and :ref:`identifiers of contracts <daml-ref_contract-identifiers>` stemming from the same contract template
Logical operators
Logical Operators
*****************
The logical operators in Daml are:

6
docs/source/daml/reference/file-structure.rst
View File

@ -1,12 +1,12 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: Daml file structure
Reference: Daml File Structure
##############################
This page gives reference information on the structure of Daml files outside of :doc:`templates <templates>`.
File structure
File Structure
**************
- This file's module name (``module NameOfThisFile where``).
@ -41,7 +41,7 @@ Use ``--`` for a single line comment. Use ``{-`` and ``-}`` for a comment exten
.. _daml-ref_contract-identifiers:
Contract identifiers
Contract Identifiers
********************
When an instance of a template (that is, a contract) is added to the ledger, it's assigned a unique identifier, of type ``ContractId <name of template>``.

10
docs/source/daml/reference/functions.rst
View File

@ -1,14 +1,14 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: functions
Reference: Functions
####################
This page gives reference information on functions in Daml.
Daml is a functional language. It lets you apply functions partially and also have functions that take other functions as arguments. This page discusses these *higher-order functions*.
Defining functions
Defining Functions
******************
In :doc:`expressions`, the ``tubeSurfaceArea`` function was defined as:
@ -23,7 +23,7 @@ You can define this function equivalently using lambdas, involving ``\``, a sequ
:language: daml
:lines: 13-14
Partial application
Partial Application
*******************
The type of the ``tubeSurfaceArea`` function described previously, is ``Decimal -> Decimal -> Decimal``. An equivalent, but more instructive, way to read its type is: ``Decimal -> (Decimal -> Decimal)``: saying that ``tubeSurfaceArea`` is a function that takes *one* argument and returns another function.
@ -46,7 +46,7 @@ You could also define equivalent lambda functions:
:language: daml
:lines: 20-22
Functions are values
Functions are Values
********************
The function type can be explicitly added to the ``tubeSurfaceArea`` function (when it is written with the lambda notation):
@ -69,7 +69,7 @@ The :ref:`daml-ref-folding` section looks into two useful built-in functions, ``
.. note:: Daml does not allow functions as parameters of contract templates and contract choices. However, a follow up of a choice can use built-in functions, defined at the top level or in the contract template body.
Generic functions
Generic Functions
*****************
A function is *parametrically polymorphic* if it behaves uniformly for all types, in at least one of its type parameters. For example, you can define function composition as follows:

4
docs/source/daml/reference/index.rst
View File

@ -1,8 +1,8 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Language reference docs
#######################
Language Reference
##################
This section contains a reference to writing templates for Daml contracts. It includes:

22
docs/source/daml/reference/interfaces.rst
View File

@ -15,12 +15,12 @@ that a template must implement. This allows decoupling such behavior from its
implementation, so other developers can write applications in terms of the
interface instead of the concrete template.
Interface declaration
Interface Declaration
*********************
An interface declaration is somewhat similar to a template declaration.
Interface name
Interface Name
--------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -32,7 +32,7 @@ Interface name
- It's preceded by the keyword ``interface`` and followed by the keyword ``where``.
- It must begin with a capital letter, like any other type name.
Interface methods
Interface Methods
-----------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -53,7 +53,7 @@ Interface methods
- Methods are also in scope in interface choices
(see :ref:`interface-choices` below).
Interface precondition
Interface Precondition
----------------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -73,7 +73,7 @@ Interface precondition
.. _interface-choices:
Interface choices
Interface Choices
-----------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -94,7 +94,7 @@ Interface choices
- See :doc:`choices` for full reference information, but note that
controller-first syntax is not supported for interface choices.
Empty interfaces
Empty Interfaces
----------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -106,7 +106,7 @@ Empty interfaces
methods, precondition or choices. In such a case, the ``where`` keyword
can be dropped.
Required interfaces
Required Interfaces
-------------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -127,7 +127,7 @@ Required interfaces
:start-after: -- EMPTY_INTERFACE_REQUIRES_BEGIN
:end-before: -- EMPTY_INTERFACE_REQUIRES_END
Interface implementation
Interface Implementation
************************
For context, a simple template definition:
@ -137,7 +137,7 @@ For context, a simple template definition:
:start-after: -- TEMPLATE_HEADER_BEGIN
:end-before: -- TEMPLATE_HEADER_END
Implements clause
Implements Clause
-----------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -154,7 +154,7 @@ Implements clause
- Methods can be defined using the same syntax as for top level functions,
including pattern matches and guards (e.g. ``method3``).
Empty implements clause
Empty Implements Clause
-----------------------
.. literalinclude:: ../code-snippets-dev/Interfaces.daml
@ -165,7 +165,7 @@ Empty implements clause
- If the interface being implemented has no methods, the ``where`` keyword
can be dropped.
Interface functions
Interface Functions
*******************
.. list-table::

22
docs/source/daml/reference/packages.rst
View File

@ -2,12 +2,12 @@
.. SPDX-License-Identifier: Apache-2.0
Reference: Daml packages
Reference: Daml Packages
########################
This page gives reference information on Daml package dependencies.
Building Daml archives
Building Daml Archives
**********************
When a Daml project is compiled, the compiler produces a `Daml archive`. These are platform-independent packages of compiled Daml code that can be uploaded to a Daml ledger or imported in other Daml projects.
@ -103,8 +103,8 @@ robust to changes across SDK versions:
Note that ``name`` and ``version`` will be ``null`` for packages in Daml-LF < 1.8.
Importing Daml packages
***********************
Import Daml Packages
********************
There are two ways to import a Daml package in a project: via ``dependencies``, and via ``data-dependencies``. They each have certain advantages and disadvantages. To summarize:
@ -114,8 +114,8 @@ There are two ways to import a Daml package in a project: via ``dependencies``,
The following sections will cover these two approaches in more depth.
Importing a Daml package via dependencies
=========================================
Import a Daml package via Dependencies
======================================
A Daml project can declare a Daml archive as a dependency in the ``dependencies`` field of ``daml.yaml``. This lets you import modules and reuse definitions from another Daml project. The main limitation of this method is that the dependency must be built for the same SDK version as the importing project.
@ -153,8 +153,8 @@ By default, all modules of ``foo`` are made available when importing ``foo`` as
exposed-modules:
- Foo
Importing a Daml archive via data-dependencies
==============================================
Import a Daml Archive via ``data-dependencies``
===============================================
You can import a Daml archive (.dar) or Daml-LF package (.dalf) using ``data-dependencies``. Unlike ``dependencies``, this can be used when the SDK versions do not match.
@ -184,8 +184,8 @@ When importing packages this way, the Daml compiler will try to reconstruct the
Because of their flexibility, data-dependencies are a tool that is recommended for performing Daml model upgrades. See the :ref:`upgrade documentation <upgrade-overview>` for more details.
Referencing Daml packages already on the ledger
===============================================
Reference Daml Packages Already On the Ledger
=============================================
Daml packages that have been uploaded to a ledger can be imported as data dependencies, given you
have the necessary permissions to download these packages. To import such a package, add the package
@ -219,7 +219,7 @@ package ID. To recreate or update your ``daml.lock`` file, delete it and run ``d
.. _module_collisions:
Handling module name collisions
Handling Module Name Collisions
*******************************
Sometimes you will have multiple packages with the same module name. In that case, a simple import will fail, since the compiler doesn't know which version of the module to load. Fortunately, there are a few tools you can use to approach this problem.

8
docs/source/daml/reference/structure.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Overview: template structure
Overview: Template Structure
############################
This page covers what a template looks like: what parts of a template there are, and where they go.
@ -10,7 +10,7 @@ For the structure of a Daml file *outside* a template, see :doc:`file-structure`
.. _daml-ref-template-structure:
Template outline structure
Template Outline Structure
**************************
Here’s the structure of a Daml template:
@ -76,7 +76,7 @@ template body
.. _daml-ref-choice-structure:
Choice structure
Choice Structure
****************
Here's the structure of a choice inside a template. There are two ways of specifying a choice:
@ -126,7 +126,7 @@ Here's the structure of a choice inside a template. There are two ways of specif
.. _daml-ref-choice-body-structure:
Choice body structure
Choice Body Structure
*********************
A choice body contains ``Update`` expressions, wrapped in a :ref:`do <daml-ref-do>` block.

10
docs/source/daml/reference/templates.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: templates
Reference: Templates
####################
This page gives reference information on templates:
@ -10,7 +10,7 @@ For the structure of a template, see :doc:`structure`.
.. _daml-ref-template-name:
Template name
Template Name
*************
.. literalinclude:: ../code-snippets/Reference.daml
@ -24,7 +24,7 @@ Template name
.. _daml-ref-template-parameters:
Template parameters
Template Parameters
*******************
.. literalinclude:: ../code-snippets/Reference.daml
@ -55,7 +55,7 @@ Template-local Definitions
.. _daml-ref-signatories:
Signatory parties
Signatory Parties
*****************
.. literalinclude:: ../code-snippets/Reference.daml
@ -140,7 +140,7 @@ Preconditions
.. _daml-ref-maintainers:
Contract keys and maintainers
Contract Keys and Maintainers
*****************************
.. literalinclude:: ../code-snippets/Reference.daml

4
docs/source/daml/reference/updates.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: updates
Reference: Updates
##################
This page gives reference information on Updates. For the structure around them, see :doc:`structure`.
@ -16,7 +16,7 @@ Background
.. _daml-ref-binding-variables:
Binding variables
Binding Variables
*****************
.. code-block:: daml

24
docs/source/daml/reference/working-with.rst
View File

@ -1,13 +1,13 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Reference: built-in functions
Reference: Built-in Functions
#############################
This page gives reference information on functions for.
This page gives reference information on built-in functions for working with a variety of common concepts.
Working with time
*****************
Work with Time
**************
Daml has these built-in functions for working with time:
@ -17,8 +17,8 @@ Daml has these built-in functions for working with time:
- ``days``, ``hours``, ``minutes``, ``seconds``: constructs a ``RelTime`` of the specified length.
- ``pass``: (in :ref:`Daml Script tests <testing-using-script>` only) use ``pass : RelTime -> Script Time`` to advance the ledger time by the argument amount. Returns the new time.
Working with numbers
********************
Work with Numbers
*****************
Daml has these built-in functions for working with numbers:
@ -43,8 +43,8 @@ Daml has these built-in functions for working with numbers:
The set of numbers expressed by ``Decimal`` is not closed under division as the result may require more than 10 decimal places to represent. For example, ``1.0 / 3.0 == 0.3333...`` is a rational number, but not a ``Decimal``.
Working with text
*****************
Work with Text
**************
Daml has these built-in functions for working with text:
@ -73,8 +73,8 @@ To escape text in Daml strings, use ``\``:
| an example) | - Hexadecimal code: ``\x21``|
+-------------------+-----------------------------+
Working with lists
******************
Work with Lists
***************
Daml has these built-in functions for working with lists:
@ -82,8 +82,8 @@ Daml has these built-in functions for working with lists:
.. _daml-ref-folding:
Folding
=======
Fold
====
A *fold* takes:

26
docs/source/daml/troubleshooting.rst
View File

@ -7,7 +7,7 @@ Troubleshooting
.. _faqs-multi-obligables:
Error: "<X> is not authorized to commit an update"
***************************************************
**************************************************
This error occurs when there are multiple obligables on a contract.
@ -17,7 +17,7 @@ To solve this, make sure each party is entering into the contract freely by exer
.. _faqs-serial-arg:
Error "Argument is not of serializable type"
Error: "Argument is not of serializable type"
*********************************************
This error occurs when you're using a function as a parameter to a template. For example, here is a contract that creates a ``Payout`` controller by a receiver's supervisor:
@ -33,12 +33,12 @@ Hovering over the compilation error displays:
[Type checker] Argument expands to non-serializable type Party -> Party.
Modeling questions
Modeling Questions
******************
.. _faqs-proposal:
How to model an agreement with another party
How To Model an Agreement With Another Party
============================================
To enter into an agreement, create a contract from a template that has explicit ``signatory`` and ``agreement`` statements.
@ -49,14 +49,14 @@ Because of the rules that Daml enforces, it is not possible for a single party t
.. _faqs-rights:
How to model rights
How To Model Rights
===================
Use a contract choice to model a right. A party exercises that right by exercising the choice.
.. _faqs-voiding-contract:
How to void a contract
How To Void a Contract
======================
To allow voiding a contract, provide a choice that does not create any new contracts. Daml contracts are archived (but not deleted) when a consuming choice is made - so exercising the choice effectively voids the contract.
@ -65,7 +65,7 @@ However, you should bear in mind who is allowed to void a contract, especially w
.. _faqs-party-delegation:
How to represent off-ledger parties
How To Represent Off-ledger Parties
===================================
You'd need to do this if you can't set up all parties as ledger participants, because the Daml ``Party`` type gets associated with a cryptographic key and can so only be used with parties that have been set up accordingly.
@ -76,7 +76,7 @@ This isn't very private, so you could use a numeric ID/an accountId to identify
.. _faqs-timed-choice:
How to limit a choice by time
How To Limit a Choice by Time
=============================
Some rights have a time limit: either a time by which it must be exercised or a time before which it cannot be exercised.
@ -85,7 +85,7 @@ You can use ``getTime`` to get the current time, and compare your desired time t
.. _faqs-mandatory-action:
How to model a mandatory action
How To Model a Mandatory Action
===============================
If you want to ensure that a party takes some action within a given time period. Might want to incur a penalty if they don't - because that would breach the contract.
@ -96,7 +96,7 @@ However, note that the penalty action can only ever create another contract on t
.. _faqs-optional:
When to use Optional
When to Use Optional
====================
The ``Optional`` type, from the standard library, to indicate that a value is optional, i.e, that in some cases it may be missing.
@ -153,12 +153,12 @@ If ``optionalValue`` is ``Some 5``, the value of ``t`` would be ``"The number is
There are many other functions in "Optional.daml" that let you perform familiar functional operations on structures that contain ``Optional`` values – such as ``map``, ``filter``, etc. on ``Lists`` of ``Optional`` values.
Testing questions
Testing Questions
*****************
.. _faqs-test-visibility:
How to test that a contract is visible to a party
How To Test That a Contract Is Visible to a Party
=================================================
Use ``queryContractId``: its first argument is a party, and the second is a ``ContractId``. If the contract corresponding to that ``ContractId`` exists and is visible to the party, the result will be wrapped in ``Some``, otherwise the result will be ``None``.
@ -185,7 +185,7 @@ Now that the contract is bound to a variable, we can check whether it has some e
.. _faqs-must-fail:
How to test that an update action cannot be committed
How To Test That an Update Action Cannot Be Committed
======================================================
Use the ``submitMustFail`` function. This is similar in form to the ``submit`` function, but is an assertion that an update will fail if attempted by some Party.

12
docs/source/deploy/generic_ledger.rst
View File

@ -3,8 +3,8 @@
.. _deploy-generic-ledger:
Deploying to a generic Daml ledger
==================================
Deploy to a Generic Daml Ledger
===============================
Daml ledgers expose a unified administration API. This means that deploying to a Daml ledger is no
different from deploying to your local sandbox.
@ -60,8 +60,8 @@ ledger --help`` to get a list of available ledger commands:
fetch-dar Fetch DAR from ledger into file
metering-report Report on Ledger Use
Connecting via TLS
------------------
Connect via TLS
---------------
To connect to the ledger via TLS, pass ``--tls`` to the
various commands. If your ledger supports or requires mutual
@ -72,8 +72,8 @@ certificate by passing ``--cacrt server.crt``. If ``--pem``, ``--crt``
or ``--cacrt`` are specified TLS is enabled automatically so ``--tls``
is redundant.
Configuring Request Timeouts
----------------------------
Configure Request Timeouts
--------------------------
You can configure the timeout used on API requests by passing
``--timeout=N`` to the various ``daml ledger`` commands and ``daml

2
docs/source/deploying.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Overview of Daml ledgers
Overview of Daml Ledgers
========================
The following table lists commercially supported Daml ledgers and environments that are available

4
docs/source/getting-started/first-feature.rst
View File

@ -168,8 +168,8 @@ Following the formatting of the previous panels, we include the new messaging co
That is all for the implementation!
Let's give the new functionality a spin.
Running the Updated UI
======================
Run the Updated UI
==================
If you have the frontend UI up and running you're all set. If you don't have the UI running, open a new terminal window and navigate to the ``create-daml-app/ui`` folder, then run the ``npm start`` command to start the UI.

4
docs/source/getting-started/index.rst
View File

@ -37,8 +37,8 @@ You will also need some common software tools to build and interact with the tem
- A terminal application for command line interaction.
Running the App
***************
Run the App
***********
To get the app up and running:

20
docs/source/getting-started/installation.rst
View File

@ -4,8 +4,8 @@
Installing the SDK
##################
1. Installing the Dependencies
******************************
Install the Dependencies
************************
The Daml SDK currently runs on Windows, macOS and Linux.
@ -16,8 +16,8 @@ You need to install:
As part of the installation process you may need to set up the ``JAVA_HOME`` variable. You can find instructions for this process on :doc:`Windows,macOS, and Linux here <path-variables>`.
2. Choosing Daml Enterprise or Daml Open Source
***********************************************
Choose Daml Enterprise or Daml Open Source
******************************************
Daml comes in two variants: Daml Enterprise or Daml Open Source. Both include the best in class SDK, Canton and all of the components that you need to write and deploy multi-party
applications in production, but they differ in terms of enterprise and non-functional capabilities:
@ -71,8 +71,8 @@ applications in production, but they differ in terms of enterprise and non-funct
- No
3. Installing Daml Open Source SDK
**********************************
Install Daml Open Source SDK
****************************
Windows 10
==========
@ -98,8 +98,8 @@ If the ``daml`` command is not available in your terminal after logging out and
.. _installing_daml_enterprise:
Installing Daml Enterprise
**************************
Install Daml Enterprise
***********************
If you have a license for Daml Enterprise, you
can install it as follows:
@ -126,8 +126,8 @@ this entry to ``daml-config.yaml``. To overwrite a previously
installed version with the corresponding Daml Enterprise version, use
``daml install --force VERSION``.
Downloading Manually
********************
Download Manually
*****************
If you want to verify the SDK download for security purposes before installing, you can look at :doc:`our detailed instructions for manual download and installation <manual-download>`.

20
docs/source/getting-started/path-variables.rst
View File

@ -8,8 +8,8 @@ Windows
*******
To set up ``JAVA_HOME`` and ``PATH`` variables on Windows:
Setting the JAVA_HOME Variable
==============================
Set the JAVA_HOME Variable
==========================
1. Search for Advanced System Settings (open ``Search``, type "advanced system settings" and hit ``Enter``).
2. Find the ``Advanced`` tab and click ``Environment Variables``.
@ -18,8 +18,8 @@ Setting the JAVA_HOME Variable
5. Click OK in the ``Variable name`` window.
6. Click OK in the tab and click Apply to apply the changes.
Setting the PATH Variable
=========================
Set the PATH Variable
=====================
The ``PATH`` variable is automatically set by the `Windows installer <https://github.com/digital-asset/daml/releases/latest>`_ .
@ -73,24 +73,24 @@ Linux
*****
To set up ``JAVA_HOME`` and ``PATH`` variables on Linux for ``bash``:
Setting the JAVA_HOME Variable
==============================
Set the JAVA_HOME Variable
==========================
Java is typically installed in a folder like ``/usr/lib/jvm/java-version``. Before running the following command
make sure to change the ``java-version`` with the actual folder found on your computer::
echo "export JAVA_HOME=/usr/lib/jvm/java-version" >> ~/.bash_profile
Setting the PATH Variable
=========================
Set the PATH Variable
=====================
The installer will ask to set the ``PATH`` variable for you. If you want to set the ``PATH`` variable
manually instead, run the following command::
echo 'export PATH="$HOME/.daml/bin:$PATH"' >> ~/.bash_profile
Verifying the Changes
=====================
Verify the Changes
==================
In order for the changes to take effect you will need to restart your computer. After the restart, verify that everything was set up correctly using the following steps:

10
docs/source/getting-started/testing.rst
View File

@ -24,8 +24,8 @@ Because these things are easier to describe with concrete examples, this
section will show how to set up end-to-end tests for the application you would
end with at the end of the :doc:`/getting-started/first-feature` section.
Setting up our tests
====================
Set Up the Tests
================
Let's see how to use these tools to write some tests for our social network app.
You can see the full suite in section :ref:`Full Test Suite` at the bottom of
@ -55,8 +55,8 @@ On the other hand the ``afterAll()`` section is used to shut down these processe
This step is important to prevent child processes persisting in the background after our program has finished.
Example: Logging in and out
===========================
Example: Log In and Out
=======================
Now let's get to a test!
The idea is to control the browser in the same way we would expect a user to in each scenario we want to test.
@ -83,7 +83,7 @@ You will likely use ``test``, ``getParty()``, ``newUiPage()`` and ``Browser.clos
In this case we use the ``@daml/ledger`` library to inspect the state of the ledger, but usually we just check the contents of the web page match our expectations.
Accessing UI elements
Accessing UI Elements
=====================
We showed how to write a simple test at a high level, but haven't shown how to make individual actions in the app using Puppeteer.

40
docs/source/json-api/index.rst
View File

@ -36,8 +36,8 @@ We welcome feedback about the JSON API on
search-query-language
production-setup
Running the JSON API
********************
Run the JSON API
****************
Start a Daml Ledger
===================
@ -206,7 +206,7 @@ Replace the version number ``2.0.0`` by the version of the SDK you are
using.
With Query Store
------------------
----------------
In production setups, you should configure the JSON API to use a
PostgreSQL backend as a cache. The in-memory backend will call the
@ -415,7 +415,7 @@ Where:
See the following blog post for more details about error handling best practices: `REST API Error Codes 101 <https://blog.restcase.com/rest-api-error-codes-101/>`_.
Successful response, HTTP status: 200 OK
Successful Response, HTTP Status: 200 OK
========================================
- Content-Type: ``application/json``
@ -428,7 +428,7 @@ Successful response, HTTP status: 200 OK
"result": <JSON object>
}
Successful response with a warning, HTTP status: 200 OK
Successful Response with a Warning, HTTP Status: 200 OK
=======================================================
- Content-Type: ``application/json``
@ -444,7 +444,7 @@ Successful response with a warning, HTTP status: 200 OK
.. _error-format:
Failure, HTTP status: 400 | 401 | 404 | 500
Failure, HTTP Status: 400 | 401 | 404 | 500
===========================================
- Content-Type: ``application/json``
@ -502,7 +502,7 @@ Examples
{"status": 500, "errors": ["Cannot initialize Ledger API"]}
Create a new Contract
Create a New Contract
*********************
To create an ``Iou`` contract from the :doc:`Quickstart guide </app-dev/bindings-java/quickstart>`:
@ -581,8 +581,8 @@ Where:
.. _create-request-with-meta:
Creating a Contract with a Command ID
*************************************
Create a Contract with a Command ID
***********************************
When creating a new contract you may specify an optional ``meta`` field. This allows you to control the ``commandId``, ``actAs``, and ``readAs`` used when submitting a command to the ledger. Each of these ``meta`` fields is optional.
@ -999,7 +999,7 @@ Contract Found HTTP Response
}
Get all Active Contracts
Get All Active Contracts
************************
List all currently active contracts for all known templates.
@ -1020,7 +1020,7 @@ HTTP Response
The response is the same as for the POST method below.
Get all Active Contracts Matching a Given Query
Get All Active Contracts Matching a Given Query
***********************************************
List currently active contracts that match a given query.
@ -1101,7 +1101,7 @@ Where
- ``result`` contains an array of contracts, each contract formatted according to :doc:`lf-value-specification`,
- ``status`` matches the HTTP status code returned in the HTTP header.
Nonempty HTTP Response with Unknown Template IDs Warning
Nonempty HTTP Response With Unknown Template IDs Warning
========================================================
- Content-Type: ``application/json``
@ -1193,7 +1193,7 @@ Where
- ``displayName`` -- optional human readable name associated with the party. Might not be unique,
- ``isLocal`` -- true if party is hosted by the backing participant.
Response with Unknown Parties Warning
Response With Unknown Parties Warning
=====================================
- Content-Type: ``application/json``
@ -1272,8 +1272,8 @@ HTTP Response
}
Creating a New User
********************
Create a New User
*****************
This endpoint exposes the Ledger API's :ref:`CreateUser RPC <com.daml.ledger.api.v1.admin.createuserrequest>`.
@ -1715,7 +1715,7 @@ HTTP Response, status: 200 OK
The content (body) of the HTTP response contains raw DALF package bytes, without any encoding. Note that the package ID specified in the URL is actually the SHA-256 hash of the downloaded DALF package and can be used to validate the integrity of the downloaded content.
HTTP Response with Error, any status different from 200 OK
HTTP Response With Error, Any Status Different from 200 OK
==========================================================
Any status different from ``200 OK`` will be in the format specified below.
@ -1745,7 +1745,7 @@ HTTP Request
The content (body) of the HTTP request contains raw DAR file bytes, without any encoding.
HTTP Response, status: 200 OK
HTTP Response, Status: 200 OK
=============================
- Content-Type: ``application/json``
@ -1758,7 +1758,7 @@ HTTP Response, status: 200 OK
"status": 200
}
HTTP Response with Error
HTTP Response With Error
========================
- Content-Type: ``application/json``
@ -2169,7 +2169,7 @@ The HTTP JSON API provides two healthcheck endpoints for integration
with schedulers like
`Kubernetes <https://kubernetes.io/docs/tasks/configure-pod-container/configure-liveness-readiness-startup-probes/>`_.
Liveness check
Liveness Check
==============
- URL: ``/livez``
@ -2180,7 +2180,7 @@ A status code of ``200`` indicates a successful liveness check.
This is an unauthenticated endpoint intended to be used as a liveness
probe.
Readiness check
Readiness Check
===============
- URL: ``/readyz``

12
docs/source/json-api/production-setup.rst
View File

@ -17,7 +17,7 @@ For this reason for production setups at a minimum we recommend to use a databas
as a query store, this will allow for more efficient caching of the data to improve
query performance. Details for enabling a query store are highlighted below.
Query store
Query Store
***********
.. note:: Daml Open Source only supports PostgreSQL backends for the *HTTP JSON API* server, but Daml Enterprise also supports Oracle backends.
@ -84,7 +84,7 @@ created, it's safe to always use ``start-mode=start-only``.
.. note:: The full list of query store configuration flags supported can be seen by running ``daml json-api --help``.
Data continuity
Data Continuity
---------------
The query store is a cache, which means that it's perfectly fine to drop it as
@ -107,7 +107,7 @@ start the server using either ``start-mode=create-only`` and ``start-mode=start-
or ``start-mode=create-and-start`` as described above, depending on your preferred
production setup.
Security and privacy
Security and Privacy
********************
For an *HTTP JSON API* server, all data is maintained by the operator of the deployment.
@ -247,7 +247,7 @@ The default log encoder used is the plaintext one for traditional logging target
Metrics
*******
Enable and configure reporting
Enable and Configure Reporting
------------------------------
@ -284,7 +284,7 @@ or the two following CLI options (deprecated):
on the ISO 8601 duration format ``PnDTnHnMn.nS`` with days considered to be exactly 24 hours.
The default interval is 10 seconds.
Types of metrics
Types of Metrics
================
This is a list of type of metrics with all data points recorded for each.
@ -314,7 +314,7 @@ A timer records all metrics registered by a meter and by a histogram, where
the histogram records the time necessary to execute a given operation (
in fractional milliseconds).
List of metrics
List of Metrics
===============
The following is a list of selected metrics that can be particularly

14
docs/source/json-api/search-query-language.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Query language
Query Language
##############
The body of ``POST /v1/query`` looks like so:
@ -15,7 +15,7 @@ The body of ``POST /v1/query`` looks like so:
The elements of that query are defined here.
Fallback rule
Fallback Rule
*************
Unless otherwise required by one of the other rules below or to follow,
@ -28,7 +28,7 @@ All types are supported by this simple equality comparison except:
- textmaps
- genmaps
Simple equality
Simple Equality
***************
Match records having at least all the (potentially nested) keys
@ -47,7 +47,7 @@ A JSON object, when considered with a record type, is always interpreted
as a field equality query. Its type context is thus mutually exclusive
with comparison queries.
Comparison query
Comparison Query
****************
Match values on comparison operators for int64, numeric, text, date, and
@ -72,7 +72,7 @@ These operators cannot occur in objects interpreted in a record context,
nor may other keys than these four operators occur where they are legal,
so there is no ambiguity with field equality.
Appendix: Type-aware queries
Appendix: Type-aware Queries
****************************
**This section is non-normative.**
@ -127,10 +127,10 @@ The above "Typecheck failure" happens because there is no LF type to
which both ``"Bob"`` and ``["Bob", "Sue"]`` conform; this would be
caught when interpreting the query, before considering any contracts.
Appendix: Known issues
Appendix: Known Issues
**********************
When using Oracle, queries fail if a token is too large
When Using Oracle, Queries Fail if a Token Is Too Large
=======================================================
This limitation is exclusive to users of the HTTP JSON API using Daml Enterprise support for Oracle. Due to a known limitation in Oracle, the full-test JSON search index on the contract payloads rejects query tokens larger than 256 bytes. This limitations shouldn't impact most workloads, but if this needs to be worked around, the HTTP JSON API server can be started passing the additional ``disableContractPayloadIndexing=true`` (after wiping an existing query store database, if necessary).

20
docs/source/ops/connect/auth0.rst
View File

@ -71,8 +71,8 @@ In order to follow along this guide, you will need:
system. In this guide, we'll use the `create-daml-app` template,
which supports Auth0 out-of-the-box on its UI side.
Generating Party Allocation Credentials
---------------------------------------
Generate Party Allocation Credentials
-------------------------------------
Since Auth0 will be in charge of requesting the allocation of parties, the
first logical step is to make it generate a token that can be used to allocate
@ -375,11 +375,11 @@ Don't forget to click on Deploy to save your changes. This time, as the Action
is already part of a Flow, clicking the Deploy button really deploys the Action
and there is no further action needed.
Running Your App
----------------
Run Your App
------------
Preparing Your Application
**************************
Prepare Your Application
************************
You may have an application already. In that case, use that. For the purposes
of illustration, here we're going to work with a modified version of
@ -594,8 +594,8 @@ our frontend. All we need now is to get a Daml system up and running.
We document two paths forward here: one that relies on the Helm chart included
in Daml Enterprise, and a manual setup using only the Open Source SDK.
Using the Daml Helm Chart
*************************
Use the Daml Helm Chart
***********************
For simplicity, we assume that you have access to a server with a public IP
address that both you and Auth0 can reach. Furthermore, we assume that you have
@ -669,8 +669,8 @@ domain on which your server is exposed. And voilà! Your application is up and
running. You should be able to log in with Auth0, exchange messages, and set up
an auto-reply trigger, all by connecting your browser to ``https://$DOMAIN/``.
Manually Setting Up the Daml Components
***************************************
Set Up the Daml Components Manually
***********************************
For simplicity, we assume that all of the Daml components will run on a single
machine (they can find each other on ``localhost``) and that this machine has

20
docs/source/ops/connect/helm.rst
View File

@ -26,8 +26,8 @@ on, you will need Artifactory credentials. In the rest of this document, we
assume that ``$ARTIFACTORY_USERNAME`` refers to your Artifactory user name,
whereas ``$ARTIFACTORY_PASSWORD`` refers to your Artifactory API key.
Installing the Helm Chart Repository
------------------------------------
Install the Helm Chart Repository
---------------------------------
To let your local Helm installation know about the Daml Helm chart, you
need to add the repository with::
@ -60,8 +60,8 @@ where ``values.yaml`` is a YAML file that includes at least the
``imagePullSecret`` key. See the rest of this page for other options in
``values.yaml``, and the Helm documentation for related Helm usage.
Setting Up the ``imagePullSecret``
----------------------------------
Set Up the ``imagePullSecret``
------------------------------
The Helm chart relies on the production-ready Docker images for individual
components that are part of Daml Enterprise. Specifically, it expects a
@ -216,8 +216,8 @@ See each component's documentation for details on the metrics exposed:
- `Daml driver for PostgreSQL </daml-driver-for-postgresql/#types-of-metrics>`_
- :ref:`JSON API metrics <json-api-metrics>`
Upgrading
---------
Upgrade
-------
.. note::
@ -237,8 +237,8 @@ place.
Assuming you do not change the database coordinates, you should have data
continuity through the upgrade.
Backing Up
----------
Back Up
-------
.. note::
@ -259,8 +259,8 @@ entirely, as the database for the HTTP JSON API Service is an
easy-to-reconstruct cache. This assume that, in this setup, the data store of
the Ledger API server is, itself, properly backed up.
Securing Daml
-------------
Secure Daml
-----------
The Helm chart assumes that the Kubernetes environment itself is trusted, and
as such does not encrypt connections between components. Full TLS encryption

4
docs/source/ops/metering.rst
View File

@ -20,8 +20,8 @@ by the local participant from remote participants are *not* included.
Only events contained in committed transactions are included, a failed transaction has no effect on ledger metering.
Generating a Metering Report
----------------------------
Generate a Metering Report
--------------------------
A metering report is generated using the :doc:`Daml assistant </tools/assistant>` utility.

12
docs/source/ops/pruning.rst
View File

@ -16,7 +16,7 @@ Please refer to the specific Daml driver information for details about its pruni
`EU's GDPR <https://gdpr-info.eu/>`_.
.. [2] Invoking the Pruning Service requires administrative privileges.
Impacts on Daml applications
Impacts on Daml Applications
----------------------------
When supported, pruning can be invoked by an operator with administrative privileges at any time on a healthy Daml participant; furthermore, it doesn't require stopping nor suspending normal operation.
@ -34,7 +34,7 @@ Still, Daml applications may be affected in the following ways:
During command submission, parties can fetch divulged contracts. This is incompatible with the pruning behaviour described above which allows participant operators to reclaim storage space by pruning divulged contracts. Daml code running on pruned participants should therefore never rely on existence of divulged contracts prior to or at the pruning offset. Instead, such applications MUST ensure re-divulgence of the used contracts.
How the Daml Ledger API is affected
How the Daml Ledger API is Affected
-----------------------------------
- Active data streams from the Daml Participant may abort and need to be re-established by the Daml application from a later offset than pruned, even if they are already streaming past it.
@ -45,7 +45,7 @@ Submission validation and Daml Ledger API endpoints that write to the ledger are
Please refer to the :doc:`protobuf documentation of the API </app-dev/grpc/proto-docs>` for details about the ``prune`` operation itself and the behavior of other Daml Ledger API endpoints when pruning is being or has been performed.
Other limitations
Other Limitations
-----------------
- Pruning may be rejected even if the node is running correctly (for example, to preserve non-repudiation properties); in this case, the application might not be able to archive contracts containing PII or pruning of these contracts may not be possible; thus, actually deleting this PII may also be technically unfeasible.
@ -55,7 +55,7 @@ Other limitations
.. [3] This might be improved in future versions.
How Pruning affects Index DB administration
How Pruning Affects Index DB Administration
-------------------------------------------
Pruning deletes data from the participant's database and therefore frees up space within it, which can and will be reused during the continued operation of the Index DB. Whether this freed up space is handed back to the OS depends on the database in use. For example, in PostgreSQL the deleted data frees up space in the table storage itself, but does not shrink the size of the files backing the tables of the IndexDB. Please refer to the PostgreSQL documentation on `VACUUM` and `VACUUM FULL` for more information.
@ -70,8 +70,8 @@ Backing up and vacuuming, in addition to pruning itself, are also long-running a
Professional advice on database administration is strongly recommended that would take into account the DB specifics as well as all of the above aspects.
Determining a suitable pruning offset
-------------------------------------
Determine a Suitable Pruning Offset
-----------------------------------
The :ref:`Transaction Service <transaction-service>` and the :ref:`Active Contract Service <active-contract-service>` provide offsets of the ledger end of the Transactions, and of Active Contracts snapshots respectively. Such offsets can be passed unchanged to `prune` calls, as long as they are lexicographically lower than the current ledger end.

2
docs/source/support/compatibility.rst
View File

@ -33,7 +33,7 @@ Participant Nodes advertise the Ledger API version they support via the :ref:`ve
As a concrete example, Daml for Postgres 1.4.0 has the Participant Node integrated, and exposes Ledger API version 1.4.0 and the Daml for VMware Blockchain 1.0 Participant Nodes expose Ledger API version 1.6.0. So any application that runs on Daml for Postgres 1.4.0 will also run on Daml for VMware Blockchain 1.0.
List of Ledger API Versions supported by Daml
List of Ledger API Versions Supported by Daml
=============================================
The below lists with which Daml version a new Ledger API version was introduced.

2
docs/source/support/component-statuses.rst
View File

@ -32,7 +32,7 @@ Ledger API
.. _runtime-components:
Runtime components
Runtime Components
******************
.. list-table::

2
docs/source/support/overview.rst
View File

@ -31,7 +31,7 @@ Taking the diagram from left to right, the SDK acts on various components of the
Daml Networks
*************
Daml Drivers
Daml drivers
============
At the bottom of every Daml Application is a Daml network, a distributed, or possibly centralized persistence infrastructure together with Daml drivers. Daml drivers enable the persistence infrastructure to act as a consensus, messaging, and in some cases persistence layer for Daml Applications. Most Daml drivers will have a public API, but there are no *uniform* public APIs on Daml drivers. This does not harm application portability since applications only interact with Daml networks through the Participant Node. A good example of a public API of a Daml driver is the deployment interface of `Daml for VMware Blockchain <https://www.digitalasset.com/daml-for-vmware-blockchain>`_. It's a public interface, but specific to the WMware driver.

2
docs/source/support/support.rst
View File

@ -17,7 +17,7 @@ Have questions or feedback? You're in the right place.
When you're in the community Forum or on Stack Overflow, please keep to our `Code of Conduct <https://github.com/digital-asset/daml/blob/main/CODE_OF_CONDUCT.md>`__.
Support expectations
Support Expectations
********************
For Daml Open Source users:

20
docs/source/tools/assistant.rst
View File

@ -31,14 +31,14 @@ Daml Assistant (``daml``)
Note that you need to update your `project config file <#configuration-files>` to use the new version.
Full help for commands
Full Help for Commands
**********************
To see information about any command, run it with ``--help``.
.. _daml-yaml-configuration:
Configuration files
Configuration Files
*******************
The Daml assistant and the SDK are configured using two files:
@ -48,7 +48,7 @@ The Daml assistant and the SDK are configured using two files:
.. _global_daml_config:
Global config file (``daml-config.yaml``)
Global Config File (``daml-config.yaml``)
=========================================
The global config file ``daml-config.yaml`` is in the ``daml`` home directory (``~/.daml`` on Linux and Mac, ``C:/Users/<user>/AppData/Roaming/daml`` on Windows). It controls options related to SDK version installation and upgrades.
@ -73,7 +73,7 @@ Here is an example ``daml-config.yaml``:
auto-install: true
update-check: 86400
Project config file (``daml.yaml``)
Project Config File (``daml.yaml``)
===================================
The project config file ``daml.yaml`` must be in the root of your Daml project directory. It controls how the Daml project is built and how tools like Sandbox and Navigator interact with it.
@ -181,8 +181,8 @@ available warnings.
.. _assistant-manual-building-dars:
Building Daml projects
**********************
Build Daml Projects
*******************
To compile your Daml source code into a Daml archive (a ``.dar`` file), run::
@ -205,8 +205,8 @@ The generated ``.dar`` file is created in ``.daml/dist/${name}.dar`` by default.
.. _assistant-manual-managing-releases:
Managing releases
*****************
Manage Releases
***************
You can manage SDK versions manually by using ``daml install``.
@ -252,8 +252,8 @@ passing ``--bash-completions=yes`` or ``--bash-completions=no`` to ``daml instal
.. _daml_project_dir:
Running Commands outside of the Project Directory
*************************************************
Run Commands Outside of the Project Directory
*********************************************
In some cases, it can be convenient to run a command in a project
without having to change directories. For that usecase, you can set

10
docs/source/tools/codegen.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Daml codegen
Daml Codegen
############
Introduction
@ -11,8 +11,8 @@ You can use the Daml codegen to generate Java, and JavaScript/TypeScript classes
These classes incorporate all boilerplate code for constructing corresponding ledger ``com.daml.ledger.api.v1.CreateCommand``,
``com.daml.ledger.api.v1.ExerciseCommand``, ``com.daml.ledger.api.v1.ExerciseByKeyCommand``, and ``com.daml.ledger.api.v1.CreateAndExerciseCommand``.
Running the Daml codegen
========================
Run the Daml Codegen
====================
The basic command to run the Daml codegen is::
@ -24,7 +24,7 @@ There are two modes:
- Project file configuration, specifying **all** settings in the ``daml.yaml`` (currently **Java** only)
Command line configuration
Command Line Configuration
--------------------------
Help for each specific codegen::
@ -51,7 +51,7 @@ Help for each specific codegen::
defaults to daml.js
-h,--help Show this help text
Project file configuration (Java)
Project File Configuration (Java)
---------------------------------
The above settings can be configured in the ``codegen`` element of the Daml project file

8
docs/source/tools/export/index.rst
View File

@ -134,8 +134,8 @@ state and to map unknown contract ids to themselves. For example:
.. TODO[AH] Add a full example project and example export.
Executing the Export
********************
Execute the Export
******************
The generated Daml project is configured such that ``daml start`` will execute
the Daml export with the default arguments defined in ``args.json``.
@ -208,8 +208,8 @@ script. However, this is not supported by all ledgers.
Caveats
*******
Contracts Created and Referenced in Same Transaction
====================================================
Contracts Created and Referenced In the Same Transaction
========================================================
Daml ledger export may fail in certain cases when it attempts to reproduce a
transaction that creates a contract and then references that contract within

8
docs/source/tools/navigator/index.rst
View File

@ -8,7 +8,7 @@ The Navigator is a front-end that you can use to connect to any Daml Ledger and
The first sections of this guide cover use of the Navigator with the SDK. Refer to :ref:`navigator-manual-advanced-usage` for information on using Navigator outside the context of the SDK.
Navigator functionality
Navigator Functionality
***********************
Connect the Navigator to any Daml Ledger and use it to:
@ -33,7 +33,7 @@ Navigator is included in the SDK. To launch it:
.. note:: Navigator is compatible with these browsers: Safari, Chrome, or
Firefox.
Logging in
Logging In
**********
By default, Navigator shows a drop-down list with the users that have been
@ -126,7 +126,7 @@ to allocate those parties before you can log in as them.
- Alice::12201d00faa0968d7ab81e63ad6ad4ee0d31b08a3581b1d8596e68a1356f27519ccb
- Bob::12201d00faa0968d7ab81e63ad6ad4ee0d31b08a3581b1d8596e68a1356f27519ccb
Viewing templates or contracts
Viewing Templates or Contracts
******************************
Daml *contract ​templates* are ​models ​that contain ​the ​agreement ​statement, ​all ​the ​applicable
@ -322,7 +322,7 @@ If the access token cannot be retrieved, is missing or wrong, you'll be unable t
.. _navigator-manual-advanced-usage:
Advanced usage
Advanced Usage
**************
.. _navigator-custom-views:

12
docs/source/tools/non-repudiation.rst
View File

@ -29,8 +29,8 @@ The non-repudiation system consists of three components:
- the non-repudiation API is a web server used by the operator to upload new certificates and verify repudiation claims
- the non-repudiation client is a gRPC interceptor that can be used alongside any gRPC client on the JVM, including the official Java bindings, that will ensure that commands are signed with a given private key
Running the server-side components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Run the Server-side Components
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The server-side components are the middleware and the API. Both can be run as a single process by running the non-repudiation fat JAR provided as part of Daml Enterprise.
@ -44,8 +44,8 @@ The following example shows how to run the non-repudiation server components by
For details on how to run them, please run the fat JAR with the ``--help`` command line option.
Using the client
~~~~~~~~~~~~~~~~
Use the Client
~~~~~~~~~~~~~~
The client is a gRPC interceptor which is available to Daml Enterprise users (hence, it's not available on Maven Central).
@ -62,7 +62,7 @@ The following example shows how to use this interceptor with the official Java b
DamlLedgerClient client = DamlLedgerClient.newBuilder(builder).build();
client.connect();
Non-repudiation over the HTTP JSON API
Non-repudiation Over the HTTP JSON API
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
The non-repudiation middleware acts *exclusively* as a reverse proxy in front of the Ledger API server: if you want to use the HTTP JSON API you will need to
@ -75,7 +75,7 @@ server against the non-repudiation middleware:
- `--non-repudiation-private-key-path`: the path to the file containing the private key that will be used to sign the commands
- `--non-repudiation-private-key-algorithm`: the name of the cryptographic algorithm of the private key (for a list of names supported in the OpenJDK: https://docs.oracle.com/javase/8/docs/technotes/guides/security/StandardNames.html#KeyFactory)
TLS support
TLS Support
~~~~~~~~~~~
At the current stage the non-repudiation feature does not support running against secure Ledger API servers. This will be added as part of stabilizing this feature.

28
docs/source/tools/sandbox.rst
View File

@ -34,8 +34,8 @@ the resulting configuration files will be merged.
.. _sandbox-authorization:
Running with authorization
**************************
Run With Authorization
**********************
By default, Sandbox accepts all valid ledger API requests without performing any request authorization.
@ -103,14 +103,14 @@ with SHA-256) with the public key loaded from the given JWKS URL.
TLS with server authentication as described in :ref:`sandbox-tls` for
any request sent to the Ledger API in production.
Generating JSON Web Tokens (JWT)
================================
Generate JSON Web Tokens (JWT)
==============================
To generate access tokens for testing purposes, use the `jwt.io <https://jwt.io/>`__ web site.
Generating RSA keys
===================
Generate RSA keys
=================
To generate RSA keys for testing purposes, use the following command
@ -123,8 +123,8 @@ which generates the following files:
- ``sandbox.key``: the private key in PEM/DER/PKCS#1 format
- ``sandbox.crt``: a self-signed certificate containing the public key, in PEM/DER/X.509 Certificate format
Generating EC keys
==================
Generate EC keys
================
To generate keys to be used with ES256 for testing purposes, use the following command
@ -145,8 +145,8 @@ Similarly, you can use the following command for ES512 keys:
.. _sandbox-tls:
Running with TLS
****************
Run With TLS
************
To enable TLS, you need to specify the private key for your server and
the certificate chain. This enables TLS for both the Ledger API and
@ -187,7 +187,7 @@ Below, you can see an example config. For more details on TLS, refer to
}
}
Command-line reference
Command-line Reference
**********************
To start Sandbox, run: ``daml sandbox [options] [-c canton.config]``.
@ -200,7 +200,7 @@ Canton. To see options of the underlying Canton runner, use
Metrics
*******
Enable and configure reporting
Enable and Configure Reporting
==============================
You can enable metrics reporting via Prometheus using the following configuration file.
@ -216,7 +216,7 @@ You can enable metrics reporting via Prometheus using the following configuratio
For other options and more details refer to the :ref:`Canton documentation <canton-metrics>`.
Types of metrics
Types of Metrics
================
This is a list of type of metrics with all data points recorded for each.
@ -298,7 +298,7 @@ These metrics are:
- ``<metric.qualified.name>.commit`` (timer): time to perform the commit
- ``<metric.qualified.name>.translation`` (timer): if relevant, time necessary to turn serialized Daml-LF values into in-memory objects
List of metrics
List of Metrics
===============
The following is a non-exhaustive list of selected metrics

4
docs/source/tools/trigger-service/authorization.rst
View File

@ -76,8 +76,8 @@ Alternatively, it can append a custom ``redirect_url`` parameter to the login UR
Note that login with the IAM may require entering credentials into a web-form,
i.e. the login URL should be opened in a web browser.
Example Usage
*************
Example
*******
This section describes how a web frontend can interact with the trigger service when authorization is required.
Note, to avoid cross-origin requests and to enable sharing of cookies

16
docs/source/tools/trigger-service/index.rst
View File

@ -18,8 +18,8 @@ Complex workflows can require running many triggers for many parties and at a ce
The Trigger Service is a ledger client that acts as an end-user agent. The Trigger Service intermediates between the ledger and end-users by running triggers on their behalf. The Trigger Service is an HTTP service. All requests and responses use JSON to encode data.
Starting the Trigger Service
****************************
Start the Trigger Service
*************************
In this example, it is assumed there is a Ledger API server running on port 6865 on `localhost`.
@ -160,7 +160,7 @@ Although, as we'll see, the Trigger Service exposes an endpoint for end-users to
Endpoints
*********
Start a trigger
Start a Trigger
===============
Start a trigger. In this example, ``alice`` starts the trigger called ``trigger`` in a module called ``TestTrigger`` of a package with ID ``312094804c1468e2166bae3c9ba8b5cc0d285e31356304a2e9b0ac549df59d14``.
@ -204,7 +204,7 @@ HTTP Response
}
Stop a trigger
Stop a Trigger
==============
Stop a running trigger. In this example, the request asks to stop the trigger started above.
@ -232,7 +232,7 @@ HTTP Response
.. _list-running-triggers:
List running triggers
List Running Triggers
=====================
List the triggers running on behalf of a given party.
@ -256,7 +256,7 @@ HTTP Response
"status":200
}
Status of a trigger
Status of a Trigger
===================
This endpoint returns data about a trigger, including the party on behalf of which it is running, its identifier,
@ -286,7 +286,7 @@ HTTP Response
"status":200
}
Upload a new DAR
Upload a New DAR
================
Upload a DAR containing one or more triggers. If successful, the DAR's "main package ID" will be in the response (the main package ID for a DAR can also be obtained using ``daml damlc inspect path/to/dar | head -1``).
@ -314,7 +314,7 @@ HTTP Response
"status": 200
}
Liveness check
Liveness Check
==============
This can be used as a liveness probe, e.g., in Kubernetes.

12
docs/source/tools/visual.rst
View File

@ -16,8 +16,8 @@ You can generate visual graphs for the contracts in your Daml project. To do thi
You can of course choose different names for the files, as long as you're consistent between file creation and point of use.
Example: Visualizing the Quickstart project
===========================================
Example: Visualize the Quickstart Project
=========================================
Here's an example visualization based on the :doc:`quickstart </app-dev/bindings-java/quickstart>`. You'll need to `install Graphviz <http://www.graphviz.org/download/>`_ to try this out.
@ -36,16 +36,16 @@ Running the above should produce an image which looks something like this:
Visualizing Daml Contracts - Within IDE
=======================================
Visualize Daml Contracts - Within IDE
=====================================
You can generate visual graphs from VS Code IDE. Open the daml project in VS Code and use `command palette <https://code.visualstudio.com/docs/getstarted/tips-and-tricks#_command-palette/>`_. Should reveal a new window pane with dot image. Also visual generates only the currently open daml file and its imports.
Note: You will need to install the Graphviz/dot packages as mentioned above.
Visualizing Daml Contracts - Interactive Graphs
===============================================
Visualize Daml Contracts - Interactive Graphs
=============================================
This does not require any packages installed. You can generate `D3 <https://d3js.org/>`_ graphs for the contracts in your Daml project. To do this

6
docs/source/triggers/index.rst
View File

@ -157,8 +157,8 @@ not be using heartbeats in this example.
.. _running-a-no-op-trigger:
Running a No-Op Trigger
=======================
Run a No-Op Trigger
===================
To implement a no-op trigger, one could write the following in a separate
``daml/ChatBot.daml`` file:
@ -391,7 +391,7 @@ If you plan to run more than one trigger at a time, or triggers for more than
one party at a time, you may be interested in the
:doc:`/tools/trigger-service/index`.
When not to use Daml triggers
When Not to Use Daml Triggers
=============================
Daml triggers deliberately only allow you to express automation that

8
docs/source/upgrade/automation.rst
View File

@ -13,8 +13,8 @@ specific to an individual application, just like the upgrade models.
Nevertheless, we have found that the pattern shown here
occurs frequently.
Structuring the Upgrade
=======================
Structure the Upgrade
=====================
There are three kinds of actions performed during the upgrade:
@ -90,8 +90,8 @@ whenever the state of the ledger changes. So whenever an owner accepts
an upgrade proposal, the trigger will run the rule and upgrade all
certificates of that owner.
Deploying and Executing the Upgrade
===================================
Deploy and Execute the Upgrade
==============================
Now that we defined our Daml script and our trigger, it is time to use
them! If you still have Sandbox running from the previous section,

2
docs/source/upgrade/extend.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Extending Daml applications
Extending Daml Applications
###########################
.. toctree::

2
docs/source/upgrade/index.rst
View File

@ -1,7 +1,7 @@
.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved.
.. SPDX-License-Identifier: Apache-2.0
Upgrading and Extending Daml applications
Upgrading and Extending Daml Applications
#########################################
.. toctree::

28
docs/source/upgrade/upgrade.rst
View File

@ -3,7 +3,7 @@
.. _upgrade-overview:
Upgrading Daml applications
Upgrading Daml Applications
###########################
.. toctree::
@ -53,7 +53,7 @@ In contrast, Daml templates always have at least one signatory. The
consequence is that the upgrade process for a Daml application needs
to be different.
Daml upgrade overview
Daml Upgrade Overview
=====================
In a Daml application running on a distributed ledger, the signatories
@ -77,8 +77,8 @@ However, the application is extended with new templates. Then if all
signatories of a contract agree, a choice can archive the old version
of a contract and create a new contract instead.
Structuring upgrade contracts
=============================
Structure Upgrade Contracts
===========================
Upgrade contracts are specific to the templates that are being
upgraded. But most of them share common patterns. Here is the
@ -135,8 +135,8 @@ template has one *nonconsuming* choice that takes the contract ID of a
:end-before: -- UPGRADE_AGREEMENT_END
Building and deploying carbon-1.0.0
===================================
Build and Deploy ``carbon-1.0.0``
=================================
Let's see everything in action by first building and deploying
``carbon-1.0.0``. After this we'll see how to deploy and upgrade to
@ -170,8 +170,8 @@ Now we can build and deploy ``carbon-1.0.0``.
$ daml ledger upload-dar --port 6865
Create some carbon-1.0.0 certificates
=====================================
Create carbon-1.0.0 Certificates
================================
Let's create some certificates!
@ -215,8 +215,8 @@ We point a browser to http://localhost:4000, and follow the steps:
#. Exercise the *CarbonCertProposal_Accept* choice on both proposal contracts.
Building and deploying carbon-2.0.0
===================================
Build and Deploy ``carbon-2.0.0``
=================================
Now we setup the project for the improved certificates containing the *carbon_offset_method* field. This project contains only the ``CarbonCertWithMethod`` template. The upgrade templates are in a third ``carbon-upgrade`` package. While it would be possible to include the upgrade templates in the same package, this means that the package containing the new ``CarbonCertWithMethod`` template depends on the previous version. With the approach taken here of keeping the upgrade templates in a separate package, the ``carbon-1.0.0`` package is no longer needed once we have upgraded all certificates.
@ -237,8 +237,8 @@ Now we can build and deploy ``carbon-2.0.0``.
$ daml build
$ daml ledger upload-dar --port 6865
Building and deploying carbon-upgrade
=====================================
Build and Deploy ``carbon-upgrade``
===================================
Having built and deployed ``carbon-1.0.0`` and ``carbon-2.0.0`` we are
now ready to build the upgrade package ``carbon-upgrade``. The project
@ -279,8 +279,8 @@ deployed as part of deploying ``carbon-upgrade``.
$ daml build
$ daml ledger upload-dar --port 6865
Upgrade existing certificates from carbon-1.0.0 to carbon-2.0.0
===============================================================
Upgrade Existing Certificates from carbon-1.0.0 to carbon-2.0.0
=================================================================
We start the navigator again.