mirror of
https://github.com/digital-asset/daml.git
synced 2024-09-20 01:07:18 +03:00
unify heading markup according to README.md (#11919)
CHANGELOG_BEGIN CHANGELOG_END
This commit is contained in:
Andreas Lochbihler
GitHub
parent
61334cff77
commit
5a9481f9d8
@ -30,7 +30,7 @@ architecture, providing you with an excellent starting point for your own applic
|
||||
- deploying your application in the cloud as a Docker container
|
||||
|
||||
Backend
|
||||
~~~~~~~
|
||||
*******
|
||||
The backend for your application can be any Daml ledger implementation running your DAR
|
||||
(:ref:`Daml Archive <dar-file-dalf-file>`) file.
|
||||
|
||||
@ -53,7 +53,7 @@ your frontend and Daml artifacts of your project to a production Daml network. S
|
||||
:ref:`Deploying to Daml Ledgers <deploy-ref_overview>` for an in depth manual for specific ledgers.
|
||||
|
||||
Frontend
|
||||
~~~~~~~~
|
||||
********
|
||||
|
||||
We recommended building your frontend with the `React <https://reactjs.org>`_ framework. However,
|
||||
you can choose virtually any language for your frontend and interact with the ledger via
|
||||
@ -93,7 +93,7 @@ If you choose a different JavaScript based frontend framework, the packages ``@d
|
||||
connect and issue commands against your ledger.
|
||||
|
||||
Authorization
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
When you deploy your application to a production ledger, you need to authenticate the identities of
|
||||
your users.
|
||||
@ -106,7 +106,7 @@ with a Daml ledger that validates authorization of incoming requests. Simply ini
|
||||
form of the required tokens is described in the :ref:`Authorization <authorization>` section.
|
||||
|
||||
Developer workflow
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
******************
|
||||
|
||||
The SDK enables a local development environment with fast iteration cycles:
|
||||
|
||||
@ -129,7 +129,7 @@ See :doc:`Your First Feature </getting-started/first-feature>` for a more detail
|
||||
.. _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.
|
||||
|
||||
@ -158,12 +158,12 @@ For more details on command deduplication, see the :ref:`Ledger API Services <co
|
||||
.. _dealing-with-failures:
|
||||
|
||||
Dealing with failures
|
||||
*********************
|
||||
=====================
|
||||
|
||||
.. _crash-recovery:
|
||||
|
||||
Crash recovery
|
||||
==============
|
||||
--------------
|
||||
|
||||
In order to restart your application from a previously known ledger state,
|
||||
your application must keep track of the last ledger offset received
|
||||
@ -176,7 +176,7 @@ atomic operation, your application can resume from where it left off.
|
||||
.. _failing-over-between-ledger-api-endpoints:
|
||||
|
||||
Failing 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.
|
||||
@ -210,7 +210,7 @@ new endpoint, it will resume normal operation.
|
||||
.. _dealing-with-time:
|
||||
|
||||
Dealing 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.
|
||||
|
||||
|
||||
@ -26,7 +26,7 @@ To set up the example projects, clone the public GitHub repository at `github.co
|
||||
This project contains three examples of the PingPong application, built with gRPC (non-reactive), Reactive and Reactive Component bindings respectively.
|
||||
|
||||
Example project
|
||||
********************************************************
|
||||
***************
|
||||
|
||||
PingPongMain.java
|
||||
=================
|
||||
|
||||
@ -11,7 +11,7 @@ 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
|
||||
-----
|
||||
*****
|
||||
|
||||
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.
|
||||
|
||||
@ -37,7 +37,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
|
||||
---------------------------------
|
||||
*********************************
|
||||
|
||||
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.
|
||||
|
||||
@ -94,12 +94,12 @@ To understand the TypeScript typings produced by the code generator, it is helpf
|
||||
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
|
||||
---------------------------
|
||||
***************************
|
||||
|
||||
The mappings from Daml to TypeScript are best explained by example.
|
||||
|
||||
Records
|
||||
~~~~~~~
|
||||
=======
|
||||
|
||||
In Daml, we might model a person like this.
|
||||
|
||||
@ -124,7 +124,7 @@ Given the above definition, the generated TypeScript code will be as follows.
|
||||
}
|
||||
|
||||
Variants
|
||||
~~~~~~~~
|
||||
========
|
||||
|
||||
This is a Daml type for a language of additive expressions.
|
||||
|
||||
@ -147,7 +147,7 @@ In TypeScript, it is represented as a `discriminated union <https://www.typescri
|
||||
| { tag: 'Add'; value: {_1: Expr<a>, _2: Expr<a>} }
|
||||
|
||||
Sum-of-products
|
||||
~~~~~~~~~~~~~~~~
|
||||
===============
|
||||
|
||||
Let's slightly modify the ``Expr a`` type of the last section into the following.
|
||||
|
||||
@ -179,7 +179,7 @@ Compared to the earlier definition, the ``Add`` case is now in terms of a record
|
||||
The thing to note is how the definition of the ``Add`` case has given rise to a record type definition ``Expr.Add``.
|
||||
|
||||
Enums
|
||||
~~~~~
|
||||
=====
|
||||
|
||||
Given a Daml enumeration like this,
|
||||
|
||||
@ -203,7 +203,7 @@ the generated TypeScript will consist of a type declaration and the definition o
|
||||
} as const;
|
||||
|
||||
Templates and choices
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
=====================
|
||||
|
||||
Here is a Daml template of a basic 'IOU' contract.
|
||||
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _da-ledgers:
|
||||
|
||||
Daml Ledger Model
|
||||
=================
|
||||
#################
|
||||
|
||||
Daml Ledgers enable multi-party workflows by providing
|
||||
parties with a virtual *shared ledger*, which encodes the current
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _da-model-daml:
|
||||
|
||||
Daml: Defining 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:
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _da-model-exceptions:
|
||||
|
||||
Exceptions
|
||||
----------
|
||||
##########
|
||||
|
||||
The introduction of exceptions, a new Daml feature, has many implications
|
||||
for the ledger model. This page describes the changes to the ledger model
|
||||
@ -15,7 +15,7 @@ introduced as part of this new feature.
|
||||
incorporated into the rest of the ledger model.
|
||||
|
||||
Structure
|
||||
+++++++++
|
||||
*********
|
||||
|
||||
Under the new feature, Daml programs can raise and catch exceptions.
|
||||
When an exception is caught in a `catch` block, the subtransaction
|
||||
@ -71,7 +71,7 @@ moment, for some reason, and a "cancel" exercise has been issued in response.
|
||||
:width: 80%
|
||||
|
||||
Consistency
|
||||
+++++++++++
|
||||
***********
|
||||
|
||||
In the previous section on :ref:`consistency <da-model-consistency>`,
|
||||
we defined a "before-after" relation on ledger actions. This notion needs
|
||||
@ -123,7 +123,7 @@ And the third:
|
||||
As you can see, in each of these continuities, no contract was consumed twice.
|
||||
|
||||
Transaction Normalization
|
||||
+++++++++++++++++++++++++
|
||||
*************************
|
||||
|
||||
The same "before-after" relation can be represented in more than one way using
|
||||
rollback nodes. For example, the following three transactions have the same
|
||||
@ -205,7 +205,7 @@ contain normalized transactions. This also applies to projected transactions.
|
||||
An unnormalized transaction is always invalid.
|
||||
|
||||
Authorization
|
||||
+++++++++++++
|
||||
*************
|
||||
|
||||
Since they are not ledger actions, rollback nodes do not have authorizers
|
||||
directly. Instead, a ledger is well-authorized exactly when the same ledger
|
||||
@ -232,7 +232,7 @@ This is captured in the following rules:
|
||||
the required authorizers of its children.
|
||||
|
||||
Privacy
|
||||
+++++++
|
||||
*******
|
||||
|
||||
Rollback nodes also have an interesting effect on the notion of privacy in
|
||||
the ledger model. When projecting a transaction for a party `p`, it's
|
||||
@ -279,7 +279,7 @@ closed under projections for any party 'p'. This is a weaker requirement
|
||||
that matches what we actually need.
|
||||
|
||||
Relation to Daml Exceptions
|
||||
+++++++++++++++++++++++++++
|
||||
***************************
|
||||
|
||||
Rollback nodes are created when an exception is thrown and caught within
|
||||
the same transaction. In particular, any exception that is caught within
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _da-model-integrity:
|
||||
|
||||
Integrity
|
||||
---------
|
||||
#########
|
||||
|
||||
This section addresses the question of who can request which
|
||||
changes.
|
||||
@ -12,7 +12,7 @@ changes.
|
||||
.. _da-model-validity:
|
||||
|
||||
Valid Ledgers
|
||||
+++++++++++++
|
||||
*************
|
||||
|
||||
At the core is the concept of a *valid ledger*; changes
|
||||
are permissible if adding the corresponding commit to the
|
||||
@ -37,7 +37,7 @@ parties) requesting the change; the other two are general.
|
||||
.. _da-model-consistency:
|
||||
|
||||
Consistency
|
||||
+++++++++++
|
||||
***********
|
||||
|
||||
Consistency consists of two parts:
|
||||
|
||||
@ -65,7 +65,7 @@ Then, `act'` happens after `act`.
|
||||
.. _da-model-contract-consistency:
|
||||
|
||||
Contract consistency
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
====================
|
||||
|
||||
Contract consistency ensures that contracts are used after they have been created and before they are consumed.
|
||||
|
||||
@ -132,7 +132,7 @@ of contracts `Iou Bank P` and `PaintAgree P A`.
|
||||
.. _da-model-key-consistency:
|
||||
|
||||
Key consistency
|
||||
~~~~~~~~~~~~~~~
|
||||
===============
|
||||
|
||||
Contract keys introduce a key uniqueness constraint for the ledger.
|
||||
To capture this notion, the contract model must specify for every contract in the system whether the contract has a key and, if so, the key.
|
||||
@ -197,14 +197,14 @@ Key consistency extends to actions, transactions and lists of transactions just
|
||||
.. _da-model-ledger-consistency:
|
||||
|
||||
Ledger consistency
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
==================
|
||||
|
||||
Definition »ledger consistency«
|
||||
A ledger is **consistent** if it is consistent for all contracts and for all keys.
|
||||
|
||||
|
||||
Internal consistency
|
||||
~~~~~~~~~~~~~~~~~~~~
|
||||
====================
|
||||
The above consistency requirement is too strong for actions and transactions
|
||||
in isolation.
|
||||
For example, the acceptance transaction from the paint offer example is not consistent as a ledger, because `PaintOffer A P Bank`
|
||||
@ -271,7 +271,7 @@ In the :ref:`blacklisting example <paint-offer-blacklist>`, `P`\ 's transaction
|
||||
.. _da-model-conformance:
|
||||
|
||||
Conformance
|
||||
+++++++++++
|
||||
***********
|
||||
|
||||
The *conformance* condition constrains the actions that may occur on the
|
||||
ledger. This is done by considering a **contract model** `M` (or a **model** for short),
|
||||
@ -328,7 +328,7 @@ not contain the top-level action she is trying to commit.
|
||||
.. _da-model-authorization:
|
||||
|
||||
Authorization
|
||||
+++++++++++++
|
||||
*************
|
||||
|
||||
The last criterion rules out the last two problematic examples,
|
||||
:ref:`an obligation imposed on a painter <obligation-imposed-on-painter>`,
|
||||
@ -348,7 +348,7 @@ and imposed on the contract's *signatories*.
|
||||
.. _da-signatories-agreements-maintainers:
|
||||
|
||||
Signatories, Agreements, and Maintainers
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
========================================
|
||||
|
||||
To capture these elements of real-world contracts, the **contract model**
|
||||
additionally specifies, for each contract in the system:
|
||||
@ -403,7 +403,7 @@ signatories yields the image below.
|
||||
.. _da-ledgers-authorization-rules:
|
||||
|
||||
Authorization Rules
|
||||
~~~~~~~~~~~~~~~~~~~
|
||||
===================
|
||||
|
||||
Signatories allow one to precisely state that the painter has an obligation.
|
||||
The imposed obligation is intuitively invalid because the painter did not
|
||||
@ -446,7 +446,7 @@ We lift this notion to ledgers, whereby a ledger is well-authorized exactly when
|
||||
|
||||
|
||||
Examples
|
||||
~~~~~~~~
|
||||
========
|
||||
|
||||
An intuition for how the authorization definitions work is most easily
|
||||
developed by looking at some examples. The main example, the
|
||||
@ -517,7 +517,7 @@ The rationale for making the maintainers required authorizers for a **NoSuchKey*
|
||||
is discussed in the next section about :ref:`privacy <da-model-privacy-authorization>`.
|
||||
|
||||
Valid Ledgers, Obligations, Offers and Rights
|
||||
+++++++++++++++++++++++++++++++++++++++++++++
|
||||
*********************************************
|
||||
|
||||
Daml ledgers are designed to mimic real-world interactions between
|
||||
parties, which are governed by contract law. The validity conditions
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _da-model-privacy:
|
||||
|
||||
Privacy
|
||||
-------
|
||||
#######
|
||||
|
||||
The previous sections have addressed two out of three questions posed in the
|
||||
introduction: "what the ledger looks like", and "who may request which changes".
|
||||
@ -20,7 +20,7 @@ And maintainers see all changes to the contract keys they maintain.
|
||||
To make this more precise, a stakeholder concept is needed.
|
||||
|
||||
Contract Observers and Stakeholders
|
||||
+++++++++++++++++++++++++++++++++++
|
||||
***********************************
|
||||
|
||||
Intuitively, as signatories are bound by a contract, they have a stake in it.
|
||||
Actors might not be bound by the contract, but they still have a stake in their actions, as these are the actor's rights.
|
||||
@ -40,7 +40,7 @@ In the graphical representation of the paint offer acceptance below, contract ob
|
||||
:width: 60%
|
||||
|
||||
Choice Observers
|
||||
++++++++++++++++
|
||||
****************
|
||||
|
||||
In addition to contract observers, the contract model can also specify **choice observers** on individual **Exercise** actions.
|
||||
Choice observers get to see a specific exercise on a contract, and to view its consequences.
|
||||
@ -50,7 +50,7 @@ on an action, for the purposes of projection (see below).
|
||||
.. _da-model-projections:
|
||||
|
||||
Projections
|
||||
+++++++++++
|
||||
***********
|
||||
|
||||
Stakeholders should see changes to contracts they hold a stake in, but that does not
|
||||
mean that they have to see the entirety of any transaction that their contract is
|
||||
@ -182,7 +182,7 @@ projections.
|
||||
.. _da-model-privacy-authorization:
|
||||
|
||||
Privacy through authorization
|
||||
+++++++++++++++++++++++++++++
|
||||
*****************************
|
||||
|
||||
Setting the maintainers as required authorizers for a **NoSuchKey** assertion ensures
|
||||
that parties cannot learn about the existence of a contract without having a right to know about their existence.
|
||||
@ -208,7 +208,7 @@ Requiring all maintainers to authorize a **NoSuchKey** assertion avoids the prob
|
||||
.. _da-model-divulgence:
|
||||
|
||||
Divulgence: When Non-Stakeholders See Contracts
|
||||
+++++++++++++++++++++++++++++++++++++++++++++++
|
||||
***********************************************
|
||||
|
||||
The guiding principle for the privacy model of Daml ledgers is that
|
||||
contracts should only be shown to their stakeholders. However,
|
||||
|
||||
@ -4,7 +4,7 @@
|
||||
.. _ledger-structure:
|
||||
|
||||
Structure
|
||||
---------
|
||||
#########
|
||||
|
||||
This section looks at the structure of a Daml ledger and the associated ledger
|
||||
changes. The basic building blocks of changes are *actions*, which get grouped
|
||||
@ -13,7 +13,7 @@ into *transactions*.
|
||||
.. _actions-and-transactions:
|
||||
|
||||
Actions and Transactions
|
||||
++++++++++++++++++++++++
|
||||
************************
|
||||
|
||||
One of the main features of the Daml ledger model is a *hierarchical action
|
||||
structure*.
|
||||
@ -197,7 +197,7 @@ So if the painter retracts its `PaintOffer` and later Alice tries to accept it,
|
||||
|
||||
|
||||
Ledgers
|
||||
+++++++
|
||||
*******
|
||||
|
||||
The transaction structure records the contents of the
|
||||
changes, but not *who requested them*. This information is added by the notion
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Portability, Compatibility, and Support Durations
|
||||
=================================================
|
||||
#################################################
|
||||
|
||||
The Daml Ecosystem offers a number of forward and backward compatibility guarantees aiming to give the Ecosystem as a whole the following properties. See :ref:`ecosystem-architecture` for the terms used here and how they fit together.
|
||||
|
||||
@ -19,7 +19,7 @@ Daml Connect Upgradeability
|
||||
Application Developers should be able to update their developer tools seamlessly to stay up to date with the latest features and fixes, and stay able to maintain and develop their existing applications.
|
||||
|
||||
Ledger API Compatibility: Application Portability
|
||||
-------------------------------------------------
|
||||
*************************************************
|
||||
|
||||
Application Portability and to some extent Network Upgradeability are achieved by intermediating through the Ledger API. As per :ref:`versioning`, and :ref:`ecosystem-architecture`, the Ledger API is independently semantically versioned, and the compatibility guarantees derived from that semantic versioning extend to the entire semantics of the API, including the behavior of Daml Packages on the Ledger. Since all interaction with a Daml Ledger happens through the Daml Ledger API, a Daml Application is guaranteed to work as long as the Participant Node exposes a compatible Ledger API version.
|
||||
|
||||
@ -34,7 +34,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 Connect
|
||||
.....................................................
|
||||
=====================================================
|
||||
|
||||
The below lists with which Daml Connect version a new Ledger API version was introduced.
|
||||
|
||||
@ -57,7 +57,7 @@ The below lists with which Daml Connect version a new Ledger API version was int
|
||||
- Introduced with the same Daml Connect / SDK version
|
||||
|
||||
Summary of Ledger API Changes
|
||||
.............................
|
||||
=============================
|
||||
|
||||
.. list-table::
|
||||
:header-rows: 1
|
||||
@ -80,14 +80,14 @@ Summary of Ledger API Changes
|
||||
- See Daml Connect (/SDK) `release notes <https://daml.com/release-notes>`_ of same version number.
|
||||
|
||||
Driver and Participant Compatibility: Network Upgradeability
|
||||
------------------------------------------------------------
|
||||
************************************************************
|
||||
|
||||
Given the Ledger API Compatibility above, network upgrades are seamless if they preserve data, and Participant Nodes keep exposing the same or a newer minor version of the same major Ledger API Version. The semantic versioning of Daml drivers and participant nodes gives this guarantee. Upgrades from one minor version to another are data preserving, and major Ledger API versions may only be removed with a new major version of integration components, Daml drivers and Participant Nodes.
|
||||
|
||||
As an example, from an application standpoint, the only effect of upgrading Daml for Postgres 1.4.0 to Daml for Postgres 1.6.0 is an uptick in the Ledger API version. There may be significant changes to components or database schemas, but these are not public APIs.
|
||||
|
||||
SDK, Runtime Component, and Library Compatibility: Daml Connect Upgradeability
|
||||
------------------------------------------------------------------------------
|
||||
******************************************************************************
|
||||
|
||||
As long as a major Ledger API version is supported (see :ref:`ledger-api-support`), there will be supported version of Daml Connect able to target all minor versions of that major version. This has the obvious caveat that new features may not be available with old Ledger API versions.
|
||||
|
||||
@ -96,7 +96,7 @@ For example, an application built and compiled with Daml Connect 1.4.0 against L
|
||||
.. _ledger-api-support:
|
||||
|
||||
Ledger API Support Duration
|
||||
---------------------------
|
||||
***************************
|
||||
|
||||
Major Ledger API versions behave like stable features in :doc:`status-definitions`. They are supported from the time they are first released as "stable" to the point where they are removed from Integration Components and Daml Connect following a 12 month deprecation cycle. The earliest point a major Ledger API version can be deprecated is with the release of the next major version. The earliest it can be removed is 12 months later with a major version release of the Integration Components.
|
||||
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Feature and Component Statuses
|
||||
==============================
|
||||
##############################
|
||||
|
||||
This page gives an overview of the statuses of released components and features according to :doc:`status-definitions`. Anything not listed here implicitly has status "Labs", but it's possible that something accidentally slipped the list so if in doubt, please :doc:`contact us <support>`.
|
||||
|
||||
Ledger API
|
||||
----------
|
||||
**********
|
||||
|
||||
.. list-table::
|
||||
:widths: 80 10 10
|
||||
@ -30,7 +30,7 @@ Ledger API
|
||||
- 2021-06-16
|
||||
|
||||
Integration Components
|
||||
----------------------
|
||||
**********************
|
||||
|
||||
.. list-table::
|
||||
:widths: 80 10 10
|
||||
@ -49,7 +49,7 @@ Integration Components
|
||||
.. _runtime-components:
|
||||
|
||||
Runtime components
|
||||
------------------
|
||||
******************
|
||||
|
||||
.. list-table::
|
||||
:widths: 80 10 10
|
||||
@ -92,7 +92,7 @@ Runtime components
|
||||
.. _libraries:
|
||||
|
||||
Libraries
|
||||
---------
|
||||
*********
|
||||
|
||||
.. list-table::
|
||||
:widths: 80 10 10
|
||||
@ -174,7 +174,7 @@ Libraries
|
||||
.. _dev-tools:
|
||||
|
||||
Developer Tools
|
||||
---------------
|
||||
***************
|
||||
|
||||
.. list-table::
|
||||
:widths: 80 10 10
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Daml Ecosystem Overview
|
||||
=======================
|
||||
#######################
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@ -17,7 +17,7 @@ The pages :doc:`status-definitions` and :doc:`component-statuses` give a fine-gr
|
||||
.. _ecosystem-architecture:
|
||||
|
||||
Architecture
|
||||
------------
|
||||
************
|
||||
|
||||
A high level view of the architecture of a Daml application or solution is helpful to make sense of how individual components, APIs and features fit into the Daml Stack.
|
||||
|
||||
@ -26,47 +26,47 @@ A high level view of the architecture of a Daml application or solution is helpf
|
||||
The stack is segmented into two parts. Daml Drivers encompass those components which enable an infrastructure to run Daml Smart Contracts, turning it into a **Daml Network**. **Daml Connect** consists of everything developers and users need to connect to a Daml Network: the tools to build, deploy, integrate, and maintain a Daml Application.
|
||||
|
||||
Daml Networks
|
||||
~~~~~~~~~~~~~
|
||||
*************
|
||||
|
||||
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 command line interface of `Daml for Postgres <https://github.com/digital-asset/daml/blob/main/ledger/daml-on-sql/README.rst>`_. It's a public interface, but specific to the Postgres driver.
|
||||
|
||||
Integration Components
|
||||
......................
|
||||
======================
|
||||
|
||||
Daml drivers and Participant Nodes share a lot of components between underlying DLTs or Databases. These shared components are called the Integration Components, or sometimes the :doc:`/daml-integration-kit/index`.
|
||||
|
||||
Participant Nodes
|
||||
~~~~~~~~~~~~~~~~~
|
||||
*****************
|
||||
|
||||
On top of, or integrated into the Daml Drivers sits a Participant Node, that has the primary purpose of exposing the Daml Ledger API. In the case of *integrated* Daml Drivers, the Participant Node usually interacts with the Daml Drivers through solution-specific APIs. In this case, Participant Nodes can only communicate with Daml Drivers of one Daml Network. In the case of *interoperable* Daml Drivers, the Participant Node communicates with the Daml Drivers through the uniform `Canton Protocol <https://www.canton.io/docs/stable/user-manual/index.html>`_. The Canton Protocol is versioned and has some cross-version compatibility guarantees, but is not a public API. So participant nodes may have public APIs like monitoring and logging, command line interfaces or similar, but the only *uniform* public API exposed by all Participant Nodes is the Ledger API.
|
||||
|
||||
Ledger API
|
||||
~~~~~~~~~~
|
||||
**********
|
||||
|
||||
The Ledger API is the primary interface that offers forward and backward compatibility between Daml Networks and Applications (including Daml Connect components). As you can see in the diagram above, all interaction between components above the Participant Node and the Participant Node or Daml Network happen through the Ledger API. The Ledger API is a public API and offers the lowest level of access to Daml Ledgers supported for application use.
|
||||
|
||||
Daml Connect
|
||||
~~~~~~~~~~~~
|
||||
************
|
||||
|
||||
Runtime Components
|
||||
..................
|
||||
==================
|
||||
|
||||
Runtime components are standalone components that run alongside Participant Nodes or Applications and expose additional services like query endpoints, automations, or integrations. Each Runtime Component has public APIs, which are covered in :doc:`component-statuses`. Typically there is a command line interface, and one or more "Runtime APIs" as indicated in the above diagram.
|
||||
|
||||
Libraries
|
||||
.........
|
||||
=========
|
||||
|
||||
Libraries naturally provide public APIs in their target language, be it Daml, or secondary languages like JavaScript or Java. For details on available libraries and their interfaces, see :doc:`component-statuses`.
|
||||
|
||||
Generated Code
|
||||
..............
|
||||
==============
|
||||
|
||||
The SDK allows the generation of code for some languages from a Daml Model. This generated code has public APIs, which are not independently versioned, but depend on the Daml Connect version and source of the generated code, like a Daml package. In this case, the version of the Daml Connect SDK used covers changes to the public API of the generated code.
|
||||
|
||||
Developer Tools / SDK
|
||||
.....................
|
||||
=====================
|
||||
|
||||
The Daml Connect SDK consists of the developer tools used to develop user code, both Daml and in secondary languages, to generate code, and to interact with running applications via Runtime, and Ledger API. The SDK has a broad public API covering the Daml Language, CLIs, IDE, and Developer tools, but few of those APIs are intended for runtime use in a production environment. Exceptions to that are called out on :doc:`component-statuses`.
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Releases and Versioning
|
||||
=======================
|
||||
#######################
|
||||
|
||||
.. _versioning:
|
||||
|
||||
Versioning
|
||||
----------
|
||||
**********
|
||||
|
||||
All Daml components follow `Semantic Versioning <https://semver.org/>`_. In short, this means that there is a well defined "public API", changes or breakages to which are indicated by the version number.
|
||||
|
||||
@ -20,7 +20,7 @@ Stable releases have versions MAJOR.MINOR.PATCH. Segments of the version are inc
|
||||
Daml's "public API" is laid out in the :doc:`overview`.
|
||||
|
||||
Cadence
|
||||
-------
|
||||
*******
|
||||
|
||||
Regular snapshot releases are made every Wednesday, with additional snapshots released as needed. These releases contain Daml Connect and Integration Components, both from the `daml repository <https://github.com/digital-asset/daml>`_ as well as some others.
|
||||
|
||||
@ -33,28 +33,28 @@ Individual Daml drivers follow their own release cadence, using already released
|
||||
.. _support_duration:
|
||||
|
||||
Support Duration
|
||||
----------------
|
||||
****************
|
||||
|
||||
Major versions will be supported for a minimum of one year after a subsequent Major version is release. Within a major version, only the latest minor version receives security and bug fixes.
|
||||
|
||||
.. _release-notes:
|
||||
|
||||
Release Notes
|
||||
-------------
|
||||
*************
|
||||
|
||||
Release notes for each release are published on the `Release Notes section of the Daml Driven blog <https://daml.com/release-notes/>`_.
|
||||
|
||||
.. _roadmap:
|
||||
|
||||
Roadmap
|
||||
-------
|
||||
*******
|
||||
|
||||
Once a month Digital Asset publishes a community update to accompany the announcement of the release candidate for the next release. The community update contains a section outlining the next priorities for development. You can find community updates on the `Daml Driven Blog <https://daml.com/blog/engineering>`_, or subscribe to the mailing list or social media profiles on `https://daml.com/ <https://daml.com/>`_ to stay up to date.
|
||||
|
||||
.. _release_process:
|
||||
|
||||
Process
|
||||
-------
|
||||
*******
|
||||
|
||||
Weekly snapshot and monthly stable releases follow a regular process and schedule. The process is documented `in the Daml repository <https://github.com/digital-asset/daml/blob/main/release/RELEASE.md>`_ so only the schedule for monthly releases is covered here.
|
||||
|
||||
|
||||
@ -2,12 +2,12 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Status Definitions
|
||||
==================
|
||||
##################
|
||||
|
||||
Throughout the documentation, we use labels to mark features of APIs not yet deemed stable. This page gives meaning to those labels.
|
||||
|
||||
Early Access Features
|
||||
---------------------
|
||||
*********************
|
||||
|
||||
Features or components covered by these docs are :ref:`Stable <status_definitions>` by default. :ref:`Stable <status_definitions>` features and components constitute Daml's "public API" in the sense of :ref:`Semantic Versioning <versioning>`. Feature and components that are not :ref:`Stable <status_definitions>` are called "Early Access" and called out explicitly.
|
||||
|
||||
@ -28,7 +28,7 @@ Beta
|
||||
Beta components and features are preview versions of features that are close to maturity. They are characterized by being considered feature complete, and the APIs close to the final public APIs. It is relatively safe to build on Beta features as long as the documented caveats to runtime characteristics are understood and bugs and minor API adjustments are not too costly.
|
||||
|
||||
Deprecation
|
||||
-----------
|
||||
***********
|
||||
|
||||
In addition to being labelled Early Access, features and components can also be labelled "Deprecated". Deprecation follows a deprecation cycle laid out in the table below. The date of deprecation is documented in :doc:`overview`.
|
||||
|
||||
@ -37,7 +37,7 @@ Deprecated features can be relied upon during the deprecation cycle to the same
|
||||
.. _status_definitions:
|
||||
|
||||
Comparison of Statuses
|
||||
----------------------
|
||||
**********************
|
||||
|
||||
The table below gives a concise overview of the labels used for Daml features and components.
|
||||
|
||||
|
||||
@ -2,7 +2,7 @@
|
||||
.. SPDX-License-Identifier: Apache-2.0
|
||||
|
||||
Getting Help
|
||||
============
|
||||
############
|
||||
|
||||
Have questions or feedback? You're in the right place.
|
||||
|
||||
@ -18,7 +18,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
|
||||
--------------------
|
||||
********************
|
||||
|
||||
For community users (ie on our Forum and Stack Overflow):
|
||||
|
||||
|
||||
Loading…
Reference in New Issue
Block a user