From cda93db944afe55d987ba8b7d5326e256ae359cf Mon Sep 17 00:00:00 2001 From: Bernhard Elsner <40762178+bame-da@users.noreply.github.com> Date: Fri, 8 Jan 2021 13:50:15 +0100 Subject: [PATCH] Daml case and logo (#8433) * Replace many occurrences of DAML with Daml * Update docs logo * A few more CLI occurrences CHANGELOG_BEGIN - Change DAML capitalization and docs logo CHANGELOG_END * Fix some over-eager replacements * A few mor occurrences in md files * Address comments in *.proto files * Change case in comments and strings in .ts files * Revert changes to frozen proto files * Also revert LF 1.11 * Update get-daml.sh * Update windows installer * Include .py files * Include comments in .daml files * More instances in the assistant CLI * some more help texts --- .github/ISSUE_TEMPLATE.md | 4 +- BAZEL-JVM.md | 6 +- BAZEL-haskell.md | 6 +- BAZEL.md | 34 +-- CONTRIBUTING.md | 32 +-- README.md | 20 +- SECURITY.md | 4 +- ci/docker/README.md | 10 +- compatibility/README.md | 12 +- .../bazel_tools/create-daml-app/index.test.ts | 2 +- compiler/README.md | 6 +- compiler/daml-extension/README.md | 18 +- compiler/daml-extension/extension_guide.md | 8 +- compiler/daml-extension/src/extension.ts | 20 +- compiler/daml-extension/syntaxes/README.md | 6 +- compiler/daml-lf-verify/README.rst | 8 +- compiler/damlc/README.md | 18 +- compiler/damlc/base-hoogle-template.txt | 2 +- compiler/damlc/base-md-template.md | 4 +- compiler/damlc/base-rst-index-template.rst | 4 +- .../daml-prim-src/Control/Exception/Base.daml | 4 +- .../daml-prim-src/DA/Internal/Erased.daml | 2 +- .../DA/Internal/PromotedText.daml | 6 +- compiler/damlc/daml-prim-src/DA/Types.daml | 4 +- compiler/damlc/daml-prim-src/GHC/Base.daml | 2 +- compiler/damlc/daml-prim-src/GHC/CString.daml | 2 +- compiler/damlc/daml-prim-src/GHC/Err.daml | 2 +- compiler/damlc/daml-prim-src/GHC/Types.daml | 8 +- compiler/damlc/daml-stdlib-src/DA/Either.daml | 4 +- .../damlc/daml-stdlib-src/DA/Generics.daml | 2 +- .../DA/Internal/Compatible.daml | 54 ++--- .../daml-stdlib-src/DA/Internal/Date.daml | 2 +- .../damlc/daml-stdlib-src/DA/Internal/LF.daml | 16 +- .../daml-stdlib-src/DA/Internal/Prelude.daml | 2 +- .../daml-stdlib-src/DA/Internal/Template.daml | 2 +- .../DA/Internal/Template/Functions.daml | 28 +-- .../daml-stdlib-src/DA/Internal/Time.daml | 2 +- compiler/damlc/daml-stdlib-src/DA/Math.daml | 4 +- compiler/damlc/daml-stdlib-src/DA/Maybe.daml | 20 +- .../damlc/daml-stdlib-src/DA/Maybe/Total.daml | 4 +- .../damlc/daml-stdlib-src/DA/Next/Map.daml | 2 +- compiler/damlc/daml-stdlib-src/DA/Text.daml | 2 +- compiler/damlc/daml-stdlib-src/Prelude.daml | 2 +- compiler/damlc/lib/DA/Cli/Damlc.hs | 28 +-- compiler/damlc/lib/DA/Cli/Options.hs | 10 +- .../daml-test-files/AliasCompression.daml | 2 +- .../daml-test-files/ClassMethodNames.daml | 2 +- .../daml-test-files/ConstrainedRecursion.daml | 2 +- .../tests/daml-test-files/DataTypes.daml | 4 +- .../damlc/tests/daml-test-files/EnumLF.daml | 2 +- .../ExerciseWithoutActors.daml | 2 +- .../tests/daml-test-files/FreshNames.daml | 2 +- .../tests/daml-test-files/KindChecking.daml | 2 +- .../daml-test-files/RecordProjection.daml | 4 +- .../daml-test-files/SemanticsEvalOrder.daml | 4 +- .../tests/daml-test-files/SemanticsValue.daml | 8 +- .../SemanticsValueSince17.daml | 2 +- .../tests/daml-test-files/SingleConEnum.daml | 2 +- .../daml-test-files/TypeVarShadowing.daml | 2 +- .../tests/daml-test-files/Unserializable.daml | 2 +- .../UnserializableScenario.daml | 2 +- .../tests/daml-test-files/UseInteger.daml | 2 +- .../daml-helper/src/DA/Daml/Helper/Main.hs | 6 +- daml-assistant/get-daml.sh | 10 +- .../scala-daml-project-config/README.md | 2 +- .../src/DA/Daml/Assistant/Command.hs | 10 +- daml-lf/README.md | 14 +- daml-lf/archive/README.md | 20 +- .../com/daml/daml_lf_dev/daml_lf.proto | 6 +- .../com/daml/daml_lf_dev/daml_lf_1.proto | 8 +- daml-lf/governance.rst | 64 +++--- daml-lf/interpreter/perf/daml/JsonParser.daml | 2 +- daml-lf/notes/README.md | 2 +- daml-lf/spec/contract-id.rst | 4 +- daml-lf/spec/daml-lf-1.rst | 206 +++++++++--------- daml-lf/spec/transaction.rst | 38 ++-- daml-lf/spec/value.rst | 38 ++-- .../protobuf/com/daml/lf/transaction.proto | 4 +- .../src/main/protobuf/com/daml/lf/value.proto | 4 +- daml-script/daml/Daml/Script.daml | 12 +- .../daml/daml-script-hoogle-template.txt | 2 +- .../daml/daml-script-index-template.rst | 4 +- dev-env/dotfiles/README.md | 4 +- docs/README.md | 4 +- docs/configs/html/conf.py | 14 +- docs/configs/pdf/conf.py | 14 +- docs/configs/pdf/index.rst | 14 +- docs/configs/static/pygments_daml_lexer.py | 2 +- docs/source/app-dev/app-arch.rst | 68 +++--- docs/source/app-dev/authorization.rst | 24 +- docs/source/app-dev/bindings-java/codegen.rst | 36 +-- docs/source/app-dev/bindings-java/example.rst | 6 +- docs/source/app-dev/bindings-java/index.rst | 18 +- .../app-dev/bindings-java/quickstart.rst | 64 +++--- docs/source/app-dev/bindings-scala/index.rst | 16 +- docs/source/app-dev/bindings-ts/daml2js.rst | 32 +-- docs/source/app-dev/bindings-ts/index.rst | 8 +- docs/source/app-dev/bindings-x-lang/index.rst | 12 +- docs/source/app-dev/daml-lf-translation.rst | 68 +++--- .../app-dev/grpc/daml-to-ledger-api.rst | 10 +- docs/source/app-dev/grpc/index.rst | 8 +- docs/source/app-dev/ledger-api.rst | 28 +-- docs/source/app-dev/services.rst | 2 +- docs/source/concepts/glossary.rst | 60 ++--- .../identity-and-package-management.rst | 42 ++-- docs/source/concepts/interoperability.rst | 58 ++--- docs/source/concepts/ledger-model/index.rst | 16 +- .../concepts/ledger-model/ledger-daml.rst | 12 +- .../ledger-model/ledger-integrity.rst | 18 +- .../concepts/ledger-model/ledger-privacy.rst | 16 +- .../ledger-model/ledger-structure.rst | 14 +- docs/source/concepts/local-ledger.rst | 46 ++-- docs/source/concepts/time.rst | 16 +- docs/source/daml-integration-kit/index.rst | 114 +++++----- docs/source/daml-repl/index.rst | 22 +- docs/source/daml-script/index.rst | 60 ++--- .../daml/code-snippets-dev/Structure.daml | 2 +- docs/source/daml/daml-studio.rst | 58 ++--- docs/source/daml/intro/0_Intro.rst | 10 +- docs/source/daml/intro/10_StdLib.rst | 20 +- docs/source/daml/intro/11_Testing.rst | 48 ++-- docs/source/daml/intro/1_Token.rst | 22 +- docs/source/daml/intro/2_DamlScript.rst | 20 +- docs/source/daml/intro/3_Data.rst | 34 +-- docs/source/daml/intro/4_Transformations.rst | 4 +- docs/source/daml/intro/5_Restrictions.rst | 24 +- docs/source/daml/intro/6_Parties.rst | 14 +- docs/source/daml/intro/7_Composing.rst | 36 +-- docs/source/daml/intro/8_Dependencies.rst | 14 +- docs/source/daml/intro/9_Functional101.rst | 42 ++-- .../daml/intro/daml/daml-intro-1/Token.daml | 2 +- .../intro/daml/daml-intro-2/Token_Test.daml | 2 +- docs/source/daml/patterns.rst | 4 +- .../daml/patterns/daml/CoinDelegation.daml | 2 +- docs/source/daml/patterns/delegation.rst | 4 +- docs/source/daml/patterns/initaccept.rst | 2 +- docs/source/daml/patterns/locking.rst | 2 +- .../patterns/locking/locking-by-state.rst | 2 +- .../daml/patterns/multiparty-agreement.rst | 2 +- docs/source/daml/reference/choices.rst | 4 +- docs/source/daml/reference/contract-keys.rst | 6 +- docs/source/daml/reference/data-types.rst | 22 +- docs/source/daml/reference/expressions.rst | 6 +- docs/source/daml/reference/file-structure.rst | 14 +- docs/source/daml/reference/functions.rst | 14 +- docs/source/daml/reference/index.rst | 2 +- docs/source/daml/reference/packages.rst | 46 ++-- docs/source/daml/reference/scenarios.rst | 2 +- docs/source/daml/reference/structure.rst | 4 +- docs/source/daml/reference/templates.rst | 2 +- docs/source/daml/reference/updates.rst | 2 +- docs/source/daml/reference/working-with.rst | 12 +- docs/source/daml/testing-scenarios.rst | 10 +- docs/source/daml/troubleshooting.rst | 14 +- docs/source/deploy/generic_ledger.rst | 10 +- docs/source/deploy/index.rst | 22 +- docs/source/deploy/ledger-topologies.rst | 14 +- .../getting-started/app-architecture.rst | 42 ++-- docs/source/getting-started/first-feature.rst | 28 +-- docs/source/getting-started/index.rst | 30 +-- docs/source/getting-started/installation.rst | 6 +- .../getting-started/manual-download.rst | 2 +- docs/source/index.rst | 14 +- docs/source/json-api/index.rst | 20 +- .../json-api/lf-value-specification.rst | 34 +-- .../source/json-api/search-query-language.rst | 4 +- docs/source/ops/index.rst | 34 +-- docs/source/support/compatibility.rst | 28 +-- docs/source/support/component-statuses.rst | 52 ++--- docs/source/support/overview.rst | 28 +-- docs/source/support/releases.rst | 18 +- docs/source/support/status-definitions.rst | 10 +- docs/source/support/support.rst | 6 +- docs/source/tools/assistant.rst | 44 ++-- docs/source/tools/codegen.rst | 10 +- docs/source/tools/extractor.rst | 10 +- .../tools/ledger-api-test-tool/index.rst | 18 +- docs/source/tools/navigator/index.rst | 20 +- docs/source/tools/sandbox.rst | 28 +-- docs/source/tools/trigger-service.rst | 2 +- docs/source/tools/visual.rst | 12 +- docs/source/triggers/index.rst | 58 ++--- docs/source/upgrade/automation.rst | 20 +- docs/source/upgrade/extend.rst | 20 +- docs/source/upgrade/index.rst | 10 +- docs/source/upgrade/upgrade.rst | 32 +-- .../static/images/DAML_Logo_Blue.svg | 64 +++--- docs/theme/docs/conf.py | 12 +- ghc-lib/new-working-on-ghc-lib.md | 8 +- ghc-lib/template-desugaring.md | 14 +- infra/README.md | 4 +- language-support/hs/bindings/README.md | 2 +- .../hs/bindings/examples/group-chat/README.md | 8 +- .../examples/group-chat/daml/GroupChat.daml | 2 +- .../hs/bindings/examples/nim/demo.md | 4 +- language-support/java/codegen/README.md | 2 +- .../scala/codegen-sample-app/README.md | 2 +- language-support/scala/codegen/README.md | 10 +- .../scala/examples/iou-no-codegen/README.md | 2 +- .../scala/examples/quickstart-scala/README.md | 10 +- language-support/ts/codegen/README.md | 12 +- language-support/ts/daml-ledger/README.md | 10 +- language-support/ts/daml-ledger/index.ts | 4 +- language-support/ts/daml-react/README.md | 12 +- .../ts/daml-react/createLedgerContext.ts | 4 +- .../ts/daml-react/defaultLedgerContext.ts | 2 +- language-support/ts/daml-types/README.md | 8 +- language-support/ts/daml-types/index.ts | 40 ++-- .../v1/admin/package_management_service.proto | 10 +- .../v1/admin/party_management_service.proto | 8 +- .../daml/ledger/api/v1/command_service.proto | 8 +- .../com/daml/ledger/api/v1/commands.proto | 6 +- .../daml/ledger/api/v1/package_service.proto | 6 +- .../com/daml/ledger/api/v1/value.proto | 4 +- ledger-service/http-json-perf/README.md | 4 +- ledger-service/http-json/README.md | 2 +- ledger/README.md | 2 +- ledger/daml-on-sql/README.rst | 88 ++++---- .../participant-integration-api/rootdoc.txt | 2 +- .../src/main/protobuf/daml_kvutils.proto | 34 +-- .../participant-state/kvutils/tools/README.md | 4 +- .../kvutils/tools/codec-benchmark/README.md | 6 +- .../state/ledger_configuration.proto | 2 +- .../protobuf/ledger_configuration.rst | 2 +- ledger/sandbox-classic/README.md | 14 +- .../src/main/scala/platform/sandbox/Cli.scala | 2 +- .../sandbox-common/historical-dars/README.md | 2 +- .../platform/sandbox/cli/CommonCli.scala | 6 +- .../main/scala/platform/sandboxnext/Cli.scala | 2 +- .../src/main/daml/semantic/SemanticTests.daml | 4 +- navigator/backend/README.md | 2 +- navigator/frontend/src/config/api/v1.ts | 2 +- navigator/frontend/src/config/api/v2.ts | 2 +- .../src/ui-core/src/api/DamlLfType.ts | 2 +- release/RELEASE.md | 4 +- release/sdk-config.yaml.tmpl | 28 +-- .../windows-installer/src/WindowsInstaller.hs | 6 +- templates/README.txt | 2 +- .../index.test.ts | 2 +- templates/create-daml-app/README.md.template | 26 +-- .../src/components/LoginScreen.tsx.template | 2 +- triggers/daml/Daml/Trigger/Internal.daml | 8 +- .../daml/daml-trigger-hoogle-template.txt | 2 +- triggers/daml/daml-trigger-index-template.rst | 4 +- .../com/daml/auth/middleware/oauth2/README.md | 2 +- 245 files changed, 1828 insertions(+), 1822 deletions(-) diff --git a/.github/ISSUE_TEMPLATE.md b/.github/ISSUE_TEMPLATE.md index 2a3002625b..bf65d27f4d 100644 --- a/.github/ISSUE_TEMPLATE.md +++ b/.github/ISSUE_TEMPLATE.md @@ -1,9 +1,9 @@ diff --git a/BAZEL-JVM.md b/BAZEL-JVM.md index e11481db8f..4ce13c5f4b 100644 --- a/BAZEL-JVM.md +++ b/BAZEL-JVM.md @@ -642,11 +642,11 @@ files. [scalafmt]: https://github.com/scalameta/scalafmt [scala_format_test]: https://github.com/DACH-NY/da/blob/e904c8eac1427633ef20b6106906a59f590de5a6/bazel_tools/scalafmt/scalafmt.bzl#L31 -### DAML +### Daml The SBT build of the `ledger-client` component defines a custom SBT plugin for -handling DAML code. It covers compilation to LF, packaging to DAR, Scala code -generation, and executing the DAML sandbox. This plugin was ported to Bazel as +handling Daml code. It covers compilation to LF, packaging to DAR, Scala code +generation, and executing the Daml sandbox. This plugin was ported to Bazel as a set of custom Bazel rules defined in [`rules_daml`][rules_daml]. Refer to the [user guide][bazel_user_guide] or the [API docs][bazel-api-documentation] for details. diff --git a/BAZEL-haskell.md b/BAZEL-haskell.md index 4770664ae1..a4939343bc 100644 --- a/BAZEL-haskell.md +++ b/BAZEL-haskell.md @@ -5,7 +5,7 @@ Finding your way around our Bazel build system from a Haskell developers' point - How toolchains and external dependencies are defined; - Specifiying stock `bazel` command options. -For this, one needs awareness of four files at the root level of the DAML repository : `WORKSPACE`, `deps.bzl`, `BUILD` and `.bazelrc`. +For this, one needs awareness of four files at the root level of the Daml repository : `WORKSPACE`, `deps.bzl`, `BUILD` and `.bazelrc`. ## `.bazelrc` the Bazel configuration file @@ -26,7 +26,7 @@ load("@bazel_tools//tools/build_defs/repo:git.bzl", "git_repository") ``` This loads the contents of the files `http.bzl` and `git.bzl` from the external workspace [`bazel_tools`](https://github.com/bazelbuild/bazel/tree/master/tools) into the "environment". `bazel_tools` is an external workspace builtin to Bazel and provides rules for working with archives and git. -*[Note : Confusingly (?), `//bazel_tools` is a DAML package (a sub-directory of the root package directory containing a `BUILD.bazel` file). Don't confuse `@bazel_tools//..` with `//bazel_tools/..`]*. +*[Note : Confusingly (?), `//bazel_tools` is a Daml package (a sub-directory of the root package directory containing a `BUILD.bazel` file). Don't confuse `@bazel_tools//..` with `//bazel_tools/..`]*. Straight after the loading of those rules, `deps.bzl` reads, ``` @@ -259,6 +259,6 @@ may take some time if the required artifacts are not built or cached already. ## Further reading: -- ["Bazel User Guide"](https://github.com/digital-asset/daml/blob/main/BAZEL.md) (DAML specific) +- ["Bazel User Guide"](https://github.com/digital-asset/daml/blob/main/BAZEL.md) (Daml specific) - ["A Users's Guide to Bazel"](https://docs.bazel.build/versions/master/guide.html) (official documentation) - [`rules_haskell` documentation](https://api.haskell.build/index.html) (core Haskell rules, Haddock support, Linting, Defining toolchains, Support for protocol buffers, Interop with `cc_*` rules, Workspace rules) diff --git a/BAZEL.md b/BAZEL.md index 4af3000e63..e6b7aa088e 100644 --- a/BAZEL.md +++ b/BAZEL.md @@ -1,6 +1,6 @@ # Bazel User Guide -This document explains how to use the Bazel build system on the DAML repository +This document explains how to use the Bazel build system on the Daml repository from a users perspective. I.e. assuming the project you are working on has already been ported to Bazel. @@ -13,7 +13,7 @@ project to Bazel. ## Setup This section goes through the required steps for a basic but fully functioning -setup of the Bazel build system for work on the DAML repository. Additional setup +setup of the Bazel build system for work on the Daml repository. Additional setup as for the IntelliJ integration is listed in its own section below. ### Bazel Executable @@ -92,7 +92,7 @@ details depend on the rule in question. The following rules are commonly used in this repository. For Scala projects `da_scala_library`, `da_scala_test_suite`, `da_scala_binary`. For Java projects -`java_library`, `java_test_suite`, `java_binary`. For DAML projects `daml`. +`java_library`, `java_test_suite`, `java_binary`. For Daml projects `daml`. Labels can point to a specific target, or to a set of targets using a wild-card. The following wild-card patterns are recognized. @@ -158,7 +158,7 @@ page][intellij_plugin_jetbrains]. To import a Bazel project into IntelliJ select "Import Bazel Project" in the welcome dialog, or `File > Import Bazel Project` in the editor window. In the -import dialog under "Workspace:" enter the path to the DAML repository root. +import dialog under "Workspace:" enter the path to the Daml repository root. The Bazel IntelliJ integration uses a *project view* file to define the list of directories and targets to make accessible in IntelliJ and to control other @@ -254,7 +254,7 @@ _Sync project with BUILD files_). This process will take a while. ### Configuring the JDK in IntelliJ -DAML downloads the version of the JDK it uses from Nix. A symlink will be +Daml downloads the version of the JDK it uses from Nix. A symlink will be created by the dev-env utilities (make sure you've set these up) in _dev-env/jdk_. @@ -264,11 +264,11 @@ TO configure IntelliJ to use this JDK: 2. Under _Platform Settings_, select _SDKs_. 3. Press the _plus_ button and select "Add JDK". 4. Choose the _dev-env/jdk_ directory. -5. Name it "DAML JDK" or something similar. +5. Name it "Daml JDK" or something similar. 6. Ensure there's sources attached under the _Sourcepath_ tab. If not, add them. Press the _plus_ button and select _dev-env/jdk/lib/openjdk/src.zip_. 7. Open _Project Settings_ → _Project_. -8. Select the DAML JDK from the _Project SDK_ list. +8. Select the Daml JDK from the _Project SDK_ list. ### Overview over Bazel IntelliJ Integration @@ -619,7 +619,7 @@ da_haskell_library( visibility = ["//visibility:public"], ) ``` -To build this single target from the root of the DAML repository, the +To build this single target from the root of the Daml repository, the command would be: ``` bazel build //compiler/damlc/daml-compiler @@ -897,18 +897,18 @@ the target `foo_deploy.jar` next to the regular `foo.jar` target. Building the `foo_deploy.jar` target will generate a self-contained fat JAR suitable to be passed to `java -jar`. -### DAML Packages +### Daml Packages -DAML package targets are defined using the `daml` rule loaded from +Daml package targets are defined using the `daml` rule loaded from `//rules_daml:daml.bzl`. To explain it we will take an example instance and describe the individual attributes. ``` daml( name = "it-daml", - # The main DAML file. This file will be passed to damlc. + # The main Daml file. This file will be passed to damlc. main_src = "src/it/resources/TestAll.daml", - # Other DAML files that may be imported by the main DAML file. + # Other Daml files that may be imported by the main Daml file. srcs = glob(["src/it/resources/**/*.daml"]), # The directory prefix under which to create the DAR tree. target_dir = "target/scala-2.12/resource_managed/it/dars", @@ -923,7 +923,7 @@ daml( ) ``` -This will compile and package the DAML code into a DAR file under the following +This will compile and package the Daml code into a DAR file under the following target, where `` is the `group` attribute with `.` replaced by `/`. ``` @@ -951,10 +951,10 @@ For example: it-daml.srcjar ``` -### DAML Executables +### Daml Executables The rule `daml_binary` is provided to generate executable targets that execute -the DAML sandbox on a given DAR package. For example: +the Daml sandbox on a given DAR package. For example: ``` daml_binary( @@ -964,7 +964,7 @@ daml_binary( ``` Such a target can then be executed as follows, where arguments after `--` are -passed to the DAML sandbox. +passed to the Daml sandbox. ``` bazel run //ledger-client/nanobot-sample-app:ping-pong-exec -- --help @@ -1006,7 +1006,7 @@ For an example, please see `compiler/daml-extension/BUILD.bazel`. ## Protocol buffers in Bazel -We use protocol buffers for DAML-LF and the Ledger API. The DAML-LF protocol +We use protocol buffers for Daml-LF and the Ledger API. The Daml-LF protocol buffer build rules can be found from //daml-lf/archive/BUILD.bazel. It produces bindings for Java and Haskell (via proto3-suite). diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index bf8076005a..1146ee6977 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -1,16 +1,16 @@ -# Contributing to DAML +# Contributing to Daml -Welcome! This page gives a high-level overview of how to contribute to the development of DAML. +Welcome! This page gives a high-level overview of how to contribute to the development of Daml. There are many ways you can contribute beyond coding. For example, you can report problems, clarify [issues](https://github.com/digital-asset/daml/issues), and write documentation. If you're completely new to open source development, the [Open Source Guides](https://opensource.guide) is a great place to start. ## Working on the codebase -For information on how to build, test, and work on the codebase, see ["Contributing to DAML" in the README](./README.md#contributing-to-daml). +For information on how to build, test, and work on the codebase, see ["Contributing to Daml" in the README](./README.md#contributing-to-daml). ## Code of conduct -This project and everyone participating in it is governed by the [DAML Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [community@digitalasset.com](mailto:community@digitalasset.com). +This project and everyone participating in it is governed by the [Daml Code of Conduct](./CODE_OF_CONDUCT.md). By participating, you are expected to uphold this code. Please report unacceptable behavior to [community@digitalasset.com](mailto:community@digitalasset.com). ## Git conventions @@ -88,9 +88,9 @@ Here are a few practical tips: This list should cover the vast majority of needs. If unsure, ask on the relevant GitHub issue or PR. - * DAML Compiler - * DAML on SQL - * DAML Studio + * Daml Compiler + * Daml on SQL + * Daml Studio * Distribution/Releases * Extractor * Java Bindings @@ -101,20 +101,20 @@ This list should cover the vast majority of needs. If unsure, ask on the relevan * Ledger API Specification * Integration Kit † * Navigator - * DAML REPL + * Daml REPL * Sandbox * Scala Bindings * Scala Codegen - * DAML Script - * DAML Assistant - * DAML Standard Library - * DAML Triggers + * Daml Script + * Daml Assistant + * Daml Standard Library + * Daml Triggers † Covers the Ledger API Test Tool and changes to libraries that affect ledger integrations (e.g. `kvutils`) ## Working with issues -We use issues and [pull requests](https://help.github.com/articles/about-pull-requests/) to collaborate and track our work. Anyone is welcome to open an issue. If you just want to ask a question, please ask away on [the DAML forum](https://discuss.daml.com). +We use issues and [pull requests](https://help.github.com/articles/about-pull-requests/) to collaborate and track our work. Anyone is welcome to open an issue. If you just want to ask a question, please ask away on [the Daml forum](https://discuss.daml.com). We encourage everyone to vote on issues that they support or not: @@ -138,7 +138,7 @@ We use labels to indicate what component the issue relates to (`component/...`). By default, issues represent "work to be done" -- that might be features, improvements, non-critical bug fixes, and so on. -The DAML Language team uses labels to indicate priority (the DAML Runtime team does not): +The Daml Language team uses labels to indicate priority (the Daml Runtime team does not): - `language/now` - `language/soon` @@ -148,7 +148,7 @@ You can see all labels [here](https://github.com/digital-asset/daml/labels). ### Milestones -In addition to labels, we group issues into *milestones*. The DAML Language team has all issues in a single *Language* milestone; the DAML Runtime team uses them to group work efforts (*Add PostgreSQL backend to the Ledger* for example). *Maintenance* and *Backlog* are special milestones. +In addition to labels, we group issues into *milestones*. The Daml Language team has all issues in a single *Language* milestone; the Daml Runtime team uses them to group work efforts (*Add PostgreSQL backend to the Ledger* for example). *Maintenance* and *Backlog* are special milestones. Issues without a milestone are treated as in need of triaging. @@ -156,7 +156,7 @@ You can see all the active milestones [here](https://github.com/digital-asset/da ## Discussions -Please hold discussions that are relevant to DAML development and not confidential in GitHub issues. That way, anyone who wants to contribute or follow along can do so. If you have private discussions, please summarise them in an issue or comment to an issue. +Please hold discussions that are relevant to Daml development and not confidential in GitHub issues. That way, anyone who wants to contribute or follow along can do so. If you have private discussions, please summarise them in an issue or comment to an issue. You can also join a `#daml-contributors` channel on our Slack: [damldriven.slack.com](https://damldriven.slack.com/sso/saml/start). diff --git a/README.md b/README.md index 840734abec..a429dc010d 100644 --- a/README.md +++ b/README.md @@ -1,4 +1,4 @@ -[![DAML logo](daml-logo.png)](https://www.daml.com) +[![Daml logo](daml-logo.png)](https://www.daml.com) [![Download](https://img.shields.io/github/release/digital-asset/daml.svg?label=Download)](https://docs.daml.com/getting-started/installation.html) [![License](https://img.shields.io/badge/License-Apache%202.0-blue.svg)](https://github.com/digital-asset/daml/blob/main/LICENSE) @@ -7,23 +7,23 @@ Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All Rights Reserved. SPDX-License-Identifier: Apache-2.0 -# Welcome to the DAML repository! +# Welcome to the Daml repository! -This repository hosts all code for the [DAML smart contract language and SDK](https://daml.com/), originally created by -[Digital Asset](https://www.digitalasset.com). DAML is an open-source smart contract language for building future-proof distributed applications on a safe, privacy-aware runtime. The SDK is a set of tools to help you develop applications based on DAML. +This repository hosts all code for the [Daml smart contract language and SDK](https://daml.com/), originally created by +[Digital Asset](https://www.digitalasset.com). Daml is an open-source smart contract language for building future-proof distributed applications on a safe, privacy-aware runtime. The SDK is a set of tools to help you develop applications based on Daml. -## Using DAML +## Using Daml -To download DAML, follow [the installation instructions](https://docs.daml.com/getting-started/installation.html). +To download Daml, follow [the installation instructions](https://docs.daml.com/getting-started/installation.html). Once installed, to try it out, follow the [quickstart guide](https://docs.daml.com/getting-started/quickstart.html). -If you have questions about how to use DAML or how to build DAML-based solutions, please ask them on +If you have questions about how to use Daml or how to build Daml-based solutions, please ask them on [StackOverflow using the `daml` tag](https://stackoverflow.com/tags/daml). -## Contributing to DAML +## Contributing to Daml We warmly welcome [contributions](./CONTRIBUTING.md). If you are looking for ideas on how to contribute, please browse our -[issues](https://github.com/digital-asset/daml/issues). To build and test DAML: +[issues](https://github.com/digital-asset/daml/issues). To build and test Daml: ### 1. Clone this repository @@ -75,7 +75,7 @@ On Mac if building is causing trouble complaining about missing nix packages, yo ### 4. Installing a local copy -On Linux and Mac run `daml-sdk-head` which installs a version of the SDK with version number `0.0.0`. Set the `version:` field in any DAML project to 0.0.0 and it will use the locally installed one. +On Linux and Mac run `daml-sdk-head` which installs a version of the SDK with version number `0.0.0`. Set the `version:` field in any Daml project to 0.0.0 and it will use the locally installed one. On Windows: diff --git a/SECURITY.md b/SECURITY.md index f4ada07016..ff819f85bb 100644 --- a/SECURITY.md +++ b/SECURITY.md @@ -2,7 +2,7 @@ ## Supported Versions -The latest released version of DAML is supported with security updates. +The latest released version of Daml is supported with security updates. You can find the latest version at: https://docs.daml.com/support/release-notes.html @@ -15,5 +15,5 @@ https://www.digitalasset.com/responsible-disclosure To report an issue that does not have a security impact, open an issue on GitHub: https://github.com/digital-asset/daml/issues/new -For general questions about DAML and/or support requests, please ask in our forum: +For general questions about Daml and/or support requests, please ask in our forum: https://discuss.daml.com/ diff --git a/ci/docker/README.md b/ci/docker/README.md index 542735d09f..08a1292b16 100644 --- a/ci/docker/README.md +++ b/ci/docker/README.md @@ -7,12 +7,12 @@ overwrite the one on Docker Hub should they differ. --> -# Dockerized DAML SDK +# Dockerized Daml SDK > This image is not supported for production use-cases. Please contact Digital > Asset to obtain supported production-ready artifacts. -Digital Asset's [DAML SDK](https://docs.daml.com/) in a can. +Digital Asset's [Daml SDK](https://docs.daml.com/) in a can. ## Tags @@ -36,19 +36,19 @@ repository key of ## Quick start * Ensure Docker is [installed](https://www.docker.com/get-started) -* Check out existing demo DAML project (or use your own): +* Check out existing demo Daml project (or use your own): ``` git clone https://github.com/digital-asset/ex-bond-trading.git cd ex-bond-trading ``` -* Run DAML scenarios: +* Run Daml scenarios: ``` DOCKER_CONTENT_TRUST=1 docker run --rm -it -v $PWD:/data digitalasset/daml-sdk:$SDK_VERSION bash -c "cd \$(mktemp -d) && cp -r /data/* ./ && DAML_SDK_VERSION=$SDK_VERSION daml test" ``` > Note: This image is primarily intended for CI workflows, where the benefits > of caching Docker images can outweigh the awkwardness of the above command. -> For local development, we strongly recommend installing the DAML SDK on the +> For local development, we strongly recommend installing the Daml SDK on the > host development machine instead, by running `curl https://get.daml.com | > bash`. For production use-cases, we strongly recommend using a supported > production binary, which can be obtained by contacting Digital Asset. diff --git a/compatibility/README.md b/compatibility/README.md index 6cdc02c1b8..cc1c2ce050 100644 --- a/compatibility/README.md +++ b/compatibility/README.md @@ -62,17 +62,17 @@ that only iterates through stable versions up to HEAD. This ensures that both individual migrations are correct as well as the migrations from one stable version to the next work as a whole. -#### Backwards-compatibility for DAML Script +#### Backwards-compatibility for Daml Script -We test that the DAML Script runner from a given SDK version can load -DARs built against the DAML Script library from an older SDK. We only +We test that the Daml Script runner from a given SDK version can load +DARs built against the Daml Script library from an older SDK. We only guarantee backwards compatibility here. -#### Backwards-compatibility for DAML Triggers +#### Backwards-compatibility for Daml Triggers -We test that the DAML Trigger runner from a given SDK version can load -DARs built against the DAML Script library from an older SDK. We only +We test that the Daml Trigger runner from a given SDK version can load +DARs built against the Daml Script library from an older SDK. We only guarantee backwards compatibility here. #### Backwards-compatibility for data-dependencies diff --git a/compatibility/bazel_tools/create-daml-app/index.test.ts b/compatibility/bazel_tools/create-daml-app/index.test.ts index b3ec47e150..357dd24c96 100644 --- a/compatibility/bazel_tools/create-daml-app/index.test.ts +++ b/compatibility/bazel_tools/create-daml-app/index.test.ts @@ -106,7 +106,7 @@ const detached = process.platform != "win32"; const npmExeName = process.platform == "win32" ? "npm" : "npm-cli.js"; -// Start the DAML and UI processes before the tests begin. +// Start the Daml and UI processes before the tests begin. // To reduce test times, we reuse the same processes between all the tests. // This means we need to use a different set of parties and a new browser page for each test. beforeAll(async () => { diff --git a/compiler/README.md b/compiler/README.md index a46b6fe052..596b0f8335 100644 --- a/compiler/README.md +++ b/compiler/README.md @@ -1,8 +1,8 @@ -# DAML Compiler +# Daml Compiler This directory contains several libraries used by and the executable for the -DAML compiler. +Daml compiler. ## Libraries -* `daml-lf-ast`: The DAML-LF AST and type checker. +* `daml-lf-ast`: The Daml-LF AST and type checker. diff --git a/compiler/daml-extension/README.md b/compiler/daml-extension/README.md index 13735fb297..f4237f18f1 100644 --- a/compiler/daml-extension/README.md +++ b/compiler/daml-extension/README.md @@ -1,19 +1,19 @@ -# DAML Studio +# Daml Studio -DAML Studio extends Visual Studio Code with the following DAML-specific +Daml Studio extends Visual Studio Code with the following Daml-specific features: -- DAML syntax highlighting +- Daml syntax highlighting - Real-time feedback on parse, name resolution, type-checking and Scenario interpretation errors and viewer for the resulting ledger - Jumping to and peeking at the definition of referenced toplevel functions - Type-information on hover - Renaming of symbols -- DAML snippet support -- Command to generate visualization for DAML project via command palette ctrl + p. +- Daml snippet support +- Command to generate visualization for Daml project via command palette ctrl + p. Please note that this will only install the VSCode extension. Full use of the -above features will also require that you have a working DAML SDK installed, +above features will also require that you have a working Daml SDK installed, which you can get with: ``` @@ -22,12 +22,12 @@ curl -s https://get.daml.com | sh To see graphs from `daml.visualize` command please install [Graphivz plugin](https://marketplace.visualstudio.com/items?itemName=EFanZh.graphviz-preview). -For more information on DAML please see [docs.daml.com](https://docs.daml.com). +For more information on Daml please see [docs.daml.com](https://docs.daml.com). ## Troubleshooting -The DAML language server log output is available under the "Output" panel -(View->Output). Select "DAML Language Server" from the dropdown in the panel +The Daml language server log output is available under the "Output" panel +(View->Output). Select "Daml Language Server" from the dropdown in the panel to see the log. ## Debugging diff --git a/compiler/daml-extension/extension_guide.md b/compiler/daml-extension/extension_guide.md index 92a0cd98b1..1b8c540f11 100644 --- a/compiler/daml-extension/extension_guide.md +++ b/compiler/daml-extension/extension_guide.md @@ -1,11 +1,11 @@ -# DAML Syntax Highlighter Dev Guide -In depth explanation syntax highlighting can be found on VS Code [website](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide). This document contains a short guide and explanations of choices made for DAML plugin. +# Daml Syntax Highlighter Dev Guide +In depth explanation syntax highlighting can be found on VS Code [website](https://code.visualstudio.com/api/language-extensions/syntax-highlight-guide). This document contains a short guide and explanations of choices made for Daml plugin. ## Overview VS code uses [TextMate Grammar](https://macromates.com/manual/en/language_grammars). File processing is based on [Oniguruma regular expressions](https://macromates.com/manual/en/regular_expressions). These are generally written as JSON or [PList format](https://developer.apple.com/library/archive/documentation/Cocoa/Conceptual/PropertyLists/UnderstandXMLPlist/UnderstandXMLPlist.html). ## Grammar File Format. -VS Code supports PList, JSON and YAML files to specify grammar. DAML VS code extension makes use of PList, as the haskell [extension](https://github.com/JustusAdam/language-haskell) and also using Plist makes having comments easy at the expense of making it more verbose. +VS Code supports PList, JSON and YAML files to specify grammar. Daml VS code extension makes use of PList, as the haskell [extension](https://github.com/JustusAdam/language-haskell) and also using Plist makes having comments easy at the expense of making it more verbose. ## Testing @@ -17,7 +17,7 @@ Example: ` employee : Party -- employee -> source.daml , Party -> storage.type.d - `employee ->` Token employee is scoped to `source.daml` this can be viewed via VS code scope inspector tool - `Party ->` Token party has three nested scopes and in the scope inspector they are listed in order -## DAML Specific constructs +## Daml Specific constructs - Colon and double colon Daml considers `::` a cons operator and `:` as type operator. - Keywords - there are a few daml specific keywords (eg: template, key, maintainer.). diff --git a/compiler/daml-extension/src/extension.ts b/compiler/daml-extension/src/extension.ts index 595c188838..a84ecbbd0d 100644 --- a/compiler/daml-extension/src/extension.ts +++ b/compiler/daml-extension/src/extension.ts @@ -134,7 +134,7 @@ function checkVersionUpgrade(version1: string, version2: string) { return o.compare(comps2, comps1) > 0; } -// Show the release notes from the DAML Blog. +// Show the release notes from the Daml Blog. // We display the HTML in a new editor tab using a "webview": // https://code.visualstudio.com/api/extension-guides/webview async function showReleaseNotes(version: string) { @@ -144,7 +144,7 @@ async function showReleaseNotes(version: string) { if (res.ok) { const panel = vscode.window.createWebviewPanel( 'releaseNotes', // Identifies the type of the webview. Used internally - `New DAML SDK ${version} Available`, // Title of the panel displayed to the user + `New Daml SDK ${version} Available`, // Title of the panel displayed to the user vscode.ViewColumn.One, // Editor column to show the new webview panel in {} // No webview options for now ); @@ -179,7 +179,7 @@ function visualize() { } } else { - vscode.window.showInformationMessage("Please open a DAML module to be visualized and then run the command") + vscode.window.showInformationMessage("Please open a Daml module to be visualized and then run the command") } } @@ -207,7 +207,7 @@ function addIfInConfig(config:vscode.WorkspaceConfiguration, baseArgs: string[], export function createLanguageClient(config: vscode.WorkspaceConfiguration, telemetryConsent: boolean|undefined): LanguageClient { // Options to control the language client let clientOptions: LanguageClientOptions = { - // Register the server for DAML + // Register the server for Daml documentSelector: ["daml"], }; @@ -221,7 +221,7 @@ export function createLanguageClient(config: vscode.WorkspaceConfiguration, tele if (fs.existsSync(damlCmdPath)) { command = damlCmdPath; } else { - vscode.window.showErrorMessage("Failed to start the DAML language server. Make sure the assistant is installed."); + vscode.window.showErrorMessage("Failed to start the Daml language server. Make sure the assistant is installed."); throw new Error("Failed to locate assistant."); } } @@ -245,11 +245,11 @@ export function createLanguageClient(config: vscode.WorkspaceConfiguration, tele ]); if(config.get('experimental')){ - vscode.window.showWarningMessage('DAMLs Experimental feature flag is enabled, this may cause instability') + vscode.window.showWarningMessage('Daml\'s Experimental feature flag is enabled, this may cause instability') } return new LanguageClient( - 'daml-language-server', 'DAML Language Server', + 'daml-language-server', 'Daml Language Server', { args: serverArgs, command: command, options: {cwd: vscode.workspace.rootPath }}, clientOptions, true); } @@ -271,7 +271,7 @@ let keepAliveInterval = 60000; // Send KA every 60s. // Wait for max 120s before restarting process. // NOTE(JM): If you change this, make sure to also change the server-side timeouts to get // detailed errors rather than cause a restart. -// Legacy DAML timeout for language server is defined in +// Legacy Daml timeout for language server is defined in // DA.Daml.LanguageServer. let keepAliveTimeout = 120000; @@ -287,7 +287,7 @@ function stopKeepAliveWatchdog() { function keepAlive() { function killDamlc() { vscode.window.showErrorMessage( - "Sorry, you’ve hit a bug requiring a DAML Language Server restart. We’d greatly appreciate a bug report — ideally with example files." + "Sorry, you’ve hit a bug requiring a Daml Language Server restart. We’d greatly appreciate a bug report — ideally with example files." ); // Terminate the damlc process with SIGTERM. The language client will restart the process automatically. @@ -461,7 +461,7 @@ let telemetryOverride = { fromConsent: "From consent popup" } const options = { - yes : "Yes, I would like to help improve DAML!", + yes : "Yes, I would like to help improve Daml!", no : "No, I'd rather not.", read : "I'd like to read the privacy policy first." } diff --git a/compiler/daml-extension/syntaxes/README.md b/compiler/daml-extension/syntaxes/README.md index a953902dfd..30000b7b9b 100644 --- a/compiler/daml-extension/syntaxes/README.md +++ b/compiler/daml-extension/syntaxes/README.md @@ -2,13 +2,13 @@ Some notes on the files you find here. - - `daml.json` defines the syntax highlighting rules used before DAML + - `daml.json` defines the syntax highlighting rules used before Daml 1.2 (`daml.configuration.json` in the parent directory configuration properties); - `daml12.tmLanguage.xml` defines the syntax highlight rules used - starting with DAML 1.2; + starting with Daml 1.2; - These rules are in fact general Haskell syntax highlighting - rules augmented with DAML specific keywords; + rules augmented with Daml specific keywords; - `daml12.tmLanguage.xml` was produced from the file `daml12.tmLanguage` by means of the VS-code extension, ["TextMate diff --git a/compiler/daml-lf-verify/README.rst b/compiler/daml-lf-verify/README.rst index 34ed4f0adb..f4bd3be317 100644 --- a/compiler/daml-lf-verify/README.rst +++ b/compiler/daml-lf-verify/README.rst @@ -1,10 +1,10 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Verification Tool +Daml Verification Tool ====================== -This project performs fully automated formal verification of DAML code. +This project performs fully automated formal verification of Daml code. Provided with a choice of a template and a field of a (potentially different) template, the verification tool employs symbolic execution and an SMT solver, to verify whether the given choice always preserves the total amount of the given field. This allows it to automatically answer @@ -14,13 +14,13 @@ money out of thin air?" Installation ============ -- Install the `DAML development dependecies`_. +- Install the `Daml development dependecies`_. - Install the `Z3 SMT solver`_. Note that on Linux, you can alternatively install Z3 using ``sudo apt install z3``. -.. _DAML development dependecies: https://github.com/digital-asset/daml/ +.. _Daml development dependecies: https://github.com/digital-asset/daml/ .. _Z3 SMT solver: https://github.com/Z3Prover/z3 Running the Verification Tool diff --git a/compiler/damlc/README.md b/compiler/damlc/README.md index e4608af96d..a041717b35 100644 --- a/compiler/damlc/README.md +++ b/compiler/damlc/README.md @@ -4,7 +4,7 @@ The following list is ordered topologicaly based on the dependency graph. ### daml-preprocessor -`daml-preprocessor` contains the DAML preprocessor which runs our version of the +`daml-preprocessor` contains the Daml preprocessor which runs our version of the `record-dot-preprocessor` and the preprocessor for generating `Generic` instances. The preprocessor also performs a few additional checks, e.g., that you do not import internal modules. @@ -23,12 +23,12 @@ making everything depend on `daml-preprocessor`. ### daml-lf-conversion -`daml-lf-conversion` handles the conversion from GHC’s Core to DAML-LF. +`daml-lf-conversion` handles the conversion from GHC’s Core to Daml-LF. ### daml-ide-core -`daml-ide-core` is a wrapper around `ghcide` that adds DAML-specific -rules such as rules for producing `DAML-LF`. +`daml-ide-core` is a wrapper around `ghcide` that adds Daml-specific +rules such as rules for producing `Daml-LF`. ### daml-doc @@ -125,10 +125,10 @@ bazel build //compiler/damlc:daml-base-docs This creates a tarball containing RST (ReStructured Text) docs, and a hoogle database. -## DAML Packages and Database +## Daml Packages and Database -A DAML project is compiled to a DAML package and can be distributed as a DAML archive (DAR). This is -essentially a zip archive containing the DAML source code of the library together with the compiled +A Daml project is compiled to a Daml package and can be distributed as a Daml archive (DAR). This is +essentially a zip archive containing the Daml source code of the library together with the compiled .dalf file. The damlc package loading mechanism is based on GHC's package database and uses the same .conf file format. GHC's package database is documented at @@ -137,8 +137,8 @@ https://downloads.haskell.org/~ghc/latest/docs/html/users_guide/packages.html. ### Loading packages `damlc` loads packages from a package database given by the option `--package-db`. It creates a -map from package name to DAML-LF file from all the contained .dalf files in this directory and links -the created DAML-LF against these packages. It uses the .hi interface files created upon +map from package name to Daml-LF file from all the contained .dalf files in this directory and links +the created Daml-LF against these packages. It uses the .hi interface files created upon installation of the packages for type checking. ### Base packages diff --git a/compiler/damlc/base-hoogle-template.txt b/compiler/damlc/base-hoogle-template.txt index a499c871f5..087b395a6c 100644 --- a/compiler/damlc/base-hoogle-template.txt +++ b/compiler/damlc/base-hoogle-template.txt @@ -4,7 +4,7 @@ -- (C) Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. -- All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited. --- | DAML standard library. +-- | Daml standard library. @url {{base-url}} @package daml-stdlib @version 1.2.0 diff --git a/compiler/damlc/base-md-template.md b/compiler/damlc/base-md-template.md index 486a3935c2..381bb2aa0b 100644 --- a/compiler/damlc/base-md-template.md +++ b/compiler/damlc/base-md-template.md @@ -1,11 +1,11 @@ # The standard library -The DAML standard library is a collection of DAML modules that can be used to implement concrete applications. +The Daml standard library is a collection of Daml modules that can be used to implement concrete applications. ## Usage -The standard library is included in the DAML compiler so it can +The standard library is included in the Daml compiler so it can be used straight out of the box. You can import modules from the standard library just like your own, for example: ``` diff --git a/compiler/damlc/base-rst-index-template.rst b/compiler/damlc/base-rst-index-template.rst index 0474ed7015..805e1bfce5 100644 --- a/compiler/damlc/base-rst-index-template.rst +++ b/compiler/damlc/base-rst-index-template.rst @@ -6,9 +6,9 @@ The standard library ==================== -The DAML standard library is a collection of DAML modules that are bundled with the SDK, and can be used to implement DAML applications. +The Daml standard library is a collection of Daml modules that are bundled with the SDK, and can be used to implement Daml applications. -The :ref:`Prelude ` module is imported automatically in every DAML module. Other modules must be imported manually, just like your own project's modules. For example: +The :ref:`Prelude ` module is imported automatically in every Daml module. Other modules must be imported manually, just like your own project's modules. For example: .. code-block:: daml diff --git a/compiler/damlc/daml-prim-src/Control/Exception/Base.daml b/compiler/damlc/daml-prim-src/Control/Exception/Base.daml index 535d9f5cdb..0f575377d5 100644 --- a/compiler/damlc/daml-prim-src/Control/Exception/Base.daml +++ b/compiler/damlc/daml-prim-src/Control/Exception/Base.daml @@ -26,7 +26,7 @@ import GHC.Types -- https://hackage.haskell.org/package/base-4.12.0.0/docs/Control-Exception-Base.html#g:13 -- All of them take UTF8-encoded C strings of type 'Addr#' in ghc's Haskell -- base library. Here, we must pass them 'Text' though to be able to call --- 'error'. The conversion to DAML-LF basically pretends that 'Addr#' and +-- 'error'. The conversion to Daml-LF basically pretends that 'Addr#' and -- 'Text' are the same type by lifting the C strings into 'Text'. recSelError, recConError, runtimeError, nonExhaustiveGuardsError, patError, noMethodBindingError, absentError, typeError : forall liftedRep r . Text -> r recSelError s = error (append "No match in record selector " s) @@ -43,7 +43,7 @@ absentSumFieldError = absentError " in unboxed sum." {- This function is copied from the same place as the functions above. -It's also modified to work with DAMLs Text type. +It's also modified to work with Daml's Text type. (untangle coded message) expects "coded" to be of the form "location|details" diff --git a/compiler/damlc/daml-prim-src/DA/Internal/Erased.daml b/compiler/damlc/daml-prim-src/DA/Internal/Erased.daml index b16265f46b..27e603cd2e 100644 --- a/compiler/damlc/daml-prim-src/DA/Internal/Erased.daml +++ b/compiler/damlc/daml-prim-src/DA/Internal/Erased.daml @@ -9,5 +9,5 @@ module DA.Internal.Erased import GHC.Types() --- | Erased type used for kinds not supported by DAML-LF. +-- | Erased type used for kinds not supported by Daml-LF. data Erased diff --git a/compiler/damlc/daml-prim-src/DA/Internal/PromotedText.daml b/compiler/damlc/daml-prim-src/DA/Internal/PromotedText.daml index 6daef50f79..767d10b64d 100644 --- a/compiler/damlc/daml-prim-src/DA/Internal/PromotedText.daml +++ b/compiler/damlc/daml-prim-src/DA/Internal/PromotedText.daml @@ -9,10 +9,10 @@ module DA.Internal.PromotedText import GHC.Types() --- | Proxy type used to support type-level strings in DAML. +-- | Proxy type used to support type-level strings in Daml. -- -- A type-level string "foo" will be represented as --- `PromotedText {"foo": Unit}` in DAML-LF, where +-- `PromotedText {"foo": Unit}` in Daml-LF, where -- `{"_foo": Unit}` is an LF struct with a single field -- of unit type. The field name represents the type-level -- string, after adding an underscore and some name @@ -20,7 +20,7 @@ import GHC.Types() -- more details. -- -- Note that there's no way to construct the requisite --- LF struct directly in DAML. In DAML, instead of using +-- LF struct directly in Daml. In Daml, instead of using -- this type, you should just use type-level strings -- directly. data PromotedText t diff --git a/compiler/damlc/daml-prim-src/DA/Types.daml b/compiler/damlc/daml-prim-src/DA/Types.daml index eea4dd24cb..c0ee492215 100644 --- a/compiler/damlc/daml-prim-src/DA/Types.daml +++ b/compiler/damlc/daml-prim-src/DA/Types.daml @@ -22,8 +22,8 @@ import GHC.Types() data Either a b = Left a | Right b --- NOTE(MH): These types are not supposed to be used in DAML. The converter to --- DAML-LF rewrites the types above to them, so they are visible to non-DAML users. +-- NOTE(MH): These types are not supposed to be used in Daml. The converter to +-- Daml-LF rewrites the types above to them, so they are visible to non-Daml users. data Tuple2 a b = Tuple2{_1 : a; _2 : b} data Tuple3 a b c = diff --git a/compiler/damlc/daml-prim-src/GHC/Base.daml b/compiler/damlc/daml-prim-src/GHC/Base.daml index c5aad57dd9..873d08e497 100644 --- a/compiler/damlc/daml-prim-src/GHC/Base.daml +++ b/compiler/damlc/daml-prim-src/GHC/Base.daml @@ -31,7 +31,7 @@ getTag : a -> Int# getTag = magic @"getTag" -- | HIDE This is referenced from error messages generated by ghc. Not --- meant to be used in DAML, and not exported in Prelude. Use <> instead. +-- meant to be used in Daml, and not exported in Prelude. Use <> instead. (++) : Text -> Text -> Text (++) = primitive @"BEAppendText" infixr 5 ++ diff --git a/compiler/damlc/daml-prim-src/GHC/CString.daml b/compiler/damlc/daml-prim-src/GHC/CString.daml index 8d6e610129..5965d07e40 100644 --- a/compiler/damlc/daml-prim-src/GHC/CString.daml +++ b/compiler/damlc/daml-prim-src/GHC/CString.daml @@ -6,7 +6,7 @@ -- | HIDE -- An internal module based on ghc's base.GHC.CString. It is used for string --- literals by ghc. All definitions are removed during conversion to DAML-LF. +-- literals by ghc. All definitions are removed during conversion to Daml-LF. module GHC.CString ( unpackCString# , unpackCStringUtf8# diff --git a/compiler/damlc/daml-prim-src/GHC/Err.daml b/compiler/damlc/daml-prim-src/GHC/Err.daml index c537bdaf06..914b6208cc 100644 --- a/compiler/damlc/daml-prim-src/GHC/Err.daml +++ b/compiler/damlc/daml-prim-src/GHC/Err.daml @@ -17,7 +17,7 @@ import GHC.Types -- | `error` stops execution and displays the given error message. -- -- If called within a transaction, it will abort the current transaction. --- Outside of a transaction (scenarios, DAML Script or DAML Triggers) +-- Outside of a transaction (scenarios, Daml Script or Daml Triggers) -- it will stop the whole scenario/script/trigger. error : Text -> a error = primitive @"BEError" diff --git a/compiler/damlc/daml-prim-src/GHC/Types.daml b/compiler/damlc/daml-prim-src/GHC/Types.daml index 3317334aa2..a7268bfb95 100644 --- a/compiler/damlc/daml-prim-src/GHC/Types.daml +++ b/compiler/damlc/daml-prim-src/GHC/Types.daml @@ -80,7 +80,7 @@ ifThenElse c t f = case c of True -> t; False -> f -- NOTE(MH): We're remove all the produced runtime represenations when --- converting to DAML-LF but still need them here for type checking. +-- converting to Daml-LF but still need them here for type checking. {- Note [Runtime representation of modules and tycons] ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ @@ -137,11 +137,11 @@ data TyCon = TyCon Word# Word# -- Fingerprint KindRep -- A representation of the type's kind --- | HIDE A DAML-LF call to an external package +-- | HIDE A Daml-LF call to an external package external : forall (f : Symbol) b. b external = external --deleted by the compiler --- | HIDE A DAML-LF primitive +-- | HIDE A Daml-LF primitive primitive : forall (f : Symbol) b. b primitive = primitive -- deleted by the compiler @@ -149,7 +149,7 @@ primitive = primitive -- deleted by the compiler magic : forall (f : Symbol) b. b magic = magic -- deleted by the compiler --- | HIDE Dummy type to mark types built into DAML-LF. +-- | HIDE Dummy type to mark types built into Daml-LF. data Opaque = Opaque -- | A type for text strings, that can represent any unicode code point. diff --git a/compiler/damlc/daml-stdlib-src/DA/Either.daml b/compiler/damlc/daml-stdlib-src/DA/Either.daml index 9071682765..1e59ad2468 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Either.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Either.daml @@ -61,10 +61,10 @@ eitherToOptional : Either a b -> Optional b eitherToOptional (Left _) = None eitherToOptional (Right x) = Some x -- | Deprecated. -{-# DEPRECATED maybeToEither "DAML 1.2 compatibility helper, use 'optionalToEither' instead of 'maybeToEither'" #-} +{-# DEPRECATED maybeToEither "Daml 1.2 compatibility helper, use 'optionalToEither' instead of 'maybeToEither'" #-} maybeToEither : a -> Optional b -> Either a b maybeToEither = optionalToEither -- | Deprecated. -{-# DEPRECATED eitherToMaybe "DAML 1.2 compatibility helper, use 'eitherToOptional' instead of 'eitherToMaybe'" #-} +{-# DEPRECATED eitherToMaybe "Daml 1.2 compatibility helper, use 'eitherToOptional' instead of 'eitherToMaybe'" #-} eitherToMaybe : Either a b -> Optional b eitherToMaybe = eitherToOptional diff --git a/compiler/damlc/daml-stdlib-src/DA/Generics.daml b/compiler/damlc/daml-stdlib-src/DA/Generics.daml index 89e68f8941..e4e4e6e1b2 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Generics.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Generics.daml @@ -277,7 +277,7 @@ data DecidedStrictness = DecidedLazy ) -- | Representable types of kind @*@. --- This class is derivable in DAML with the @DeriveGeneric@ flag on. +-- This class is derivable in Daml with the @DeriveGeneric@ flag on. -- -- A 'Generic' instance must satisfy the following laws: -- diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Compatible.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Compatible.daml index 7647133fe3..6ececc4864 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Compatible.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Compatible.daml @@ -11,102 +11,102 @@ module DA.Internal.Compatible where import DA.Internal.Prelude import DA.Internal.LF -{-# DEPRECATED Datetime "DAML compatibility helper, use Time instead of 'Datetime'" #-} +{-# DEPRECATED Datetime "Daml compatibility helper, use Time instead of 'Datetime'" #-} type Datetime = Time -{-# DEPRECATED Tuple "DAML compatibility helper, use (a,b) instead of 'Tuple a b'" #-} +{-# DEPRECATED Tuple "Daml compatibility helper, use (a,b) instead of 'Tuple a b'" #-} type Tuple a b = (a,b) -{-# DEPRECATED tuple "DAML compatibility helper, use (,)" #-} +{-# DEPRECATED tuple "Daml compatibility helper, use (,)" #-} tuple : a -> b -> (a,b) tuple = (,) -{-# DEPRECATED Tuple3 "DAML compatibility helper, use (a,b,c) instead of 'Tuple3 a b c'" #-} +{-# DEPRECATED Tuple3 "Daml compatibility helper, use (a,b,c) instead of 'Tuple3 a b c'" #-} type Tuple3 a b c = (a,b,c) -{-# DEPRECATED tuple3 "DAML compatibility helper, use (,,)" #-} +{-# DEPRECATED tuple3 "Daml compatibility helper, use (,,)" #-} tuple3 : a -> b -> c -> (a,b,c) tuple3 = (,,) -{-# DEPRECATED List "DAML compatibility helper, use [a] instead of 'List a'" #-} +{-# DEPRECATED List "Daml compatibility helper, use [a] instead of 'List a'" #-} type List a = [a] -{-# DEPRECATED nil "DAML compatibility helper, use []" #-} +{-# DEPRECATED nil "Daml compatibility helper, use []" #-} nil : [a] nil = [] -{-# DEPRECATED cons "DAML compatibility helper, use (::), which also works infix as 'x :: xs'" #-} +{-# DEPRECATED cons "Daml compatibility helper, use (::), which also works infix as 'x :: xs'" #-} cons : a -> [a] -> [a] cons = (::) -{-# DEPRECATED does "DAML compatibility helper, does is redundant and the first argument is ignored" #-} +{-# DEPRECATED does "Daml compatibility helper, does is redundant and the first argument is ignored" #-} does : Party -> Update a -> Update a does _ x = x -{-# DEPRECATED toText "DAML compatibility helper, use 'show' instead" #-} +{-# DEPRECATED toText "Daml compatibility helper, use 'show' instead" #-} toText : Show a => a -> Text toText = show -{-# DEPRECATED Integer "DAML compatibility helper, use 'Int' instead of 'Integer'" #-} +{-# DEPRECATED Integer "Daml compatibility helper, use 'Int' instead of 'Integer'" #-} type Integer = Int -{-# DEPRECATED toInteger "DAML compatibility helper, use 'truncate' instead" #-} +{-# DEPRECATED toInteger "Daml compatibility helper, use 'truncate' instead" #-} toInteger : Decimal -> Int toInteger = truncate -{-# DEPRECATED mapU "DAML compatibility helper, use 'mapA' instead of 'mapU'" #-} +{-# DEPRECATED mapU "Daml compatibility helper, use 'mapA' instead of 'mapU'" #-} mapU : Applicative m => (a -> m b) -> [a] -> m [b] mapU = mapA -{-# DEPRECATED forU "DAML compatibility helper, use 'forA' instead of 'forU'" #-} +{-# DEPRECATED forU "Daml compatibility helper, use 'forA' instead of 'forU'" #-} forU : Applicative m => [a] -> (a -> m b) -> m [b] forU = forA -{-# DEPRECATED mapM "DAML compatibility helper, use 'mapA' instead of 'mapM'" #-} +{-# DEPRECATED mapM "Daml compatibility helper, use 'mapA' instead of 'mapM'" #-} mapM : Applicative m => (a -> m b) -> [a] -> m [b] mapM = mapA -{-# DEPRECATED forM "DAML compatibility helper, use 'forA' instead of 'forM'" #-} +{-# DEPRECATED forM "Daml compatibility helper, use 'forA' instead of 'forM'" #-} forM : Applicative m => [a] -> (a -> m b) -> m [b] forM = forA -{-# DEPRECATED Monad "DAML compatibility helper, use 'Action' instead of 'Monad'" #-} +{-# DEPRECATED Monad "Daml compatibility helper, use 'Action' instead of 'Monad'" #-} type Monad = Action -{-# DEPRECATED String "DAML compatibility helper, use 'Text' instead of 'String'" #-} +{-# DEPRECATED String "Daml compatibility helper, use 'Text' instead of 'String'" #-} type String = Text -{-# DEPRECATED MonadFail "DAML compatibility helper, use 'ActionFail' instead of 'MonadFail'" #-} +{-# DEPRECATED MonadFail "Daml compatibility helper, use 'ActionFail' instead of 'MonadFail'" #-} type MonadFail = ActionFail -{-# DEPRECATED Num "DAML compatibility helper, use 'Number' instead of 'Num'" #-} +{-# DEPRECATED Num "Daml compatibility helper, use 'Number' instead of 'Num'" #-} type Num = Number -{-# DEPRECATED commits "DAML compatibility helper, use 'submit' instead of 'commits'" #-} +{-# DEPRECATED commits "Daml compatibility helper, use 'submit' instead of 'commits'" #-} infixr 0 `commits` commits : Party -> Update a -> Scenario a commits = submit -{-# DEPRECATED fails "DAML compatibility helper, use 'submitMustFail' instead of 'fails'" #-} +{-# DEPRECATED fails "Daml compatibility helper, use 'submitMustFail' instead of 'fails'" #-} infixr 0 `fails` fails : Party -> Update a -> Scenario () fails = submitMustFail -{-# DEPRECATED test "DAML compatibility helper, use 'scenario' instead" #-} +{-# DEPRECATED test "Daml compatibility helper, use 'scenario' instead" #-} test : Scenario a -> Scenario a test = identity -{-# DEPRECATED Maybe "DAML compatibility helper, use 'Optional' instead of 'Maybe'" #-} +{-# DEPRECATED Maybe "Daml compatibility helper, use 'Optional' instead of 'Maybe'" #-} type Maybe = Optional -{-# DEPRECATED Nothing "DAML compatibility helper, use 'None' instead of 'Nothing'" #-} +{-# DEPRECATED Nothing "Daml compatibility helper, use 'None' instead of 'Nothing'" #-} pattern Nothing : Maybe a pattern Nothing = None -{-# DEPRECATED Just "DAML compatibility helper, use 'Some' instead of 'Just'" #-} +{-# DEPRECATED Just "Daml compatibility helper, use 'Some' instead of 'Just'" #-} pattern Just : a -> Maybe a pattern Just x = Some x -{-# DEPRECATED maybe "DAML compatibility helper, use 'optional' instead of 'maybe'" #-} +{-# DEPRECATED maybe "Daml compatibility helper, use 'optional' instead of 'maybe'" #-} maybe : b -> (a -> b) -> Maybe a -> b maybe = optional diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Date.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Date.daml index 30efdf3a10..d56b8ba724 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Date.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Date.daml @@ -3,7 +3,7 @@ {-# LANGUAGE NoImplicitPrelude #-} --- | MOVE Prelude DAML-LF types and primitives, apart from templates/contracts. +-- | MOVE Prelude Daml-LF types and primitives, apart from templates/contracts. module DA.Internal.Date where import DA.Internal.Prelude diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml index a8cc22cb29..692a83fc29 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/LF.daml @@ -5,7 +5,7 @@ {-# LANGUAGE NoImplicitPrelude #-} {-# OPTIONS -Wno-unused-binds #-} -- the opaque constructors are not exported --- | MOVE Prelude DAML-LF types and primitives, apart from templates/contracts. +-- | MOVE Prelude Daml-LF types and primitives, apart from templates/contracts. module DA.Internal.LF ( Party , getParty @@ -51,13 +51,13 @@ import GHC.Stack.Types (HasCallStack) import GHC.Types (Opaque, Symbol, primitive, magic) import DA.Internal.Prelude --- This module should not define any new types. It should only provide the DAML equivalent for LF +-- This module should not define any new types. It should only provide the Daml equivalent for LF -- builtins using Opaque. -- | The `Party` type represents a party to a contract. data Party = Party Opaque --- Note that before DAML-LF 1.2 BEToText added single quotes around the party. +-- Note that before Daml-LF 1.2 BEToText added single quotes around the party. -- now it does not, and the old behavior has been renamed BEPartyToQuotedText. -- Since we want this to work with both versions, keep the old behavior. instance Show Party where show = primitive @"BEPartyToQuotedText" @@ -75,7 +75,7 @@ partyToText : Party -> Text partyToText = primitive @"BEToText" -- | Converts a `Text` to `Party`. It returns `None` if the provided text contains --- any forbidden characters. See DAML-LF spec for a specification on which characters +-- any forbidden characters. See Daml-LF spec for a specification on which characters -- are allowed in parties. Note that this function accepts text _without_ -- single quotes. -- @@ -92,7 +92,7 @@ partyToText = primitive @"BEToText" -- ∀ txt p. partyFromText txt = Some p ==> partyToText p = txt -- ``` -- --- This function will crash at runtime if you compile DAML to DAML-LF < 1.2. +-- This function will crash at runtime if you compile Daml to Daml-LF < 1.2. partyFromText : Text -> Optional Party partyFromText = primitive @"BEPartyFromText" @@ -150,7 +150,7 @@ instance Show (ContractId a) where show _ = "" #endif --- | HIDE This is currently used in the internals of DAML script and DAML triggers +-- | HIDE This is currently used in the internals of Daml script and Daml triggers -- but not really something that we want to expose to users. coerceContractId : ContractId a -> ContractId b coerceContractId = primitive @"BECoerceContractId" @@ -239,11 +239,11 @@ infixr 0 `submitMustFail` scenario : Scenario a -> Scenario a scenario = identity --- | HIDE A dummy type for the DAML-LF structural record type +-- | HIDE A dummy type for the Daml-LF structural record type -- ``. data Pair (f1 : Symbol) (f2 : Symbol) a1 a2 = Pair Opaque --- | HIDE Function to turn a DAML-LF structural record type into a DAML pair. +-- | HIDE Function to turn a Daml-LF structural record type into a Daml pair. unpackPair : forall f1 f2 a1 a2. Pair f1 f2 a1 a2 -> (a1, a2) unpackPair = magic @"unpackPair" diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Prelude.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Prelude.daml index 1613a29d88..6c26d17631 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Prelude.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Prelude.daml @@ -79,7 +79,7 @@ class Functor f => Applicative f where -- in imperative languages. (>>) : Action m => m a -> m b -> m b -- NOTE(MH): We need an `Action` constraint here rather than an `Applicative` --- constrait since the conversion to DAML-LF rewrites `A >> B` into +-- constrait since the conversion to Daml-LF rewrites `A >> B` into -- `A >>= \_ -> B`. This is to make `(>>)` lazy in its second argument and -- hence give `do A; B` the desired semantics where `B` is not evaluated if -- `A` short-circuits the monad computation.. diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Template.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Template.daml index cc7b32e4a3..0fb88253de 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Template.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Template.daml @@ -6,7 +6,7 @@ {-# LANGUAGE NoImplicitPrelude #-} {-# LANGUAGE ScopedTypeVariables #-} --- | MOVE Prelude DAML-LF primitives, just templates/contracts +-- | MOVE Prelude Daml-LF primitives, just templates/contracts module DA.Internal.Template where -- This module should only define stable types. diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Template/Functions.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Template/Functions.daml index 24e582b126..4fc5be723d 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Template/Functions.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Template/Functions.daml @@ -10,7 +10,7 @@ -- which provides functions and typeclasses. -- DA.Internal.Template ends up in its own module with -- a fixed package id so that the hash of the types does not change. --- | MOVE Prelude DAML-LF primitives, just templates/contracts +-- | MOVE Prelude Daml-LF primitives, just templates/contracts module DA.Internal.Template.Functions where #ifdef DAML_ANY_TYPE @@ -75,19 +75,19 @@ class HasArchive t where -- | Archive the contract with the given contract ID. archive : ContractId t -> Update () --- | Exposes `templateTypeRep` function in DAML-LF 1.7 or later. +-- | Exposes `templateTypeRep` function in Daml-LF 1.7 or later. -- Part of the `Template` constraint. class HasTemplateTypeRep t where -- | HIDE _templateTypeRep : proxy t -> TypeRep --- | Exposes `toAnyTemplate` function in DAML-LF 1.7 or later. +-- | Exposes `toAnyTemplate` function in Daml-LF 1.7 or later. -- Part of the `Template` constraint. class HasToAnyTemplate t where -- | HIDE _toAnyTemplate : t -> Any --- | Exposes `fromAnyTemplate` function in DAML-LF 1.7 or later. +-- | Exposes `fromAnyTemplate` function in Daml-LF 1.7 or later. -- Part of the `Template` constraint. class HasFromAnyTemplate t where -- | HIDE @@ -110,13 +110,13 @@ class HasExercise t c r | t c -> r where -- | Exercise a choice on the contract with the given contract ID. exercise : ContractId t -> c -> Update r --- | Exposes `toAnyChoice` function for DAML-LF 1.7 or later. +-- | Exposes `toAnyChoice` function for Daml-LF 1.7 or later. -- Part of the `Choice` constraint. class HasToAnyChoice t c r | t c -> r where -- | HIDE _toAnyChoice : proxy t -> c -> Any --- | Exposes `fromAnyChoice` function for DAML-LF 1.7 or later. +-- | Exposes `fromAnyChoice` function for Daml-LF 1.7 or later. -- Part of the `Choice` constraint. class HasFromAnyChoice t c r | t c -> r where -- | HIDE @@ -178,13 +178,13 @@ class HasMaintainer t k | t -> k where maintainer : forall t k. HasMaintainer t k => k -> [Party] maintainer = _maintainer ([] : [t]) --- | Exposes `toAnyContractKey` function in DAML-LF 1.7 or later. +-- | Exposes `toAnyContractKey` function in Daml-LF 1.7 or later. -- Part of the `TemplateKey` constraint. class HasToAnyContractKey t k | t -> k where -- | HIDE _toAnyContractKey : proxy t -> k -> Any --- | Exposes `fromAnyContractKey` function in DAML-LF 1.7 or later. +-- | Exposes `fromAnyContractKey` function in Daml-LF 1.7 or later. -- Part of the `TemplateKey` constraint. class HasFromAnyContractKey t k | t -> k where -- | HIDE @@ -261,14 +261,14 @@ deriving instance Ord TemplateTypeRep -- | Wrap the template in `AnyTemplate`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. toAnyTemplate : HasToAnyTemplate t => t -> AnyTemplate toAnyTemplate x = AnyTemplate (_toAnyTemplate x) -- | Extract the underlying template from `AnyTemplate` if the type matches -- or return `None`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. fromAnyTemplate : HasFromAnyTemplate t => AnyTemplate -> Optional t fromAnyTemplate (AnyTemplate x) = _fromAnyTemplate x @@ -277,7 +277,7 @@ fromAnyTemplate (AnyTemplate x) = _fromAnyTemplate x -- You must pass the template type `t` using an explicit type application. -- For example `toAnyChoice @Account Withdraw`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. toAnyChoice : forall t c r. (HasTemplateTypeRep t, HasToAnyChoice t c r) => c -> AnyChoice toAnyChoice c = AnyChoice @@ -290,7 +290,7 @@ toAnyChoice c = -- You must pass the template type `t` using an explicit type application. -- For example `fromAnyChoice @Account choice`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. fromAnyChoice : forall t c r. (HasTemplateTypeRep t, HasFromAnyChoice t c r) => AnyChoice -> Optional c fromAnyChoice (AnyChoice any typeRep) | Some c <- _fromAnyChoice ([] : [t]) any @@ -302,7 +302,7 @@ fromAnyChoice (AnyChoice any typeRep) -- You must pass the template type `t` using an explicit type application. -- For example `toAnyContractKey @Proposal k`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. toAnyContractKey : forall t k. (HasTemplateTypeRep t, HasToAnyContractKey t k) => k -> AnyContractKey toAnyContractKey k = AnyContractKey @@ -315,7 +315,7 @@ toAnyContractKey k = -- You must pass the template type `t` using an explicit type application. -- For example `fromAnyContractKey @Proposal k`. -- --- Only available for DAML-LF 1.7 or later. +-- Only available for Daml-LF 1.7 or later. fromAnyContractKey : forall t k. (HasTemplateTypeRep t, HasFromAnyContractKey t k) => AnyContractKey -> Optional k fromAnyContractKey (AnyContractKey any rep) | Some k <- _fromAnyContractKey ([] : [t]) any diff --git a/compiler/damlc/daml-stdlib-src/DA/Internal/Time.daml b/compiler/damlc/daml-stdlib-src/DA/Internal/Time.daml index 8494e1b45d..5d5ce76c8a 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Internal/Time.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Internal/Time.daml @@ -3,7 +3,7 @@ {-# LANGUAGE NoImplicitPrelude #-} --- | MOVE DA.Time DAML-LF types and primitives, apart from templates/contracts. +-- | MOVE DA.Time Daml-LF types and primitives, apart from templates/contracts. module DA.Internal.Time where import DA.Internal.Prelude diff --git a/compiler/damlc/daml-stdlib-src/DA/Math.daml b/compiler/damlc/daml-stdlib-src/DA/Math.daml index 8a4851692f..76156f7f7c 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Math.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Math.daml @@ -4,7 +4,7 @@ -- | Math - Utility Math functions for `Decimal` -- The this library is designed to give good precision, typically giving 9 correct decimal places. -- The numerical algorithms run with many iterations to achieve that precision and are interpreted --- by the DAML runtime so they are not performant. Their use is not advised in performance critical +-- by the Daml runtime so they are not performant. Their use is not advised in performance critical -- contexts. module DA.Math ( (**) @@ -90,7 +90,7 @@ type Sci = (Decimal, Int) -- | `to36dig` tries to put a number in scientific notation in a form -- where the `x` has order of magnitude 10^26. Given the fixed point --- NUMBER(38,10) format of `Decimal` in DAML, this gives good +-- NUMBER(38,10) format of `Decimal` in Daml, this gives good -- precision with a little bit of room to multiply with numbers less -- than 100. to36dig: Sci -> Sci diff --git a/compiler/damlc/daml-stdlib-src/DA/Maybe.daml b/compiler/damlc/daml-stdlib-src/DA/Maybe.daml index 3e731698e5..3a566a27a3 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Maybe.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Maybe.daml @@ -7,42 +7,42 @@ module DA.Maybe(Maybe, pattern Nothing, pattern Just, maybe, module DA.Maybe) wh import DA.Optional -{-# DEPRECATED fromJust "DAML 1.2 compatibility helper, use 'fromSome' from 'DA.Optional' instead of 'fromJust'" #-} +{-# DEPRECATED fromJust "Daml 1.2 compatibility helper, use 'fromSome' from 'DA.Optional' instead of 'fromJust'" #-} fromJust : Optional a -> a fromJust = fromSome -{-# DEPRECATED fromJustNote "DAML 1.2 compatibility helper, use 'fromSomeNote' from 'DA.Optional' instead of 'fromJustNote'" #-} +{-# DEPRECATED fromJustNote "Daml 1.2 compatibility helper, use 'fromSomeNote' from 'DA.Optional' instead of 'fromJustNote'" #-} fromJustNote : Text -> Optional a -> a fromJustNote = fromSomeNote -{-# DEPRECATED catMaybes "DAML 1.2 compatibility helper, use 'catOptionals' from 'DA.Optional' instead of 'catMaybes'" #-} +{-# DEPRECATED catMaybes "Daml 1.2 compatibility helper, use 'catOptionals' from 'DA.Optional' instead of 'catMaybes'" #-} catMaybes : [Optional a] -> [a] catMaybes = catOptionals -{-# DEPRECATED listToMaybe "DAML 1.2 compatibility helper, use 'listToOptional' from 'DA.Optional' instead of 'listToMaybe'" #-} +{-# DEPRECATED listToMaybe "Daml 1.2 compatibility helper, use 'listToOptional' from 'DA.Optional' instead of 'listToMaybe'" #-} listToMaybe : [a] -> Optional a listToMaybe = listToOptional -{-# DEPRECATED maybeToList "DAML 1.2 compatibility helper, use 'optionalToList' from 'DA.Optional' instead of 'maybeToList'" #-} +{-# DEPRECATED maybeToList "Daml 1.2 compatibility helper, use 'optionalToList' from 'DA.Optional' instead of 'maybeToList'" #-} maybeToList : Optional a -> [a] maybeToList = optionalToList -{-# DEPRECATED fromMaybe "DAML 1.2 compatibility helper, use 'fromOptional' from 'DA.Optional' instead of 'fromMaybe'" #-} +{-# DEPRECATED fromMaybe "Daml 1.2 compatibility helper, use 'fromOptional' from 'DA.Optional' instead of 'fromMaybe'" #-} fromMaybe : a -> Optional a -> a fromMaybe = fromOptional -{-# DEPRECATED isJust "DAML 1.2 compatibility helper, use 'isSome' from 'DA.Optional' instead of 'isJust'" #-} +{-# DEPRECATED isJust "Daml 1.2 compatibility helper, use 'isSome' from 'DA.Optional' instead of 'isJust'" #-} isJust : Optional a -> Bool isJust = isSome -{-# DEPRECATED isNothing "DAML 1.2 compatibility helper, use 'isNone' from 'DA.Optional' instead of 'isNothing'" #-} +{-# DEPRECATED isNothing "Daml 1.2 compatibility helper, use 'isNone' from 'DA.Optional' instead of 'isNothing'" #-} isNothing : Optional a -> Bool isNothing = isNone -{-# DEPRECATED mapMaybe "DAML 1.2 compatibility helper, use 'mapOptional' from 'DA.Optional' instead of 'mapMaybe'" #-} +{-# DEPRECATED mapMaybe "Daml 1.2 compatibility helper, use 'mapOptional' from 'DA.Optional' instead of 'mapMaybe'" #-} mapMaybe : (a -> Optional b) -> [a] -> [b] mapMaybe = mapOptional -{-# DEPRECATED whenJust "DAML 1.2 compatibility helper, use 'whenSome' from 'DA.Optional' instead of 'whenJust'" #-} +{-# DEPRECATED whenJust "Daml 1.2 compatibility helper, use 'whenSome' from 'DA.Optional' instead of 'whenJust'" #-} whenJust : Applicative m => Optional a -> (a -> m ()) -> m () whenJust = whenSome diff --git a/compiler/damlc/daml-stdlib-src/DA/Maybe/Total.daml b/compiler/damlc/daml-stdlib-src/DA/Maybe/Total.daml index 9fedd99961..59e93eef9f 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Maybe/Total.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Maybe/Total.daml @@ -11,10 +11,10 @@ where import DA.Maybe hiding (fromJust, fromJustNote) import DA.Optional.Total -{-# DEPRECATED fromJust "DAML 1.2 compatibility helper, use 'fromSome' from 'DA.Optional.Total' instead of 'fromJust'" #-} +{-# DEPRECATED fromJust "Daml 1.2 compatibility helper, use 'fromSome' from 'DA.Optional.Total' instead of 'fromJust'" #-} fromJust : ActionFail m => Optional a -> m a fromJust = fromSome -{-# DEPRECATED fromJustNote "DAML 1.2 compatibility helper, use 'fromSomeNote' from 'DA.Optional.Total' instead of 'fromJustNote'" #-} +{-# DEPRECATED fromJustNote "Daml 1.2 compatibility helper, use 'fromSomeNote' from 'DA.Optional.Total' instead of 'fromJustNote'" #-} fromJustNote : ActionFail m => Text -> Optional a -> m a fromJustNote = fromSomeNote diff --git a/compiler/damlc/daml-stdlib-src/DA/Next/Map.daml b/compiler/damlc/daml-stdlib-src/DA/Next/Map.daml index 324a97d982..47a11e4537 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Next/Map.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Next/Map.daml @@ -170,7 +170,7 @@ instance (MapKey k, Show k, Show v) => Show (Map k v) where deriving instance MapKey k => Semigroup (Map k v) --- TODO(MH): The converter to DAML-LF can't handle deriving this right now. +-- TODO(MH): The converter to Daml-LF can't handle deriving this right now. -- It fails with "Coercion with symco." -- deriving instance MapKey k => Monoid (Map k v) instance MapKey k => Monoid (Map k v) where diff --git a/compiler/damlc/daml-stdlib-src/DA/Text.daml b/compiler/damlc/daml-stdlib-src/DA/Text.daml index 2832401b87..fcf03aeb2c 100644 --- a/compiler/damlc/daml-stdlib-src/DA/Text.daml +++ b/compiler/damlc/daml-stdlib-src/DA/Text.daml @@ -324,7 +324,7 @@ parseDecimal = primitive @"BEDecimalFromText" -- | Computes the SHA256 hash of the UTF8 bytes of the `Text`, and returns it in its hex-encoded -- form. The hex encoding uses lowercase letters. -- --- This function will crash at runtime if you compile DAML to DAML-LF < 1.2. +-- This function will crash at runtime if you compile Daml to Daml-LF < 1.2. sha256 : Text -> Text sha256 = primitive @"BESha256Text" diff --git a/compiler/damlc/daml-stdlib-src/Prelude.daml b/compiler/damlc/daml-stdlib-src/Prelude.daml index 3e329565cb..a4e2ef60ed 100644 --- a/compiler/damlc/daml-stdlib-src/Prelude.daml +++ b/compiler/damlc/daml-stdlib-src/Prelude.daml @@ -2,7 +2,7 @@ -- SPDX-License-Identifier: Apache-2.0 {-# LANGUAGE CPP #-} --- | The pieces that make up the DAML language. +-- | The pieces that make up the Daml language. module Prelude (module X) where import DA.Internal.Prelude as X hiding (magic) diff --git a/compiler/damlc/lib/DA/Cli/Damlc.hs b/compiler/damlc/lib/DA/Cli/Damlc.hs index 4dca920116..2137124ab3 100644 --- a/compiler/damlc/lib/DA/Cli/Damlc.hs +++ b/compiler/damlc/lib/DA/Cli/Damlc.hs @@ -6,7 +6,7 @@ {-# LANGUAGE CPP #-} {-# LANGUAGE MultiWayIf #-} --- | Main entry-point of the DAML compiler +-- | Main entry-point of the Daml compiler module DA.Cli.Damlc (main) where import qualified "zip-archive" Codec.Archive.Zip as ZipArchive @@ -125,7 +125,7 @@ cmdIde :: Int -> Mod CommandFields Command cmdIde numProcessors = command "ide" $ info (helper <*> cmd) $ progDesc - "Start the DAML language server on standard input/output." + "Start the Daml language server on standard input/output." <> fullDesc where cmd = execIde @@ -138,13 +138,13 @@ cmdLicense :: Mod CommandFields Command cmdLicense = command "license" $ info (helper <*> pure execLicense) $ progDesc - "License information for open-source projects included in DAML Connect." + "License information for open-source projects included in Daml Connect." <> fullDesc cmdCompile :: Int -> Mod CommandFields Command cmdCompile numProcessors = command "compile" $ info (helper <*> cmd) $ - progDesc "Compile the DAML program into a Core/DAML-LF archive." + progDesc "Compile the Daml program into a Core/DAML-LF archive." <> fullDesc where cmd = execCompile @@ -164,7 +164,7 @@ cmdCompile numProcessors = cmdLint :: Int -> Mod CommandFields Command cmdLint numProcessors = command "lint" $ info (helper <*> cmd) $ - progDesc "Lint the DAML program." + progDesc "Lint the Daml program." <> fullDesc where cmd = execLint @@ -178,8 +178,8 @@ cmdTest numProcessors = <> fullDesc where progDoc = unlines - [ "Test the current DAML project or the given files by running all test declarations." - , "Must be in DAML project if --files is not set." + [ "Test the current Daml project or the given files by running all test declarations." + , "Must be in Daml project if --files is not set." ] cmd = runTestsInProjectOrFiles <$> projectOpts "daml test" @@ -240,7 +240,7 @@ cmdBuild :: Int -> Mod CommandFields Command cmdBuild numProcessors = command "build" $ info (helper <*> cmd) $ - progDesc "Initialize, build and package the DAML project" <> fullDesc + progDesc "Initialize, build and package the Daml project" <> fullDesc where cmd = execBuild @@ -253,7 +253,7 @@ cmdBuild numProcessors = cmdRepl :: Int -> Mod CommandFields Command cmdRepl numProcessors = command "repl" $ info (helper <*> cmd) $ - progDesc "Launch the DAML REPL." <> + progDesc "Launch the Daml REPL." <> fullDesc where cmd = @@ -347,21 +347,21 @@ cmdClean :: Mod CommandFields Command cmdClean = command "clean" $ info (helper <*> cmd) $ - progDesc "Remove DAML project build artifacts" <> fullDesc + progDesc "Remove Daml project build artifacts" <> fullDesc where cmd = execClean <$> projectOpts "daml clean" cmdInit :: Int -> Mod CommandFields Command cmdInit numProcessors = command "init" $ - info (helper <*> cmd) $ progDesc "Initialize a DAML project" <> fullDesc + info (helper <*> cmd) $ progDesc "Initialize a Daml project" <> fullDesc where cmd = execInit <$> optionsParser numProcessors (EnableScenarioService False) (pure Nothing) <*> projectOpts "daml damlc init" cmdPackage :: Int -> Mod CommandFields Command cmdPackage numProcessors = command "package" $ info (helper <*> cmd) $ - progDesc "Compile the DAML program into a DAR (deprecated)" + progDesc "Compile the Daml program into a DAR (deprecated)" <> fullDesc where cmd = execPackage @@ -374,7 +374,7 @@ cmdPackage numProcessors = optFromDalf :: Parser FromDalf optFromDalf = fmap FromDalf $ switch $ - help "package an existing dalf file rather than compiling DAML sources" <> + help "package an existing dalf file rather than compiling Daml sources" <> long "dalf" <> internal @@ -872,7 +872,7 @@ parserInfo :: Int -> ParserInfo Command parserInfo numProcessors = info (helper <*> options numProcessors) ( fullDesc - <> progDesc "Invoke the DAML compiler. Use -h for help." + <> progDesc "Invoke the Daml compiler. Use -h for help." <> headerDoc (Just $ PP.vcat [ "damlc - Compiler and IDE backend for the Digital Asset Modelling Language" , buildInfo diff --git a/compiler/damlc/lib/DA/Cli/Options.hs b/compiler/damlc/lib/DA/Cli/Options.hs index 262df3363d..3809eb5d22 100644 --- a/compiler/damlc/lib/DA/Cli/Options.hs +++ b/compiler/damlc/lib/DA/Cli/Options.hs @@ -93,12 +93,12 @@ targetFileNameOpt = option (Just <$> str) $ packageNameOpt :: Parser GHC.UnitId packageNameOpt = fmap GHC.stringToUnitId $ argument str $ metavar "PACKAGE-NAME" - <> help "Name of the DAML package" + <> help "Name of the Daml package" lfVersionOpt :: Parser LF.Version lfVersionOpt = option (str >>= select) $ metavar "DAML-LF-VERSION" - <> help ("DAML-LF version to output: " ++ versionsStr) + <> help ("Daml-LF version to output: " ++ versionsStr) <> long "target" <> value LF.versionDefault <> internal @@ -113,7 +113,7 @@ lfVersionOpt = option (str >>= select) $ , version `elem` LF.supportedOutputVersions -> return version | otherwise - -> readerError $ "Unknown DAML-LF version: " ++ versionsStr + -> readerError $ "Unknown Daml-LF version: " ++ versionsStr dotFileOpt :: Parser (Maybe FilePath) dotFileOpt = option (Just <$> str) $ @@ -200,7 +200,7 @@ projectOpts name = ProjectOpts <$> projectRootOpt <*> projectCheckOpt name , "If you use the assistant, you should set the DAML_PROJECT environment variable instead." ]) projectCheckOpt cmdName = fmap (ProjectCheck cmdName) . switch $ - help "Check if running in DAML project." + help "Check if running in Daml project." <> long "project-check" enableScenarioOpt :: Parser EnableScenarioService @@ -209,7 +209,7 @@ enableScenarioOpt = EnableScenarioService <$> enableScriptsOpt :: Parser EnableScripts enableScriptsOpt = EnableScripts <$> - flagYesNoAuto "daml-script" True "Enable/disable support for running DAML Scripts" internal + flagYesNoAuto "daml-script" True "Enable/disable support for running Daml Scripts" internal dlintEnabledOpt :: Parser DlintUsage dlintEnabledOpt = DlintEnabled diff --git a/compiler/damlc/tests/daml-test-files/AliasCompression.daml b/compiler/damlc/tests/daml-test-files/AliasCompression.daml index 2eba3ebc90..acc47e32b6 100644 --- a/compiler/damlc/tests/daml-test-files/AliasCompression.daml +++ b/compiler/damlc/tests/daml-test-files/AliasCompression.daml @@ -1,7 +1,7 @@ -- Copyright (c) 2020, Digital Asset (Switzerland) GmbH and/or its affiliates. -- All rights reserved. --- Check that alias compresion during the conversion to DAML-LF works properly +-- Check that alias compresion during the conversion to Daml-LF works properly -- with chains of aliases. module AliasCompression where diff --git a/compiler/damlc/tests/daml-test-files/ClassMethodNames.daml b/compiler/damlc/tests/daml-test-files/ClassMethodNames.daml index 167d90fb7e..26c1a43ba4 100644 --- a/compiler/damlc/tests/daml-test-files/ClassMethodNames.daml +++ b/compiler/damlc/tests/daml-test-files/ClassMethodNames.daml @@ -2,7 +2,7 @@ -- SPDX-License-Identifier: Apache-2.0 -- -- Ensure that class method names are preserved during the translation --- to DAML-LF. +-- to Daml-LF. -- -- @SINCE-LF 1.7 -- @QUERY-LF (.interned_strings | map(select(. == "m_baz")) == ["m_baz"]) diff --git a/compiler/damlc/tests/daml-test-files/ConstrainedRecursion.daml b/compiler/damlc/tests/daml-test-files/ConstrainedRecursion.daml index 8c66ffc466..ced6fb7113 100644 --- a/compiler/damlc/tests/daml-test-files/ConstrainedRecursion.daml +++ b/compiler/damlc/tests/daml-test-files/ConstrainedRecursion.daml @@ -1,4 +1,4 @@ --- Copyright (c) 2020 The DAML Authors. All rights reserved. +-- Copyright (c) 2020 The Daml Authors. All rights reserved. -- SPDX-License-Identifier: Apache-2.0 -- -- @INFO range=12:1-13:21; Use foldl diff --git a/compiler/damlc/tests/daml-test-files/DataTypes.daml b/compiler/damlc/tests/daml-test-files/DataTypes.daml index df4c61d215..ba3017eb2f 100644 --- a/compiler/damlc/tests/daml-test-files/DataTypes.daml +++ b/compiler/damlc/tests/daml-test-files/DataTypes.daml @@ -2,8 +2,8 @@ -- All rights reserved. -- Check that various ways to define data types work. We're mostly interested --- in the generated DAML-LF. Unfortunately, we don't have a way to test for --- properties of the generated DAML-LF, cf. DEL-6418. +-- in the generated Daml-LF. Unfortunately, we don't have a way to test for +-- properties of the generated Daml-LF, cf. DEL-6418. module DataTypes where diff --git a/compiler/damlc/tests/daml-test-files/EnumLF.daml b/compiler/damlc/tests/daml-test-files/EnumLF.daml index 943c009764..255bc3dc29 100644 --- a/compiler/damlc/tests/daml-test-files/EnumLF.daml +++ b/compiler/damlc/tests/daml-test-files/EnumLF.daml @@ -1,7 +1,7 @@ -- Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. -- SPDX-License-Identifier: Apache-2.0 --- Check that enum types get translated to DAML-LF's enum types. +-- Check that enum types get translated to Daml-LF's enum types. -- @SINCE-LF 1.6 -- @QUERY-LF .modules[] | .data_types[] | select(lf::get_dotted_name($pkg) == ["Color"]) | has("enum") -- @QUERY-LF .modules[] | .values[] | select(.name_with_type | lf::get_value_name($pkg) == ["red"]) | .expr | has("enum_con") diff --git a/compiler/damlc/tests/daml-test-files/ExerciseWithoutActors.daml b/compiler/damlc/tests/daml-test-files/ExerciseWithoutActors.daml index 6c812391a2..f40e34552a 100644 --- a/compiler/damlc/tests/daml-test-files/ExerciseWithoutActors.daml +++ b/compiler/damlc/tests/daml-test-files/ExerciseWithoutActors.daml @@ -1,7 +1,7 @@ -- Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. -- SPDX-License-Identifier: Apache-2.0 --- Check that `exercise` is compiled to the DAML-LF `exercise` instruction +-- Check that `exercise` is compiled to the Daml-LF `exercise` instruction -- without actors. Also check that `internalExerciseWithActors` actually -- uses actors as a sanity check. diff --git a/compiler/damlc/tests/daml-test-files/FreshNames.daml b/compiler/damlc/tests/daml-test-files/FreshNames.daml index cc0ee8980e..f62bcecbd4 100644 --- a/compiler/damlc/tests/daml-test-files/FreshNames.daml +++ b/compiler/damlc/tests/daml-test-files/FreshNames.daml @@ -1,5 +1,5 @@ -- Test that we don't use the hard coded variable names `v1`, `v2`, ... during --- the conversion of some builtins to DAML-LF. +-- the conversion of some builtins to Daml-LF. module FreshNames where import DA.Assert diff --git a/compiler/damlc/tests/daml-test-files/KindChecking.daml b/compiler/damlc/tests/daml-test-files/KindChecking.daml index d593cf10aa..ff23ff916d 100644 --- a/compiler/damlc/tests/daml-test-files/KindChecking.daml +++ b/compiler/damlc/tests/daml-test-files/KindChecking.daml @@ -2,7 +2,7 @@ -- All rights reserved. -- @SINCE-LF 1.7 --- Make sure that invalid kinds are reported as errors by the DAML compiler. +-- Make sure that invalid kinds are reported as errors by the Daml compiler. module KindChecking where -- @ERROR range=10:1-10:4; Nat kind on the right-hand side of kind arrow diff --git a/compiler/damlc/tests/daml-test-files/RecordProjection.daml b/compiler/damlc/tests/daml-test-files/RecordProjection.daml index c43bfbb8b5..1ec414c973 100644 --- a/compiler/damlc/tests/daml-test-files/RecordProjection.daml +++ b/compiler/damlc/tests/daml-test-files/RecordProjection.daml @@ -1,8 +1,8 @@ -- Copyright (c) 2020, Digital Asset (Switzerland) GmbH and/or its affiliates. -- All rights reserved. --- The tests here check that we compile all syntactic variants of DAML record --- projection into the DAML-LF builtin for record projection as soon as we know +-- The tests here check that we compile all syntactic variants of Daml record +-- projection into the Daml-LF builtin for record projection as soon as we know -- the record type and the field name. module RecordProjection where diff --git a/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml b/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml index 9b30f64d3f..efaba02205 100644 --- a/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml +++ b/compiler/damlc/tests/daml-test-files/SemanticsEvalOrder.daml @@ -169,7 +169,7 @@ evExpRecUpdErr2_3 = scenario do pure (R1 {a=0, b=0}) { a = error "EvExpRecUpdErr2_3 OK", a = error "EvExpRecUpdErr2_3 failed" } --- Can't test LF struct evaluation order from DAML, since we purposely avoid +-- Can't test LF struct evaluation order from Daml, since we purposely avoid -- evaluation of struct fields during typeclass desugaring, and we don't have -- a way to construct LF structs directly. @@ -231,7 +231,7 @@ evExpUpFetchErr = scenario do let _ : Update T = fetch (error "EvExpUpFetchErr OK") pure () --- "exercise with actors" is not testable from DAML. +-- "exercise with actors" is not testable from Daml. evExpUpExerciseWithoutActorsErr1 = scenario do let _ : Update () = diff --git a/compiler/damlc/tests/daml-test-files/SemanticsValue.daml b/compiler/damlc/tests/daml-test-files/SemanticsValue.daml index c6502d0302..6362a613f8 100644 --- a/compiler/damlc/tests/daml-test-files/SemanticsValue.daml +++ b/compiler/damlc/tests/daml-test-files/SemanticsValue.daml @@ -1,7 +1,7 @@ -- | This module checks that what is considered a value in --- the operational semantics of DAML-LF matches what is --- treated as a value in DAML. +-- the operational semantics of Daml-LF matches what is +-- treated as a value in Daml. -- -- According to the spec, a value is "an expression which does not -- need to be evaluated further". Any unevaluated subexpressions @@ -13,7 +13,7 @@ -- * updates with 'bind' or 'embed_expr' -- * scenarios with 'sbind' or 'sembed_expr' -- --- Where we can, we test this from DAML by using values with +-- Where we can, we test this from Daml by using values with -- embedded error expressions. The value should evaluate without -- raising an error. -- @@ -42,6 +42,6 @@ main = scenario do let _ : Scenario () = do _ <- pure () error "ValScenarioBind" - -- cannot test ValScenarioEmbedExpr from DAML, since + -- cannot test ValScenarioEmbedExpr from Daml, since -- the compiler does not generate it. pure () diff --git a/compiler/damlc/tests/daml-test-files/SemanticsValueSince17.daml b/compiler/damlc/tests/daml-test-files/SemanticsValueSince17.daml index 40a7b8e2d7..37d8923488 100644 --- a/compiler/damlc/tests/daml-test-files/SemanticsValueSince17.daml +++ b/compiler/damlc/tests/daml-test-files/SemanticsValueSince17.daml @@ -1,5 +1,5 @@ --- | Tests new "value cases" available since DAML 1.7 +-- | Tests new "value cases" available since Daml 1.7 -- -- @SINCE-LF 1.7 module SemanticsValueSince17 where diff --git a/compiler/damlc/tests/daml-test-files/SingleConEnum.daml b/compiler/damlc/tests/daml-test-files/SingleConEnum.daml index c6c1204204..4afe0079ce 100644 --- a/compiler/damlc/tests/daml-test-files/SingleConEnum.daml +++ b/compiler/damlc/tests/daml-test-files/SingleConEnum.daml @@ -1,7 +1,7 @@ -- Copyright (c) 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. -- SPDX-License-Identifier: Apache-2.0 --- Check that enum types get translated to DAML-LF's enum types. +-- Check that enum types get translated to Daml-LF's enum types. -- @SINCE-LF 1.6 -- @QUERY-LF .modules[] | .data_types[] | select(lf::get_dotted_name($pkg) == ["Color"]) | has("enum") -- @QUERY-LF .modules[] | .values[] | select(.name_with_type | lf::get_value_name($pkg) == ["red"]) | .expr | has("enum_con") diff --git a/compiler/damlc/tests/daml-test-files/TypeVarShadowing.daml b/compiler/damlc/tests/daml-test-files/TypeVarShadowing.daml index 33b48149e9..5e819074a1 100644 --- a/compiler/damlc/tests/daml-test-files/TypeVarShadowing.daml +++ b/compiler/damlc/tests/daml-test-files/TypeVarShadowing.daml @@ -20,7 +20,7 @@ type F f = forall a. f a shadow : forall a. F (Either a) shadow = error "shadow" --- This breaks if we don't allow for shadowing type variables in DAML-LF. +-- This breaks if we don't allow for shadowing type variables in Daml-LF. type Kont a = forall r. (a -> r) -> r kont2 : Kont (Kont Int) diff --git a/compiler/damlc/tests/daml-test-files/Unserializable.daml b/compiler/damlc/tests/daml-test-files/Unserializable.daml index 58f02845d7..65fa50e644 100644 --- a/compiler/damlc/tests/daml-test-files/Unserializable.daml +++ b/compiler/damlc/tests/daml-test-files/Unserializable.daml @@ -1,7 +1,7 @@ -- Copyright (c) 2020, Digital Asset (Switzerland) GmbH and/or its affiliates. -- All rights reserved. --- Test the serializability checker for DAML LF. +-- Test the serializability checker for Daml LF. -- We use the template typeclass and instances directly as otherwise the error -- is caught prior due to missing Eq and Show instances. diff --git a/compiler/damlc/tests/daml-test-files/UnserializableScenario.daml b/compiler/damlc/tests/daml-test-files/UnserializableScenario.daml index dcce2da31c..2d355041d3 100644 --- a/compiler/damlc/tests/daml-test-files/UnserializableScenario.daml +++ b/compiler/damlc/tests/daml-test-files/UnserializableScenario.daml @@ -1,4 +1,4 @@ --- Copyright (c) 2020 The DAML Authors. All rights reserved. +-- Copyright (c) 2020 The Daml Authors. All rights reserved. -- SPDX-License-Identifier: Apache-2.0 -- @SINCE-LF 1.7 diff --git a/compiler/damlc/tests/daml-test-files/UseInteger.daml b/compiler/damlc/tests/daml-test-files/UseInteger.daml index 4f50aa92a5..a5757fafe1 100644 --- a/compiler/damlc/tests/daml-test-files/UseInteger.daml +++ b/compiler/damlc/tests/daml-test-files/UseInteger.daml @@ -7,7 +7,7 @@ -- Test that foo does not overflow -- @ QUERY-LF .modules[] | .values[] | select(.name_with_type | lf::get_value_name($pkg) == ["foo"]) | .expr.prim_lit | lf::get_int64($pkg) == "1" --- Test that DAML-LF can hold maxBound :: Int64 +-- Test that Daml-LF can hold maxBound :: Int64 -- @ QUERY-LF .modules[] | .values[] | select(.name_with_type | lf::get_value_name($pkg) == ["bar"]) | .expr.prim_lit | lf::get_int64($pkg) == "9223372036854775807" module UseInteger where diff --git a/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs b/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs index 9337cccec5..dbfa66baf5 100644 --- a/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs +++ b/daml-assistant/daml-helper/src/DA/Daml/Helper/Main.hs @@ -169,7 +169,7 @@ commandParser = subparser $ fold <*> (SandboxOptions <$> many (strOption (long "sandbox-option" <> metavar "SANDBOX_OPTION" <> help "Pass option to sandbox"))) <*> (NavigatorOptions <$> many (strOption (long "navigator-option" <> metavar "NAVIGATOR_OPTION" <> help "Pass option to navigator"))) <*> (JsonApiOptions <$> many (strOption (long "json-api-option" <> metavar "JSON_API_OPTION" <> help "Pass option to HTTP JSON API"))) - <*> (ScriptOptions <$> many (strOption (long "script-option" <> metavar "SCRIPT_OPTION" <> help "Pass option to DAML script interpreter"))) + <*> (ScriptOptions <$> many (strOption (long "script-option" <> metavar "SCRIPT_OPTION" <> help "Pass option to Daml script interpreter"))) <*> stdinCloseOpt <*> (SandboxClassic <$> switch (long "sandbox-classic" <> help "Deprecated. Run with Sandbox Classic.")) @@ -198,7 +198,7 @@ commandParser = subparser $ fold deployCmdInfo = mconcat [ progDesc $ concat - [ "Deploy the current DAML project to a remote DAML ledger. " + [ "Deploy the current Daml project to a remote Daml ledger. " , "This will allocate the project's parties on the ledger " , "(if missing) and upload the project's built DAR file. You " , "can specify the ledger in daml.yaml with the ledger.host and " @@ -245,7 +245,7 @@ commandParser = subparser $ fold ledgerCmdInfo = mconcat [ forwardOptions , progDesc $ concat - [ "Interact with a remote DAML ledger. You can specify " + [ "Interact with a remote Daml ledger. You can specify " , "the ledger in daml.yaml with the ledger.host and " , "ledger.port options, or you can pass the --host " , "and --port flags to each command below. " diff --git a/daml-assistant/get-daml.sh b/daml-assistant/get-daml.sh index a163a0e936..d53fb0f597 100755 --- a/daml-assistant/get-daml.sh +++ b/daml-assistant/get-daml.sh @@ -4,7 +4,7 @@ # SPDX-License-Identifier: Apache-2.0 # -# DAML is an open-source privacy-aware smart contract language. +# Daml is an open-source privacy-aware smart contract language. # This script downloads and installs the SDK on Linux and macOS. # This will overwrite any existing installation in ~/.daml # For more information please visit https://daml.com/ and https://docs.daml.com/ @@ -31,7 +31,7 @@ rmTmpDir() { if [ -z $TEMPDIR ]; then rm -rf $TMPDIR else - echo "You may now remove the DAML installation files from $TEMPDIR" + echo "You may now remove the Daml installation files from $TEMPDIR" fi } @@ -47,7 +47,7 @@ trap cleanup EXIT # Check that the temporary directory has enough space for the installation # if [ "$(df $TMPDIR | tail -1 | awk '{print $4}')" -lt $INSTALL_MINSIZE ]; then - echo "Not enough disk space available to extract DAML SDK in $TMPDIR." + echo "Not enough disk space available to extract Daml SDK in $TMPDIR." echo "" echo "You can specify an alternative extraction directory by" echo "setting the TEMPDIR environment variable." @@ -71,7 +71,7 @@ else MISSING="tar" fi if [ -n "$MISSING" ]; then - echo "Missing tools required for DAML installation: $MISSING" + echo "Missing tools required for Daml installation: $MISSING" exit 1 fi @@ -142,6 +142,6 @@ fi # Done. # trap - EXIT -echo "$(tput setaf 3)Successfully installed DAML.$(tput sgr 0)" +echo "$(tput setaf 3)Successfully installed Daml.$(tput sgr 0)" cd $SWD rmTmpDir diff --git a/daml-assistant/scala-daml-project-config/README.md b/daml-assistant/scala-daml-project-config/README.md index 228a5eb5a3..9ac5ea9c29 100644 --- a/daml-assistant/scala-daml-project-config/README.md +++ b/daml-assistant/scala-daml-project-config/README.md @@ -1,3 +1,3 @@ -# Scala DAML project config +# Scala Daml project config This Scala library contains helpers to load SDK configuration files. \ No newline at end of file diff --git a/daml-assistant/src/DA/Daml/Assistant/Command.hs b/daml-assistant/src/DA/Daml/Assistant/Command.hs index 3117d2e5ec..f8aa7482c8 100644 --- a/daml-assistant/src/DA/Daml/Assistant/Command.hs +++ b/daml-assistant/src/DA/Daml/Assistant/Command.hs @@ -90,7 +90,7 @@ sdkCommandArgsParser info = fromM (go (unwrapSdkCommandArgs $ sdkCommandArgs inf commandParser :: [SdkCommandInfo] -> Parser Command commandParser cmds | (hidden, visible) <- partition isHidden cmds = asum [ subparser -- visible commands - $ builtin "version" "Display DAML version information" mempty (Version <$> versionParser <**> helper) + $ builtin "version" "Display Daml version information" mempty (Version <$> versionParser <**> helper) <> builtin "install" "Install the specified SDK version" mempty (Install <$> installParser <**> helper) <> builtin "uninstall" "Uninstall the specified SDK version" mempty (Uninstall <$> uninstallParser <**> helper) <> foldMap dispatch visible @@ -105,19 +105,19 @@ versionParser :: Parser VersionOptions versionParser = VersionOptions <$> flagYesNoAuto "all" False "Display all available versions." idm <*> flagYesNoAuto "snapshots" False "Display all available snapshot versions." idm - <*> flagYesNoAuto "assistant" False "Display DAML assistant version." idm + <*> flagYesNoAuto "assistant" False "Display Daml assistant version." idm installParser :: Parser InstallOptions installParser = InstallOptions <$> optional (RawInstallTarget <$> argument str (metavar "TARGET" <> completeWith ["latest"] <> help "The SDK version to install. Use 'latest' to download and install the latest stable SDK version available. Run 'daml install' to see the full set of options.")) <*> flagYesNoAuto "snapshots" False "Pick up snapshot versions with daml install latest." idm - <*> (InstallAssistant <$> flagYesNoAuto' "install-assistant" "Install associated DAML assistant version. Can be set to \"yes\" (always installs), \"no\" (never installs), or \"auto\" (installs if newer). Default is \"auto\"." idm) + <*> (InstallAssistant <$> flagYesNoAuto' "install-assistant" "Install associated Daml assistant version. Can be set to \"yes\" (always installs), \"no\" (never installs), or \"auto\" (installs if newer). Default is \"auto\"." idm) <*> iflag ActivateInstall "activate" hidden "Activate installed version of daml" <*> iflag ForceInstall "force" (short 'f') "Overwrite existing installation" <*> iflag QuietInstall "quiet" (short 'q') "Don't display installation messages" <*> fmap SetPath (flagYesNoAuto' "set-path" "Adjust PATH automatically" idm) - <*> fmap BashCompletions (flagYesNoAuto' "bash-completions" "Install bash completions for DAML assistant. Default is yes for linux and mac, no for windows." idm) - <*> fmap ZshCompletions (flagYesNoAuto' "zsh-completions" "Install Zsh completions for DAML assistant. Default is yes for linux and mac, no for windows." idm) + <*> fmap BashCompletions (flagYesNoAuto' "bash-completions" "Install bash completions for Daml assistant. Default is yes for linux and mac, no for windows." idm) + <*> fmap ZshCompletions (flagYesNoAuto' "zsh-completions" "Install Zsh completions for Daml assistant. Default is yes for linux and mac, no for windows." idm) where iflag p name opts desc = fmap p (switch (long name <> help desc <> opts)) diff --git a/daml-lf/README.md b/daml-lf/README.md index 6860e81464..a340c54e5a 100644 --- a/daml-lf/README.md +++ b/daml-lf/README.md @@ -1,4 +1,4 @@ -The unified DAML-LF interpreter and engine +The unified Daml-LF interpreter and engine ========================================== This package contains the canonical in-memory LF ASTs of both the public @@ -22,7 +22,7 @@ Components Protobuf utilities for reading it into a raw memory form. This should reflect the [official LF specification][] at any given time. As with the LF specification, changes to the Protobuf definition are governed - by the [DAML-LF Governance process][]. + by the [Daml-LF Governance process][]. - `interface` is an ADT of the "public interface" of a given LF package, meaning its templates, their choices, and serializable data types in @@ -84,13 +84,13 @@ Components - `testing-tools` helps you run scenarios from Scalatest. [official LF specification]: spec/daml-lf-1.rst -[DAML-LF Governance process]: governance.rst +[Daml-LF Governance process]: governance.rst [CEK machine]: https://gist.github.com/ekmett/f081b5e36bac3fed1ea6b21eb25327c6 Building and testing -------------------- -DAML-LF uses Bazel to build and test the components. Please refer to top-level +Daml-LF uses Bazel to build and test the components. Please refer to top-level `BAZEL.md` and `BAZEL-JVM.md` documents for high-level instructions on how to use Bazel and how it works within IntelliJ. @@ -163,10 +163,10 @@ bazel run //daml-lf/scenario-interpreter:scenario-perf -- -p dar=/path/to/some/d ``` This can be combined with the `-f 0` flag as well. -These benchmarks are focused on DAML execution speed and try to avoid noise +These benchmarks are focused on Daml execution speed and try to avoid noise caused by, say, I/O as much as possible. -DAML-LF-REPL Usage +Daml-LF-REPL Usage ------------------ The REPL can be compiled with `bazel build //:daml-lf-repl` and run with @@ -195,7 +195,7 @@ NOTE: When running via `bazel run` one needs to specify full path (or relative p Profiling scenarios ------------------- -DAML-LF-REPL provides a command to run a scenario and collect profiling +Daml-LF-REPL provides a command to run a scenario and collect profiling information while running it. This information is then written into a file that can be viewed using the [speedscope](https://www.speedscope.app/) flamegraph visualizer. The easiest way to install speedscope is to run diff --git a/daml-lf/archive/README.md b/daml-lf/archive/README.md index 8fabdaee46..a97d5288f1 100644 --- a/daml-lf/archive/README.md +++ b/daml-lf/archive/README.md @@ -1,7 +1,7 @@ -# DAML-LF archive +# Daml-LF archive This component contains the `.proto` definitions specifying the format -in which DAML-LF packages are stored -- the DAML-LF archive. All the +in which Daml-LF packages are stored -- the Daml-LF archive. All the proto definitions are kept in the directory `src/protobuf/com/daml/daml_lf_dev/` @@ -15,22 +15,22 @@ decoding of the payload is handled by Haskell and Java libraries in `daml-core-package`, so that consumers and producers do not really need to worry about it. -`ArchivePayload` is a sum type containing the various DAML-LF versions -supported by the DAML-LF archive. Currently we have two major versions: +`ArchivePayload` is a sum type containing the various Daml-LF versions +supported by the Daml-LF archive. Currently we have two major versions: -* `DAML-LF-0`, which is the deprecated legacy DAML core; -* `DAML-LF-1`, which is the first version of DAML-LF as specified by +* `Daml-LF-0`, which is the deprecated legacy Daml core; +* `Daml-LF-1`, which is the first version of Daml-LF as specified by . ## Snapshot versions The component contains also an arbitrary number of snapshots of the protobuf definitions as they were as the time a particular version of -DAML-LF was frozen. For versions <= 1.8, those snapshots are kept in the directories +Daml-LF was frozen. For versions <= 1.8, those snapshots are kept in the directories `src/protobuf/com/digitalasset/daml_lf_x_y/`, where `x.y` is a -already frozen DAML-LF version. For newer versions, the directory is +already frozen Daml-LF version. For newer versions, the directory is `src/protobuf/com/daml/daml_lf_x_y/`. A snapshot for version `x.y` can be -used to read any DAML-LF version from `1.0` to `x.y` without suffering +used to read any Daml-LF version from `1.0` to `x.y` without suffering breaking changes (at the generated code level) often introduced in the current version. @@ -81,7 +81,7 @@ message Foo { ## Conversion from the `.proto` to AST -The `.proto` definitions contain the serialized format for DAML-LF +The `.proto` definitions contain the serialized format for Daml-LF packages, however the code to convert from the `.proto` definitions to the actual AST lives elsewhere. diff --git a/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf.proto b/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf.proto index 3cf6f2c1e2..000967bb2d 100644 --- a/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf.proto +++ b/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf.proto @@ -11,7 +11,7 @@ import "com/daml/daml_lf_dev/daml_lf_1.proto"; message ArchivePayload { // this is number 3 for historical reasons -- we had - // DAML-LF v0 and v1 before we had minor versions. + // Daml-LF v0 and v1 before we had minor versions. string minor = 3; reserved 9999; // for the removed "dev" major version @@ -43,8 +43,8 @@ message Archive { // // Note that the hash is computed directly on the blob and not // on the decoded structure. This means that servers implementing - // a DAML ledger need to store the blob as-is somewhere to be able - // to always offer proof that they have a DAML package matching + // a Daml ledger need to store the blob as-is somewhere to be able + // to always offer proof that they have a Daml package matching // the requested hash. We decided to go for this route rather than // relying on a canonical encoding of the AST since such a scheme // would be extremely hard (for example protobuf encoding is not diff --git a/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf_1.proto b/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf_1.proto index d9709de42e..f57fa5db89 100644 --- a/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf_1.proto +++ b/daml-lf/archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf_1.proto @@ -1,7 +1,7 @@ // Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. // SPDX-License-Identifier: Apache-2.0 -// .proto representation of the first version of the DAML-LF language, +// .proto representation of the first version of the Daml-LF language, // as specified by // . // @@ -441,7 +441,7 @@ enum PrimCon { } // Builtin functions -// Refer to DAML-LF major version 1 specification for types and behavior of those. +// Refer to Daml-LF major version 1 specification for types and behavior of those. enum BuiltinFunction { ADD_DECIMAL = 0; // *Available in versions < 1.7* SUB_DECIMAL = 1; // *Available in versions < 1.7* @@ -907,7 +907,7 @@ message Expr { Expr exception_expr = 3; } - // Location of the expression in the DAML code source. + // Location of the expression in the Daml code source. // Optional Location location = 25; @@ -1390,7 +1390,7 @@ message DefTemplate { int32 param_interned_str = 11; // *Available in versions >= 1.7* } - // NOTE(MH): The new runtime authorization check for DAML 1.0 does not rely + // NOTE(MH): The new runtime authorization check for Daml 1.0 does not rely // on the stakeholder signatures produced by the obligables computation // anymore but uses the interpreter to compute the signatories and // stakeholders of contract instances. diff --git a/daml-lf/governance.rst b/daml-lf/governance.rst index fabacec117..88553ac911 100644 --- a/daml-lf/governance.rst +++ b/daml-lf/governance.rst @@ -1,11 +1,11 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML-LF Governance process +Daml-LF Governance process ========================== These are the principles and rules by which changes to three data -formats are governed by the DAML Language team: +formats are governed by the Daml Language team: * language, * values and, @@ -15,38 +15,38 @@ formats are governed by the DAML Language team: Overview -------- -* The *DAML-LF language* is the typed core calculus that DAML gets +* The *Daml-LF language* is the typed core calculus that Daml gets compiled to, and that the ledger runs. -* *DAML-LF serializable values* or (DAML-LF values for brevity - (DAML-LF values for brevity in the rest in the rest of this document) - is the universe of DAML-LF values that can be stored on the +* *Daml-LF serializable values* or (Daml-LF values for brevity + (Daml-LF values for brevity in the rest in the rest of this document) + is the universe of Daml-LF values that can be stored on the ledger. Currently nominal records, nominal variants, lists, optionals, maps, and primitive types. -* *DAML-LF transaction nodes* (DAML-LF nodes for brevity in the rest - of this document) used to represent DAML actions described in the - DAML ledger model. Currently there are *create*, *exercise*, +* *Daml-LF transaction nodes* (Daml-LF nodes for brevity in the rest + of this document) used to represent Daml actions described in the + Daml ledger model. Currently there are *create*, *exercise*, *fetch*, and *lookup-by-key* nodes. -* *DAML-F transactions* are sequences of transaction nodes that +* *Daml-F transactions* are sequences of transaction nodes that defines an update to the ledger. -* The DAML-LF language is versioned using a major and minor component. +* The Daml-LF language is versioned using a major and minor component. Changes to the major component allow us to drop features, or update the serialization format. Changes to the minor component cannot break backward compatibility, and operate on the same major version of the serialization format in a backward compatible way. For historical reason this scheme starts at `1.6`. -* DAML-LF values, nodes, and transactions are versioned using a common +* Daml-LF values, nodes, and transactions are versioned using a common one component version scheme, called transaction version scheme. For historical reason this scheme starts at `10`. -* DAML-LF Language, values, nodes, and transactions are evolved +* Daml-LF Language, values, nodes, and transactions are evolved together without ever breaking backwards compatibility. -* DAML-LF values, nodes, and transactions, and language are involved +* Daml-LF values, nodes, and transactions, and language are involved together, meaning the introduction of a new language version implies the introduction of a new transaction version, and reciprocally. @@ -55,7 +55,7 @@ Overview transactions. Moreover, a one-line summary of each version must be present in the ``daml-lf-X.proto`` and ``transaction.proto`` files. -* Every change to DAML-LF values, nodes, transactions or languages +* Every change to Daml-LF values, nodes, transactions or languages *must* be checked for governance rules conformance and be approved by at least two persons among Rémy Haemmerle, Martin Huschenbett and Sophia Mota. Proposed changes can be filed as tickets under @@ -66,17 +66,17 @@ Language Some version bumps might not change the ``.proto`` at all, but just add / change semantics in the specification. For example, the string -format for decimal numbers in DAML-LF values might be made more +format for decimal numbers in Daml-LF values might be made more lenient, resulting in a version bump with no ``.proto`` schema changes (but probably a comment). -Also note that the DAML-LF versioning is independent from the DAML +Also note that the Daml-LF versioning is independent from the Daml surface language versioning. "dev" version ~~~~~~~~~~~~~ -Every DAML-LF major version includes a minor version, the *dev* +Every Daml-LF major version includes a minor version, the *dev* version, which we use as staging area for the next stable minor version of that major version. @@ -89,7 +89,7 @@ All newly-implemented minor version features or changes must be staged in the *dev* version for later release as a stable group of backward-compatible features. -The DAML-LF dev version is enabled in the sandbox and ledger server, +The Daml-LF dev version is enabled in the sandbox and ledger server, but will never be emitted by damlc unless explicitly requested via ``--target 1.dev`` or similar. @@ -126,7 +126,7 @@ rather than "best-effort" consuming it in such a case, because any field might be ignored when within values/transactions of later versions. -For DAML-LF values, node and transaction we have a single document for +For Daml-LF values, node and transaction we have a single document for all the versions, with annotations on version-specific features (in the form of "since version XYZ"). @@ -142,11 +142,11 @@ Unlike the language, values and transactions have only one major version each; in terms of how language is versioned, they only have minor versions. Their treatment is different for a few reasons: -- We expect DAML-LF values to be often stored in a long-term fashion - +- We expect Daml-LF values to be often stored in a long-term fashion - for example a ledger needs to do so. - It should be possible to revalidate old transactions at any time; - requiring users to maintain an archive of every DAML-LF engine + requiring users to maintain an archive of every Daml-LF engine version they ever used in order to be able to revalidate would be extremely onerous, and ledger operators should be able to upgrade the engine freely. @@ -154,8 +154,8 @@ minor versions. Their treatment is different for a few reasons: - While we could have major revisions and have each ledger deployment to have a blessed set of major revisions, like we plan do for code, we expect the impact of such a decision to be much greater, since - there is essentially only one consumer of DAML-LF code (the server), - while DAML-LF values will be stored all over the place, and the + there is essentially only one consumer of Daml-LF code (the server), + while Daml-LF values will be stored all over the place, and the disruption of breaking changes would be too burdensome. - It is *much* easier to preserve compatibility of simple first-order @@ -164,8 +164,8 @@ minor versions. Their treatment is different for a few reasons: Working with LF data -------------------- -The language Team provides libraries to read and write DAML-LF values, -DAML-LF transactions, and DAML-LF packages in a version-aware manner, +The language Team provides libraries to read and write Daml-LF values, +Daml-LF transactions, and Daml-LF packages in a version-aware manner, to aid the implementation of readers and writers. With "version-aware" we mean that the libraries encoding and decoding @@ -175,7 +175,7 @@ becomes more complex as the specifications evolve, we strongly recommend that JVM-hosted applications use our libraries for encoding and decoding. -The ``daml-lf/transaction`` library for DAML-LF values and +The ``daml-lf/transaction`` library for Daml-LF values and transactions includes: .. todo include this at some point? - Specification @@ -187,12 +187,12 @@ transactions includes: Scala and Java, and functions to decode / encode between the ``.proto`` and the data structures. -The ``daml-lf/lfpackage`` library for the DAML-LF language includes: +The ``daml-lf/lfpackage`` library for the Daml-LF language includes: .. todo include this at some point? - Specifications, one per major revision -- Data structures to work with DAML-LF packages. Currently, this is an - AST that supports a set of DAML-LF versions, spanning across multiple +- Data structures to work with Daml-LF packages. Currently, this is an + AST that supports a set of Daml-LF versions, spanning across multiple major revisions, either by having a larger type or by converting some features into other features (e.g. if we add dependent functions the library would convert non-dependent functions and foralls into @@ -214,8 +214,8 @@ The ``daml-lf/validation`` library includes: Engine ------ -The Language team provides the DAML-LF engine. The DAML-LF engine -will advertise what versions of the DAML-LF language it accepts. +The Language team provides the Daml-LF engine. The Daml-LF engine +will advertise what versions of the Daml-LF language it accepts. It is guaranteed and engine will accept all transaction version associated to those language versions. diff --git a/daml-lf/interpreter/perf/daml/JsonParser.daml b/daml-lf/interpreter/perf/daml/JsonParser.daml index 63cec8fe4f..be46870fc2 100644 --- a/daml-lf/interpreter/perf/daml/JsonParser.daml +++ b/daml-lf/interpreter/perf/daml/JsonParser.daml @@ -4,7 +4,7 @@ {-# OPTIONS_GHC -Wall -Wno-name-shadowing #-} -- This is not an industial strength JSON parser! (Although it is fairly complete) --- The DAML code is written for sole intent of having a semi-realistic computationally heavy exmaple. +-- The Daml code is written for sole intent of having a semi-realistic computationally heavy exmaple. -- The JSON parser is based on the Crockford grammar: https://www.json.org/json-en.html -- The parser is written using parser-combinators, following: -- "Parser combinators need four values to report errors", Andrew Partridge & David Wright diff --git a/daml-lf/notes/README.md b/daml-lf/notes/README.md index 5e7faa8639..5cb70edb33 100644 --- a/daml-lf/notes/README.md +++ b/daml-lf/notes/README.md @@ -1,3 +1,3 @@ -The DAML-LF collective scratchpad. If you have some notes that you want +The Daml-LF collective scratchpad. If you have some notes that you want to share and maintain to a certain extent, feel free to put it here. Markdown and reStructuredText are preferred. diff --git a/daml-lf/spec/contract-id.rst b/daml-lf/spec/contract-id.rst index 3e56aaecc5..8845155db4 100644 --- a/daml-lf/spec/contract-id.rst +++ b/daml-lf/spec/contract-id.rst @@ -8,7 +8,7 @@ V1 Contract ID allocation scheme Goals ^^^^^ -* Allows ordering contract IDs and make DAML semantics depend on this +* Allows ordering contract IDs and make Daml semantics depend on this order, e.g., for comparison builtin and maps using IDs as keys. * Eliminate all contract ID translations for central committer ledger * Allows ledgers to store information about the contract and the @@ -18,7 +18,7 @@ Goals Requirements ^^^^^^^^^^^^ -**Executability**: DAML engine can determine ordering of the contract +**Executability**: Daml engine can determine ordering of the contract IDs before it hands out the transaction to the write service. **Validation**: The allocation scheme commutes with transaction diff --git a/daml-lf/spec/daml-lf-1.rst b/daml-lf/spec/daml-lf-1.rst index 3a13e80402..97cb9015b1 100644 --- a/daml-lf/spec/daml-lf-1.rst +++ b/daml-lf/spec/daml-lf-1.rst @@ -5,7 +5,7 @@ Copyright © 2020, `Digital Asset (Switzerland) GmbH `_ and/or its affiliates. All rights reserved. -DAML-LF 1 specification +Daml-LF 1 specification ======================= .. contents:: Contents @@ -14,13 +14,13 @@ DAML-LF 1 specification Introduction ^^^^^^^^^^^^ -This document specifies version 1 of the DAML-LF language — the -language that DAML ledgers execute. DAML compiles to DAML-LF which -executes on DAML ledgers, similar to how Java compiles to JVM byte -code which executes on the JVM. “LF” in DAML-LF stands for “Ledger -Fragment”. DAML-LF is a small, strongly typed, functional language +This document specifies version 1 of the Daml-LF language — the +language that Daml ledgers execute. Daml compiles to Daml-LF which +executes on Daml ledgers, similar to how Java compiles to JVM byte +code which executes on the JVM. “LF” in Daml-LF stands for “Ledger +Fragment”. Daml-LF is a small, strongly typed, functional language with strict evaluation that includes native representations for core -DAML concepts such as templates, updates, and parties. It is primarily +Daml concepts such as templates, updates, and parties. It is primarily intended as a compilation target. @@ -69,31 +69,31 @@ symbols used in this doc:: Version history ~~~~~~~~~~~~~~~ -The DAML-LF language is versioned using a major and minor component. +The Daml-LF language is versioned using a major and minor component. Increasing the major component allows us to drop features, change the semantics of existing features, or update the serialization format. Changes to the minor component cannot break backward compatibility, and operate on the same major version of the serialization format in -a backward compatible way. This document describes DAML-LF major version +a backward compatible way. This document describes Daml-LF major version 1, including all its minor versions. -Starting from SDK 1.0 release, DAML-LF versions older than 1.6 are +Starting from SDK 1.0 release, Daml-LF versions older than 1.6 are deprecated. An engine compliant with the present specification must handle -all versions newer than or equal to DAML-LF 1.6, no requirement is made on +all versions newer than or equal to Daml-LF 1.6, no requirement is made on handling older version. -Each DAML-LF program is accompanied by the version identifier of the -language it was serialized in. This number enables the DAML-LF engine +Each Daml-LF program is accompanied by the version identifier of the +language it was serialized in. This number enables the Daml-LF engine to interpret previous versions of the language in a backward compatibility way. In the following of this document, we will use annotations between square brackets such as *[Available in version < x.y]*, *[Available in versions >= x.y]*, and *[Changed in version x.y]* to emphasize that a -particular feature is concerned with a change introduced in DAML x.y +particular feature is concerned with a change introduced in Daml x.y version. In addition, we will mark lines within inference rules with -annotations of the form ``[DAML-LF < x.y]`` and ``[DAML-LF ≥ x.y]`` to -make the respective line conditional upon the DAML-LF version. +annotations of the form ``[Daml-LF < x.y]`` and ``[Daml-LF ≥ x.y]`` to +make the respective line conditional upon the Daml-LF version. A *preview* version is an snapshot of the next 1.x version to be released. It is provided for beta testing purpose and may only be @@ -104,7 +104,7 @@ changed without notice. Compliant implementations are not required to implement any features exclusive to development version, but should take them under advisement as likely elements of the next 1.x version. -Below, we list the versions of DAML-LF 1.x that a DAML-LF engine +Below, we list the versions of Daml-LF 1.x that a Daml-LF engine compliant with the present specification must handle, in ascending order. The optional preview version is marked with the tag *(preview)* while the development version is marked with the tag *(development)*. @@ -229,7 +229,7 @@ Version: 1.dev (development) Abstract syntax ^^^^^^^^^^^^^^^ -This section specifies the abstract syntax tree of a DAML-LF +This section specifies the abstract syntax tree of a Daml-LF package. We define identifiers, literals, types, expressions, and definitions. @@ -293,7 +293,7 @@ brevity and readability. Identifiers ~~~~~~~~~~~ In this section, we define the sorts of strings and identifiers that appear in -DAML-LF programs. +Daml-LF programs. We first define two types of *strings*:: @@ -316,7 +316,7 @@ We first define two types of *strings*:: `_ code points where the line feed character ``\n``, the carriage return character ``\r``, the double quote character ``\"``, and the backslash character ``\\`` must -be escaped with backslash ``\\``. DAML-LF considers legal `Unicode +be escaped with backslash ``\\``. Daml-LF considers legal `Unicode code point `_ that is not a `Surrogate Code Point `_, in other words @@ -367,7 +367,7 @@ restricted to US-ASCII while names are sequences of identifiers intercalated with dots. The character ``%`` is reserved for external languages built on -DAML-LF as a "not an Ident" notation, so should not be considered for +Daml-LF as a "not an Ident" notation, so should not be considered for future addition to allowed identifier characters. In the following, we will use identifiers to represent *built-in @@ -428,12 +428,12 @@ strings as *package identifiers*. :: Contract identifiers can be created dynamically through interactions with the underlying ledger. See the `operation semantics of update statements `_ for the formal specification of -those interactions. Depending on its configuration, a DAML-LF engine +those interactions. Depending on its configuration, a Daml-LF engine can produce V0 or V1 contract identifiers. When configured to produce -V0 contract identifiers, a DAML-LF compliant engine must refuse to -load any DAML-LF >= 1.11 archives. On the contrary, when configured -to produce V1 contract IDs, a DAML-LF compliant engine must accept to -load any non-deprecated DAML-LF version. V1 Contract IDs allocation +V0 contract identifiers, a Daml-LF compliant engine must refuse to +load any Daml-LF >= 1.11 archives. On the contrary, when configured +to produce V1 contract IDs, a Daml-LF compliant engine must accept to +load any non-deprecated Daml-LF version. V1 Contract IDs allocation scheme is described in the `V1 Contract ID allocation scheme specification <./contract-id.rst>`_. @@ -469,7 +469,7 @@ We now define all the literals that a program can handle:: Contract ID literals: cid ::= cidV0 | cidV1 -- LitCid -The literals represent actual DAML-LF values: +The literals represent actual Daml-LF values: * A ``LitNatType`` represents a natural number between ``0`` and ``38``, bounds inclusive. @@ -520,7 +520,7 @@ Then we can define our kinds, types, and expressions:: Kinds k - ::= 'nat' -- KindNat [DAML-LF ≥ 1.7] + ::= 'nat' -- KindNat [Daml-LF ≥ 1.7] | ek -- KindErasable Erasable Kind @@ -547,26 +547,26 @@ Then we can define our kinds, types, and expressions:: | 'List' -- BTyList | 'Optional' -- BTyOptional | 'TextMap' -- BTTextMap: map with string keys - | 'GenMap' -- BTGenMap: map with general value keys [DAML-LF ≥ 1.11] + | 'GenMap' -- BTGenMap: map with general value keys [Daml-LF ≥ 1.11] | 'ContractId' -- BTyContractId - | 'Any' -- BTyAny [DAML-LF ≥ 1.7] - | 'TypeRep' -- BTTypeRep [DAML-LF ≥ 1.7] + | 'Any' -- BTyAny [Daml-LF ≥ 1.7] + | 'TypeRep' -- BTTypeRep [Daml-LF ≥ 1.7] | 'Update' -- BTyUpdate | 'Scenario' -- BTyScenario - | 'AnyException' -- BTyAnyException [DAML-LF ≥ 1.dev] - | 'GeneralError' -- BTyGeneralError [DAML-LF ≥ 1.dev] - | 'ArithmeticError' -- BTyArithmeticError [DAML-LF ≥ 1.dev] - | 'ContractError' -- BTyContractError [DAML-LF ≥ 1.dev] + | 'AnyException' -- BTyAnyException [Daml-LF ≥ 1.dev] + | 'GeneralError' -- BTyGeneralError [Daml-LF ≥ 1.dev] + | 'ArithmeticError' -- BTyArithmeticError [Daml-LF ≥ 1.dev] + | 'ContractError' -- BTyContractError [Daml-LF ≥ 1.dev] Types (mnemonic: tau for type) τ, σ ::= α -- TyVar: Type variable - | n -- TyNat: Nat Type [DAML-LF ≥ 1.7] + | n -- TyNat: Nat Type [Daml-LF ≥ 1.7] | τ σ -- TyApp: Type application | ∀ α : k . τ -- TyForall: Universal quantification | BuiltinType -- TyBuiltin: Builtin type | Mod:T -- TyCon: type constructor - | |Mod:S τ₁ … τₘ| -- TySyn: type synonym [DAML-LF ≥ 1.8] + | |Mod:S τ₁ … τₘ| -- TySyn: type synonym [Daml-LF ≥ 1.8] | ⟨ f₁: τ₁, …, fₘ: τₘ ⟩ -- TyStruct: Structural record type Expressions @@ -602,15 +602,15 @@ Then we can define our kinds, types, and expressions:: | 'None' @τ -- ExpOptionalNone: Empty Optional | 'Some' @τ e -- ExpOptionalSome: Non-empty Optional | [t₁ ↦ e₁; …; tₙ ↦ eₙ] -- ExpTextMap - | 〚e₁ ↦ e₁; …; eₙ ↦ eₙ'〛 -- ExpGenMap [DAML-LF ≥ 1.11] - | 'to_any' @τ e -- ExpToAny: Wrap a value of the given type in Any [DAML-LF ≥ 1.7] - | 'from_any' @τ e -- ExpToAny: Extract a value of the given from Any or return None [DAML-LF ≥ 1.7] - | 'type_rep' @τ -- ExpToTypeRep: A type representation [DAML-LF ≥ 1.7] + | 〚e₁ ↦ e₁; …; eₙ ↦ eₙ'〛 -- ExpGenMap [Daml-LF ≥ 1.11] + | 'to_any' @τ e -- ExpToAny: Wrap a value of the given type in Any [Daml-LF ≥ 1.7] + | 'from_any' @τ e -- ExpToAny: Extract a value of the given from Any or return None [Daml-LF ≥ 1.7] + | 'type_rep' @τ -- ExpToTypeRep: A type representation [Daml-LF ≥ 1.7] | u -- ExpUpdate: Update expression | s -- ExpScenario: Scenario expression | 'throw' @σ @τ e -- ExpThrow: throw exception - | 'make_any_exception' @τ eₘ eₚ -- ExpMakeAnyException: Turn a concrete exception into an 'AnyException' [DAML-LF ≥ 1.dev] - | 'from_any_exception' @τ e -- ExpFromAnyException: Extract a concrete exception from an 'AnyException' [DAML-LF ≥ 1.dev] + | 'make_any_exception' @τ eₘ eₚ -- ExpMakeAnyException: Turn a concrete exception into an 'AnyException' [Daml-LF ≥ 1.dev] + | 'from_any_exception' @τ e -- ExpFromAnyException: Extract a concrete exception from an 'AnyException' [Daml-LF ≥ 1.dev] Patterns p @@ -632,12 +632,12 @@ Then we can define our kinds, types, and expressions:: | 'fetch' @Mod:T e -- UpdateFetch | 'exercise' @Mod:T Ch e₁ e₂ e₃ -- UpdateExercise | 'exercise_without_actors' @Mod:T Ch e₁ e₂ -- UpdateExerciseWithoutActors - | 'exercise_by_key' @Mod:T Ch e₁ e₂ -- UpdateExerciseByKey [DAML-LF ≥ 1.11] + | 'exercise_by_key' @Mod:T Ch e₁ e₂ -- UpdateExerciseByKey [Daml-LF ≥ 1.11] | 'get_time' -- UpdateGetTime | 'fetch_by_key' @τ e -- UpdateFecthByKey | 'lookup_by_key' @τ e -- UpdateLookUpByKey | 'embed_expr' @τ e -- UpdateEmbedExpr - | 'try' @τ e₁ 'catch' x. e₂ -- UpdateTryCatch [DAML-LF ≥ 1.dev] + | 'try' @τ e₁ 'catch' x. e₂ -- UpdateTryCatch [Daml-LF ≥ 1.dev] Scenario s ::= 'spure' @τ e -- ScenarioPure @@ -708,7 +708,7 @@ available for usage:: , 'choices' { ChDef₁, …, ChDefₘ } , KeyDef } - | 'exception' T ↦ { 'message' e } -- DefException [DAML-LF ≥ 1.dev] + | 'exception' T ↦ { 'message' e } -- DefException [Daml-LF ≥ 1.dev] Module (mnemonic: delta for definitions) Δ ::= ε -- DefCtxEmpty @@ -721,8 +721,8 @@ available for usage:: PackageModules ∈ ModName ↦ Δ -- PackageModules Package - Package ::= Package PackageModules PackageMetadata – since DAML-LF 1.8 - Package ::= Package PackageModules -- until DAML-LF 1.8 + Package ::= Package PackageModules PackageMetadata – since Daml-LF 1.8 + Package ::= Package PackageModules -- until Daml-LF 1.8 Package collection Ξ ∈ pid ↦ Package -- Packages @@ -738,7 +738,7 @@ module. The following feature flags are available: +-------------------------------------------+----------------------------------------------------------+ | Flag | Semantic meaning | +===========================================+==========================================================+ - | ForbidPartyLiterals | Party literals are not allowed in a DAML-LF module. | + | ForbidPartyLiterals | Party literals are not allowed in a Daml-LF module. | | | (See `Party Literal restriction`_ for more details) | +-------------------------------------------+----------------------------------------------------------+ | DontDivulgeContractIdsInCreateArguments | contract IDs captured in ``create`` arguments are not | @@ -829,7 +829,7 @@ These two properties will be enforced by the notion of Note ``↠`` is undefined on type contains an undefined type synonym or a type synonym applied to a wrong number. Such types are assumed non -well-formed and will be rejected by the DAML-LF type checker. +well-formed and will be rejected by the Daml-LF type checker. Well-formed types @@ -932,16 +932,16 @@ We now formally defined *well-formed types*. :: ————————————————————————————————————————————— TyScenario Γ ⊢ 'Scenario' : ⋆ → ⋆ - ————————————————————————————————————————————— TyAnyException [DAML-LF ≥ 1.dev] + ————————————————————————————————————————————— TyAnyException [Daml-LF ≥ 1.dev] Γ ⊢ 'AnyException' : ⋆ - ————————————————————————————————————————————— TyGeneralError [DAML-LF ≥ 1.dev] + ————————————————————————————————————————————— TyGeneralError [Daml-LF ≥ 1.dev] Γ ⊢ 'GeneralError' : ⋆ - ————————————————————————————————————————————— TyArithmeticError [DAML-LF ≥ 1.dev] + ————————————————————————————————————————————— TyArithmeticError [Daml-LF ≥ 1.dev] Γ ⊢ 'ArithmeticError' : ⋆ - ————————————————————————————————————————————— TyContractError [DAML-LF ≥ 1.dev] + ————————————————————————————————————————————— TyContractError [Daml-LF ≥ 1.dev] Γ ⊢ 'ContractError' : ⋆ @@ -1153,18 +1153,18 @@ Then we define *well-formed expressions*. :: Γ ⊢ σ : ⋆ ⊢ₑ τ Γ ⊢ e : τ - ——————————————————————————————————————————————————————————————— ExpThrow [DAML-LF ≥ 1.dev] + ——————————————————————————————————————————————————————————————— ExpThrow [Daml-LF ≥ 1.dev] Γ ⊢ 'throw' @σ @τ @e : σ ⊢ₑ τ Γ ⊢ eₘ : 'Text' Γ ⊢ eₚ : τ - ——————————————————————————————————————————————————————————————— ExpMakeAnyException [DAML-LF ≥ 1.dev] + ——————————————————————————————————————————————————————————————— ExpMakeAnyException [Daml-LF ≥ 1.dev] Γ ⊢ 'make_any_exception' @τ eₘ eₚ : 'AnyException' ⊢ₑ τ Γ ⊢ e : 'AnyException' - ——————————————————————————————————————————————————————————————— ExpFromAnyException [DAML-LF ≥ 1.dev] + ——————————————————————————————————————————————————————————————— ExpFromAnyException [Daml-LF ≥ 1.dev] Γ ⊢ 'from_any_exception' @τ e : 'Optional' τ Γ ⊢ τ : ⋆ Γ ⊢ e : τ @@ -1237,7 +1237,7 @@ Then we define *well-formed expressions*. :: τ ↠ τ' Γ ⊢ e₁ : 'Update' τ' x : 'AnyException' · Γ ⊢ e₂ : 'Optional' ('Update' τ') - ——————————————————————————————————————————————————————————————— UpdTryCatch [DAML-LF ≥ 1.dev] + ——————————————————————————————————————————————————————————————— UpdTryCatch [Daml-LF ≥ 1.dev] Γ ⊢ 'try' @τ e₁ 'catch' x. e₂ : 'Update' τ' Γ ⊢ τ : ⋆ Γ ⊢ e : τ @@ -1542,7 +1542,7 @@ for the ``DefTemplate`` rule). :: 'record' T ↦ { f₁ : τ₁, …, fₙ : τₙ } ∈ 〚Ξ〛Mod ⊢ₛ Mod:T ⊢ e : Mod:T → 'Text' - ——————————————————————————————————————————————————————————————— DefException [DAML-LF ≥ 1.dev] + ——————————————————————————————————————————————————————————————— DefException [Daml-LF ≥ 1.dev] ⊢ 'exception' T ↦ { 'message' e } ┌───────────────────┐ @@ -1577,7 +1577,7 @@ for the ``DefTemplate`` rule). :: Γ ⊢ 'no_key' ⊢ₛ τ Γ ⊢ eₖ : τ - ⊢ₖ eₖ [DAML-LF = 1.3] + ⊢ₖ eₖ [Daml-LF = 1.3] ε ⊢ eₘ : τ → 'List' 'Party' ——————————————————————————————————————————————————————————————— KeyDefSome Γ ⊢ 'key' τ eₖ eₘ @@ -1620,10 +1620,10 @@ Party literal restriction ``ForbidPartyLiterals`` feature flag party literals were allowed everywhere. -The usage of party literals is restricted in DAML-LF. By default, +The usage of party literals is restricted in Daml-LF. By default, party literals are neither allowed in templates nor in values used in templates directly or indirectly. In practice, this restricted the -usage of party literals to test cases written in DAML-LF. Usage of +usage of party literals to test cases written in Daml-LF. Usage of party literals can be completely forbidden thanks to the `feature flag `_ ``ForbidPartyLiterals``. If this flag is on, any occurrence of a party literal anywhere in the module makes the module @@ -1633,7 +1633,7 @@ not well-formed. Name collision restriction ~~~~~~~~~~~~~~~~~~~~~~~~~~ -DAML-LF relies on `names and identifiers `_ to refer to +Daml-LF relies on `names and identifiers `_ to refer to different kinds of constructs such as modules, type constructors, variants constructor, and fields. These are relative; type names are relative to modules; field names are relative to type record and so @@ -1644,7 +1644,7 @@ for module and type is different. Fully resolved name ................... -DAML-LF restricts the way names and identifiers are used within a +Daml-LF restricts the way names and identifiers are used within a package. This restriction relies on the notion of *fully resolved name* construct as follows: @@ -1692,11 +1692,11 @@ collisions. Note also that value references are not concerned with collisions as defined here. Also note that while the collision is case-insensitive, name resolution -is *not* case-insensitive in DAML-LF. In other words, to refer to a +is *not* case-insensitive in Daml-LF. In other words, to refer to a name, one must refer to it with the same case that it was defined with. The case-insensitivity for collisions is in place since we often generate -files from DAML-LF packages, and we want to make sure for things to work +files from Daml-LF packages, and we want to make sure for things to work smoothly when operating in case-insensitive file systems, while at the same time preserving case sensitivity in the language. @@ -1704,7 +1704,7 @@ same time preserving case sensitivity in the language. Name collision condition ........................ -In DAML-LF, the only permitted name collisions are those occurring +In Daml-LF, the only permitted name collisions are those occurring between variant constructors and record types defined in the same module. Every other collision makes the module (and thus the package) not well-formed. For example, a module ``Mod`` can contain the following @@ -1760,7 +1760,7 @@ usage ``Ξ``. Values ~~~~~~ -To define any call-by-value semantics for DAML-LF expression, we need +To define any call-by-value semantics for Daml-LF expression, we need first to define the notion of *values*, the expressions which do not need to be evaluated further. :: @@ -2183,7 +2183,7 @@ closure of ``<ₜ``. Expression evaluation ~~~~~~~~~~~~~~~~~~~~~ -DAML-LF evaluation is only defined on closed, well-typed expressions. +Daml-LF evaluation is only defined on closed, well-typed expressions. Note that the evaluation of the body of a value definition is lazy. It happens only when needed and cached to avoid repeated computations. We @@ -2198,7 +2198,7 @@ preserved between different evaluations happening in the ledger. We only guarantee that within a single evaluation each value definition is evaluated at most once. -The output of any DAML-LF built-in function ``F`` fully applied to +The output of any Daml-LF built-in function ``F`` fully applied to types ``@τ₁ … @τₘ`` and values ``v₁ … vₙ`` is deterministic. In the following rules, we abstract this output with the notation ``𝕆(F @τ₁ … @τₘ v₁ … vₙ)``. Please refer to the `Built-in functions`_ section for the @@ -3181,7 +3181,7 @@ About scenario interpretation ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ The interpretation of scenarios is a feature an engine can provide to -test business logic within a DAML-LF archive. Nevertheless, the +test business logic within a Daml-LF archive. Nevertheless, the present specification does not define how scenarios should be actually interpreted. An engine compliant with this specification does not have to provide support for scenario interpretation. It must however accept @@ -3198,7 +3198,7 @@ evaluated during the interpretation of an update. Built-in functions ^^^^^^^^^^^^^^^^^^ -This section lists the built-in functions supported by DAML LF 1. +This section lists the built-in functions supported by Daml LF 1. The functions come with their types and a description of their behavior. @@ -3753,7 +3753,7 @@ Timestamp functions * The output uses at least as many digits as necessary but may be padded on the right with an unspecified number of "``0``". - * The output will not change within minor version of DAML-LF 1. + * The output will not change within minor version of Daml-LF 1. Date functions @@ -4198,20 +4198,20 @@ Debugging functions Program serialization ^^^^^^^^^^^^^^^^^^^^^ -DAML-LF programs are serialized using `Protocol Buffers +Daml-LF programs are serialized using `Protocol Buffers `_. The -machine-readable definition of the serialization for DAML-LF major +machine-readable definition of the serialization for Daml-LF major version 1 can be found in the `daml_lf_1.proto <../archive/src/main/protobuf/com/daml/daml_lf_dev/daml_lf_1.proto>`_ file. -For the sake of brevity, we do no exhaustively describe how DAML-LF +For the sake of brevity, we do no exhaustively describe how Daml-LF programs are (un)serialized into protocol buffer. In the rest of this section, we describe the particularities of the encoding and how -DAML-LF version impacts it. +Daml-LF version impacts it. -Specificities of DAML-LF serialization +Specificities of Daml-LF serialization ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ Required fields @@ -4294,7 +4294,7 @@ The message is interpreted as n applications ``(e e₁ … eₙ)`` where ``eᵢ`` is the interpretation of the ``iᵗʰ`` elements of ``args`` (whenever ``1 ≤ i ≤ n``) and ``e`` is the interpretation of ``fun``. -Note that the DAML-LF deserialization process verifies the repeated +Note that the Daml-LF deserialization process verifies the repeated fields of those compressed structures are non-empty. For instance, the previous message can be used only if it encodes at least one application. @@ -4312,7 +4312,7 @@ Maps .... The program serialization format does not provide any direct way to -encode either `TextMap` or `GenMap`. DAML-LF programs can create such +encode either `TextMap` or `GenMap`. Daml-LF programs can create such objects only dynamically using the builtin functions prefixed by `TEXTMAP_` or `'GENMAP_'` @@ -4357,8 +4357,8 @@ package if and only if the latter of these two validation passes. Serialization changes since version 1.6 ~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ -As explained in `Version history`_ section, DAML-LF programs are -accompanied by a number version. This enables the DAML-LF +As explained in `Version history`_ section, Daml-LF programs are +accompanied by a number version. This enables the Daml-LF deserialization process to interpret different versions of the language in a backward compatibility way. During deserialization, any encoding that does not follow the minor version provided is rejected. @@ -4389,14 +4389,14 @@ in ``Package.interned_strings``. + An `interned identifier` is an `interned string` that can be interpreted as a valid `identifier` -Starting from DAML-LF 1.7, all ``string`` (or ``repeated string``) +Starting from Daml-LF 1.7, all ``string`` (or ``repeated string``) fields with the suffix ``_str`` are forbidden. Alternative fields of type ``int32`` (or ``repeated int32``) with the suffix ``_interned_str`` must be used instead. Except ``PackageRef.package_id_interned_str`` which is [*Available in versions >= 1.6*], all fields with suffix ``_interned_str`` are [*Available in versions >= 1.7*]. The deserialization process will -reject any DAML-LF 1.7 (or later) that does not comply with this +reject any Daml-LF 1.7 (or later) that does not comply with this restriction. Name Interning @@ -4416,11 +4416,11 @@ so-called `interned name` is a valid zero-based index of this list. An `interned name` is interpreted as the name built form the `name` it points to in ``Package.interned_dotted_names``. -Starting from DAML-LF 1.7, all ``DottedName`` (or ``repeated +Starting from Daml-LF 1.7, all ``DottedName`` (or ``repeated string``) fields with the suffix ``_dname`` are forbidden. Alternative fields of type ``int32`` with the suffix ``_interned_dname`` [*Available in versions >= 1.7*] must be used instead. The -deserialization process will reject any DAML-LF 1.7 (or later) that +deserialization process will reject any Daml-LF 1.7 (or later) that that does not comply this restriction. Nat kind and Nat types @@ -4428,15 +4428,15 @@ Nat kind and Nat types [*Available in versions >= 1.7*] -The deserialization process will reject any DAML-LF 1.6 (or earlier) +The deserialization process will reject any Daml-LF 1.6 (or earlier) that uses ``nat`` field in ``Kind`` or ``Type`` messages. -Starting from DAML-LF 1.7 those messages are deserialized to ``nat`` +Starting from Daml-LF 1.7 those messages are deserialized to ``nat`` kind and ``nat`` type respectively. The field ``nat`` of ``Type`` message must be a positive integer. Note that despite there being no concrete way to build Nat types in a -DAML-LF 1.6 (or earlier) program, those are implicitly generated when +Daml-LF 1.6 (or earlier) program, those are implicitly generated when reading as Numeric type and Numeric builtin as described in the next section. @@ -4445,12 +4445,12 @@ Parametric scaled Decimals [*Available in versions >= 1.7*] -DAML-LF 1.7 is the first version that supports parametric scaled +Daml-LF 1.7 is the first version that supports parametric scaled decimals. Prior versions have decimal number with a fixed scale of 10 called Decimal. Backward compatibility with the current specification is achieved as follows: -On the one hand, in case of DAML-LF 1.6 archive: +On the one hand, in case of Daml-LF 1.6 archive: - The ``decimal`` field of the ``PrimLit`` message must match the regexp:: @@ -4486,10 +4486,10 @@ On the one hand, in case of DAML-LF 1.6 archive: In other words ``numeric`` fields in ``PrimLit`` and ``PrimType`` messages must remain unset and Numeric ``BuiltinFunction`` (those containing ``NUMERIC`` in their name) are forbidden. The - deserialization process will reject any DAML-LF 1.6 (or earlier) + deserialization process will reject any Daml-LF 1.6 (or earlier) that does not comply those restrictions. -On the other hand, starting from DAML-LF 1.7: +On the other hand, starting from Daml-LF 1.7: - The ``numeric`` field of the ``PrimLit`` message must match the regexp: @@ -4506,16 +4506,16 @@ On the other hand, starting from DAML-LF 1.7: In other words ``decimal`` fields in ``PrimLit`` and ``PrimType`` messages must remain unset and Decimal ``BuiltinFunction`` (those containing ``DECIMAL`` in their name are forbidden). The - deserialization process will reject any DAML-LF 1.7 (or later) + deserialization process will reject any Daml-LF 1.7 (or later) that does not comply those restrictions. Any type and type representation ................................ -DAML-LF 1.7 is the first version that supports any type and +Daml-LF 1.7 is the first version that supports any type and type representation. -The deserialization process will reject any DAML-LF 1.6 program using +The deserialization process will reject any Daml-LF 1.6 program using this data structure. Generic Equality/Order @@ -4523,11 +4523,11 @@ Generic Equality/Order [*Available in versions >= 1.11*] -The deserialization process will reject any DAML-LF 1.8 (or earlier) +The deserialization process will reject any Daml-LF 1.8 (or earlier) program using the following builtin functions ``EQUAL``, ``LESS_EQ``, ``LESS``, ``GREATER_EQ``, ``GREATER`` -The deserialization process will reject any DAML-LF 1.11 (or latter) +The deserialization process will reject any Daml-LF 1.11 (or latter) program using the following builtin functions , ``EQUAL_INT64``, ``EQUAL_NUMERIC``, ``EQUAL_TEXT``, ``EQUAL_TIMESTAMP``, ``EQUAL_DATE``, ``EQUAL_PARTY``, ``EQUAL_BOOL``, @@ -4545,7 +4545,7 @@ Generic Map [*Available in versions >= 1.11*] -The deserialization process will reject any DAML-LF 1.8 (or earlier) +The deserialization process will reject any Daml-LF 1.8 (or earlier) program using the builtin type ``GENMAP`` or the builtin functions ``GENMAP_EMPTY``, ``GENMAP_INSERT``, ``GENMAP_LOOKUP``, ``GENMAP_DELETE``, ``GENMAP_KEYS``, ``GENMAP_VALUES``, @@ -4556,7 +4556,7 @@ exercise_by_key [*Available in versions >= 1.11*] -The deserialization process will reject any DAML-LF 1.8 (or earlier) +The deserialization process will reject any Daml-LF 1.8 (or earlier) program using the field ``exercise_by_key`` in the ``Update`` message. TO_TEXT_CONTRACT_ID @@ -4564,7 +4564,7 @@ TO_TEXT_CONTRACT_ID [*Available in versions >= 1.11*] -The deserialization process will reject any DAML-LF 1.8 (or earlier) +The deserialization process will reject any Daml-LF 1.8 (or earlier) program using the builtin function ``TO_TEXT_CONTRACT_ID``. Choice observers @@ -4576,7 +4576,7 @@ An optional `observer` expression may be attached to a flexible choice. This allows the specification of additional parties to whom the sub-transaction is disclosed. -The deserialization process will reject any DAML-LF 1.8 (or earlier) +The deserialization process will reject any Daml-LF 1.8 (or earlier) program using the field ``observers`` in the ``TemplateChoice`` message. @@ -4585,7 +4585,7 @@ Exception [*Available in versions >= 1.1dev*] -The deserialization process will reject any DAML-LF 1.11 (or earlier) +The deserialization process will reject any Daml-LF 1.11 (or earlier) program exception using - the field ``throw``, ``to_any_exception``, or ``from_any_exception`` in the ``Expr`` message, diff --git a/daml-lf/spec/transaction.rst b/daml-lf/spec/transaction.rst index f386103b56..28f1dc328a 100644 --- a/daml-lf/spec/transaction.rst +++ b/daml-lf/spec/transaction.rst @@ -2,13 +2,13 @@ .. SPDX-License-Identifier: Apache-2.0 -DAML-LF Transaction Specification +Daml-LF Transaction Specification ================================= **version 10, 25 March 2020** This specification, in concert with the ``transaction.proto`` -machine-readable definition, defines a format for *DAML LF +machine-readable definition, defines a format for *Daml LF transactions*, to be used when inspecting ledger activity as a st ream, or submitting changes to the ledger. @@ -17,9 +17,9 @@ A *ledger* can be viewed as a sequence of these transactions. Do not read this without ``transaction.proto`` ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -``transaction.proto`` defines the baseline rules for *DAML-LF +``transaction.proto`` defines the baseline rules for *Daml-LF transactions*; that file must be consulted in concert with this -document for a full specification of DAML-LF transactions. Except +document for a full specification of Daml-LF transactions. Except where required for clarity, we do not repeat rules defined and enforced in that file within this document. When consulting the section on each message type, you must also refer to the same @@ -39,16 +39,16 @@ impossible to define all the requirements for transactions in the ``.proto`` format. All such rules are included in this document, instead. -If you are constructing a DAML-LF transaction, it is not sufficient to +If you are constructing a Daml-LF transaction, it is not sufficient to merely conform to the structure defined in ``transaction.proto``; you must also conform to the rules defined in this document. A transaction that happens to conform to ``transaction.proto``, yet violates some rule -of this document, is not a valid DAML-LF transaction. +of this document, is not a valid Daml-LF transaction. Backward compatibility ^^^^^^^^^^^^^^^^^^^^^^ -DAML-LF transaction nodes, and transactions are encoded according a +Daml-LF transaction nodes, and transactions are encoded according a common versioning scheme, called the *transaction version scheme*. Each version of this scheme, called a transaction version, is associated to a language version. @@ -126,7 +126,7 @@ version 13* section must be ignored entirely. Changing this specification ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Future versions of this specification must conform to the `DAML-LF +Future versions of this specification must conform to the `Daml-LF Governance process`_ and preserve all invariants described above. Where these are in conflict, the governance process takes priority. @@ -159,7 +159,7 @@ important subtlety in the comparison. Additionally, you should update the following `Version history`_. -.. _`DAML-LF Governance process`: ../governance.rst +.. _`Daml-LF Governance process`: ../governance.rst .. _`value`: value.rst Version history @@ -221,7 +221,7 @@ message ContractInstance *since version 10* -An instance of a DAML-LF template, represented by the DAML-LF value used +An instance of a Daml-LF template, represented by the Daml-LF value used to construct that instance. As of version 10, these fields are included: @@ -232,7 +232,7 @@ As of version 10, these fields are included: ``template_id`` and ``value`` are required; ``agreement`` is optional. -``value`` must conform to the type of the DAML-LF associated data type +``value`` must conform to the type of the Daml-LF associated data type indicated by ``template_id``. ``template_id``'s structure is defined by `the value specification`_; @@ -332,7 +332,7 @@ message NodeCreate *since version 10* -The creation of a contract by instantiating a DAML-LF template with the +The creation of a contract by instantiating a Daml-LF template with the given argument. As of version 10, these fields are included: @@ -356,7 +356,7 @@ Every element of ``stakeholders`` is a party identifier. The stakeholders of a contract are the signatories and the observers of said contract. - The signatories of a contract are specified in the DAML-LF definition of + The signatories of a contract are specified in the Daml-LF definition of the template for said contract. Conceptually, they are the parties that agreed for that contract to be created. @@ -368,7 +368,7 @@ Every element of ``stakeholders`` is a party identifier. * Its ``key`` must conform to the key definition for the ``template_id`` in the ``contract_instance``. -The maintainers of a contract key are specified in the DAML-LF definition of +The maintainers of a contract key are specified in the Daml-LF definition of the template for the contract. message NodeFetch @@ -376,7 +376,7 @@ message NodeFetch *since version 10* -Evidence of a DAML-LF ``fetch`` invocation. +Evidence of a Daml-LF ``fetch`` invocation. As of version 10, these fields are included: @@ -407,7 +407,7 @@ identifier. contract itself. ``key_with_maintainers`` is optional. It is present if and only if the -``template_id`` field refers to a template with a DAML-LF key +``template_id`` field refers to a template with a Daml-LF key definition. When present, the field's sub-fields ``key`` and ``maintainers`` must conform to the key definition for the ``template_id``. @@ -418,7 +418,7 @@ message NodeExercise *since version 10* The exercise of a choice on a contract, selected from the available -choices in the associated DAML-LF template definition. +choices in the associated Daml-LF template definition. As of version 10, these fields are included: @@ -444,10 +444,10 @@ to be non-empty. the version of that specification to use when consuming it is the ``version`` field of ``chosen_value``. -``choice`` must be the name of a choice defined in the DAML-LF template +``choice`` must be the name of a choice defined in the Daml-LF template definition referred to by ``template_id``. -``chosen_value`` must conform to the DAML-LF argument type of the +``chosen_value`` must conform to the Daml-LF argument type of the ``choice``. ``children`` is constrained as described under `field node_id`_. Every diff --git a/daml-lf/spec/value.rst b/daml-lf/spec/value.rst index 24a6864b33..d2301390fb 100644 --- a/daml-lf/spec/value.rst +++ b/daml-lf/spec/value.rst @@ -1,21 +1,21 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML-LF Value Specification +Daml-LF Value Specification =========================== **version 6, 10 Dec 2020** -The DAML-LF language includes ways to define *data types*, +The Daml-LF language includes ways to define *data types*, specifications of structure, and includes rules by which a restricted subset of those data types are considered *serializable*. This specification, in concert with the ``value.proto`` machine-readable -definition, defines a format by which *values* of *serializable DAML-LF +definition, defines a format by which *values* of *serializable Daml-LF types* may be represented. Only such *serializable values* may be stored on a ledger. -Values are typically consumed in tandem with related DAML-LF type +Values are typically consumed in tandem with related Daml-LF type information, so many fields that may be inferred with this information are optional. For example, `message RecordField`_ names are defined as part of their respective LF datatypes, so there is no need to repeat @@ -26,7 +26,7 @@ Do not read this without ``value.proto`` ``value.proto`` defines the baseline rules for values; that file must be consulted in concert with this document for a full specification of -DAML-LF values. Except where required for clarity, we do not repeat +Daml-LF values. Except where required for clarity, we do not repeat rules defined and enforced in that file within this document. When consulting the section on each message type, you must also refer to the same definition in ``value.proto`` for a full definition of the @@ -43,16 +43,16 @@ full specification of the value format, because it is impossible to define all the requirements for values in the ``.proto`` format. All such rules are included in this document, instead. -If you are constructing a DAML-LF value, it is not sufficient to merely +If you are constructing a Daml-LF value, it is not sufficient to merely conform to the structure defined in ``value.proto``; you must also conform to the rules defined in this document. A value that happens to conform to ``value.proto``, yet violates some rule of this document, is -not a valid DAML-LF value. +not a valid Daml-LF value. Backward compatibility ^^^^^^^^^^^^^^^^^^^^^^ -DAML-LF values are accompanied by a version identifier; every change to +Daml-LF values are accompanied by a version identifier; every change to ``value.proto`` entails a change to this specification, and every change to this specification introduces a unique new version. `Version history`_ defines a total ordering of all past versions; any version *y* @@ -104,7 +104,7 @@ must be ignored entirely. Changing this specification ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -Future versions of this specification must conform to the `DAML-LF +Future versions of this specification must conform to the `Daml-LF Governance process`_ and preserve all invariants described above. Where these are in conflict, the governance process takes priority. @@ -137,7 +137,7 @@ important subtlety in the comparison. Additionally, you should update the following `Version history`_. -.. _`DAML-LF Governance process`: ../governance.rst +.. _`Daml-LF Governance process`: ../governance.rst .. _`transaction`: transaction.rst Version history @@ -196,7 +196,7 @@ message Value *since version 6* -An actual DAML-LF *serializable value*. +An actual Daml-LF *serializable value*. As of version 6, may be any one of these: @@ -288,7 +288,7 @@ field unit While ``Empty`` contains no information, conforming consumers are permitted to expect this member of `message Value`_ to be chosen -correctly in appropriate contexts. So if the ``Value``'s DAML-LF type +correctly in appropriate contexts. So if the ``Value``'s Daml-LF type is ``Unit``, a consumer *may* reject the message if the ``Value`` is not the ``unit`` member of the sum, so value producers must take care to select this member and not another value as a placeholder (e.g. 0, @@ -322,7 +322,7 @@ field record_id *since version 6* -The fully-qualified `message Identifier`_ of the DAML-LF record type. +The fully-qualified `message Identifier`_ of the Daml-LF record type. It may be omitted. field fields @@ -332,13 +332,13 @@ field fields Zero or more `message RecordField`_ values. -The number and types of values in the fields must match the DAML-LF +The number and types of values in the fields must match the Daml-LF record type associated with the `message Record`_, whether that record type is inferred from context or explicitly supplied as a `field record_id`_. Additionally, the *order* of fields must match the order in which they -are declared in DAML-LF for that record type. Neither producers nor +are declared in Daml-LF for that record type. Neither producers nor consumers are permitted to use ``label`` to reorder the fields. So, for example, it is unsafe to use a ``Map``, ``HashMap``, or some @@ -360,7 +360,7 @@ As of version 6, these fields are included: * `message Value`_ value ``label`` may be an empty string. However, if ``label`` is non-empty, -it must match the name of the field in this position in the DAML-LF +it must match the name of the field in this position in the Daml-LF record type under consideration. For example, if the second field of an LF record type is named ``bar``, then label of the second element of `field fields`_ may be ``"bar"``, or an empty string in circumstances @@ -375,7 +375,7 @@ message Identifier *since version 6* -A reference to a DAML-LF record or variant type. +A reference to a Daml-LF record or variant type. As of version 1, these fields are included, all required to be non-empty: @@ -384,7 +384,7 @@ non-empty: * repeated ``string`` module_name * repeated ``string`` name -``package_id`` is a DAML-LF package ID, indicating the LF package in +``package_id`` is a Daml-LF package ID, indicating the LF package in which the type is defined. package ID are restricted to be a non-empty string of printable US-ASCII characters (characters ranging from '\32' to '\127'). @@ -427,7 +427,7 @@ field variant_id *since version 6* -The fully-qualified `message Identifier`_ of the DAML-LF variant type. +The fully-qualified `message Identifier`_ of the Daml-LF variant type. It may be omitted. field constructor diff --git a/daml-lf/transaction/src/main/protobuf/com/daml/lf/transaction.proto b/daml-lf/transaction/src/main/protobuf/com/daml/lf/transaction.proto index 579a584f79..f06044da0a 100644 --- a/daml-lf/transaction/src/main/protobuf/com/daml/lf/transaction.proto +++ b/daml-lf/transaction/src/main/protobuf/com/daml/lf/transaction.proto @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // Please refer to the transaction spec (in daml-foundations/daml-lf/spec/transaction.rst) -// which describes the semantics of DAML-LF transactions in more detail. +// which describes the semantics of Daml-LF transactions in more detail. // // [one-line] version summary // * 10: new field key_with_maintainers in NodeFetch @@ -15,7 +15,7 @@ option java_package = "com.daml.lf.transaction"; import "com/daml/lf/value.proto"; -// data structure represent an update to the ledger. executing a DAML-LF action of type +// data structure represent an update to the ledger. executing a Daml-LF action of type // Update A produces produces one of these. // architecture-handbook-entry-begin: Transaction message Transaction { diff --git a/daml-lf/transaction/src/main/protobuf/com/daml/lf/value.proto b/daml-lf/transaction/src/main/protobuf/com/daml/lf/value.proto index 7fd87eddfc..96ee57dbad 100644 --- a/daml-lf/transaction/src/main/protobuf/com/daml/lf/value.proto +++ b/daml-lf/transaction/src/main/protobuf/com/daml/lf/value.proto @@ -2,7 +2,7 @@ // SPDX-License-Identifier: Apache-2.0 // Please refer to the value spec (in daml-foundations/daml-lf/spec/value.rst) -// which describes the semantics of DAML-LF values in more detail. +// which describes the semantics of Daml-LF values in more detail. // // [one-line] version summary // * 6: initial version @@ -20,7 +20,7 @@ message VersionedValue { Value value = 2; } -// The universe of serializable DAML-LF values. +// The universe of serializable Daml-LF values. // architecture-handbook-entry-begin: Value message Value { oneof sum { diff --git a/daml-script/daml/Daml/Script.daml b/daml-script/daml/Daml/Script.daml index b62db8fe4f..b419efcc6f 100644 --- a/daml-script/daml/Daml/Script.daml +++ b/daml-script/daml/Daml/Script.daml @@ -147,10 +147,10 @@ data SetTimePayload a = SetTimePayload -- | Set the time via the time service. -- -- This is only supported in static time mode when running over the gRPC API --- and in DAML Studio. +-- and in Daml Studio. -- -- Note that the ledger time service does not support going backwards in time. --- However, you can go back in time in DAML Studio. +-- However, you can go back in time in Daml Studio. setTime : Time -> Script () setTime time = lift $ Free $ SetTime $ SetTimePayload with time @@ -159,12 +159,12 @@ setTime time = lift $ Free $ SetTime $ SetTimePayload with -- | Advance ledger time by the given interval. -- -- Only supported in static time mode when running over the gRPC API --- and in DAML Studio. Note that this is not an atomic operation over the +-- and in Daml Studio. Note that this is not an atomic operation over the -- gRPC API so no other clients should try to change time while this is -- running. -- -- Note that the ledger time service does not support going backwards in time. --- However, you can go back in time in DAML Studio. +-- However, you can go back in time in Daml Studio. passTime : RelTime -> Script () passTime rt = do t <- getTime @@ -332,7 +332,7 @@ instance HasSubmit Script Commands where -- -- 1. NonEmpty Party -> [Party] -> … -- This is the safest one but it’s rather awkward to use since NonEmpty is --- long and fairly uncommon. Given that DAML Script is primarily used during +-- long and fairly uncommon. Given that Daml Script is primarily used during -- testing and development, the extra safety is also not that crucial. -- It is also different from signatories which also needs to be nonempty but -- does not enforce this statically. @@ -375,7 +375,7 @@ submitMultiMustFail actAs readAs cmds = continue = const () locations = getCallStack callStack --- | This is the type of A DAML script. `Script` is an instance of `Action`, +-- | This is the type of A Daml script. `Script` is an instance of `Action`, -- so you can use `do` notation. data Script a = Script with runScript : () -> (Free ScriptF (a, ())) diff --git a/daml-script/daml/daml-script-hoogle-template.txt b/daml-script/daml/daml-script-hoogle-template.txt index 6d4ddb86e7..5a6e1fc172 100644 --- a/daml-script/daml/daml-script-hoogle-template.txt +++ b/daml-script/daml/daml-script-hoogle-template.txt @@ -4,7 +4,7 @@ -- (C) Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. -- All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited. --- | DAML Script library. +-- | Daml Script library. @url {{base-url}} @package daml-script @version 1.2.0 diff --git a/daml-script/daml/daml-script-index-template.rst b/daml-script/daml/daml-script-index-template.rst index de79f261fc..7b90dd8b01 100644 --- a/daml-script/daml/daml-script-index-template.rst +++ b/daml-script/daml/daml-script-index-template.rst @@ -3,9 +3,9 @@ .. _daml-script-api-docs: -DAML Script Library +Daml Script Library ==================== -The DAML Script library defines the API used to implement DAML scripts. See :doc:`/daml-script/index`:: for more information on DAML script. +The Daml Script library defines the API used to implement Daml scripts. See :doc:`/daml-script/index`:: for more information on Daml script. {{{body}}} diff --git a/dev-env/dotfiles/README.md b/dev-env/dotfiles/README.md index 4f21eac254..30575c72ef 100644 --- a/dev-env/dotfiles/README.md +++ b/dev-env/dotfiles/README.md @@ -1,4 +1,4 @@ -# Editor DAML Language Integration +# Editor Daml Language Integration ## Vim @@ -15,7 +15,7 @@ your `~/.vimrc`. ## VS Code -Follow the DAML Studio installation instructions in the DAML user guide. +Follow the Daml Studio installation instructions in the Daml user guide. ## Update Keywords diff --git a/docs/README.md b/docs/README.md index 5635483c54..ed100d647a 100644 --- a/docs/README.md +++ b/docs/README.md @@ -1,4 +1,4 @@ -# DAML Documentation +# Daml Documentation This directory contains all of the documentation that gets published to docs.daml.com. @@ -20,7 +20,7 @@ To edit documentation: Not all of our docs are in rst files: some get generated. They are: - the ledger API proto docs -- the DAML standard library reference +- the Daml standard library reference - the Java bindings reference To edit those docs, edit the content inside the code source. diff --git a/docs/configs/html/conf.py b/docs/configs/html/conf.py index 9d9497add1..2cd078b6e5 100644 --- a/docs/configs/html/conf.py +++ b/docs/configs/html/conf.py @@ -3,7 +3,7 @@ # -*- coding: utf-8 -*- # -# DAML SDK documentation build configuration file, created by +# Daml SDK documentation build configuration file, created by # sphinx-quickstart on Wed Jul 5 17:39:28 2017. # # This file is execfile()d with the current directory set to its @@ -51,8 +51,8 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'DAML SDK' -copyright = u'© Copyright 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited. "Digital Asset" and "DAML" are Registered in the U.S. Patent and Trademark Office.' +project = u'Daml SDK' +copyright = u'© Copyright 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited. "Digital Asset" and "Daml" are Registered in the U.S. Patent and Trademark Office.' author = u'Digital Asset' # The version info for the project you're documenting, acts as replacement for @@ -145,7 +145,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'DigitalAssetSDK.tex', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK.tex', u'Daml SDK Documentation', u'Digital Asset', 'manual'), ] @@ -155,7 +155,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'digitalassetsdk', u'DAML SDK Documentation', + (master_doc, 'digitalassetsdk', u'Daml SDK Documentation', [author], 1) ] @@ -166,7 +166,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'DigitalAssetSDK', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK', u'Daml SDK Documentation', author, 'DigitalAssetSDK', 'One line description of project.', 'Miscellaneous'), ] @@ -178,7 +178,7 @@ rst_prolog = """ .. _http-json: https://github.com/digital-asset/daml/releases/download/v{release}/http-json-{release}.jar """.format(release = release) -# Import the DAML lexer +# Import the Daml lexer def setup(sphinx): from pygments_daml_lexer import DAMLLexer sphinx.add_lexer("daml", DAMLLexer()) diff --git a/docs/configs/pdf/conf.py b/docs/configs/pdf/conf.py index 9e5890b690..3eb17a5f50 100644 --- a/docs/configs/pdf/conf.py +++ b/docs/configs/pdf/conf.py @@ -3,7 +3,7 @@ # -*- coding: utf-8 -*- # -# DAML SDK documentation build configuration file, created by +# Daml SDK documentation build configuration file, created by # sphinx-quickstart on Wed Jul 5 17:39:28 2017. # # This file is execfile()d with the current directory set to its @@ -53,7 +53,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'DAML SDK' +project = u'Daml SDK' copyright = u'© Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited.' author = u'Digital Asset' @@ -256,7 +256,7 @@ latex_elements = { \centering \vspace*{40mm} %%% * is used to give space from top - \textcolor{headerblue}{\sffamily{\textbf{\Huge {DAML SDK Documentation}}}} + \textcolor{headerblue}{\sffamily{\textbf{\Huge {Daml SDK Documentation}}}} \vspace{20mm} \begin{figure}[!h] @@ -303,7 +303,7 @@ latex_logo = 'logo.png' # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'DigitalAssetSDK.tex', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK.tex', u'Daml SDK Documentation', u'Digital Asset', 'manual'), ] @@ -313,7 +313,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'digitalassetsdk', u'DAML SDK Documentation', + (master_doc, 'digitalassetsdk', u'Daml SDK Documentation', [author], 1) ] @@ -324,7 +324,7 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'DigitalAssetSDK', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK', u'Daml SDK Documentation', author, 'DigitalAssetSDK', 'One line description of project.', 'Miscellaneous'), ] @@ -336,7 +336,7 @@ rst_prolog = """ .. _api-test-tool: https://repo1.maven.org/maven2/com/daml/ledger-api-test-tool/{release}/ledger-api-test-tool-{release}.jar """.format(release = release) -# Import the DAML lexer +# Import the Daml lexer def setup(sphinx): from pygments_daml_lexer import DAMLLexer sphinx.add_lexer("daml", DAMLLexer()) diff --git a/docs/configs/pdf/index.rst b/docs/configs/pdf/index.rst index 284f596abe..82dc1243e8 100644 --- a/docs/configs/pdf/index.rst +++ b/docs/configs/pdf/index.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Documentation +Daml Documentation ================== Getting started @@ -18,7 +18,7 @@ Getting started getting-started/testing Cheat Sheet -Writing DAML +Writing Daml ------------ .. toctree:: @@ -42,13 +42,13 @@ Building applications app-dev/app-arch app-dev/bindings-ts/index json-api/index - DAML Script - DAML REPL + Daml Script + Daml REPL upgrade/index app-dev/authorization app-dev/ledger-api -Deploying to DAML ledgers +Deploying to Daml ledgers ------------------------- .. toctree:: @@ -59,7 +59,7 @@ Deploying to DAML ledgers deploy/generic_ledger deploy/ledger-topologies -Operating DAML +Operating Daml -------------- .. toctree:: @@ -117,7 +117,7 @@ Early Access Features tools/trigger-service concepts/interoperability -DAML Ecosystem +Daml Ecosystem -------------- .. toctree:: diff --git a/docs/configs/static/pygments_daml_lexer.py b/docs/configs/static/pygments_daml_lexer.py index d4040ae54a..41aebf2623 100644 --- a/docs/configs/static/pygments_daml_lexer.py +++ b/docs/configs/static/pygments_daml_lexer.py @@ -7,7 +7,7 @@ from pygments.token import * class DAMLLexer(HaskellLexer): - name = 'DAML' + name = 'Daml' aliases = ['daml'] filenames = ['*.daml'] diff --git a/docs/source/app-dev/app-arch.rst b/docs/source/app-dev/app-arch.rst index 90069be2f6..d2a8b6d95c 100644 --- a/docs/source/app-dev/app-arch.rst +++ b/docs/source/app-dev/app-arch.rst @@ -6,13 +6,13 @@ Application architecture ######################## -This section describes our recommended design of a full-stack DAML application. +This section describes our recommended design of a full-stack Daml application. .. image:: ./recommended_architecture.svg The above image shows the recommended architecture. Of course there are many ways how you can change the architecture and technology stack to fit your needs, which we'll mention in the corresponding -sections. Note that the Participant Node is integrated into the DAML drivers in some cases rather +sections. Note that the Participant Node is integrated into the Daml drivers in some cases rather than being part of the Application Backend. See :doc:`/support/overview` for more details. To get started quickly with the recommended application architecture clone the @@ -25,34 +25,34 @@ To get started quickly with the recommended application architecture clone the ``create-daml-app`` is a small, but fully functional demo application implementing the recommended architecture, providing you with an excellent starting point for your own application. It showcases -- using DAML React libraries -- quick iteration against the :ref:`DAML Sandbox `. +- using Daml React libraries +- quick iteration against the :ref:`Daml Sandbox `. - authorization - 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 `) file. +The backend for your application can be any Daml ledger implementation running your DAR +(:ref:`Daml Archive `) file. -We recommend using the :ref:`DAML JSON API ` as an interface to your frontend. It is +We recommend using the :ref:`Daml JSON API ` as an interface to your frontend. It is served by the HTTP JSON API server connected to the ledger API server. It provides simple HTTP endpoints to interact with the ledger via GET/POST requests. However, if you prefer, you can also use the :ref:`gRPC Ledger API ` directly. -When you use the ``create-daml-app`` template application, you can start a DAML Sandbox together +When you use the ``create-daml-app`` template application, you can start a Daml Sandbox together with a JSON API server by running .. code-block:: bash daml start --start-navigator=no -in the root of the project. DAML Sandbox exposes the same DAML Ledger API a Participant Node would -expose without requiring a fully-fledged DAML network to back the application. Once your +in the root of the project. Daml Sandbox exposes the same Daml Ledger API a Participant Node would +expose without requiring a fully-fledged Daml network to back the application. Once your application matures and becomes ready for production, the ``daml deploy`` command helps you deploy -your frontend and DAML artifacts of your project to a production DAML network. See -:ref:`Deploying to DAML Ledgers ` for an in depth manual for specific ledgers. +your frontend and Daml artifacts of your project to a production Daml network. See +:ref:`Deploying to Daml Ledgers ` for an in depth manual for specific ledgers. Frontend ~~~~~~~~ @@ -64,21 +64,21 @@ you can choose virtually any language for your frontend and interact with the le :ref:`gRPC Ledger API ` directly. -We provide two libraries to build your React frontend for a DAML application. +We provide two libraries to build your React frontend for a Daml application. +--------------------------------------------------------------+--------------------------------------------------------------------------+ | Name | Summary | +==============================================================+==========================================================================+ -| `@daml/react `_ | React hooks to query/create/exercise DAML contracts | +| `@daml/react `_ | React hooks to query/create/exercise Daml contracts | +--------------------------------------------------------------+--------------------------------------------------------------------------+ -| `@daml/ledger `_ | DAML ledger object to connect and directly submit commands to the ledger | +| `@daml/ledger `_ | Daml ledger object to connect and directly submit commands to the ledger | +--------------------------------------------------------------+--------------------------------------------------------------------------+ You can install any of these libraries by running ``npm install `` in the ``ui`` directory of your project, e.g. ``npm install @daml/react``. Please explore the ``create-daml-app`` example project to see the usage of these libraries. -To make your life easy when interacting with the ledger, the DAML assistant can generate JavaScript +To make your life easy when interacting with the ledger, the Daml assistant can generate JavaScript libraries with TypeScript typings from the data types declared in the deployed DAR. .. code-block:: bash @@ -100,10 +100,10 @@ Authorization When you deploy your application to a production ledger, you need to authenticate the identities of your users. -DAML ledgers support a unified interface for authorization of commands. Some DAML ledgers, like for +Daml ledgers support a unified interface for authorization of commands. Some Daml ledgers, like for example https://projectdabl.com, offer integrated authentication and authorization, but you can also -use an external service provider like https://auth0.com. The DAML react libraries support interfacing -with a DAML ledger that validates authorization of incoming requests. Simply initialize your +use an external service provider like https://auth0.com. The Daml react libraries support interfacing +with a Daml ledger that validates authorization of incoming requests. Simply initialize your ``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 ` section. @@ -111,18 +111,18 @@ Developer workflow ~~~~~~~~~~~~~~~~~~ The SDK enables a local development environment with fast iteration cycles. If you run -``daml-reload-on-change.sh`` of the ``create-daml-app``, a local DAML Sandbox is started that -is updated with your most recent DAML code on any change. Next, you can start your frontend in +``daml-reload-on-change.sh`` of the ``create-daml-app``, a local Daml Sandbox is started that +is updated with your most recent Daml code on any change. Next, you can start your frontend in development mode by changing to your ``ui`` directory and run ``npm start``. This will reload your -frontend whenever you make changes to it. You can add unit tests for your DAML models by writing -:ref:`DAML scenarios `. These will also be reevaluated on change. A -typical DAML developer workflow is to +frontend whenever you make changes to it. You can add unit tests for your Daml models by writing +:ref:`Daml scenarios `. These will also be reevaluated on change. A +typical Daml developer workflow is to - #. Make a small change to your DAML data model - #. Optionally test your DAML code and with :ref:`scenarios ` - #. Edit your React components to be aligned with changes made in DAML code + #. Make a small change to your Daml data model + #. Optionally test your Daml code and with :ref:`scenarios ` + #. Edit your React components to be aligned with changes made in Daml code #. Extend the UI to make use of the newly introduced feature - #. Make further changes either to your DAML and/or React code until you're happy with what you've developed + #. Make further changes either to your Daml and/or React code until you're happy with what you've developed .. image:: ./developer_workflow.svg @@ -131,12 +131,12 @@ typical DAML developer workflow is to 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. +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. There are several things that can fail during this time window: the application can crash, the participant node can crash, messages can be lost on the network, or the ledger may be just slow to respond due to a high load. If you want to make sure that a command is not executed twice, your application needs to robustly handle all the various failure scenarios. -DAML ledgers provide a mechanism for :ref:`command deduplication ` to help deal this problem. +Daml ledgers provide a mechanism for :ref:`command deduplication ` to help deal this problem. For each command applications provide a command ID and an optional parameter that specifies the deduplication time. If the latter parameter is not specified in the command submission itself, the ledger will fall back to using the configured maximum deduplication time. The ledger will then guarantee that commands for the same submitting party and command ID will be ignored within the deduplication time window. @@ -156,7 +156,7 @@ For more details on command deduplication, see the :ref:`Ledger API Services ` 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. +The Daml language contains a function :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. -In order to provide a useful notion of time in DAML without incurring severe performance or liveness penalties, DAML has two notions of time: *Ledger Time* and *Record Time*: +In order to provide a useful notion of time in Daml without incurring severe performance or liveness penalties, Daml has two notions of time: *Ledger Time* and *Record Time*: - As part of command interpretation, each transaction is automatically assigned a *Ledger Time* by the participant server. - All calls to ``getTime`` within a transaction return the *Ledger Time* assigned to that transaction. @@ -205,7 +205,7 @@ Some commands might take a long time to process, and by the time the resulting t How is this used in practice? -- Be aware that ``getTime`` is only reasonably close to real time, and not completely monotonic. Avoid DAML workflows that rely on very accurate time measurements or high frequency time changes. +- Be aware that ``getTime`` is only reasonably close to real time, and not completely monotonic. Avoid Daml workflows that rely on very accurate time measurements or high frequency time changes. - Set ``min_ledger_time_abs`` or ``min_ledger_time_rel`` if the duration of command interpretation and transmission is likely to take a long time relative to the tolerance interval set by the ledger. - In some corner cases, the participant node may be unable to determine a suitable Ledger Time by itself. If you get an error that no Ledger Time could be found, check whether you have contention on any contract referenced by your command or whether the referenced contracts are sensitive to small changes of ``getTime``. diff --git a/docs/source/app-dev/authorization.rst b/docs/source/app-dev/authorization.rst index d0d05274d1..471d81ba31 100644 --- a/docs/source/app-dev/authorization.rst +++ b/docs/source/app-dev/authorization.rst @@ -6,7 +6,7 @@ Authorization ############# -When developing DAML applications using SDK tools, +When developing Daml applications using SDK tools, your local setup will most likely not verify any authorization - by default, any valid ledger API request will be accepted by the sandbox. @@ -19,22 +19,22 @@ The :doc:`Ledger API ` is used to request changes to the le wants to exercise choice X on contract Y*"), or to read data from the ledger (e.g., "*Alice wants to see all active contracts*"). -What requests are valid is defined by :ref:`integrity ` and :ref:`privacy ` parts the :ref:`DAML Ledger Model `. -This model is defined in terms of :ref:`DAML parties `, +What requests are valid is defined by :ref:`integrity ` and :ref:`privacy ` parts the :ref:`Daml Ledger Model `. +This model is defined in terms of :ref:`Daml parties `, and does not require any cryptographic information to be sent along with requests. In particular, this model does not talk about authentication ("*Is the request claiming to come from Alice really sent by Alice?*") -and authorization ("*Is Alice authorized to add a new DAML package to the ledger?*"). +and authorization ("*Is Alice authorized to add a new Daml package to the ledger?*"). -In practice, DAML ledgers will therefore need to add authentication to the ledger API. +In practice, Daml ledgers will therefore need to add authentication to the ledger API. .. note:: - Depending on the ledger topology, a DAML ledger may consist of multiple participant nodes, + Depending on the ledger topology, a Daml ledger may consist of multiple participant nodes, each having its own ledger API server. - Each participant node typically hosts different DAML parties, - and only sees data visible to the parties hosted on that node (as defined by the DAML privacy model). + Each participant node typically hosts different Daml parties, + and only sees data visible to the parties hosted on that node (as defined by the Daml privacy model). - For more details on DAML ledger topologies, refer to the :ref:`DAML Ledger Topologies ` documentation. + For more details on Daml ledger topologies, refer to the :ref:`Daml Ledger Topologies ` documentation. Adding authentication ===================== @@ -42,14 +42,14 @@ Adding authentication How authentication is set up on a particular ledger is defined by the ledger operator. However, most authentication setups share the following pattern: -First, the DAML application contacts a token issuer to get an access token. +First, the Daml application contacts a token issuer to get an access token. The token issuer verifies the identity of the requesting user (e.g., by checking the username/password credentials sent with the request), looks up the privileges of the user, and generates a signed access token describing those privileges. -Then, the DAML application sends the access token along with each ledger API request. -The DAML ledger verifies the signature of the token (to make sure it has not been tampered with), +Then, the Daml application sends the access token along with each ledger API request. +The Daml ledger verifies the signature of the token (to make sure it has not been tampered with), and then checks that the privileges described in the token authorize the given ledger API request. .. image:: ./images/Authentication.svg diff --git a/docs/source/app-dev/bindings-java/codegen.rst b/docs/source/app-dev/bindings-java/codegen.rst index 3cd9cfc7c5..c032066bea 100644 --- a/docs/source/app-dev/bindings-java/codegen.rst +++ b/docs/source/app-dev/bindings-java/codegen.rst @@ -3,13 +3,13 @@ .. _daml-codegen-java: -Generate Java code from DAML +Generate Java code from Daml ############################ Introduction ============ -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. To achieve this, you can use DAML to Java code generator ("Java codegen") to generate Java types based on a DAML model. You can then use these types in your Java code when reading information from and sending data to the ledger. +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. To achieve this, you can use Daml to Java code generator ("Java codegen") to generate Java types based on a Daml model. You can then use these types in your Java code when reading information from and sending data to the ledger. Download ======== @@ -25,7 +25,7 @@ You can download the `latest version `) * Constructor names @@ -173,12 +173,12 @@ If any of these identifiers match one of the `Java reserved keywords ` 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. +A :ref:`Daml record ` 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. .. literalinclude:: ./code-snippets/Com/Acme/ProductTypes.daml :language: daml @@ -237,7 +237,7 @@ A Java file is generated that defines the class for the type ``Name``: Templates ^^^^^^^^^ -The Java codegen generates three classes for a DAML template: +The Java codegen generates three classes for a Daml template: **TemplateName** Represents the contract data or the template fields. @@ -393,9 +393,9 @@ Parameterized types This section is only included for completeness: we don't expect users to make use of the ``fromValue`` and ``toValue methods``, because they would typically come from a template that doesn't have any unbound type parameters. -The Java codegen uses Java Generic types to represent :ref:`DAML parameterized types `. +The Java codegen uses Java Generic types to represent :ref:`Daml parameterized types `. -This DAML fragment defines the parameterized type ``Attribute``, used by the ``BookAttribute`` type for modeling the characteristics of the book: +This Daml fragment defines the parameterized type ``Attribute``, used by the ``BookAttribute`` type for modeling the characteristics of the book: .. literalinclude:: ./code-snippets/Com/Acme/ParameterizedTypes.daml :language: daml @@ -489,9 +489,9 @@ Below is a Java fragment that converts an attribute with a ``java.lang.Long`` va Value serializedPages = pagesAttribute.toValue(Int64::new); -See :ref:`DAML To Java Type Mapping ` for an overview of the Java Bindings `Value`_ types. +See :ref:`Daml To Java Type Mapping ` for an overview of the Java Bindings `Value`_ types. -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. +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 """"""""""""""""""""""""""""""""""""""""""""""""""""""""""""" @@ -550,7 +550,7 @@ of the container. Value serializedAuthors = authorsAttribute.toValue(f -> f.stream().collect(DamlCollector.toList(Text::new)); -To convert back DAML containers to Java ones, one must use the +To convert back Daml containers to Java ones, one must use the containers methods ``toList`` or ``toMap``. Those methods expect functions to convert back the container's entries. diff --git a/docs/source/app-dev/bindings-java/example.rst b/docs/source/app-dev/bindings-java/example.rst index c8595f0208..4430141aae 100644 --- a/docs/source/app-dev/bindings-java/example.rst +++ b/docs/source/app-dev/bindings-java/example.rst @@ -8,7 +8,7 @@ To try out the Java bindings library, use the `examples on GitHub The Java bindings is a client implementation of the *Ledger API* -based on `RxJava `_, a library for composing asynchronous and event-based programs using observable sequences for the Java VM. It provides an idiomatic way to write DAML Ledger applications. +based on `RxJava `_, a library for composing asynchronous and event-based programs using observable sequences for the Java VM. It provides an idiomatic way to write Daml Ledger applications. .. seealso:: This documentation for the Java bindings API includes the `JavaDoc reference documentation `_. @@ -38,11 +38,11 @@ The Java bindings library is composed of: The Reactive Layer also exposes the main interface representing a client connecting via the Ledger API. This interface is called ``LedgerClient`` and the - main implementation working against a DAML Ledger is the ``DamlLedgerClient``. + main implementation working against a Daml Ledger is the ``DamlLedgerClient``. Can be found in the java package ``com.daml.ledger.rxjava``. - The Reactive Components - A set of optional components you can use to assemble DAML Ledger applications. These components are deprecated as of 2020-10-14. + A set of optional components you can use to assemble Daml Ledger applications. These components are deprecated as of 2020-10-14. The most important components are: @@ -54,16 +54,16 @@ The Java bindings library is composed of: Code generation =============== -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. +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. -To achieve this, you can use DAML to Java code generator ("Java codegen") to generate Java types based on a DAML model. You can then use these types in your Java code when reading information from and sending data to the ledger. +To achieve this, you can use Daml to Java code generator ("Java codegen") to generate Java types based on a Daml model. You can then use these types in your Java code when reading information from and sending data to the ledger. For more information on Java code generation, see :doc:`/app-dev/bindings-java/codegen`. Connecting 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. +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 `. Consult the `JavaDoc for DamlLedgerClient `_ for full details. @@ -127,11 +127,11 @@ If you're communicating with a ledger that verifies authorization it's very impo Connecting securely =================== -The Java bindings library lets you connect to a DAML Ledger via a secure connection. The builders created by +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``. Using the default plaintext connection is useful only when connecting to a locally running Sandbox for development purposes. -Secure connections to a DAML Ledger must be configured to use client authentication certificates, which can be provided by a Ledger Operator. +Secure connections to a Daml Ledger must be configured to use client authentication certificates, which can be provided by a Ledger Operator. For information on how to set up an ``SslContext`` with the provided certificates for client authentication, please consult the gRPC documentation on `TLS with OpenSSL `_ as well as the @@ -170,7 +170,7 @@ for the application, the application ``LedgerView`` is updated to contain that c Writing automations: Bot ------------------------ -The ``Bot`` is an abstraction used to write automation for a DAML Ledger. It is conceptually +The ``Bot`` is an abstraction used to write automation for a Daml Ledger. It is conceptually defined by two aspects: - the ``LedgerView`` diff --git a/docs/source/app-dev/bindings-java/quickstart.rst b/docs/source/app-dev/bindings-java/quickstart.rst index d22bf4d061..2a7008fdf1 100644 --- a/docs/source/app-dev/bindings-java/quickstart.rst +++ b/docs/source/app-dev/bindings-java/quickstart.rst @@ -6,7 +6,7 @@ IOU Quickstart Tutorial ####################### -In this guide, you will learn about developer tools and DAML applications by: +In this guide, you will learn about developer tools and Daml applications by: - developing a simple ledger application for issuing, managing, transferring and trading IOUs ("I Owe You!") - developing an integration layer that exposes some of the functionality via custom REST services @@ -21,7 +21,7 @@ Prerequisites: Download the quickstart application *********************************** -You can get the quickstart application using the DAML assistant (``daml``): +You can get the quickstart application using the Daml assistant (``daml``): #. Run ``daml new quickstart --template quickstart-java`` @@ -58,9 +58,9 @@ The project contains the following files: └── resources └── logback.xml -- ``daml.yaml`` is a DAML project config file used by the SDK to find out how to build the DAML project and how to run it. -- ``daml`` contains the :ref:`DAML code ` specifying the contract model for the ledger. -- ``daml/Tests`` contains :ref:`test scenarios ` for the DAML model. +- ``daml.yaml`` is a Daml project config file used by the SDK to find out how to build the Daml project and how to run it. +- ``daml`` contains the :ref:`Daml code ` specifying the contract model for the ledger. +- ``daml/Tests`` contains :ref:`test scenarios ` for the Daml model. - ``frontend-config.js`` and ``ui-backend.conf`` are configuration files for the :ref:`Navigator ` frontend. - ``pom.xml`` and ``src/main/java`` constitute a :ref:`Java application ` that provides REST services to interact with the ledger. @@ -75,7 +75,7 @@ To run through this guide, you will need to understand what an IOU is. This sect A bank bill represents a contract between the owner of the bill and its issuer, the central bank. Historically, it is a bearer instrument - it gives anyone who holds it the right to demand a fixed amount of material value, often gold, from the issuer in exchange for the note. -To do this, the note must have certain properties. In particular, the British pound note shown below illustrates the key elements that are needed to describe money in DAML: +To do this, the note must have certain properties. In particular, the British pound note shown below illustrates the key elements that are needed to describe money in Daml: .. figure:: quickstart/images/poundNote.jpg :align: center @@ -109,11 +109,11 @@ The note itself is printed on paper, and its legal owner is the person holding i 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: +In this section, you will run the quickstart application and get introduced to the main tools for prototyping Daml: -#. To compile the DAML model, run ``daml build`` +#. To compile the Daml model, run ``daml build`` - This creates a :ref:`DAR file ` (DAR is just the format that DAML compiles to) called ``.daml/dist/quickstart-0.0.1.dar``. The output should look like this: + This creates a :ref:`DAR file ` (DAR is just the format that Daml compiles to) called ``.daml/dist/quickstart-0.0.1.dar``. The output should look like this: .. code-block:: none @@ -142,7 +142,7 @@ In this section, you will run the quickstart application and get introduced to t #. Open a new terminal window and navigate to your project directory, ``quickstart``. -#. To initialize the ledger with some parties and contracts we use :doc:`DAML Script ` by running ``daml script --dar .daml/dist/quickstart-0.0.1.dar --script-name Main:initialize --ledger-host localhost --ledger-port 6865 --static-time`` +#. To initialize the ledger with some parties and contracts we use :doc:`Daml Script ` by running ``daml script --dar .daml/dist/quickstart-0.0.1.dar --script-name Main:initialize --ledger-host localhost --ledger-port 6865 --static-time`` .. _quickstart-navigator: @@ -168,7 +168,7 @@ Now everything is running, you can try out the quickstart application: This is showing you what contracts are currently active on the sandbox ledger and visible to *Alice*. You can see that there is a single such contract, in our case with Id ``#9:1``, created from a *template* called ``Iou:Iou@ffb...``. - Your contract ID may vary. There's a lot going on in a DAML ledger, so things could have happened in a different order, or other internal ledger events might have occurred. The actual value doesn't matter. We'll refer to this contract as ``#9:1`` in the rest of this document, and you'll need to substitute your own value mentally. + Your contract ID may vary. There's a lot going on in a Daml ledger, so things could have happened in a different order, or other internal ledger events might have occurred. The actual value doesn't matter. We'll refer to this contract as ``#9:1`` in the rest of this document, and you'll need to substitute your own value mentally. #. On the left-hand side, you can see what the pages the Navigator contains: @@ -200,14 +200,14 @@ Now everything is running, you can try out the quickstart application: The screen shows the same contract ``#9:1`` that you already saw on the *Contracts* page. It is an Iou for €100, issued by *EUR_Bank*. #. Go to the **Iou Transfers** page. It shows the transfer of your recently issued Iou to Bob, but Bob has not accepted the transfer, so it is not settled. - This is an important part of DAML: nobody can be forced into owning an *Iou*, or indeed agreeing to any other contract. They must explicitly consent. + This is an important part of Daml: nobody can be forced into owning an *Iou*, or indeed agreeing to any other contract. They must explicitly consent. You could cancel the transfer by using the *IouTransfer_Cancel* choice within it, but for this walk-through, leave it alone for the time being. #. Try asking *Bob* to exchange your €100 for $110. To do so, you first have to show your Iou to *Bob* so that he can verify the settlement transaction, should he accept the proposal. Go back to *Owned Ious*, open the Iou for €100 and click on the button *Iou_AddObserver*. Submit *Bob* as the *newObserver*. - Contracts in DAML are immutable, meaning they cannot be changed, only created and archived. If you head back to the **Owned Ious** screen, you can see that the Iou now has a new Contract ID. In our case, it's `#13:1`. + Contracts in Daml are immutable, meaning they cannot be changed, only created and archived. If you head back to the **Owned Ious** screen, you can see that the Iou now has a new Contract ID. In our case, it's `#13:1`. #. To propose the trade, go to the **Templates** screen. Click on the *IouTrade:IouTrade* template, fill in the form as shown below and submit the transaction. .. figure:: quickstart/images/tradeProp.png @@ -223,7 +223,7 @@ Now everything is running, you can try out the quickstart application: #. Settle the trade. Go to the **Trades** page, and click on the row of the proposal. Accept the trade by clicking **IouTrade_Accept**. In the popup, enter the Contract ID you just noted as the *quoteIouCid*, then click **Submit**. The two legs of the transfer are now settled atomically in a single transaction. The trade either fails or succeeds as a whole. -#. Privacy is an important feature of DAML. You can check that Alice and Bob's privacy relative to the Banks was preserved. +#. Privacy is an important feature of Daml. You can check that Alice and Bob's privacy relative to the Banks was preserved. To do this, log out, then log in as **USD_Bank**. @@ -250,12 +250,12 @@ 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. +The *contract model* specifies the possible contracts, as well as the allowed transactions on the ledger, and is written in Daml. -The core concept in DAML is a *contract template* - you used them earlier to create contracts. Contract templates specify: +The core concept in Daml is a *contract template* - you used them earlier to create contracts. Contract templates specify: - a type of contract that may exist on the ledger, including a corresponding data type - the *signatories*, who need to agree to the *creation* of a contract of that type @@ -263,14 +263,14 @@ The core concept in DAML is a *contract template* - you used them earlier to cre - constraints or conditions on the data on a contract - additional parties, called observers, who can see the contract -For more information about DAML Ledgers, consult :ref:`da-ledgers` for an in-depth technical description. +For more information about Daml Ledgers, consult :ref:`da-ledgers` for an in-depth technical description. -Develop with DAML Studio +Develop with Daml Studio ======================== -Take a look at the DAML that specifies the contract model in the quickstart application. The core template is ``Iou``. +Take a look at the Daml that specifies the contract model in the quickstart application. The core template is ``Iou``. -#. Open :doc:`DAML Studio `, a DAML IDE based on VS Code, by running ``daml studio`` from the root of your project. +#. Open :doc:`Daml Studio `, a Daml IDE based on VS Code, by running ``daml studio`` from the root of your project. #. Using the explorer on the left, open ``daml/Iou.daml``. The first two lines specify language version and module name: @@ -327,24 +327,24 @@ A more interesting choice is ``IouTrade_Accept``. To look at it, open ``IouTrade :language: daml :lines: 25-46 -This choice uses the ``===`` operator from the :doc:`DAML Standard Library ` to check pre-conditions. The standard library is imported using ``import DA.Assert`` at the top of the module. +This choice uses the ``===`` operator from the :doc:`Daml Standard Library ` to check pre-conditions. The standard library is imported using ``import DA.Assert`` at the top of the module. Then, it *composes* the ``Iou_Transfer`` and ``IouTransfer_Accept`` choices to build one big transaction. In this transaction, ``buyer`` and ``seller`` exchange their Ious atomically, without disclosing the entire transaction to all parties involved. The *Issuers* of the two Ious, which are involved in the transaction because they are signatories on the ``Iou`` and ``IouTransfer`` contracts, only get to see the sub-transactions that concern them, as we saw earlier. -For a deeper introduction to DAML, consult the :doc:`DAML Reference `. +For a deeper introduction to Daml, consult the :doc:`Daml Reference `. .. _quickstart-scenarios: Test using scenarios ==================== -You can check the correct authorization and privacy of a contract model using *scenarios*: tests that are written in DAML. +You can check the correct authorization and privacy of a contract model using *scenarios*: tests that are written in Daml. -Scenarios are a linear sequence of transactions that is evaluated using the same consistency, conformance and authorization rules as it would be on the full ledger server or the sandbox ledger. They are integrated into DAML Studio, which can show you the resulting transaction graph, making them a powerful tool to test and troubleshoot the contract model. +Scenarios are a linear sequence of transactions that is evaluated using the same consistency, conformance and authorization rules as it would be on the full ledger server or the sandbox ledger. They are integrated into Daml Studio, which can show you the resulting transaction graph, making them a powerful tool to test and troubleshoot the contract model. -To take a look at the scenarios in the quickstart application, open ``daml/Tests/Trade.daml`` in DAML Studio. +To take a look at the scenarios in the quickstart application, open ``daml/Tests/Trade.daml`` in Daml Studio. A scenario test is defined with ``trade_test = scenario do``. The ``submit`` function takes a submitting party and a transaction, which is specified the same way as in contract choices. @@ -456,7 +456,7 @@ The ``submit`` function used in this scenario tries to perform a transaction and .. 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 `. It is based on `gRPC `_. + All interaction with a Daml ledger, be it sandbox or any other implementation, happens via the :doc:`Ledger API `. It is based on `gRPC `_. The Navigator uses this API, as will any :ref:`custom integration `. @@ -473,9 +473,9 @@ The ``submit`` function used in this scenario tries to perform a transaction and Integrate with the ledger ************************* -A distributed ledger only forms the core of a full DAML application. +A distributed ledger only forms the core of a full Daml application. -To build automations and integrations around the ledger, DAML Connect has :doc:`language bindings ` for the Ledger API in several programming languages. +To build automations and integrations around the ledger, Daml Connect has :doc:`language bindings ` for the Ledger API in several programming languages. To compile the Java integration for the quickstart application, we first need to run the Java codegen on the DAR we built before:: @@ -524,7 +524,7 @@ The automation is based on the :doc:`Java bindings `_. +It consists of the application in file ``IouMain.java``. It uses the class ``Iou`` from ``Iou.java``, which is generated from the Daml model with the Java code generator. The ``Iou`` class provides better serialization and de-serialization to JSON via `gson `_. #. A connection to the ledger is established using a ``LedgerClient`` object. @@ -590,7 +590,7 @@ Great - you've completed the quickstart guide! Some steps you could take next include: - Explore `examples `_ for guidance and inspiration. -- :doc:`Learn DAML `. +- :doc:`Learn Daml `. - :doc:`Language reference `. - Learn more about :doc:`application development `. -- Learn about the :doc:`conceptual models ` behind DAML. +- Learn about the :doc:`conceptual models ` behind Daml. diff --git a/docs/source/app-dev/bindings-scala/index.rst b/docs/source/app-dev/bindings-scala/index.rst index 3a864a5d75..cfbb581cd6 100644 --- a/docs/source/app-dev/bindings-scala/index.rst +++ b/docs/source/app-dev/bindings-scala/index.rst @@ -8,30 +8,30 @@ Scala bindings The Scala bindings are deprecated as of 2020-10-14. -This page provides a basic Scala programmer's introduction to working with DAML Ledgers, +This page provides a basic Scala programmer's introduction to working with Daml Ledgers, using the Scala programming language and the **Ledger API**. Introduction ============ -The Scala bindings is a client implementation of the **Ledger API**. The Scala bindings library lets you write applications that connect to a DAML Ledger using the Scala programming language. +The Scala bindings is a client implementation of the **Ledger API**. The Scala bindings library lets you write applications that connect to a Daml Ledger using the Scala programming language. There are two main components: - Scala codegen - DAML to Scala code generator. Use this to generate Scala classes from DAML models. The generated Scala code provides a type safe way of creating contracts (:ref:`com.daml.ledger.api.v1.CreateCommand`) and exercising contract choices (:ref:`com.daml.ledger.api.v1.ExerciseCommand`). + Daml to Scala code generator. Use this to generate Scala classes from Daml models. The generated Scala code provides a type safe way of creating contracts (:ref:`com.daml.ledger.api.v1.CreateCommand`) and exercising contract choices (:ref:`com.daml.ledger.api.v1.ExerciseCommand`). - Akka Streams-based API The API that you use to send commands to the ledger and receive transactions back. In order to use the Scala bindings, you should be familiar with: -- :doc:`DAML language ` +- :doc:`Daml language ` - :doc:`Ledger API ` - `Akka Streams API `_ - `Scala programming language `_ - :ref:`assistant-manual-building-dars` -- :doc:`DAML codegen ` +- :doc:`Daml codegen ` Getting started =============== @@ -61,9 +61,9 @@ Generating Scala code 1) Install :doc:`the latest version of the SDK `. -2) Build a **DAR** file from a **DAML** model. Refer to :ref:`assistant-manual-building-dars` for more instructions. +2) Build a **DAR** file from a **Daml** model. Refer to :ref:`assistant-manual-building-dars` for more instructions. -3) Configure ``codegen`` in the ``daml.yaml`` (for more details see :doc:`DAML codegen ` documentation). +3) Configure ``codegen`` in the ``daml.yaml`` (for more details see :doc:`Daml codegen ` documentation). .. literalinclude:: ./code-snippets/quickstart-scala/daml.yaml :start-after: # @@ -93,7 +93,7 @@ Example code In this section we will demonstrate how to use the Scala bindings library. -This section refers to the IOU DAML example from the :doc:`Quickstart guide ` and +This section refers to the IOU Daml example from the :doc:`Quickstart guide ` and `quickstart-scala example `_ that we already mentioned above. Please keep in mind that **quickstart-scala example** compiles with ``-Xsource:2.13`` **scalac** option, this is to activate the fix for a Scala bug that forced users to add extra imports for implicits that should not be needed. diff --git a/docs/source/app-dev/bindings-ts/daml2js.rst b/docs/source/app-dev/bindings-ts/daml2js.rst index 11e4e2c49a..7dbeee68b7 100644 --- a/docs/source/app-dev/bindings-ts/daml2js.rst +++ b/docs/source/app-dev/bindings-ts/daml2js.rst @@ -4,16 +4,16 @@ 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>`_. +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>`_. -Inputs to the command are DAR files. Outputs are JavaScript packages with TypeScript typings containing metadata and types for all DAML packages included in the DAR files. +Inputs to the command are DAR files. Outputs are JavaScript packages with TypeScript typings containing metadata and types for all Daml packages included in the DAR files. The generated packages use the library `@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. +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. Here's a complete example on a project built from the standard "skeleton" template. @@ -22,24 +22,24 @@ Here's a complete example on a project built from the standard "skeleton" templa daml new my-proj --template skeleton # Create a new project based off the skeleton template cd my-proj # Enter the newly created project directory - daml build # Compile the project's DAML files into a DAR + daml build # Compile the project's Daml files into a DAR daml codegen js -o daml.js .daml/dist/my-proj-0.0.1.dar # Generate JavaScript packages in the daml.js directory - On execution of these commands: - The directory ``my-proj/daml.js`` contains generated JavaScript packages with TypeScript typings; - The files are arranged into directories; - - One of those directories will be named my-proj-0.0.1 and will contain the definitions corresponding to the DAML files in the project; + - One of those directories will be named my-proj-0.0.1 and will contain the definitions corresponding to the Daml files in the project; - For example, ``daml.js/my-proj-0.0.1/lib/index.js`` provides access to the definitions for ``daml/Main.daml``; - - The remaining directories correspond to modules of the DAML standard library; - - Those directories have numeric names (the names are hashes of the DAML-LF package they are derived from). + - The remaining directories correspond to modules of the Daml standard library; + - Those directories have numeric names (the names are hashes of the Daml-LF package they are derived from). 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. +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. **Interfaces**: @@ -49,7 +49,7 @@ To understand the TypeScript typings produced by the code generator, it is helpf **Types**: +-------------------+--------------------+----------------------------------+ -| DAML | TypeScript | TypeScript definition | +| Daml | TypeScript | TypeScript definition | +===================+====================+==================================+ | ``()`` | ``Unit`` | ``{}`` | +-------------------+--------------------+----------------------------------+ @@ -93,15 +93,15 @@ 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`` whereas, ``[]`` and ``["foo"]`` are two possible values of type ``Optional>`` (``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. +The mappings from Daml to TypeScript are best explained by example. Records ~~~~~~~ -In DAML, we might model a person like this. +In Daml, we might model a person like this. .. code-block:: daml :linenos: @@ -126,7 +126,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. +This is a Daml type for a language of additive expressions. .. code-block:: daml :linenos: @@ -181,7 +181,7 @@ The thing to note is how the definition of the ``Add`` case has given rise to a Enums ~~~~~ -Given a DAML enumeration like this, +Given a Daml enumeration like this, .. code-block:: daml :linenos: @@ -205,7 +205,7 @@ the generated TypeScript will consist of a type declaration and the definition o Templates and choices ~~~~~~~~~~~~~~~~~~~~~ -Here is a DAML template of a basic 'IOU' contract. +Here is a Daml template of a basic 'IOU' contract. .. code-block:: daml :linenos: diff --git a/docs/source/app-dev/bindings-ts/index.rst b/docs/source/app-dev/bindings-ts/index.rst index 0e4e9bde93..2200f46579 100644 --- a/docs/source/app-dev/bindings-ts/index.rst +++ b/docs/source/app-dev/bindings-ts/index.rst @@ -6,15 +6,15 @@ JavaScript Client Libraries .. _typescript: -The JavaScript Client Libraries are the recommended way to build a frontend for a DAML application. -The :doc:`JavaScript Code Generator ` can automatically generate JavaScript containing metadata about DAML packages that is required to use these libraries. +The JavaScript Client Libraries are the recommended way to build a frontend for a Daml application. +The :doc:`JavaScript Code Generator ` can automatically generate JavaScript containing metadata about Daml packages that is required to use these libraries. We provide an integration for the `React `_ framework with the `@daml/react `_ library. However, you can choose any JavaScript/TypeScript based framework and use the `@daml/ledger `_ library directly to connect and interact with a -DAML ledger via its :ref:`HTTP JSON API `. +Daml ledger via its :ref:`HTTP JSON API `. The `@daml/types `_ library contains TypeScript data types corresponding to -primitive DAML data types, such as ``Party`` or ``Text``. It is used by the `@daml/react `_ +primitive Daml data types, such as ``Party`` or ``Text``. It is used by the `@daml/react `_ and `@daml/ledger `_ libraries. .. toctree:: diff --git a/docs/source/app-dev/bindings-x-lang/index.rst b/docs/source/app-dev/bindings-x-lang/index.rst index 2145dfd637..ef15b43881 100644 --- a/docs/source/app-dev/bindings-x-lang/index.rst +++ b/docs/source/app-dev/bindings-x-lang/index.rst @@ -4,7 +4,7 @@ Creating your own bindings ########################## -This page gets you started with creating custom bindings for a DAML Ledger. +This page gets you started with creating custom bindings for a Daml Ledger. Bindings for a language consist of two main components: @@ -12,7 +12,7 @@ Bindings for a language consist of two main components: Client "stubs" for the programming language, -- the remote API that allows sending ledger commands and receiving ledger transactions. You have to generate **Ledger API** from `the gRPC protobuf definitions in the daml repository on GitHub `_. **Ledger API** is documented on this page: :doc:`/app-dev/grpc/index`. The `gRPC `_ tutorial explains how to generate client "stubs". - Codegen - A code generator is a program that generates classes representing DAML contract templates in the language. These classes incorporate all boilerplate code for constructing: :ref:`com.daml.ledger.api.v1.CreateCommand` and :ref:`com.daml.ledger.api.v1.ExerciseCommand` corresponding for each DAML contract template. + A code generator is a program that generates classes representing Daml contract templates in the language. These classes incorporate all boilerplate code for constructing: :ref:`com.daml.ledger.api.v1.CreateCommand` and :ref:`com.daml.ledger.api.v1.ExerciseCommand` corresponding for each Daml contract template. Technically codegen is optional. You can construct the commands manually from the auto-generated **Ledger API** classes. However, it is very tedious and error-prone. If you are creating *ad hoc* bindings for a project with a few contract templates, writing a proper codegen may be overkill. On the other hand, if you have hundreds of contract templates in your project or are planning to build language bindings that you will share across multiple projects, we recommend including a codegen in your bindings. It will save you and your users time in the long run. @@ -44,7 +44,7 @@ Here is how to manually build a :ref:`com.daml.ledger.api.v1.CreateCommand` for :start-after: // :end-before: // -If you do not specify any of the above fields or type their names or values incorrectly, or do not order them exactly as they are in the DAML template, the above code will compile but fail at run-time because you did not structure your create command correctly. +If you do not specify any of the above fields or type their names or values incorrectly, or do not order them exactly as they are in the Daml template, the above code will compile but fail at run-time because you did not structure your create command correctly. Codegen should simplify the command construction by providing auto-generated utilities to help you construct commands. For example, when you use :doc:`Scala codegen ` to generate contract classes, a similar contract instantiation would look like this: @@ -77,11 +77,11 @@ versus creating the same command using a value class generated by :doc:`Scala co Summary ======= -When creating custom bindings for DAML Ledgers, you will need to: +When creating custom bindings for Daml Ledgers, you will need to: - generate **Ledger API** from the gRPC definitions -- decide whether to write a codegen to generate ledger commands or manually build them for all contracts defined in your DAML model. +- decide whether to write a codegen to generate ledger commands or manually build them for all contracts defined in your Daml model. The above examples should help you get started. If you are creating custom binding or have any questions, see the :doc:`/support/support` page for how to get in touch with us. @@ -96,7 +96,7 @@ Links - Documentation for Protobuf "well known types": https://developers.google.com/protocol-buffers/docs/reference/google.protobuf -- DAML Ledger API gRPC Protobuf definitions +- Daml Ledger API gRPC Protobuf definitions - current main: https://github.com/digital-asset/daml/tree/main/ledger-api/grpc-definitions - for specific versions: https://github.com/digital-asset/daml/releases diff --git a/docs/source/app-dev/daml-lf-translation.rst b/docs/source/app-dev/daml-lf-translation.rst index 3158c57418..2c3fbcffe8 100644 --- a/docs/source/app-dev/daml-lf-translation.rst +++ b/docs/source/app-dev/daml-lf-translation.rst @@ -1,28 +1,28 @@ .. Copyright (c) 2021 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. +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`. +For an introduction to Daml-LF, see :ref:`daml-lf-intro`. Primitive types *************** -:ref:`Built-in data types ` in DAML have straightforward mappings to DAML-LF. +:ref:`Built-in data types ` in Daml have straightforward mappings to Daml-LF. -This section only covers the serializable types, as these are what client applications can interact with via the generated DAML-LF. (Serializable types are ones whose values can be written in a text or binary format. So not function types, ``Update`` and ``Scenario`` types, as well as any types built up from those.) +This section only covers the serializable types, as these are what client applications can interact with via the generated Daml-LF. (Serializable types are ones whose values can be written in a text or binary format. So not function types, ``Update`` and ``Scenario`` types, as well as any types built up from those.) -Most built-in types have the same name in DAML-LF as in DAML. These are the exact mappings: +Most built-in types have the same name in Daml-LF as in Daml. These are the exact mappings: .. list-table:: :widths: 10 15 :header-rows: 1 - * - DAML primitive type - - DAML-LF primitive type + * - Daml primitive type + - Daml-LF primitive type * - ``Int`` - ``Int64`` * - ``Time`` @@ -44,41 +44,41 @@ Most built-in types have the same name in DAML-LF as in DAML. These are the exac * - ``ContractId`` - ``ContractId`` -Be aware that only the DAML primitive types exported by the :ref:`Prelude ` 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``. +Be aware that only the Daml primitive types exported by the :ref:`Prelude ` 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 *********** -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. +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. -The equivalent DAML-LF type constructors are ``daml-prim:DA.Types:TupleN``, for each particular N (where 2 <= N <= 20). This qualified name refers to the package name (``ghc-prim``) and the module name (``GHC.Tuple``). +The equivalent Daml-LF type constructors are ``daml-prim:DA.Types:TupleN``, for each particular N (where 2 <= N <= 20). This qualified name refers to the package name (``ghc-prim``) and the module name (``GHC.Tuple``). -For example: the DAML pair type ``(Int, Text)`` is translated to ``daml-prim:DA.Types:Tuple2 Int64 Text``. +For example: the Daml pair type ``(Int, Text)`` is translated to ``daml-prim:DA.Types:Tuple2 Int64 Text``. Data types ********** -DAML-LF has three kinds of data declarations: +Daml-LF has three kinds of data declarations: - **Record** types, which define a collection of data - **Variant** or **sum** types, which define a number of alternatives - **Enum**, which defines simplified **sum** types without type parameters nor argument. -:ref:`Data type declarations in DAML ` (starting with the ``data`` keyword) are translated to record, variant or enum types. It’s sometimes not obvious what they will be translated to, so this section lists many examples of data types in DAML and their translations in DAML-LF. +:ref:`Data type declarations in Daml ` (starting with the ``data`` keyword) are translated to record, variant or enum types. It’s sometimes not obvious what they will be translated to, so this section lists many examples of data types in Daml and their translations in Daml-LF. -.. In the tables below, the left column uses DAML 1.2 syntax and the right column uses the notation from the `DAML-LF specification `_. +.. In the tables below, the left column uses Daml 1.2 syntax and the right column uses the notation from the `Daml-LF specification `_. Record declarations =================== -This section uses the syntax for DAML :ref:`records ` with curly braces. +This section uses the syntax for Daml :ref:`records ` with curly braces. .. list-table:: :widths: 10 15 :header-rows: 1 - * - DAML declaration - - DAML-LF translation + * - Daml declaration + - Daml-LF translation * - ``data Foo = Foo { foo1: Int; foo2: Text }`` - ``record Foo ↦ { foo1: Int64; foo2: Text }`` * - ``data Foo = Bar { bar1: Int; bar2: Text }`` @@ -99,8 +99,8 @@ Variant declarations :widths: 10 15 :header-rows: 1 - * - DAML declaration - - DAML-LF translation + * - Daml declaration + - Daml-LF translation * - ``data Foo = Bar Int | Baz Text`` - ``variant Foo ↦ Bar Int64 | Baz Text`` * - ``data Foo a = Bar a | Baz Text`` @@ -135,8 +135,8 @@ Enum declarations :widths: 10 15 :header-rows: 1 - * - DAML declaration - - DAML-LF declaration + * - Daml declaration + - Daml-LF declaration * - ``data Foo = Bar | Baz`` - ``enum Foo ↦ Bar | Baz`` * - ``data Color = Red | Green | Blue`` @@ -145,13 +145,13 @@ Enum 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. +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. The first: a single constructor data type must be made unambiguous as to whether it is a record or a variant type. Concretely, the data type declaration ``data Foo = Foo`` causes a compile-time error, because it is unclear whether it is declaring a record or a variant type. To fix this, you must make the distinction explicitly. Write ``data Foo = Foo {}`` to declare a record type with no fields, or ``data Foo = Foo ()`` for a variant with a single constructor taking unit argument. -The second gotcha is that a constructor in a data type declaration can have at most one unlabelled argument type. This restriction is so that we can provide a straight-forward encoding of DAML-LF types in a variety of client languages. +The second gotcha is that a constructor in a data type declaration can have at most one unlabelled argument type. This restriction is so that we can provide a straight-forward encoding of Daml-LF types in a variety of client languages. .. list-table:: :widths: 10 15 @@ -173,16 +173,16 @@ The second gotcha is that a constructor in a data type declaration can have at m Type synonyms ************* -: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. +: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. -For example, consider the following DAML type declarations. +For example, consider the following Daml type declarations. .. literalinclude:: code-snippets/LfTranslation.daml :language: daml :start-after: -- start code snippet: type synonyms :end-before: -- end code snippet: type synonyms -The ``Username`` type is eliminated in the DAML-LF translation, as follows: +The ``Username`` type is eliminated in the Daml-LF translation, as follows: .. code-block:: none @@ -191,9 +191,9 @@ The ``Username`` type is eliminated in the DAML-LF translation, as follows: Template types ************** -A :ref:`template declaration ` 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. +A :ref:`template declaration ` 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. -They are translated to DAML-LF using the same rules as for record declarations above. +They are translated to Daml-LF using the same rules as for record declarations above. These declarations are all at the top level of the module in which the template is defined. @@ -214,7 +214,7 @@ results in this record declaration: :start-after: -- start snippet: data from template :end-before: -- end snippet: data from template -This translates to the DAML-LF record declaration: +This translates to the Daml-LF record declaration: .. code-block:: none @@ -239,7 +239,7 @@ This results in these two record types: Whether the choice is consuming or nonconsuming is irrelevant to the data type declaration. The data type is a record even if there are no fields. -These translate to the DAML-LF record declarations: +These translate to the Daml-LF record declarations: .. code-block:: none @@ -249,7 +249,7 @@ These translate to the DAML-LF record declarations: 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: +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: - ``$`` changes to ``$$``, - Unicode codepoints less than 65536 translate to ``$uABCD``, where ``ABCD`` are exactly four (zero-padded) hexadecimal digits of the codepoint in question, using only lowercase ``a-f``, and @@ -259,8 +259,8 @@ All names in DAML—of types, templates, choices, fields, and variant data const :widths: 10 15 :header-rows: 1 - * - DAML name - - DAML-LF identifier + * - Daml name + - Daml-LF identifier * - ``Foo_bar`` - ``Foo_bar`` * - ``baz'`` diff --git a/docs/source/app-dev/grpc/daml-to-ledger-api.rst b/docs/source/app-dev/grpc/daml-to-ledger-api.rst index 2d97c01aca..4057e763bc 100644 --- a/docs/source/app-dev/grpc/daml-to-ledger-api.rst +++ b/docs/source/app-dev/grpc/daml-to-ledger-api.rst @@ -1,15 +1,15 @@ .. Copyright (c) 2021 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: +This page gives an overview and reference on how Daml types and contracts are represented by the Ledger API as protobuf messages, most notably: - in the stream of transactions from the :ref:`com.daml.ledger.api.v1.transactionservice` - as payload for :ref:`com.daml.ledger.api.v1.createcommand` and :ref:`com.daml.ledger.api.v1.exercisecommand` sent to :ref:`com.daml.ledger.api.v1.commandsubmissionservice` and :ref:`com.daml.ledger.api.v1.commandservice`. -The DAML code in the examples below is written in DAML *1.1*. +The Daml code in the examples below is written in Daml *1.1*. Notation ******** @@ -30,7 +30,7 @@ The name of messages is added as a comment after the opening curly brace. 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: +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: .. literalinclude:: ../code-snippets/Types.daml :language: daml @@ -42,7 +42,7 @@ And here's an example of creating a value of type `MyProductType`: :language: daml :lines: 29,31,33-41 -For this data, the respective data on the Ledger API is shown below. Note that this value would be enclosed by a particular contract containing a field of type `MyProductType`. See `Contract templates`_ for the translation of DAML contracts to the representation by the Ledger API. +For this data, the respective data on the Ledger API is shown below. Note that this value would be enclosed by a particular contract containing a field of type `MyProductType`. See `Contract templates`_ for the translation of Daml contracts to the representation by the Ledger API. .. literalinclude:: ../code-snippets/records.payload diff --git a/docs/source/app-dev/grpc/index.rst b/docs/source/app-dev/grpc/index.rst index 841cb49359..c3ac569be9 100644 --- a/docs/source/app-dev/grpc/index.rst +++ b/docs/source/app-dev/grpc/index.rst @@ -32,14 +32,14 @@ We have an example project demonstrating the use of the Ledger API with gRPC. To 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``. +The example shows very simply how two parties can interact via a ledger, using two Daml contract templates, ``Ping`` and ``Pong``. The logic of the application goes like this: #. The application injects a contract of type ``Ping`` for ``Alice``. #. ``Alice`` sees this contract and exercises the consuming choice ``RespondPong`` to create a contract of type ``Pong`` for ``Bob``. #. ``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. +#. Points 2 and 3 are repeated until the maximum number of contracts defined in the Daml is reached. The entry point for the Java code is the main class ``src/main/java/examples/pingpong/grpc/PingPongGrpcMain.java``. Look at it to see how connect to and interact with a ledger using gRPC. @@ -58,10 +58,10 @@ 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`. +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 ************** diff --git a/docs/source/app-dev/ledger-api.rst b/docs/source/app-dev/ledger-api.rst index 372cc835f1..02ef711b79 100644 --- a/docs/source/app-dev/ledger-api.rst +++ b/docs/source/app-dev/ledger-api.rst @@ -18,8 +18,8 @@ The Ledger API bindings-x-lang/index -To write an application around a DAML ledger, you'll need to interact with the **Ledger API** from -another language. Every ledger that DAML can run on exposes this same API. +To write an application around a Daml ledger, you'll need to interact with the **Ledger API** from +another language. Every ledger that Daml can run on exposes this same API. What's in the Ledger API ************************ @@ -38,7 +38,7 @@ all cases, the Ledger API exposes the same services: - Use the :ref:`active contracts service ` to quickly bootstrap an application with the currently active contracts. It saves you the work to process the ledger from the beginning to obtain its current state. - Utility services - - Use the :ref:`package service ` to query the DAML packages deployed to the ledger. + - Use the :ref:`package service ` to query the Daml packages deployed to the ledger. - Use the :ref:`ledger identity service ` to retrieve the Ledger ID of the ledger the application is connected to. - Use the :ref:`ledger configuration service ` to retrieve some dynamic properties of the ledger, like maximum deduplication time for commands. - Use the :ref:`version service ` to retrieve information about the Ledger API version. @@ -53,28 +53,28 @@ You may also want to read the :doc:`protobuf documentation `, the underlying format is DAML-LF. DAML-LF is similar to DAML, but is stripped down to a core set of features. The relationship between the surface DAML syntax and DAML-LF is loosely similar to that between Java and JVM bytecode. +When you :ref:`compile Daml source into a .dar file `, the underlying format is Daml-LF. Daml-LF is similar to Daml, but is stripped down to a core set of features. The relationship between the surface Daml syntax and Daml-LF is loosely similar to that between Java and JVM bytecode. -As a user, you don't need to interact with DAML-LF directly. But internally, it's used for: +As a user, you don't need to interact with Daml-LF directly. But internally, it's used for: -- Executing DAML code on the Sandbox or on another platform +- Executing Daml code on the Sandbox or on another platform - Sending and receiving values via the Ledger API (using a protocol such as gRPC) -- Generating code in other languages for interacting with DAML models (often called “codegen”) +- Generating code in other languages for interacting with Daml models (often called “codegen”) -.. DAML-LF content appears in the package service interactions. It is represented as opaque blobs that require a secondary decoding phase. +.. 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. +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. -Otherwise, it can be helpful to know what the types in your DAML code look like at the DAML-LF level, so you know what to expect from the Ledger API. +Otherwise, it can be helpful to know what the types in your Daml code look like at the Daml-LF level, so you know what to expect from the Ledger API. -For example, if you are writing an application that creates some DAML contracts, you need to construct values to pass as parameters to the contract. These values are determined by the DAML-LF types in that contract template. This means you need an idea of how the DAML-LF types correspond to the types in the original DAML model. +For example, if you are writing an application that creates some Daml contracts, you need to construct values to pass as parameters to the contract. These values are determined by the Daml-LF types in that contract template. This means you need an idea of how the Daml-LF types correspond to the types in the original Daml model. -For the most part the translation of types from DAML to DAML-LF should not be surprising. :doc:`This page goes through all the cases in detail `. +For the most part the translation of types from Daml to Daml-LF should not be surprising. :doc:`This page goes through all the cases in detail `. For the bindings to your specific programming language, you should refer to the language-specific documentation. diff --git a/docs/source/app-dev/services.rst b/docs/source/app-dev/services.rst index 6eba1bc2ca..12edb41324 100644 --- a/docs/source/app-dev/services.rst +++ b/docs/source/app-dev/services.rst @@ -178,7 +178,7 @@ Allocating parties is necessary to interact with the ledger. For more informatio Package service =============== -Use the **package service** to obtain information about DAML packages available on the ledger. +Use the **package service** to obtain information about Daml packages available on the ledger. This is useful for obtaining type and metadata information that allow you to interpret event data in a more useful way. diff --git a/docs/source/concepts/glossary.rst b/docs/source/concepts/glossary.rst index 9597d5e54d..25f49e1321 100644 --- a/docs/source/concepts/glossary.rst +++ b/docs/source/concepts/glossary.rst @@ -4,10 +4,10 @@ Glossary of concepts #################### -DAML +Daml **** -**DAML** is a programming language for writing `smart contracts <#contract>`__, that you can use to build an application based on a `ledger <#ledger-daml-ledger>`__. You can run DAML contracts on many different ledgers. +**Daml** is a programming language for writing `smart contracts <#contract>`__, that you can use to build an application based on a `ledger <#ledger-daml-ledger>`__. You can run Daml contracts on many different ledgers. Contract =========================== @@ -33,7 +33,7 @@ Once the contract is archived, it is no longer valid, and `choices <#choice>`__ Template ======== -A **template** is a blueprint for creating a `contract <#contract>`__. This is the DAML code you write. +A **template** is a blueprint for creating a `contract <#contract>`__. This is the Daml code you write. For full documentation on what can be in a template, see :doc:`/daml/reference/templates`. @@ -85,7 +85,7 @@ Party A **party** represents a person or legal entity. Parties can `create contracts <#create>`__ and `exercise choices <#exercise>`__. -`Signatories <#signatory>`_, `observers <#observer>`__, `controllers <#controller>`__, and `maintainers <#maintainer>`__ all must be parties, represented by the ``Party`` data type in DAML. +`Signatories <#signatory>`_, `observers <#observer>`__, `controllers <#controller>`__, and `maintainers <#maintainer>`__ all must be parties, represented by the ``Party`` data type in Daml. .. Something about how they work in the `execution engine`. @@ -118,7 +118,7 @@ A **choice observer** is a `party <#party>`__ on a `choice <#choice>`__. Choice Stakeholder ----------- -**Stakeholder** is not a term used within the DAML language, but the concept refers to the `signatories <#signatory>`__ and `observers <#observer>`__ collectively. That is, it means all of the `parties <#party>`__ that are interested in a `contract <#contract>`__. +**Stakeholder** is not a term used within the Daml language, but the concept refers to the `signatories <#signatory>`__ and `observers <#observer>`__ collectively. That is, it means all of the `parties <#party>`__ that are interested in a `contract <#contract>`__. Maintainer ---------- @@ -132,9 +132,9 @@ For documentation on contract keys, see :doc:`/daml/reference/contract-keys`. Authorization, signing ====================== -The DAML runtime checks that every submitted transaction is **well-authorized**, according to the :doc:`authorization rules of the ledger model `, which guarantee the integrity of the underlying ledger. +The Daml runtime checks that every submitted transaction is **well-authorized**, according to the :doc:`authorization rules of the ledger model `, which guarantee the integrity of the underlying ledger. -A DAML update is the composition of update actions created with one of the items in the table below. A DAML update is well-authorized when **all** its contained update actions are well-authorized. Each operation has an associated set of parties that need to authorize it: +A Daml update is the composition of update actions created with one of the items in the table below. A Daml update is well-authorized when **all** its contained update actions are well-authorized. Each operation has an associated set of parties that need to authorize it: .. list-table:: Updates and required authorization :header-rows: 1 @@ -158,7 +158,7 @@ A DAML update is the composition of update actions created with one of the items - ``k -> Update (Optional (ContractId c))`` - All key maintainers -At runtime, the DAML execution engine computes the required authorizing parties from this mapping. It also computes which parties have given authorization to the update in question. A party is giving authorization to an update in one of two ways: +At runtime, the Daml execution engine computes the required authorizing parties from this mapping. It also computes which parties have given authorization to the update in question. A party is giving authorization to an update in one of two ways: - It is the signatory of the contract that contains the update action. - It is element of the controllers executing the choice containing the update action. @@ -170,7 +170,7 @@ It is noteworthy, that authorizing parties are always determined only from the l Standard library ================ -The **DAML standard library** is a set of `DAML` functions, classes and more that make developing with DAML easier. +The **Daml standard library** is a set of `Daml` functions, classes and more that make developing with Daml easier. For documentation, see :doc:`/daml/stdlib/index`. @@ -208,7 +208,7 @@ See :doc:`/daml/reference/updates`. Scenario ======== -A **scenario** is a way of testing DAML code during development. You can run scenarios inside `DAML Studio <#daml-studio>`__, or write them to be executed on `Sandbox <#sandbox>`__ when it starts up. +A **scenario** is a way of testing Daml code during development. You can run scenarios inside `Daml Studio <#daml-studio>`__, or write them to be executed on `Sandbox <#sandbox>`__ when it starts up. They're useful for: @@ -216,14 +216,14 @@ They're useful for: - ensuring that parties can exclusively create contracts, observe contracts, and exercise choices that they are meant to - acting as regression tests to confirm that everything keeps working correctly -Scenarios emulate a real ledger. You specify a linear sequence of actions that various parties take, and these are evaluated in order, according to the same consistency, authorization, and privacy rules as they would be on a DAML ledger. DAML Studio shows you the resulting `transaction <#transactions>`__ graph, and (if a scenario fails) what caused it to fail. +Scenarios emulate a real ledger. You specify a linear sequence of actions that various parties take, and these are evaluated in order, according to the same consistency, authorization, and privacy rules as they would be on a Daml ledger. Daml Studio shows you the resulting `transaction <#transactions>`__ graph, and (if a scenario fails) what caused it to fail. See :doc:`/daml/testing-scenarios`. -.. DAMLe, DAML runtime, DAML execution engine +.. Damle, Daml runtime, Daml execution engine .. ========================================== -.. The **DAML runtime** (sometimes also called the DAML execution engine or DAMLe)... +.. The **Daml runtime** (sometimes also called the Daml execution engine or Damle)... Contract key ============ @@ -239,11 +239,11 @@ See :doc:`/daml/reference/contract-keys`. DAR file, DALF file =================== -A ``.dar`` file is the result of compiling DAML using the `Assistant <#assistant>`__. +A ``.dar`` file is the result of compiling Daml using the `Assistant <#assistant>`__. You upload ``.dar`` files to a `ledger <#ledger-daml-ledger>`__ in order to be able to create contracts from the templates in that file. -A ``.dar`` contains multiple ``.dalf`` files. A ``.dalf`` file is the output of a compiled DAML package or library. Its underlying format is `DAML-LF <#daml-lf>`__. +A ``.dar`` contains multiple ``.dalf`` files. A ``.dalf`` file is the output of a compiled Daml package or library. Its underlying format is `Daml-LF <#daml-lf>`__. .. Package, module, library .. ======================== @@ -256,14 +256,14 @@ Developer tools Assistant ========= -**DAML Assistant** is a command-line tool for many tasks related to DAML. Using it, you can create DAML projects, compile DAML projects into `.dar files <#dar-file-dalf-file>`__, launch other developer tools, and download new SDK versions. +**Daml Assistant** is a command-line tool for many tasks related to Daml. Using it, you can create Daml projects, compile Daml projects into `.dar files <#dar-file-dalf-file>`__, launch other developer tools, and download new SDK versions. See :doc:`/tools/assistant`. Studio ====== -**DAML Studio** is a plugin for Visual Studio Code, and is the IDE for writing DAML code. +**Daml Studio** is a plugin for Visual Studio Code, and is the IDE for writing Daml code. See :doc:`/daml/daml-studio`. @@ -308,8 +308,8 @@ There's a lot of information available about application development, starting w Ledger API ========== -The **Ledger API** is an API that's exposed by any `DAML ledger <#ledger-daml-ledger>`__. -Alternative names: **DAML Ledger API** and **gRPC Ledger API** if disambiguation from other technologies is needed. +The **Ledger API** is an API that's exposed by any `Daml ledger <#ledger-daml-ledger>`__. +Alternative names: **Daml Ledger API** and **gRPC Ledger API** if disambiguation from other technologies is needed. See :doc:`/app-dev/ledger-api` page. It includes the following :doc:`services `. @@ -341,7 +341,7 @@ Use the **active contract service** to obtain a party-specific view of all `cont Package service --------------- -Use the **package service** to obtain information about DAML packages available on the `ledger <#ledger-daml-ledger>`__. See :ref:`package-service`. +Use the **package service** to obtain information about Daml packages available on the `ledger <#ledger-daml-ledger>`__. See :ref:`package-service`. Ledger identity service ----------------------- @@ -394,37 +394,37 @@ A **command** is an instruction to add a transaction to the `ledger <#ledger-dam .. _daml-lf: -DAML-LF +Daml-LF ======= -When you compile DAML source code into a `.dar file <#dar-file-dalf-file>`__, the underlying format is **DAML-LF**. DAML-LF is similar to DAML, but is stripped down to a core set of features. The relationship between the surface DAML syntax and DAML-LF is loosely similar to that between Java and JVM bytecode. +When you compile Daml source code into a `.dar file <#dar-file-dalf-file>`__, the underlying format is **Daml-LF**. Daml-LF is similar to Daml, but is stripped down to a core set of features. The relationship between the surface Daml syntax and Daml-LF is loosely similar to that between Java and JVM bytecode. -As a user, you don't need to interact with DAML-LF directly. But internally, it's used for: +As a user, you don't need to interact with Daml-LF directly. But internally, it's used for: -- executing DAML code on the Sandbox or on another platform +- executing Daml code on the Sandbox or on another platform - sending and receiving values via the Ledger API (using a protocol such as gRPC) -- generating code in other languages for interacting with DAML models (often called “codegen”) +- generating code in other languages for interacting with Daml models (often called “codegen”) General concepts **************** -Ledger, DAML ledger +Ledger, Daml ledger =================== -**Ledger** can refer to a lot of things, but a ledger is essentially the underlying storage mechanism for a running DAML applications: it's where the contracts live. A **DAML ledger** is a ledger that you can store DAML contracts on, because it implements the `ledger API <#ledger-api>`__. +**Ledger** can refer to a lot of things, but a ledger is essentially the underlying storage mechanism for a running Daml applications: it's where the contracts live. A **Daml ledger** is a ledger that you can store Daml contracts on, because it implements the `ledger API <#ledger-api>`__. -DAML ledgers provide various guarantees about what you can expect from it, all laid out in the :doc:`/concepts/ledger-model/index` page. +Daml ledgers provide various guarantees about what you can expect from it, all laid out in the :doc:`/concepts/ledger-model/index` page. When you're developing, you'll use `Sandbox <#sandbox>`__ as your ledger. -If you would like to integrate DAML with a storage infrastructure not already in development (see `daml.com `__), please get in touch on `Slack `__ in the channel ``#daml-contributors``. +If you would like to integrate Daml with a storage infrastructure not already in development (see `daml.com `__), please get in touch on `Slack `__ in the channel ``#daml-contributors``. .. _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. +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. .. Transaction diff --git a/docs/source/concepts/identity-and-package-management.rst b/docs/source/concepts/identity-and-package-management.rst index 123bf56597..a0c6b1673e 100644 --- a/docs/source/concepts/identity-and-package-management.rst +++ b/docs/source/concepts/identity-and-package-management.rst @@ -6,12 +6,12 @@ Identity and Package Management ############################### -Since DAML ledgers enable parties to automate the management of their rights and obligations through smart contract code, they also have to provide party and code management functions. +Since Daml ledgers enable parties to automate the management of their rights and obligations through smart contract code, they also have to provide party and code management functions. Hence, this document addresses: -1. Management of parties' digital identifiers in a DAML ledger. +1. Management of parties' digital identifiers in a Daml ledger. -2. Distribution of smart contract code between the parties connected to the same DAML ledger. +2. Distribution of smart contract code between the parties connected to the same Daml ledger. The access to this functionality is usually more restricted compared to the other Ledger API services, as they are part of the administrative API. This document is intended for the users and implementers of this API. @@ -30,10 +30,10 @@ The remainder of the document will present: Identity Management ******************* -A DAML ledger may freely define its own format of party and :ref:`participant node ` identifiers, with some minor constraints on the identifiers' serialized form. +A Daml ledger may freely define its own format of party and :ref:`participant node ` identifiers, with some minor constraints on the identifiers' serialized form. For example, a ledger may use human-readable strings as identifiers, such as "Alice" or "Alice's Bank". A different ledger might use public keys as identifiers, or the keys' fingerprints. -The applications should thus not rely on the format of the identifier -- even a software upgrade of a DAML ledger may introduce a new format. +The applications should thus not rely on the format of the identifier -- even a software upgrade of a Daml ledger may introduce a new format. By definition, identifiers identify parties, and are thus unique for a ledger. They do not, however, have to be unique across different ledgers. @@ -53,7 +53,7 @@ For example, a party might change its display name from "Bruce" to "Caitlyn" -- Provisioning Identifiers ======================== -The set of parties of any DAML ledger is dynamic: new parties may always be added to the system. +The set of parties of any Daml ledger is dynamic: new parties may always be added to the system. The first step in adding a new party to the ledger is to provision a new identifier for the party. The Ledger API provides an :ref:`AllocateParty ` method for this purpose. The method, if successful, returns an new party identifier. @@ -97,7 +97,7 @@ To learn more about Ledger API security model, please read the :doc:`Authorizati Identifiers and the Real World ============================== -The "substrate" on which DAML workflows are built are the real-world obligations of the parties in the workflow. +The "substrate" on which Daml workflows are built are the real-world obligations of the parties in the workflow. To give value to these obligations, they must be connected to parties in the real world. However, the process of linking party identifiers to real-world entities is left to the ledger implementation. @@ -106,14 +106,14 @@ For example, if the operator is a stock exchange, it might guarantee that a real Alternatively, it might use a random identifier, but guarantee that the display name is "Bank Inc.". Ledgers with :ref:`partitioned topologies ` in general might not have such a single store of identities. The solutions for linking the identifiers to real-world identities could rely on certificate chains, `verifiable credentials `__, or other mechanisms. -The mechanisms can be implemented off-ledger, using DAML workflows (for instance, a "know your customer" workflow), or a combination of these. +The mechanisms can be implemented off-ledger, using Daml workflows (for instance, a "know your customer" workflow), or a combination of these. .. _package-management: Package Management ****************** -All DAML ledgers implement endpoints that allow for provisioning new DAML code to the ledger. +All Daml ledgers implement endpoints that allow for provisioning new Daml code to the ledger. The vetting process for this code, however, depends on the particular ledger implementation and its configuration. The remainder of this section describes the endpoints and general principles behind the vetting process. The details of the process are ledger-dependent. @@ -123,8 +123,8 @@ The details of the process are ledger-dependent. Package Formats and Identifiers =============================== -Any code -- i.e., DAML templates -- to be uploaded must compiled down to the :ref:`DAML-LF ` language. -The unit of packaging for DAML-LF is the :ref:`.dalf ` file. +Any code -- i.e., Daml templates -- to be uploaded must compiled down to the :ref:`Daml-LF ` language. +The unit of packaging for Daml-LF is the :ref:`.dalf ` file. Each ``.dalf`` file is uniquely identified by its **package identifier**, which is the hash of its contents. Templates in a ``.dalf`` file can reference templates from other ``.dalf`` files, i.e., ``.dalf`` files can depend on other ``.dalf`` files. A :ref:`.dar ` file is a simple archive containing multiple ``.dalf`` files, and has no identifier of its own. @@ -153,23 +153,23 @@ The package management API supports two methods: Package Vetting =============== -Using a DAML package entails running its DAML code. -The DAML interpreter ensures that the DAML code cannot interact with the environment of the system on which it is executing. -However, the operators of the ledger infrastructure nodes may still wish to review and vet any DAML code before allowing it to execute. -One reason for this is that the DAML interpreter currently lacks a notion of reproducible resource limits, and executing a DAML contract might result in high memory or CPU usage. +Using a Daml package entails running its Daml code. +The Daml interpreter ensures that the Daml code cannot interact with the environment of the system on which it is executing. +However, the operators of the ledger infrastructure nodes may still wish to review and vet any Daml code before allowing it to execute. +One reason for this is that the Daml interpreter currently lacks a notion of reproducible resource limits, and executing a Daml contract might result in high memory or CPU usage. -Thus, DAML ledgers generally allow some form of vetting a package before running its code on a node. -Not all nodes in a DAML ledger must vet all packages, as it is possible that some of them will not execute the code. -For example, in :ref:`global state topologies `, every :ref:`trust domain ` that controls how commits are appended to the shared ledger must execute DAML code. +Thus, Daml ledgers generally allow some form of vetting a package before running its code on a node. +Not all nodes in a Daml ledger must vet all packages, as it is possible that some of them will not execute the code. +For example, in :ref:`global state topologies `, every :ref:`trust domain ` that controls how commits are appended to the shared ledger must execute Daml code. Thus, the operators of these trust domains will in general be allowed to vet the code before they execute it. The exact vetting mechanism is ledger-dependent. -For example, in the :ref:`DAML Sandbox `, the vetting is implicit: uploading a package through the Ledger API already vets the package, since it's assumed that only the system administrator has access to these API facilities. +For example, in the :ref:`Daml Sandbox `, the vetting is implicit: uploading a package through the Ledger API already vets the package, since it's assumed that only the system administrator has access to these API facilities. In a replicated ledger, the vetting might require consent from all or a quorum of replicas. The vetting process can be manual, where an administrator inspects each package, or it can be automated, for example, by accepting only packages with a digital signature from a trusted package issuer. In :ref:`partitioned topologies `, individual trust domains store only parts of the ledger. Thus, they only need to approve packages whose templates are used in the ledger part visible to them. -For example, in DAML on `R3 Corda `__, participants only need to approve code for the contracts in their parties' projections. +For example, in Daml on `R3 Corda `__, participants only need to approve code for the contracts in their parties' projections. If non-validating Corda notaries are used, they do not need to vet code. If validating Corda notaries are used, they can also choose which code to vet. In `Canton `__, participant nodes also only need to vet code for the contracts of the parties they host. @@ -185,4 +185,4 @@ Package Upgrades The Ledger API does not have any special support for package upgrades. A new version of an existing package is treated the same as a completely new package, and undergoes the same vetting process. -Upgrades to active contracts can be done by the DAML code of the new package version, by archiving the old contracts and creating new ones. +Upgrades to active contracts can be done by the Daml code of the new package version, by archiving the old contracts and creating new ones. diff --git a/docs/source/concepts/interoperability.rst b/docs/source/concepts/interoperability.rst index c2f044dce2..754f1f9daa 100644 --- a/docs/source/concepts/interoperability.rst +++ b/docs/source/concepts/interoperability.rst @@ -6,10 +6,10 @@ Ledger Interoperability ####################### -Certain DAML ledgers can interoperate with other DAML ledgers. +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. Some Participant Nodes can connect to multiple ledgers and provide their parties unified access to those ledgers via the :ref:`Ledger API `. -For example, when an organization initially deploys two workflows to two DAML ledgers, it can later compose those workflows into a larger workflow that spans both ledgers. +For example, when an organization initially deploys two workflows to two Daml ledgers, it can later compose those workflows into a larger workflow that spans both ledgers. Interoperability may limit the visibility a Participant Node has into a party's ledger projection, i.e., its :ref:`local ledger `, when the party is hosted on multiple Participant Nodes. These limitations influence what parties can observe via the Ledger API of each Participant Node. @@ -20,12 +20,12 @@ The presentation assumes that you are familiar with the following concepts: * The :ref:`Ledger API ` -* The :ref:`DAML Ledger Model ` +* The :ref:`Daml Ledger Model ` * :ref:`Local ledgers and causality graphs ` .. note:: - Interoperability for DAML ledgers is under active development. + Interoperability for Daml ledgers is under active development. This document describes the vision for interoperability and gives an idea of how the Ledger API services may change and what guarantees are provided. The described services and guarantees may change without notice as the interoperability implementation proceeds. @@ -40,7 +40,7 @@ Interoperability examples Topology ======== -Participant Nodes connect to DAML ledgers and parties access projections of these ledgers via the Ledger API. +Participant Nodes connect to Daml ledgers and parties access projections of these ledgers via the Ledger API. The following picture shows such a setup. .. https://app.lucidchart.com/documents/edit/6b818d37-cf4c-4513-9d31-d68acddf4533 @@ -53,15 +53,15 @@ The following picture shows such a setup. The components in this diagram are the following: -* There is a set of interoperable **DAML ledgers**: Ledger 1 (green) and Ledger 2 (yellow). +* There is a set of interoperable **Daml ledgers**: Ledger 1 (green) and Ledger 2 (yellow). -* Each **Participant Node** is connected to a subset of the DAML ledgers. +* Each **Participant Node** is connected to a subset of the Daml ledgers. - Participant Nodes 1 and 3 are connected to Ledger 1 and 2. - Participant Node 2 is connected to Ledger 1 only. -* Participant Nodes host parties on a subset of the DAML ledgers they are connected to. - A Participant Node provides a party access to the DAML ledgers that it hosts the party on. +* Participant Nodes host parties on a subset of the Daml ledgers they are connected to. + A Participant Node provides a party access to the Daml ledgers that it hosts the party on. - Participant Node 1 hosts Alice on Ledger 1 and 2. - Participant Node 2 hosts Alice on Ledger 1. @@ -73,7 +73,7 @@ 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. -When a Participant Node hosts a party only on a subset of the interoperable DAML ledgers, +When a Participant Node hosts a party only on a subset of the interoperable Daml ledgers, then the transaction and active contract services of the Participant Node are derived only from those ledgers. For example, in the :ref:`above topology `, when a transaction creates a contract with stakeholder Alice on Ledger 2, @@ -130,9 +130,9 @@ In contrast, `P1` need not output the **Enter** and **Leave** actions at all in Cross-ledger transactions ========================= -With interoperability, a cross-ledger transaction can be committed on several interoperable DAML ledgers simultaneously. +With interoperability, a cross-ledger transaction can be committed on several interoperable Daml ledgers simultaneously. Such a cross-ledger transaction avoids some of the synchronization overhead of **Enter** and **Leave** actions. -When a cross-ledger transaction uses contracts from several DAML ledgers, +When a cross-ledger transaction uses contracts from several Daml ledgers, stakeholders may witness actions on their contracts that are actually not visible on the Participant Node. For example, suppose that the :ref:`split paint counteroffer workflow ` from the causality examples is committed as follows: @@ -161,15 +161,15 @@ Multi-ledger causality graphs This section generalizes :ref:`causality graphs ` to the interoperability setting. -Every active DAML contract resides on at most one DAML ledger. -Any use of a contract must be committed on the DAML ledger where it resides. -Initially, when the contract is created, it takes up residence on the DAML ledger on which the **Create** action is committed. -To use contracts residing on different DAML ledgers, cross-ledger transactions are committed on several DAML ledgers. +Every active Daml contract resides on at most one Daml ledger. +Any use of a contract must be committed on the Daml ledger where it resides. +Initially, when the contract is created, it takes up residence on the Daml ledger on which the **Create** action is committed. +To use contracts residing on different Daml ledgers, cross-ledger transactions are committed on several Daml ledgers. -However, cross-ledger transactions incur overheads and if a contract is frequently used on a DAML ledger that is not its residence, the interoperability protocol can migrate the contract to the other DAML ledger. -The process of the contract giving up residence on the origin DAML ledger and taking up residence on the target DAML ledger is called a **contract transfer**. +However, cross-ledger transactions incur overheads and if a contract is frequently used on a Daml ledger that is not its residence, the interoperability protocol can migrate the contract to the other Daml ledger. +The process of the contract giving up residence on the origin Daml ledger and taking up residence on the target Daml ledger is called a **contract transfer**. The **Enter** and **Leave** events on the transaction stream originate from such contract transfers, as will be explained below. -Moreover, contract transfers are synchronization points between the origin and target DAML ledgers and therefore affect the ordering guarantees. +Moreover, contract transfers are synchronization points between the origin and target Daml ledgers and therefore affect the ordering guarantees. We therefore generalize causality graphs for interoperability. Definition »Transfer action« @@ -182,7 +182,7 @@ Transfer actions do not appear in transactions though. So a transaction action cannot have a transfer action as a consequence and transfer actions do not have consequences at all. Definition »Multi-Ledger causality graph« - A **multi-ledger causality graph** `G` for a set `Y` of DAML ledgers is a finite, transitively closed, directed acyclic graph. + A **multi-ledger causality graph** `G` for a set `Y` of Daml ledgers is a finite, transitively closed, directed acyclic graph. The vertices are either transactions or transfer actions. Every action is possibly annotated with an **incoming ledger** and an **outgoing ledger** from `Y` according to the following table: @@ -242,7 +242,7 @@ The last transaction `tx4` is a cross-ledger transaction because its actions hav :align: center :width: 100% - Multi-Ledger causality graph for the split paint counteroffer workflow on two DAML ledgers + Multi-Ledger causality graph for the split paint counteroffer workflow on two Daml ledgers Consistency @@ -251,8 +251,8 @@ Consistency Definition »Ledger trace« A **ledger trace** is a finite list of pairs `(a`:sub:`i`\ `, b`:sub:`i`\ `)` such that `b`:sub:`i - 1` = `a`:sub:`i` for all `i` > 0. - Here `a`:sub:`i` and `b`:sub:`i` identify DAML ledgers or are the special value `NONE`, - which is different from all DAML ledger identifiers. + Here `a`:sub:`i` and `b`:sub:`i` identify Daml ledgers or are the special value `NONE`, + which is different from all Daml ledger identifiers. Definition »Multi-Ledger causal consistency for a contract« @@ -275,7 +275,7 @@ The first three conditions mimick the conditions of :ref:`causal consistency ` is multi-ledger consistent for `c`. @@ -343,7 +343,7 @@ If the original causality graph is `X`\ -consistent, then so is the topological 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. +Multi-Ledger causality graphs `G` are linked to ledgers `L` in the Daml Ledger Model via topological sort and reduction. * Given a multi-ledger causality graph `G`, drop the incoming and outgoing ledger annotations and all transfer vertices, @@ -373,7 +373,7 @@ Definition »Y-labelled action« if its incoming or outgoing ledger annotation is an element of `Y`. Definition »Ledger-aware projection for transactions« - Let `Y` be a set of DAML ledgers and `tx` a transaction whose actions are annotated with incoming and outgoing ledgers. + Let `Y` be a set of Daml ledgers and `tx` a transaction whose actions are annotated with incoming and outgoing ledgers. Let `Act` be the set of `Y`\ -labelled subactions of `tx` that the party `P` is an informee of. The **ledger-aware projection** of `tx` for `P` on `Y` (`P`-**projection on** `Y`) consists of all the maximal elements of `Act` (w.r.t. the subaction relation) in execution order. @@ -408,7 +408,7 @@ Definition »Multi-Ledger consistency for a party« The notions of `X`-minimality and `X`-reduction extend to a party `P` on a set `Y` of ledgers accordingly. Definition »Ledger-aware projection for multi-ledger causality graphs« - Let `G` be a multi-ledger consistent causality graph and `Y` be a set of DAML ledgers. + Let `G` be a multi-ledger consistent causality graph and `Y` be a set of Daml ledgers. The **projection** of `G` to party `P` on `Y` (`P`\ -**projection** on `Y`) is the `P`\ -reduction on `Y` of the following causality graph `G'`, which is `P`\ -consistent on `Y`: * The vertices of `G'` are the vertices of `G` projected to `P` on `Y`, excluding empty projections. @@ -472,6 +472,6 @@ The flat transaction stream contains precisely the ``CreatedEvent``\ s, ``Archiv Similarly, the active contract service provides the set of contracts that are active at the returned offset according to the flat transaction stream. That is, the contract state changes of all events from the transaction event stream are taken into account in the provided set of contracts. -The :ref:`ordering guarantees ` for single DAML ledgers extend accordingly. -In particular, interoperability ensures that all local ledgers are projections of a virtual shared multi-ledger causality graph that connects to the DAML Ledger Model as described above. +The :ref:`ordering guarantees ` for single Daml ledgers extend accordingly. +In particular, interoperability ensures that all local ledgers are projections of a virtual shared multi-ledger causality graph that connects to the Daml Ledger Model as described above. The ledger validity guarantees therefore extend via the local ledgers to the Ledger API. diff --git a/docs/source/concepts/ledger-model/index.rst b/docs/source/concepts/ledger-model/index.rst index 31b630265a..34062e869c 100644 --- a/docs/source/concepts/ledger-model/index.rst +++ b/docs/source/concepts/ledger-model/index.rst @@ -3,25 +3,25 @@ .. _da-ledgers: -DAML Ledger Model +Daml Ledger Model ================= -DAML Ledgers enable multi-party workflows by providing +Daml Ledgers enable multi-party workflows by providing parties with a virtual *shared ledger*, which encodes the current -state of their shared contracts, written in DAML. At a high level, the interactions are visualized as +state of their shared contracts, written in Daml. At a high level, the interactions are visualized as follows: .. https://www.lucidchart.com/documents/edit/505709a9-e972-4272-b1fd-c01674c323b8 .. image:: ./images/da-ledger-model.svg -The DAML ledger model defines: +The Daml ledger model defines: - #. what the ledger looks like - the structure of DAML ledgers - #. who can request which changes - the integrity model for DAML ledgers - #. who sees which changes and data - the privacy model for DAML ledgers + #. what the ledger looks like - the structure of Daml ledgers + #. who can request which changes - the integrity model for Daml ledgers + #. who sees which changes and data - the privacy model for Daml ledgers The below sections review these concepts of the ledger model in turn. -They also briefly describe the link between DAML and the model. +They also briefly describe the link between Daml and the model. .. toctree:: :maxdepth: 3 diff --git a/docs/source/concepts/ledger-model/ledger-daml.rst b/docs/source/concepts/ledger-model/ledger-daml.rst index afc859d243..02e736dd60 100644 --- a/docs/source/concepts/ledger-model/ledger-daml.rst +++ b/docs/source/concepts/ledger-model/ledger-daml.rst @@ -3,7 +3,7 @@ .. _da-model-daml: -DAML: Defining Contract Models Compactly +Daml: Defining Contract Models Compactly ---------------------------------------- As described in preceeding sections, both the integrity and privacy notions depend on @@ -20,7 +20,7 @@ arbitrary obligor and an arbitrary owner. As enumerating all possible actions from an infinite set is infeasible, a more compact way of representing models is needed. -DAML provides exactly that: a compact representation of a contract model. +Daml provides exactly that: a compact representation of a contract model. Intuitively, the allowed actions are: #. **Create** actions on all instances of templates such that @@ -51,14 +51,14 @@ Intuitively, the allowed actions are: #. **NoSuchKey** assertions corresponding to a :ref:`lookupByKey` update statement for the given key that does not find a contract. -An instance of a DAML template, that is, a **DAML contract**, +An instance of a Daml template, that is, a **Daml contract**, is a triple of: #. a contract identifier #. the template identifier #. the template arguments -The signatories of a DAML contract are derived from the template arguments and the explicit signatory annotations on the contract template. +The signatories of a Daml contract are derived from the template arguments and the explicit signatory annotations on the contract template. The observers are also derived from the template arguments and include: 1. the observers as explicitly annotated on the template @@ -79,8 +79,8 @@ In this example, the owner is automatically made an observer on the contract, as The template identifiers of contracts are created through a content-addressing scheme. This means every contract is self-describing in a sense: it constrains its stakeholder annotations -and all DAML-conformant actions on itself. As a consequence, one can -talk about "the" DAML contract model, as a single contract model encoding all possible +and all Daml-conformant actions on itself. As a consequence, one can +talk about "the" Daml contract model, as a single contract model encoding all possible instances of all possible templates. This model is subaction-closed; all exercise and create actions done within an update block are also always permissible as top-level actions. diff --git a/docs/source/concepts/ledger-model/ledger-integrity.rst b/docs/source/concepts/ledger-model/ledger-integrity.rst index 7978108205..4dcff93675 100644 --- a/docs/source/concepts/ledger-model/ledger-integrity.rst +++ b/docs/source/concepts/ledger-model/ledger-integrity.rst @@ -302,9 +302,9 @@ Furthermore, to be conformant, the actor of a transfer action must be the same a Of course, the constraints on the relationship between the parameters can be arbitrarily complex, and cannot conveniently be reproduced in this -graphical representation. This is the role of DAML -- it +graphical representation. This is the role of Daml -- it provides a much more convenient way of representing contract models. -The link between DAML and contract models is explained in more detail in a :ref:`later section `. +The link between Daml and contract models is explained in more detail in a :ref:`later section `. To see the conformance criterion in action, assume that the contract model allows only the following actions on `PaintOffer` @@ -410,7 +410,7 @@ The imposed obligation is intuitively invalid because the painter did not agree to this obligation. In other words, the painter did not *authorize* the creation of the obligation. -In a DAML ledger, a party can **authorize** a subaction of a commit in +In a Daml ledger, a party can **authorize** a subaction of a commit in either of the following ways: * Every top-level action of the commit is authorized by all requesters @@ -519,7 +519,7 @@ is discussed in the next section about :ref:`privacy `, controllers specified using simple syntax are automatically made observers whenever possible. +Note that in Daml, as detailed :ref:`later `, controllers specified using simple syntax are automatically made observers whenever possible. In the graphical representation of the paint offer acceptance below, observers who are not signatories are indicated by an underline. @@ -85,7 +85,7 @@ for, providing privacy to `A` and `P` with respect to the bank. .. _def-informee: -As a design choice, DAML Ledgers show to observers on a contract only the +As a design choice, Daml Ledgers show to observers on a contract only the :ref:`state changing ` actions on the contract. More precisely, **Fetch** and non-consuming **Exercise** actions are not shown to the observers - except when they are the actors of these actions. @@ -94,7 +94,7 @@ This motivates the following definition: a party `p` is an **informee** of an ac * `A` is a **Create** on a contract `c` and `p` is a stakeholder of `c`. * `A` is a consuming **Exercise** on a contract `c`, and `p` is a stakeholder of `c` or an actor on `A`. - Note that a DAML "flexible controller" :ref:`can be an exercise actor without being a contract stakeholder `. + Note that a Daml "flexible controller" :ref:`can be an exercise actor without being a contract stakeholder `. * `A` is a non-consuming **Exercise** on a contract `c`, and `p` is a signatory of `c` or an actor on `A`. @@ -165,7 +165,7 @@ In other words, contract model is **subaction-closed**, which means that for every action `act` in the model, all subactions of `act` are also in the model, then the projection is guaranteed to be -conformant. As we will see shortly, DAML-based contract models are +conformant. As we will see shortly, Daml-based contract models are conformant. Lastly, as projections carry no information about the requesters, we cannot talk about authorization on the level of projections. @@ -202,7 +202,7 @@ Requiring all maintainers to authorize a **NoSuchKey** assertion avoids the prob Divulgence: When Non-Stakeholders See Contracts +++++++++++++++++++++++++++++++++++++++++++++++ -The guiding principle for the privacy model of DAML ledgers is that +The guiding principle for the privacy model of Daml ledgers is that contracts should only be shown to their stakeholders. However, ledger projections can cause contracts to become visible to other parties as well. @@ -218,7 +218,7 @@ and `Iou Bank P` was shown to Alice. Showing contracts to non-stakeholders through ledger projections is called **divulgence**. Divulgence is a deliberate choice in the design -of DAML ledgers. In the paint offer example, the only proper way to +of Daml ledgers. In the paint offer example, the only proper way to accept the offer is to transfer the money from Alice to the painter. Conceptually, at the instant where the offer is accepted, its stakeholders also gain a temporary stake in the actions on the two diff --git a/docs/source/concepts/ledger-model/ledger-structure.rst b/docs/source/concepts/ledger-model/ledger-structure.rst index 7808497e89..e8e2f69590 100644 --- a/docs/source/concepts/ledger-model/ledger-structure.rst +++ b/docs/source/concepts/ledger-model/ledger-structure.rst @@ -6,7 +6,7 @@ Structure --------- -This section looks at the structure of a DAML ledger and the associated ledger +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 into *transactions*. @@ -15,7 +15,7 @@ into *transactions*. Actions and Transactions ++++++++++++++++++++++++ -One of the main features of the DAML ledger model is a *hierarchical action +One of the main features of the Daml ledger model is a *hierarchical action structure*. This structure is illustrated below on a toy example of a multi-party @@ -35,7 +35,7 @@ which a new IOU for `P` is *created*. Second, a new contract is Thus, the acceptance in this example is reduced to two types of actions: (1) creating contracts, and (2) exercising rights on them. These are also the -two main kinds of actions in the DAML ledger model. The visual notation below +two main kinds of actions in the Daml ledger model. The visual notation below records the relations between the actions during the above acceptance. .. image:: ./images/action-structure-expanded-paint-offer.svg @@ -102,7 +102,7 @@ conventions that: #. the consequences are ordered left-to-right. #. to aid intuitions, exercise actions are annotated with suggestive names like "accept" or "transfer". Intuitively, these correspond to names of - DAML choices, but they have no semantic meaning. + Daml choices, but they have no semantic meaning. An alternative shorthand notation, shown below uses the abbreviations **Exe** and **ExeN** for exercises, and omits the **Create** labels on create actions. @@ -206,7 +206,7 @@ changes, but not *who requested them*. This information is added by the notion of a **commit**: a transaction paired with the parties that requested it, called the **requesters** of the commit. In the ledger model, a commit is allowed to have multiple requesters, -although the current DAML Ledger API offers the request functionality only to individual parties. +although the current Daml Ledger API offers the request functionality only to individual parties. Given a commit `(p, tx)` with transaction `tx = act`:sub:`1`\ `, …, act`:sub:`n`, every `act`:sub:`i` is called a **top-level action** of the commit. A **ledger** is a sequence of commits. A top-level action of any ledger commit is also a top-level action of @@ -219,7 +219,7 @@ The following EBNF grammar summarizes the structure of commits and ledgers: Commit ::= party Transaction Ledger ::= Commit* -A DAML ledger thus represents the full history of all actions taken by +A Daml ledger thus represents the full history of all actions taken by parties.\ [#ledger-vs-journal]_ Since the ledger is a sequence (of dependent actions), it induces an *order* on the commits in the ledger. Visually, a ledger can be represented as a sequence growing from left to right as time progresses. Below, @@ -236,7 +236,7 @@ follows. The definitions presented here are all the ingredients required to -*record* the interaction between parties in a DAML ledger. That is, they +*record* the interaction between parties in a Daml ledger. That is, they address the first question: "what do changes and ledgers look like?". To answer the next question, "who can request which changes", a precise definition is needed of which ledgers are permissible, diff --git a/docs/source/concepts/local-ledger.rst b/docs/source/concepts/local-ledger.rst index dce042f554..4df374a8f0 100644 --- a/docs/source/concepts/local-ledger.rst +++ b/docs/source/concepts/local-ledger.rst @@ -6,26 +6,26 @@ Causality and Local Ledgers ########################### -DAML ledgers do not totally order all transactions. +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 `. Moreover, different Participant Nodes may output two transactions for the same party in different orders. -This document explains the ordering guarantees that DAML ledgers do provide, by :ref:`example ` and formally via the concept of :ref:`causality graphs ` and :ref:`local ledgers `. +This document explains the ordering guarantees that Daml ledgers do provide, by :ref:`example ` and formally via the concept of :ref:`causality graphs ` and :ref:`local ledgers `. The presentation assumes that you are familiar with the following concepts: * The :ref:`Ledger API ` -* The :ref:`DAML Ledger Model ` +* The :ref:`Daml Ledger Model ` .. _causality-examples: Causality examples ****************** -A DAML Ledger need not totally order all transaction, unlike ledgers in the DAML Ledger Model. +A Daml Ledger need not totally order all transaction, unlike ledgers in the Daml Ledger Model. The following examples illustrate these ordering guarantees of the Ledger API. -They are based the paint counteroffer workflow from the DAML Ledger Model's :ref:`privacy section `, -ignoring the total ordering coming from the DAML Ledger Model. +They are based the paint counteroffer workflow from the Daml Ledger Model's :ref:`privacy section `, +ignoring the total ordering coming from the Daml Ledger Model. Recall that :ref:`the party projections ` are as follows. .. https://www.lucidchart.com/documents/edit/c4df0455-13ab-415f-b457-f5654c2684be @@ -39,8 +39,8 @@ Recall that :ref:`the party projections ` are as 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.) +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.) Accordingly, Alice will see the creation before the archival on her transaction stream and so will the painter. This does not depend on whether they are hosted on the same Participant Node. @@ -107,7 +107,7 @@ The rationale for this behaviour is that Alice could have learnt about the contr The Participant Nodes therefore cannot know whether there will ever be a **Create** event for the contract. So if Participant Nodes delayed outputting the **Create** action for the `CounterOffer` until a **Create** event for the `Iou` contract was published, this delay might last forever and liveness is lost. -DAML ledgers therefore do not capture data flow through applications. +Daml ledgers therefore do not capture data flow through applications. .. _causality-divulgence-example: @@ -128,7 +128,7 @@ Even though this may seem unexpected, it is in line with stakeholder-based ledge Since the painter is not a stakeholder of the `Iou` contract, he should not care about the archivals or creates of the contract. In fact, the divulged `Iou` contract shows up neither in the painter's active contract service nor in the flat transaction stream. Such witnessed events are included in the transaction tree stream as a convenience: -They relieve the painter from computing the consequences of the choice and enable him to check that the action conforms to the DAML model. +They relieve the painter from computing the consequences of the choice and enable him to check that the action conforms to the Daml model. Similarly, being an actor of an **Exercise** action induces order with respect to other uses of the contract only if the actor is a contract stakeholder. This is because non-stakeholder actors of an **Exercise** action merely authorize the action, but they do not track whether the contract is active; this is what signatories and observers are for. @@ -149,8 +149,8 @@ This shows that the ordering guarantees depend on the party. Causality graphs **************** -The above examples indicate that DAML ledgers order transactions only partially. -DAML ledgers can be represented as finite directed acyclic graphs (DAG) of transactions. +The above examples indicate that Daml ledgers order transactions only partially. +Daml ledgers can be represented as finite directed acyclic graphs (DAG) of transactions. .. _def-causality-graph: @@ -198,7 +198,7 @@ Consistency =========== Consistency ensures that a causality graph sufficiently orders all the transactions. -It generalizes :ref:`ledger consistency ` from the DAML Ledger Model as :ref:`explained below `. +It generalizes :ref:`ledger consistency ` from the Daml Ledger Model as :ref:`explained below `. .. _def-causal-consistency-contract: @@ -321,13 +321,13 @@ It is also the reduction of the topological sort, i.e., the :ref:`ledger ` according to DAML Ledger Model +* :ref:`Ledger Consistency ` according to Daml Ledger Model * :ref:`Consistency of causality graph ` @@ -340,7 +340,7 @@ Conversely, if the sequence of commits `L` is ledger consistent, `G`:sub:`L` is Local ledgers ************* -As explained in the DAML Ledger Model, parties see only a :ref:`projection ` of the shared ledger for privacy reasons. +As explained in the Daml Ledger Model, parties see only a :ref:`projection ` of the shared ledger for privacy reasons. Like consistency, projection extends to causality graphs as follows. Definition »Causal consistency for a party« @@ -384,7 +384,7 @@ This difference explains the :ref:`divulgence causality example ` provides the updates as a stream of DAML transactions +The :ref:`Transaction Service ` provides the updates as a stream of Daml transactions and the :ref:`Active Contract Service ` summarizes all the updates up to a given point by the contracts that are active at this point. Conceptually, both services are derived from the local ledger that the Participant Node manages for each hosted party. @@ -403,13 +403,13 @@ In particular, an application can process all subsequent events from the flat tr Since the topological sort of a local ledger is not unique, different Participant Nodes may pick different orders for the transaction streams of the same party. Similarly, the transaction streams for different parties may order common transactions differently, as the party's local ledgers impose different ordering constraints. -Nevertheless, DAML ledgers ensure that all local ledgers are projections of a virtual shared causality graph that connects to the DAML Ledger Model as described above. +Nevertheless, Daml ledgers ensure that all local ledgers are projections of a virtual shared causality graph that connects to the Daml Ledger Model as described above. The ledger validity guarantees therefore extend via the local ledgers to the Ledger API. -These guarantees are subject to the deployed DAML ledger's trust assumptions. +These guarantees are subject to the deployed Daml ledger's trust assumptions. .. note:: - The virtual shared causality graph exists only as a concept, to reason about DAML ledger guarantees. - A deployed DAML ledger in general does not store or even construct such a shared causality graph. + The virtual shared causality graph exists only as a concept, to reason about Daml ledger guarantees. + A deployed Daml ledger in general does not store or even construct such a shared causality graph. The Participant Nodes merely maintain the local ledgers for their parties. They synchronize these local ledgers to the extent that they remain consistent. That is, all the local ledgers can in theory be combined into a consistent single causality graph of which they are projections. @@ -451,4 +451,4 @@ The :ref:`causality examples ` can be explained in terms of #. :ref:`causality-example-depend-on-party` Alice is an informee of the **Fetch** and **Exercise** actions on her `Iou`. Unlike for the painter, :ref:`her local ledger ` does order `tx3` before `tx4`, - so Alice is guaranteed to observe `tx3` before `tx4` on all Participant Nodes through which she is connect to the DAML ledger. + so Alice is guaranteed to observe `tx3` before `tx4` on all Participant Nodes through which she is connect to the Daml ledger. diff --git a/docs/source/concepts/time.rst b/docs/source/concepts/time.rst index 42c169ae85..fc59b591e9 100644 --- a/docs/source/concepts/time.rst +++ b/docs/source/concepts/time.rst @@ -6,10 +6,10 @@ Time #### -The DAML language contains a function :ref:`getTime ` which returns the “current time”. +The Daml language contains a function :ref:`getTime ` which returns the “current time”. However, the notion of time comes with a lot of problems in a distributed setting. -This document describes the detailed semantics of time on DAML ledgers, +This document describes the detailed semantics of time on Daml ledgers, centered around the two timestamps assigned to each transaction: the *ledger time* ``lt_TX`` and the *record time* ``rt_TX``. @@ -22,7 +22,7 @@ Ledger time The *ledger time* ``lt_TX`` is a property of a transaction. It is a timestamp that defines the value of all :ref:`getTime ` calls in the given transaction, and has microsecond resolution. -The ledger time is assigned by the submitting participant as part of the DAML command interpretation. +The ledger time is assigned by the submitting participant as part of the Daml command interpretation. .. _record-time: @@ -35,7 +35,7 @@ It is timestamp with microsecond resolution, and is assigned by the ledger when the transaction is recorded on the ledger. The record time should be an intuitive representation of "real time", -but the DAML ledger model does not prescribe how exactly the record time is assigned. +but the Daml ledger model does not prescribe how exactly the record time is assigned. Each ledger implementation might use a different way of representing time in a distributed setting - for details, contact your ledger operator. @@ -57,8 +57,8 @@ The ledger time of valid transaction ``TX`` must fullfil the following rules: Apart from that, no other guarantees are given on the ledger time. In particular, neither the ledger time nor the record time need to be monotonically increasing. -Time has therefore to be considered slightly fuzzy in DAML, with the fuzziness depending on the skew parameters. -DAML applications should not interpret the value returned by :ref:`getTime ` as a precise timestamp. +Time has therefore to be considered slightly fuzzy in Daml, with the fuzziness depending on the skew parameters. +Daml applications should not interpret the value returned by :ref:`getTime ` as a precise timestamp. .. _ledger-time-model: @@ -86,10 +86,10 @@ Assigning 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. +In most cases, Daml applications will not need to worry about ledger time and record time at all. For reference, this section describes the details of how the ledger time is currently assigned. -The algorithm is not part of the definition of time in DAML, and may change in the future. +The algorithm is not part of the definition of time in Daml, and may change in the future. #. When submitting commands over the ledger API, users can optionally specify a ``min_ledger_time_rel`` or ``min_ledger_time_abs`` argument. diff --git a/docs/source/daml-integration-kit/index.rst b/docs/source/daml-integration-kit/index.rst index 9455f57beb..f89e314049 100644 --- a/docs/source/daml-integration-kit/index.rst +++ b/docs/source/daml-integration-kit/index.rst @@ -1,24 +1,24 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Integration Kit +Daml Integration Kit #################### -The DAML integration kit is currently an :doc:`Early Access Feature in Labs status `. It comprises the components needed to build your own :ref:`DAML Drivers `. +The Daml integration kit is currently an :doc:`Early Access Feature in Labs status `. It comprises the components needed to build your own :ref:`Daml Drivers `. .. toctree:: :hidden: /tools/ledger-api-test-tool/index -:doc:`DAML Applications ` run on DAML Ledgers. -A DAML Ledger is a server serving the +:doc:`Daml Applications ` run on Daml Ledgers. +A Daml Ledger is a server serving the :doc:`Ledger API ` as per the semantics defined in the :doc:`/concepts/ledger-model/index` and the -`DAML-LF specification `_. +`Daml-LF specification `_. -The DAML integration kit helps third-party ledger developers to -implement a DAML Ledger on top of their distributed ledger or database of +The Daml integration kit helps third-party ledger developers to +implement a Daml Ledger on top of their distributed ledger or database of choice. We provide the resources in the kit, which include guides to @@ -30,13 +30,13 @@ We provide the resources in the kit, which include guides to - :ref:`integration-kit_benchmarking` Using these guides, you can focus on your own distributed-ledger or database -and reuse our DAML Ledger server and DAML interpreter code for -implementing the DAML Ledger API. For example uses of the integration kit, see +and reuse our Daml Ledger server and Daml interpreter code for +implementing the Daml Ledger API. For example uses of the integration kit, see below. .. _status_and_roadmap: -DAML Integration Kit status and roadmap +Daml Integration Kit status and roadmap *************************************** The current status of the integration kit is ALPHA. We are working towards BETA, @@ -44,16 +44,16 @@ and General Availability (GA) will come quite a bit later. The roadmap below exp these different statuses, and what's missing to progress. ALPHA (current status) - In the ALPHA status, the DAML integration kit is ready to be used by + In the ALPHA status, the Daml integration kit is ready to be used by third-parties willing to accept the following caveats: - - The architecture includes everything required to run DAML Applications using the - DAML Ledger API. However, it misses support for testing DAML Applications in a - uniform way against different DAML Ledgers. + - The architecture includes everything required to run Daml Applications using the + Daml Ledger API. However, it misses support for testing Daml Applications in a + uniform way against different Daml Ledgers. - Ledger API authorization, package upload, party on-boarding, ledger reset, - and time manipulation are specific to each DAML Ledger, until the uniform - *administrative DAML ledger access* API is introduced, which is different - to the uniform *per-party DAML ledger access* that the DAML Ledger API provides. + and time manipulation are specific to each Daml Ledger, until the uniform + *administrative Daml ledger access* API is introduced, which is different + to the uniform *per-party Daml ledger access* that the Daml Ledger API provides. We will address this before reaching BETA status. - The architecture is likely to change due to learnings from integrators like you! Where possible we strive to make these changes backwards compatible. though this @@ -63,7 +63,7 @@ ALPHA (current status) - Some of our code might be fresh off the press and might therefore have a higher rate of bugs. - That said: we highly value your feedback and input on where you find DAML software and this integration kit most useful. + That said: we highly value your feedback and input on where you find Daml software and this integration kit most useful. You can get into contact with us using the feedback form on this documentation page or by creating issues or pull-requests against the `digital-asset/daml `__ GitHub repository. @@ -72,16 +72,16 @@ ALPHA (current status) BETA For us, BETA status means that we have architectural stability and solid documentation in place. At this point, third-parties should have everything - they need to integrate DAML with their ledger of choice completely on their + they need to integrate Daml with their ledger of choice completely on their own. Before reaching BETA status, we expect to have: - hardened our test tooling - - built tooling for benchmarking DAML ledgers - - completed several integrations of DAML for different ledgers - - implemented uniform *administrative DAML ledger access* to provide a - portable way for testing DAML applications against different DAML ledgers + - built tooling for benchmarking Daml ledgers + - completed several integrations of Daml for different ledgers + - implemented uniform *administrative Daml ledger access* to provide a + portable way for testing Daml applications against different Daml ledgers Related links @@ -90,7 +90,7 @@ BETA GA For us GA (General Availability) means that there are several - production-ready DAML ledgers built using the DAML integration kit. + production-ready Daml ledgers built using the Daml integration kit. We expect to reach GA in 2019. Related links @@ -99,13 +99,13 @@ GA .. _integration-kit_implementing: -Implementing your own DAML Ledger +Implementing your own Daml Ledger ********************************* Each `X` ledger requires at least the implementation of a specific -``daml-on--server``, which implements the DAML Ledger API. It might also +``daml-on--server``, which implements the Daml Ledger API. It might also require the implementation of a ``-daml-validator``, which provides the -ability for nodes to validate DAML transactions. +ability for nodes to validate Daml transactions. For more about these parts of the architecture, read the `Architectural overview`_. @@ -117,13 +117,13 @@ Prerequisite knowledge ---------------------- Before you can decide on an appropriate architecture and implement your own -server and validator, you need a significant amount of context about DAML. +server and validator, you need a significant amount of context about Daml. To acquire this context, you should: 1. Complete the :doc:`/app-dev/bindings-java/quickstart`. 2. Get an in-depth understanding of the :doc:`/concepts/ledger-model/index`. 3. Build a mental model of how the :doc:`Ledger API ` - is used to :doc:`build DAML Applications `. + is used to :doc:`build Daml Applications `. .. _integration-kit_writing_code: @@ -133,7 +133,7 @@ Deciding on the architecture and writing the code Once you have the necessary context, we recommend the steps to implement your own server and validator: -1. Clone our example DAML Ledger (which is backed by an in-memory key-value store) +1. Clone our example Daml Ledger (which is backed by an in-memory key-value store) from the `digital-asset/daml-on-x-example `__. 1. Read the example code jointly with @@ -141,12 +141,12 @@ to implement your own server and validator: the `Library infrastructure overview`_ below. 1. Combine all the knowledge gained to decide on the architecture for your - DAML on `X` ledger. + Daml on `X` ledger. 1. Implement your architecture; and let the world know about it by creating a PR against the `digital-asset/daml `__ repository - to add your ledger to the list of :ref:`DAML Ledgers built or in development `. + to add your ledger to the list of :ref:`Daml Ledgers built or in development `. If you need help, then feel free to use the feedback form on this documentation page or GitHub issues on the `digital-asset/daml `__ repository to @@ -155,11 +155,11 @@ get into contact with us. Architectural overview ====================== -This section explains the architecture of a DAML ledger backed by a specific +This section explains the architecture of a Daml ledger backed by a specific ledger `X`. The backing ledger can be a proper distributed ledger or also just a database. -The goal of a DAML ledger implementation is to allow multiple DAML applications, +The goal of a Daml ledger implementation is to allow multiple Daml applications, which are potentially run by different entities, to execute multi-party workflows using the ledger `X`. @@ -175,19 +175,19 @@ documentation, we call these nodes `participant nodes`. In the diagram: -- The boxes labeled `daml-on--server` denote the DAML Ledger API - servers, which implement the DAML Ledger API on top of the services provided +- The boxes labeled `daml-on--server` denote the Daml Ledger API + servers, which implement the Daml Ledger API on top of the services provided by the `X` participant nodes. -- The boxes labeled `-daml-validator` denote `X`-specific DAML transaction +- The boxes labeled `-daml-validator` denote `X`-specific Daml transaction validation services. In a distributed ledger they provide the ability for - nodes to :doc:`validate DAML transactions ` + nodes to :doc:`validate Daml transactions ` at the appropriate stage in the `X` ledger's transaction commit process. Whether they are needed, by what nodes they are used, and whether they are run in-process or out-of-process depends on the `X` ledger's architecture. Above we depict a common case where the participant nodes jointly maintain the - ledger's integrity and therefore need to validate DAML transactions. + ledger's integrity and therefore need to validate Daml transactions. Message flow @@ -203,17 +203,17 @@ Message flow Resources we provide ==================== -- Scala libraries for validating DAML transactions and serving the +- Scala libraries for validating Daml transactions and serving the Ledger API given implementations of two specific interfaces. See the `Library infrastructure overview`_ for an overview of these libraries. -- A complete example of a DAML Ledger backed by an in-memory key-value store, +- A complete example of a Daml Ledger backed by an in-memory key-value store, in the `digital-asset/daml-on-x-example `__ GitHub repository. It builds on our Scala libraries and demonstrates how they - can be assembled to serve the Ledger API and validate DAML transactions. + can be assembled to serve the Ledger API and validate Daml transactions. For ledgers where data is shared between all participant nodes, we recommend using this example as a starting point for implementing your @@ -222,14 +222,14 @@ Resources we provide For ledgers with stronger privacy models, this example can serve as an inspiration. You will need to dive deeper into how transactions are represented and how to communicate them to - implement :doc:`DAML's privacy model ` + implement :doc:`Daml's privacy model ` at the ledger level instead of just at the Ledger API level. Library infrastructure overview ------------------------------- To help you implement your server and validator, we provide the following -four Scala libraries as part of DAML Connect. Changes +four Scala libraries as part of Daml Connect. Changes to them are explained as part of the :ref:`release-notes`. As explained in :ref:`integration-kit_writing_code`, @@ -238,7 +238,7 @@ this section is best read jointly with the code in ``participant-state.jar`` (`source code `__) Contains interfaces abstracting over the state of - a participant node relevant for a DAML Ledger API server. + a participant node relevant for a Daml Ledger API server. These are the interfaces whose implementation is specific to a particular `X` ledger. These @@ -251,11 +251,11 @@ this section is best read jointly with the code in `package.scala `__ ``ledger-api-server.jar`` (`source code for API server `__, `source code for indexer `__) - Contains code that implements a DAML Ledger API server and the SQL-backed indexer + Contains code that implements a Daml Ledger API server and the SQL-backed indexer given implementations of the interfaces in ``participant-state.jar``. ``daml-engine.jar`` (`source code `__) - Contains code for serializing and deserializing DAML + Contains code for serializing and deserializing Daml transactions and for validating them. An `-daml-validator` is typically @@ -266,7 +266,7 @@ this section is best read jointly with the code in to its participant node. This diagram shows how the classes and interfaces provided by these -libraries are typically combined to instantiate a DAML Ledger API server +libraries are typically combined to instantiate a Daml Ledger API server backed by an `X` ledger: *TODO: Update this diagram to mention ledger server classes above instead of deprecated daml-on-x-server* @@ -296,11 +296,11 @@ of their qualified names where unambiguous): ``.LedgerApiServer`` is the class whose main method or constructor creates the contained instances and wires them up to provide the Ledger API - backed by the `` services``. You need to implement this for your DAML on + backed by the `` services``. You need to implement this for your Daml on `X` ledger. ``WriteService`` (`source code `_) is an interface abstracting over the mechanism to submit - DAML transactions to the underlying `X` ledger via a participant node. + Daml transactions to the underlying `X` ledger via a participant node. ``ReadService`` (`source code `__) is an interface abstracting over the ability to subscribe to changes of the `X` ledger visible to a particular participant node. @@ -312,7 +312,7 @@ of their qualified names where unambiguous): ``.Backend`` is a class implementing the ``ReadService`` and the ``WriteService`` on top of the `` services``. You need to implement this - for your DAML on `X` ledger. + for your Daml on `X` ledger. ``StandaloneIndexerServer`` (`source code `__) is a standalone service that subscribe to ledger changes using ``ReadService`` and inserts the data into a SQL backend ("index") for the purpose of serving the data over the Ledger API. @@ -322,7 +322,7 @@ of their qualified names where unambiguous): .. _integration-kit_deploying: -Deploying a DAML Ledger +Deploying a Daml Ledger *********************** **TODO (BETA):** @@ -332,7 +332,7 @@ Deploying a DAML Ledger (`GitHub issue `__) - explain option of using a persistent SQL-backed participant state index (`GitHub issue `__). -- explain how testing of DAML applications (ledger reset, time manipulation, +- explain how testing of Daml applications (ledger reset, time manipulation, scripted package upload) can be supported by a uniform admin interface (`GitHub issue `__). @@ -363,10 +363,10 @@ For reference, you can have a look at how authorization is implemented in the sa .. _integration-kit_testing: -Testing a DAML Ledger +Testing a Daml Ledger ********************* -You can test your DAML ledger implementation using +You can test your Daml ledger implementation using :doc:`Ledger API Test Tool `, which will assess correctness of implementation of the :doc:`Ledger API `. For example, it will show you if @@ -377,7 +377,7 @@ Assuming that your Ledger API endpoint is accessible at ``localhost:6865``, you #. Download the Ledger API Test Tool from `Maven `_ and save it as ``ledger-api-test-tool.jar`` in your current directory. -#. Obtain the DAML archives required to run the tests: +#. Obtain the Daml archives required to run the tests: ``java -jar ledger-api-test-tool.jar --extract`` @@ -391,7 +391,7 @@ See more in :doc:`Ledger API Test Tool `. .. _integration-kit_benchmarking: -Benchmarking a DAML Ledger +Benchmarking a Daml Ledger ************************** **TODO (BETA):** diff --git a/docs/source/daml-repl/index.rst b/docs/source/daml-repl/index.rst index 354b2a8e87..7e21e0392f 100644 --- a/docs/source/daml-repl/index.rst +++ b/docs/source/daml-repl/index.rst @@ -1,10 +1,10 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML REPL +Daml REPL ########### -The DAML REPL allows you to use the :doc:`/daml-script/index` API +The Daml REPL allows you to use the :doc:`/daml-script/index` API interactively. This is useful for debugging and for interactively inspecting and manipulating a ledger. @@ -62,7 +62,7 @@ two forms: 2. A pure expression ``expr`` of type ``a`` for some type ``a`` where ``a`` is an instance of ``Show``. This will evaluate ``expr`` and print the result. If you are only interest in pure expressions you - can also use DAML REPL + can also use Daml REPL :ref:`without connecting to a ledger `. 3. A binding of the form ``pat <- expr`` where ``pat`` is pattern, e.g., @@ -76,7 +76,7 @@ two forms: and ``y`` is a pure expression or ``let f x = y`` to define a function. The bound variables can be used on subsequent lines. -5. Next to DAML code the REPL also understands REPL commands which are prefixed +5. Next to Daml code the REPL also understands REPL commands which are prefixed by ``:``. Enter ``:help`` to see a list of supported REPL commands. First create two parties: A party with the display name ``"Alice"`` @@ -129,8 +129,8 @@ What is in scope at the prompt? =============================== In the prompt, all modules from DALFs specified in ``--import`` are -imported automatically. In addition to that, the ``DAML.Script`` -module is also imported and gives you access to the DAML Script API. +imported automatically. In addition to that, the ``Daml.Script`` +module is also imported and gives you access to the Daml Script API. You can use the commands ``:module + ModA ModB …`` to import additional modules and ``:module - ModA ModB …`` to remove previously added imports. Modules can @@ -144,13 +144,13 @@ 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 to test how some function behaves you can omit the ``--ledger-host`` -and ``-ledger-port`` parameters. DAML REPL will work as usual but any -attempts to call DAML Script APIs that interact with the ledger, e.g., +and ``-ledger-port`` parameters. Daml REPL will work as usual but any +attempts to call Daml Script APIs that interact with the ledger, e.g., ``submit`` will result in the following error: .. code-block:: none @@ -173,10 +173,10 @@ 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 +Using the ``:json`` command you can encode serializable Daml expressions as JSON. For example using the definitions and imports from above: .. code-block:: none diff --git a/docs/source/daml-script/index.rst b/docs/source/daml-script/index.rst index a9e01e314c..d9bd05a7de 100644 --- a/docs/source/daml-script/index.rst +++ b/docs/source/daml-script/index.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Script +Daml Script ########### .. toctree:: @@ -9,21 +9,21 @@ DAML Script api/index -DAML scenarios provide a simple way for testing DAML models -and getting quick feedback in DAML studio. However, scenarios are run +Daml scenarios provide a simple way for testing Daml models +and getting quick feedback in Daml studio. However, scenarios are run in a special process and do not interact with an actual ledger. This means that you cannot use scenarios to test other ledger clients, -e.g., your UI or :doc:`DAML triggers `. +e.g., your UI or :doc:`Daml triggers `. -DAML Script addresses this problem by providing you with an API with -the simplicity of DAML scenarios and all the benefits such as being -able to reuse your DAML types and logic while running against an +Daml Script addresses this problem by providing you with an API with +the simplicity of Daml scenarios and all the benefits such as being +able to reuse your Daml types and logic while running against an actual ledger in addition to allowing you to experiment in -:ref:`DAML Studio `. This means that you can use it for +:ref:`Daml Studio `. This means that you can use it for application scripting, to test automation logic and also for :ref:`ledger initialization `. -You can also use DAML Script interactively using :doc:`/daml-repl/index`. +You can also use Daml Script interactively using :doc:`/daml-repl/index`. Usage ===== @@ -51,8 +51,8 @@ Second, we have a template called ``CoinProposal``: single ``Accept`` choice which, when exercised by the controller will create the corresponding ``Coin``. -Having defined the templates, we can now move on to write DAML scripts -that operate on these templates. To get access to the API used to implement DAML scripts, you need to add the ``daml-script`` +Having defined the templates, we can now move on to write Daml scripts +that operate on these templates. To get access to the API used to implement Daml scripts, you need to add the ``daml-script`` library to the ``dependencies`` field in ``daml.yaml``. .. literalinclude:: ./template-root/daml.yaml.template @@ -79,7 +79,7 @@ script so that we can easily swap them out. Let us now write a function to initialize the ledger with 3 ``CoinProposal`` contracts and accept 2 of them. This function takes the ``LedgerParties`` as an argument and return something of type ``Script -()`` which is DAML script’s equivalent of ``Scenario ()``. +()`` which is Daml script’s equivalent of ``Scenario ()``. .. literalinclude:: ./template-root/src/ScriptExample.daml :language: daml @@ -214,15 +214,15 @@ If you open Navigator, you can now see the contracts that have been created. While we will not use it here, there is also an ``--output-file`` option that you can use to write the result of a script to a file -using the DAML-LF JSON encoding. This is particularly useful if you need to consume +using the Daml-LF JSON encoding. This is particularly useful if you need to consume the result from another program. .. _script-ledger-initialization: -Using DAML Script for Ledger Initialization +Using Daml Script for Ledger Initialization =========================================== -You can use DAML script to initialize a ledger on startup. To do so, +You can use Daml script to initialize a ledger on startup. To do so, specify an ``init-script: ScriptExample:initializeFixed`` field in your ``daml.yaml``. This will automatically be picked up by ``daml start`` and used to initialize sandbox. Since it is often useful to @@ -242,7 +242,7 @@ Migrating 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: +translated to Daml script but there are a few things to keep in mind: #. You need to add ``daml-script`` to the list of dependencies in your ``daml.yaml``. @@ -253,7 +253,7 @@ translated to DAML script but there are a few things to keep in mind: #. Instead of specifying a ``scenario`` field in your ``daml.yaml``, you need to specify an ``init-script`` field. The initialization script is specified via ``Module:identifier`` for both fields. -#. In DAML script, ``submit`` and ``submitMustFail`` are limited to +#. In Daml script, ``submit`` and ``submitMustFail`` are limited to the functionality provided by the ledger API: A list of independent commands consisting of ``createCmd``, ``exerciseCmd``, ``createAndExerciseCmd`` and ``exerciseByKeyCmd``. There are two @@ -273,7 +273,7 @@ translated to DAML script but there are a few things to keep in mind: with the caveat that they do not run within the same transaction. Other types of ``Update`` statements can be moved to a choice that you call via ``createAndExerciseCmd``. -#. Instead of Scenario’s ``getParty``, DAML Script provides you with +#. Instead of Scenario’s ``getParty``, Daml Script provides you with ``allocateParty`` and ``allocatePartyWithHint``. There are a few important differences: @@ -285,19 +285,19 @@ translated to DAML script but there are a few things to keep in mind: #. If you want to allocate a party with a specific party id, you can use ``allocatePartyWithHint x (PartyIdHint x)`` as a replacement for `getParty x`. Note that - while this is supported in DAML Studio and DAML for PostgreSQL, other + while this is supported in Daml Studio and Daml for PostgreSQL, other ledgers can behave differently and ignore the party id hint or interpret it another way. Try to not rely on any specific party id. -#. Instead of ``pass`` and ``passToDate``, DAML Script provides +#. Instead of ``pass`` and ``passToDate``, Daml Script provides ``passTime`` and ``setTime``. .. _daml-script-distributed: -Using DAML Script in Distributed Topologies +Using Daml Script in Distributed Topologies =========================================== -So far, we have run DAML script against a single participant node. It +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 are hosted on different participant nodes. To do so, pass the ``--participant-config participants.json`` file to ``daml script`` @@ -320,10 +320,10 @@ argument. .. _daml-script-auth: -Running DAML Script against Ledgers with Authorization +Running Daml Script against Ledgers with Authorization ====================================================== -To run DAML Script against a ledger that verifies 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: 1. Specify a single access token via ``--access-token-file @@ -333,7 +333,7 @@ you need to specify an access token. There are two ways of doing that: single-party tokens you can use the ``access_token`` field in the participant config specified via ``--participant-config``. The section on - :ref:`using DAML Script in distributed topologies ` + :ref:`using Daml Script in distributed topologies ` contains an example. Note that you can specify the same participant twice if you want different auth tokens. @@ -344,17 +344,17 @@ have a token specified in the config. .. _daml-script-json-api: -Running DAML Script against the HTTP JSON API +Running Daml Script against the HTTP JSON API ============================================= In some cases, you only have access to the :doc:`HTTP JSON API ` but not to the gRPC of a ledger, e.g., on -`project:DABL `_. For this usecase, DAML +`project:DABL `_. For this usecase, Daml script can be run against the JSON API. Note that if you do have -access to the gRPC Ledger API, running DAML script against the JSON API does +access to the gRPC Ledger API, running Daml script against the JSON API does not have any advantages. -To run DAML script against the JSON API you have to pass the ``--json-api`` parameter to ``daml script``. There are a few differences and limitations compared to running DAML Script against the gRPC Ledger API: +To run Daml script against the JSON API you have to pass the ``--json-api`` parameter to ``daml script``. There are a few differences and limitations compared to running Daml Script against the gRPC Ledger API: #. When running against the JSON API, the ``--host`` argument has to contain an ``http://`` or ``https://`` prefix, e.g., ``daml @@ -371,7 +371,7 @@ To run DAML script against the JSON API you have to pass the ``--json-api`` para that means ``actAs`` and ``readAs`` must match exactly what you specified whereas for queries the union of ``actAs`` and ``readAs`` must match the parties specified in the query. -#. If you use multiple parties within your DAML Script, you need to +#. If you use multiple parties within your Daml Script, you need to specify one token per party or every submission and query must specify all parties of the multi-party token. #. ``getTime`` will always return the Unix epoch in static time mode diff --git a/docs/source/daml/code-snippets-dev/Structure.daml b/docs/source/daml/code-snippets-dev/Structure.daml index 08b0c750e7..cb49a133b9 100644 --- a/docs/source/daml/code-snippets-dev/Structure.daml +++ b/docs/source/daml/code-snippets-dev/Structure.daml @@ -24,7 +24,7 @@ template NameOfTemplate () -- replace () with the actual return type with party : Party -- parameters here - observer party -- optional specification of choice observers (currently only available in DAML-LF 1.11) + observer party -- optional specification of choice observers (currently only available in Daml-LF 1.11) controller exampleParty do return () -- replace this line with the choice body diff --git a/docs/source/daml/daml-studio.rst b/docs/source/daml/daml-studio.rst index 2ce658598f..316642a5bb 100644 --- a/docs/source/daml/daml-studio.rst +++ b/docs/source/daml/daml-studio.rst @@ -1,27 +1,27 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Studio +Daml Studio ########### -DAML Studio is an integrated development environment (IDE) for DAML. It is an extension on top of `Visual Studio Code `__ (VS Code), a cross-platform, open-source editor providing a `rich code editing experience `__. +Daml Studio is an integrated development environment (IDE) for Daml. It is an extension on top of `Visual Studio Code `__ (VS Code), a cross-platform, open-source editor providing a `rich code editing experience `__. Installing ********** -DAML Studio is included in :doc:`the DAML Connect SDK `. +Daml Studio is included in :doc:`the Daml Connect SDK `. -Creating your first DAML file +Creating your first Daml file ***************************** -1. Start DAML Studio by running ``daml studio`` in the current project. +1. Start Daml Studio by running ``daml studio`` in the current project. - This command starts Visual Studio Code and (if needs be) installs the DAML Studio extension, or upgrades it to the latest version. + This command starts Visual Studio Code and (if needs be) installs the Daml Studio extension, or upgrades it to the latest version. -2. Make sure the DAML Studio extension is installed: +2. Make sure the Daml Studio extension is installed: 1. Click on the Extensions icon at the bottom of the VS Code sidebar. - 2. Click on the DAML Studio extension that should be listed on the pane. + 2. Click on the Daml Studio extension that should be listed on the pane. .. image:: daml-studio/images/daml_studio_extension_view.png @@ -45,19 +45,19 @@ Your screen should now look like the image below. We recommend reviewing the `Visual Studio Code documentation `_ to learn more about how to use it. -To learn more about DAML, see :doc:`reference/index`. +To learn more about Daml, see :doc:`reference/index`. Supported features ****************** -Visual Studio Code provides many helpful features for editing DAML files and we recommend reviewing +Visual Studio Code provides many helpful features for editing Daml files and we recommend reviewing `Visual Studio Code Basics `__ and `Visual Studio Code Keyboard Shortcuts for OS X `_. -The DAML Studio extension for Visual Studio Code provides the following DAML-specific features: +The Daml Studio extension for Visual Studio Code provides the following Daml-specific features: 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, +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, lambda arguments, variables, and so on. ============================ =============== @@ -99,14 +99,14 @@ You can `hover`_ over most symbols in the code to display additional information .. _scenario-script-results: -Scenario and DAML Script results +Scenario and Daml Script results ================================ Top-level declarations of type ``Scenario`` or ``Script`` are decorated with a ``Scenario results`` or a ``Script results`` code lens. You can click on the code lens to inspect the execution transaction graph and the active contracts. The functionality -for inspecting the results is identical for DAML Scripts +for inspecting the results is identical for Daml Scripts and scenarios. For the scenario from the :download:`Iou` @@ -132,7 +132,7 @@ which displays why the contract is visible to each party, based on four categori because they witnessed an exercise that resulted in a ``fetch`` of this contract. For details on the meaning of those four categories, refer to the -:ref:`DAML Ledger Model`. +:ref:`Daml Ledger Model`. For the example above, the resulting table looks as follows. You can see the archived ``Bank`` contract and the active ``Bank`` contract whose creation ``Alice`` has witnessed by virtue of being an actor on the ``exercise`` that @@ -176,14 +176,14 @@ 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 -source file. By default, hitting ``^-Space`` after typing a DAML keyword +You can automatically complete a number of "snippets" when editing a Daml +source file. By default, hitting ``^-Space`` after typing a Daml keyword displays available snippets that you can insert. -To define your own workflow around DAML snippets, adjust +To define your own workflow around Daml snippets, adjust your user settings in Visual Studio Code to include the following options: .. code-block:: json @@ -207,8 +207,8 @@ snippet file. Common scenario 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. +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. When a runtime error occurs in a scenario execution, the scenario result view shows the error together with the following additional information, if available: @@ -367,10 +367,10 @@ To fix this issue the party 'Bob' should be made a controlling party in one of t Working 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 +Often a Daml project consists of multiple packages, e.g., one +containing your templates and one containing a Daml trigger so that you can keep the templates stable while modifying the trigger. It is -possible to work on multiple packages in a single session of DAML +possible to work on multiple packages in a single session of Daml studio but you have to keep some things in mind. You can see the directory structure of a simple multi-package project consisting of two packages ``pkga`` and ``pkgb`` below: @@ -388,8 +388,8 @@ two packages ``pkga`` and ``pkgb`` below: │   └── B.daml └── daml.yaml -``pkga`` and ``pkgb`` are regular DAML projects with a ``daml.yaml`` -and a DAML module. In addition to the ``daml.yaml`` files for the +``pkga`` and ``pkgb`` are regular Daml projects with a ``daml.yaml`` +and a Daml module. In addition to the ``daml.yaml`` files for the respective packages, you also need to add a ``daml.yaml`` to the root of your project. This file only needs to specify the SDK version. Replace ``X.Y.Z`` by the SDK version you specified in the @@ -399,11 +399,11 @@ version. Replace ``X.Y.Z`` by the SDK version you specified in the sdk-version: X.Y.Z -You can then open DAML Studio once in the root of your project and +You can then open Daml Studio once in the root of your project and work on files in both packages. Note that if ``pkgb`` refers to ``pkga.dar`` in its ``dependencies`` field, changes will not be picked -up automatically. This is always the case even if you open DAML Studio +up automatically. This is always the case even if you open Daml Studio in ``pkgb``. However, for multi-package projects there is an additional caveat: You have to both rebuild ``pkga.dar`` using ``daml build`` and then build ``pkgb`` using ``daml build`` before restarting -DAML Studio. +Daml Studio. diff --git a/docs/source/daml/intro/0_Intro.rst b/docs/source/daml/intro/0_Intro.rst index c67764f2f5..1235214298 100644 --- a/docs/source/daml/intro/0_Intro.rst +++ b/docs/source/daml/intro/0_Intro.rst @@ -1,18 +1,18 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -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`. +Daml is a smart contract language designed to build composable applications on an abstract :ref:`da-ledgers`. -In this introduction, you will learn about the structure of a DAML Ledger, and how to write DAML applications that run on any DAML Ledger implementation, by building an asset-holding and -trading application. You will gain an overview over most important language features, how they relate to the :ref:`da-ledgers` and how to use DAML Connect's developer tools to write, test, compile, package and ship your application. +In this introduction, you will learn about the structure of a Daml Ledger, and how to write Daml applications that run on any Daml Ledger implementation, by building an asset-holding and -trading application. You will gain an overview over most important language features, how they relate to the :ref:`da-ledgers` and how to use Daml Connect's developer tools to write, test, compile, package and ship your application. -This introduction is structured such that each section presents a new self-contained application with more functionality than that from the previous section. You can find the DAML code for each section `here `_ or download them using the DAML assistant. For example, to load the sources for section 1 into a folder called ``1_Token``, run ``daml new 1_Token --template daml-intro-1``. +This introduction is structured such that each section presents a new self-contained application with more functionality than that from the previous section. You can find the Daml code for each section `here `_ or download them using the Daml assistant. For example, to load the sources for section 1 into a folder called ``1_Token``, run ``daml new 1_Token --template daml-intro-1``. Prerequisites: -- You have installed the :doc:`DAML Connect SDK ` +- You have installed the :doc:`Daml Connect SDK ` Next: :doc:`1_Token`. diff --git a/docs/source/daml/intro/10_StdLib.rst b/docs/source/daml/intro/10_StdLib.rst index 430b914b1b..80d768a1b8 100644 --- a/docs/source/daml/intro/10_StdLib.rst +++ b/docs/source/daml/intro/10_StdLib.rst @@ -1,10 +1,10 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -10 Intro to the DAML Standard Library +10 Intro to the Daml Standard Library ===================================== -In chapters :doc:`3_Data` and :doc:`9_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: +In chapters :doc:`3_Data` and :doc:`9_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: - The Prelude - Important types from the Standard Library, and associated functions and typeclasses @@ -21,7 +21,7 @@ To go in depth on some of these topics, the literature referenced in :ref:`haske 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 `. 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. +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 `. 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 -------------------------------- @@ -67,7 +67,7 @@ Tuples, like lists have some syntactic magic. Both the types as well as the cons Optional ........ -The ``Optional`` type represents a value that may be missing. It's the closest thing DAML has to a "nullable" value. ``Optional`` has two constructors: ``Some``, which takes a value, and ``None``, which doesn't take a value. In many languages one would write code like this: +The ``Optional`` type represents a value that may be missing. It's the closest thing Daml has to a "nullable" value. ``Optional`` has two constructors: ``Some``, which takes a value, and ``None``, which doesn't take a value. In many languages one would write code like this: .. code-block:: JavaScript @@ -79,7 +79,7 @@ The ``Optional`` type represents a value that may be missing. It's the closest t // Do something else } -In DAML the same thing would be expressed as +In Daml the same thing would be expressed as .. literalinclude:: daml/daml-intro-10/daml/Main.daml :language: daml @@ -139,21 +139,21 @@ Show Functor ....... -:ref:`Functors ` are the closest thing to "containers" that DAML has. Whenever you see a type with a single type parameter, you are probably looking at a ``Functor``: ``[a]``, ``Optional a``, ``Either Text a``, ``Update a``. Functors are things that can be mapped over and as such, the key function of ``Functor`` is ``fmap``, which does generically what the ``map`` function does for lists. +:ref:`Functors ` are the closest thing to "containers" that Daml has. Whenever you see a type with a single type parameter, you are probably looking at a ``Functor``: ``[a]``, ``Optional a``, ``Either Text a``, ``Update a``. Functors are things that can be mapped over and as such, the key function of ``Functor`` is ``fmap``, which does generically what the ``map`` function does for lists. Other classic examples of Functors are Sets, Maps, Trees, etc. Applicative Functor ................... -:ref:`Applicative Functors ` are a bit like Actions, which you met in :doc:`5_Restrictions`, except that you can't use the result of one action as the input to another action. The only important Applicative Functor that isn't an action in DAML is the ``Commands`` type submitted in a ``submit`` block in DAML Script. That's why in order to use ``do`` notation in DAML Script, you have to enable the ``ApplicativeDo`` language extension. +:ref:`Applicative Functors ` are a bit like Actions, which you met in :doc:`5_Restrictions`, except that you can't use the result of one action as the input to another action. The only important Applicative Functor that isn't an action in Daml is the ``Commands`` type submitted in a ``submit`` block in Daml Script. That's why in order to use ``do`` notation in Daml Script, you have to enable the ``ApplicativeDo`` language extension. Actions ....... :ref:`Actions ` were already covered in :doc:`5_Restrictions`. One way to think of them is as "recipes" for a value, which need to be "executed to get at that value. Actions are always Functors (and Applicative Functors). The intuition for that is simply that ``fmap f x`` is the recipe in ``x`` with the extra instruction to apply the pure function ``f`` to the result. -The really important Actions in DAML are ``Update`` and ``Script``, but there are many others, like ``[]``, ``Optional``, and ``Either a``. +The really important Actions in Daml are ``Update`` and ``Script``, but there are many others, like ``[]``, ``Optional``, and ``Either a``. Semigroups and Monoids ...................... @@ -190,7 +190,7 @@ Searching 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 `__ search engine, which offers search both by name and by signature. It's fully integrated into the search bar on `https://docs.daml.com/ `__, but for those wanting a pure Standard Library search, it's also available on ``__. +Daml has it's own version of the `Hoogle `__ search engine, which offers search both by name and by signature. It's fully integrated into the search bar on `https://docs.daml.com/ `__, but for those wanting a pure Standard Library search, it's also available on ``__. Searching for functions by Name ............................... @@ -240,5 +240,5 @@ Let's try another search. Suppose you didn't want the first element, but the one 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:`11_Testing`, and about the operational semantics of some keywords and common associated failures. +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:`11_Testing`, and about the operational semantics of some keywords and common associated failures. diff --git a/docs/source/daml/intro/11_Testing.rst b/docs/source/daml/intro/11_Testing.rst index 748da1798d..b3a91b5a05 100644 --- a/docs/source/daml/intro/11_Testing.rst +++ b/docs/source/daml/intro/11_Testing.rst @@ -1,45 +1,45 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -11 Testing DAML Contracts +11 Testing 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: +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: -- DAML Test tooling - Script, REPL, and Navigator +- Daml Test tooling - Script, REPL, and Navigator - The ``trace`` and ``debug`` functions - Contention -Note that this section only covers testing your DAML contracts. For more holistic application testing, please refer to :doc:`/getting-started/testing`. +Note that this section only covers testing your Daml contracts. For more holistic application testing, please refer to :doc:`/getting-started/testing`. If you no longer have your projects set up, please follow the setup instructions in :doc:`8_Dependencies` to get hold of the code for this chapter. There is no code specific to this chapter. -DAML Test Tooling +Daml Test Tooling ----------------- -There are three primary tools available in the SDK to test and interact with DAML contracts. It is highly recommended to explore the respective docs. The chapter 8 model lends itself well to being tested using these tools. +There are three primary tools available in the SDK to test and interact with Daml contracts. It is highly recommended to explore the respective docs. The chapter 8 model lends itself well to being tested using these tools. -:doc:`DAML Script ` +:doc:`Daml Script ` - :doc:`DAML Script ` should be familiar by now. It's a way to script commands and queries from multiple parties against a DAML Ledger. Unless you've browsed other sections of the documentation already, you have probably used it mostly in the IDE. However, DAML Script can do much more than that. It has four different modes of operation: + :doc:`Daml Script ` should be familiar by now. It's a way to script commands and queries from multiple parties against a Daml Ledger. Unless you've browsed other sections of the documentation already, you have probably used it mostly in the IDE. However, Daml Script can do much more than that. It has four different modes of operation: 1. Run on a special Script Service in the IDE, providing the Script Views. 2. Run the Script Service via the CLI, which is useful for quick regression testing. 3. Start a Sandbox and run against that for regression testing against an actual Ledger API. 4. Run against any other already running Ledger. -:doc:`DAML Navigator ` +:doc:`Daml Navigator ` - DAML Navigator is a UI that runs against a Ledger API and allows interaction with contracts. + Daml Navigator is a UI that runs against a Ledger API and allows interaction with contracts. -:doc:`DAML REPL ` +:doc:`Daml REPL ` - If you want to do things interactively, DAML REPL is the tool to use. The best way to think of DAML REPL is as an interactive version of DAML Script, but it doubles up as a language REPL (Read-Evaluate-Print Loop), allowing you to evaluate pure expressions and inspect the results. + If you want to do things interactively, Daml REPL is the tool to use. The best way to think of Daml REPL is as an interactive version of Daml Script, but it doubles up as a language REPL (Read-Evaluate-Print Loop), allowing you to evaluate pure expressions and inspect the results. Debug, Trace, and Stacktraces ----------------------------- -The above demonstrates nicely how to test the happy path, but what if a function doesn't behave as you expected? DAML has two functions that allow you to do fine-grained printf debugging: ``debug`` and ``trace``. Both allow you to print something to StdOut if the code is reached. The difference between ``debug`` and ``trace`` is similar to the relationship between ``abort`` and ``error``: +The above demonstrates nicely how to test the happy path, but what if a function doesn't behave as you expected? Daml has two functions that allow you to do fine-grained printf debugging: ``debug`` and ``trace``. Both allow you to print something to StdOut if the code is reached. The difference between ``debug`` and ``trace`` is similar to the relationship between ``abort`` and ``error``: - ``debug : Text -> m ()`` maps a text to an Action that has the side-effect of printing to StdOut. - ``trace : Text -> a -> a`` prints to StdOut when the expression is evaluated. @@ -57,14 +57,14 @@ The above demonstrates nicely how to test the happy path, but what if a function If in doubt, use ``debug``. It's the easier of the two to interpret the results of. -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. +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 ---------------------------- -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. +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. -Contention refers to conflicts over access to contracts. DAML guarantees that there can only be one consuming choice exercised per contract so what if two parties simultaneously submit an exercise command on the same contract? Only one can succeed. Contention can also occur due to incomplete or stale knowledge. Maybe a contract was archived a little while ago, but due to latencies, a client hasn't found out yet, or maybe due to the privacy model, they never will. What all these cases have in common is that someone has incomplete knowledge of the state the ledger will be in at the time a transaction will be processed and/or committed. +Contention refers to conflicts over access to contracts. Daml guarantees that there can only be one consuming choice exercised per contract so what if two parties simultaneously submit an exercise command on the same contract? Only one can succeed. Contention can also occur due to incomplete or stale knowledge. Maybe a contract was archived a little while ago, but due to latencies, a client hasn't found out yet, or maybe due to the privacy model, they never will. What all these cases have in common is that someone has incomplete knowledge of the state the ledger will be in at the time a transaction will be processed and/or committed. If we look back at :ref:`execution_model` we'll see there are three places where ledger state is consumed: @@ -72,7 +72,7 @@ If we look back at :ref:`execution_model` we'll see there are three places where 2. During interpretation, ledger state is used to look up active contracts. 3. During commit, ledger state is again used to look up contracts and validate the transaction by reinterpreting it. -Collisions can occur both between 1 and 2 and between 2 and 3. Only during the commit phase is the complete relevant ledger state at the time of the transaction known, which means the ledger state at commit time is king. As a DAML contract developer, you need to understand the different causes of contention, be able to diagnose the root cause if errors of this type occur, and be able to avoid collisions by designing contracts appropriately. +Collisions can occur both between 1 and 2 and between 2 and 3. Only during the commit phase is the complete relevant ledger state at the time of the transaction known, which means the ledger state at commit time is king. As a Daml contract developer, you need to understand the different causes of contention, be able to diagnose the root cause if errors of this type occur, and be able to avoid collisions by designing contracts appropriately. Common Errors ~~~~~~~~~~~~~ @@ -90,7 +90,7 @@ ContractId Not Found During Interpretation .. code-block:: none - Command interpretation error in LF-DAMLe: dependency error: couldn't find contract ContractId(004481eb78464f1ed3291b06504d5619db4f110df71cb5764717e1c4d3aa096b9f). + Command interpretation error in LF-Damle: dependency error: couldn't find contract ContractId(004481eb78464f1ed3291b06504d5619db4f110df71cb5764717e1c4d3aa096b9f). ContractId Not Found During Validation ...................................... @@ -104,7 +104,7 @@ fetchByKey Error during Interpretation .. code-block:: none - Command interpretation error in LF-DAMLe: dependency error: couldn't find key com.daml.lf.transaction.GlobalKey@11f4913d. + Command interpretation error in LF-Damle: dependency error: couldn't find key com.daml.lf.transaction.GlobalKey@11f4913d. fetchByKey Dispute During Validation .................................... @@ -134,14 +134,14 @@ Here are a few scenarios and measures you can take to reduce this type of collis Contract keys can seem like a way out, but they are not. Contract keys are resolved to Contract IDs during the interpretation phase on the participant node. So it reduces latencies slightly by moving resolution from the client layer to the participant layer, but it doesn't remove the issue. Going back to the auction example above, if Alice sent a command ``exerciseByKey @Auction auctionKey Bid with amount = 100``, this would be resolved to an ``exercise cid Bid with amount = 100`` during interpretation, where ``cid`` is the participant's best guess what ContractId the key refers to. 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. +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 ~~~~~~~~~~~~~~~~~~~~~~~~~~~ -The :doc:`DAML Ledger Model ` 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``? +The :doc:`Daml Ledger Model ` 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``? -To illustrate the problem, let's assume there is a template ``T`` with a contract key, and Alice has witnessed two ``Create`` nodes of a contract of type ``T`` with key ``k``, but no corresponding archive nodes. Alice may not be able to order these two nodes causally in the sense of "one create came before the other". See :doc:`/concepts/local-ledger` for an in-depth treatment of causality on DAML Ledgers. +To illustrate the problem, let's assume there is a template ``T`` with a contract key, and Alice has witnessed two ``Create`` nodes of a contract of type ``T`` with key ``k``, but no corresponding archive nodes. Alice may not be able to order these two nodes causally in the sense of "one create came before the other". See :doc:`/concepts/local-ledger` for an in-depth treatment of causality on Daml Ledgers. So what should happen now if Alice's participant encounters a ``fetchByKey @T k`` or ``lookupByKey @T k`` during interpretation? What if it encounters a ``fetch`` node? These decisions are part of the operational semantics, and the decision of what should happen is based on the consideration that the chance of a participant submitting an invalid transaction should be minimized. @@ -156,9 +156,9 @@ Let's illustrate how collisions and operational semantics and interleave: 3. Bob submits an ``exerciseByKey @T k Archive``. 4. Depending on which of the transactions from 2 and 3 gets sequenced first, either just 3, or both 2 and 3 get committed. If 3 is committed before 2, 2 becomes valid while in transit. -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. +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 ------- -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 `__. Or put your skills to good use by developing a DAML application. There are plenty of examples to inspire you on the `Examples `_ page. +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 `__. Or put your skills to good use by developing a Daml application. There are plenty of examples to inspire you on the `Examples `_ page. diff --git a/docs/source/daml/intro/1_Token.rst b/docs/source/daml/intro/1_Token.rst index a16a506708..6bbb380ca7 100644 --- a/docs/source/daml/intro/1_Token.rst +++ b/docs/source/daml/intro/1_Token.rst @@ -4,10 +4,10 @@ 1 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: +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: - Transactions -- DAML Modules and Files +- Daml Modules and Files - Templates - Contracts - Signatories @@ -16,10 +16,10 @@ 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 1_Token --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. +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. *Transaction* is a concept we'll cover in more detail through this introduction. The most basic examples are the creation and archival of a *contract*. @@ -29,18 +29,18 @@ A contract is *active* from the point where there is a committed transaction tha Individual contracts are *immutable* in the sense that an active contract can not be changed. You can only change the *active contract set* by creating a new contract, or archiving an old one. -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 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: +Each ``.daml`` file defines a *Daml Module* at the top: .. literalinclude:: daml/daml-intro-1/Token.daml :language: daml :lines: 5 -Code comments in DAML are introduced with ``--``: +Code comments in Daml are introduced with ``--``: .. literalinclude:: daml/daml-intro-1/Token.daml :language: daml @@ -58,7 +58,7 @@ A ``template`` defines a type of contract that can be created, and who has the r You declare a template starting with the ``template`` keyword, which takes a name as an argument. -DAML is whitespace-aware and uses layout to structure *blocks*. Everything that's below the first line is indented, and thus part of the template's body. +Daml is whitespace-aware and uses layout to structure *blocks*. Everything that's below the first line is indented, and thus part of the template's body. *Contracts* contain data, referred to as the *create arguments* or simply *arguments*. The ``with`` block defines the data type of the create arguments by listing field names and their types. The single colon ``:`` means "of type", so you can read this as "template ``Token`` with a field ``owner`` of type ``Party``". @@ -69,9 +69,9 @@ Signatories The ``signatory`` keyword specifies the *signatories* of a contract. These are the parties whose *authority* is required to create the contract or archive it -- just like a real contract. Every contract must have at least one signatory. -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. +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 ------- -In :doc:`2_DamlScript`, you'll learn about how to try out the ``Token`` contract template in DAML's inbuilt DAML Script testing language. +In :doc:`2_DamlScript`, you'll learn about how to try out the ``Token`` contract template in Daml's inbuilt Daml Script testing language. diff --git a/docs/source/daml/intro/2_DamlScript.rst b/docs/source/daml/intro/2_DamlScript.rst index 3871949cc1..78457d3ec3 100644 --- a/docs/source/daml/intro/2_DamlScript.rst +++ b/docs/source/daml/intro/2_DamlScript.rst @@ -1,10 +1,10 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -2 Testing templates using DAML Script +2 Testing templates using Daml Script ===================================== -In this section you will test the ``Token`` model from :doc:`1_Token` using the :doc:`DAML Script ` integration in :ref:`DAML Studio `. You'll learn about the basic features of : +In this section you will test the ``Token`` model from :doc:`1_Token` using the :doc:`Daml Script ` integration in :ref:`Daml Studio `. You'll learn about the basic features of : - Allocating parties - Submitting transactions @@ -43,7 +43,7 @@ Before you can create any ``Token`` contracts, you need some parties on the test If that doesn't quite make sense yet, for the time being you can think of this arrow as extracting the right-hand-side value from the ledger and storing it into the variable on the left. -- The argument ``"Alice"`` to ``allocateParty`` does not have to be enclosed in brackets. Functions in DAML are called using the syntax ``fn arg1 arg2 arg3``. +- The argument ``"Alice"`` to ``allocateParty`` does not have to be enclosed in brackets. Functions in Daml are called using the syntax ``fn arg1 arg2 arg3``. With a variable ``alice`` of type ``Party`` in hand, you can submit your first transaction. Unsurprisingly, you do this using the ``submit`` function. ``submit`` takes two arguments: the ``Party`` and the ``Commands``. @@ -56,14 +56,14 @@ You could write this as ``submit alice (createCmd Token with owner = alice)``, b Running scripts --------------- -There are a few ways to run DAML Scripts: +There are a few ways to run Daml Scripts: -- In DAML Studio against a test ledger, providing visualizations of the resulting ledger +- In Daml Studio against a test ledger, providing visualizations of the resulting ledger - Using the command line ``daml test`` also against a test ledger, useful for continuous integration -- Against a real ledger, take a look at the documentation for :doc:`DAML Script ` for more information. -- Interactively using :doc:`DAML REPL `. +- Against a real ledger, take a look at the documentation for :doc:`Daml Script ` for more information. +- Interactively using :doc:`Daml REPL `. -In DAML Studio, you should see the text "Script results" just above the line ``token_test_1 = do``. Click on it to display the outcome of the script. +In Daml Studio, you should see the text "Script results" just above the line ``token_test_1 = do``. Click on it to display the outcome of the script. .. figure:: images/2_Scenario/scenario_results1.png @@ -142,7 +142,7 @@ Click on the adjacent "Show transaction view" button to see the entire transacti .. figure:: images/2_Scenario/tx_graph.png -In the DAML Studio script runner, committed transactions are numbered sequentially. The lines starting with ``TX`` indicate that there are three committed transactions, with ids ``#0``, ``#1``, and ``#2``. These correspond to the three ``submit`` and ``submitMustFail`` statements in the script. +In the Daml Studio script runner, committed transactions are numbered sequentially. The lines starting with ``TX`` indicate that there are three committed transactions, with ids ``#0``, ``#1``, and ``#2``. These correspond to the three ``submit`` and ``submitMustFail`` statements in the script. Transaction ``#0`` has one *sub-transaction* ``#0:0``, which the arrow indicates is a ``create`` of a ``Token``. Identifiers ``#X:Y`` mean ``commit X, sub-transaction Y``. All transactions have this format in the script runner. However, this format is a testing feature. In general, you should consider Transaction and Contract IDs to be opaque. @@ -169,4 +169,4 @@ To get a better understanding of script, try the following exercises: 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. +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. diff --git a/docs/source/daml/intro/3_Data.rst b/docs/source/daml/intro/3_Data.rst index 66b067e090..f1266b85b4 100644 --- a/docs/source/daml/intro/3_Data.rst +++ b/docs/source/daml/intro/3_Data.rst @@ -6,7 +6,7 @@ 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. -In :doc:`2_DamlScript`, you learnt about the script view in DAML Studio, which displays the current ledger state. It shows one table per template, with one row per contract of that type and one column per field in the arguments. +In :doc:`2_DamlScript`, you learnt about the script view in Daml Studio, which displays the current ledger state. It shows one table per template, with one row per contract of that type and one column per field in the arguments. This actually provides a useful way of thinking about templates: like tables in databases. Templates specify a data schema for the ledger: @@ -16,14 +16,14 @@ This actually provides a useful way of thinking about templates: like tables in In this section, you'll learn how to create rich data schemas for your ledger. Specifically you'll learn about: -- DAML's built-in and native data types +- Daml's built-in and native data types - Record types - Derivation of standard properties - Variants - Manipulating immutable data - Contract keys -After this section, you should be able to use a DAML ledger as a simple database where individual parties can write, read and delete complex data. +After this section, you should be able to use a Daml ledger as a simple database where individual parties can write, read and delete complex data. .. hint:: @@ -34,7 +34,7 @@ After this section, you should be able to use a DAML ledger as a simple database 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: +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: - ``Party`` Stores the identity of an entity that is able to act on the ledger, in the sense that they can sign contracts and submit transactions. In general, ``Party`` is opaque. @@ -64,13 +64,13 @@ The below script instantiates each one of these types, manipulates it where appr Despite its simplicity, there are quite a few things to note in this script: -- The ``import`` statements at the top import two packages from the DAML Standard Library, which contain all the date and time related functions we use here as well as the functions used in DAML Scripts. More on packages, imports and the standard library later. +- The ``import`` statements at the top import two packages from the Daml Standard Library, which contain all the date and time related functions we use here as well as the functions used in Daml Scripts. More on packages, imports and the standard library later. - Most of the variables are declared inside a ``let`` block. That's because the ``script do`` block expects script actions like ``submit`` or ``Party``. An integer like ``123`` is not an action, it's a pure expression, something we can evaluate without any ledger. You can think of the ``let`` as turning variable declaration into an action. - Most variables do not have annotations to say what type they are. - That's because DAML is very good at *inferring* types. The compiler knows that ``123`` is an ``Int``, so if you declare ``my_int = 123``, it can infer that ``my_int`` is also an ``Int``. This means you don't have to write the type annotation ``my_int : Int = 123``. + That's because Daml is very good at *inferring* types. The compiler knows that ``123`` is an ``Int``, so if you declare ``my_int = 123``, it can infer that ``my_int`` is also an ``Int``. This means you don't have to write the type annotation ``my_int : Int = 123``. However, if the type is ambiguous so that the compiler can't infer it, you do have to add a type annotation. This is the case for @@ -90,12 +90,12 @@ With templates and these native types, it's already possible to write a schema a Assembling 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. +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. Tuples ~~~~~~ -A common task is to group values in a generic way. Take, for example, a key-value pair with a ``Text`` key and an ``Int`` value. In DAML, you could use a two-tuple of type ``(Text, Int)`` to do so. If you wanted to express a coordinate in three dimensions, you could group three ``Decimal`` values using a three-tuple ``(Decimal, Decimal, Decimal)``. +A common task is to group values in a generic way. Take, for example, a key-value pair with a ``Text`` key and an ``Int`` value. In Daml, you could use a two-tuple of type ``(Text, Int)`` to do so. If you wanted to express a coordinate in three dimensions, you could group three ``Decimal`` values using a three-tuple ``(Decimal, Decimal, Decimal)``. .. literalinclude:: daml/daml-intro-3/Tuple.daml :language: daml @@ -107,14 +107,14 @@ You can access the data in the tuples using: - functions ``fst``, ``snd``, ``fst3``, ``snd3``, ``thd3`` - a dot-syntax with field names ``_1``, ``_2``, ``_3``, etc. -DAML supports tuples with up to 20 elements, but accessor functions like ``fst`` are only included for 2- and 3-tuples. +Daml supports tuples with up to 20 elements, but accessor functions like ``fst`` are only included for 2- and 3-tuples. Lists ~~~~~ -Lists in DAML take a single type parameter defining the type of thing in the list. So you can have a list of integers ``[Int]`` or a list of strings ``[Text]``, but not a list mixing integers and strings. +Lists in Daml take a single type parameter defining the type of thing in the list. So you can have a list of integers ``[Int]`` or a list of strings ``[Text]``, but not a list mixing integers and strings. -That's because DAML is statically and strongly typed. When you get an element out of a list, the compiler needs to know what type that element has. +That's because Daml is statically and strongly typed. When you get an element out of a list, the compiler needs to know what type that element has. The below script instantiates a few lists of integers and demonstrates the most important list functions. @@ -137,7 +137,7 @@ You can think of records as named tuples with named fields. Declare them using t You'll notice that the syntax to declare records is very similar to the syntax used to declare templates. That's no accident because a template is really just a special record. When you write ``template Token with``, one of the things that happens in the background is that this becomes a ``data Token = Token with``. -In the ``assert`` statements above, we always compared values of in-built types. If you wrote ``assert (my_record == my_record)`` in the script, you may be surprised to get an error message ``No instance for (Eq MyRecord) arising from a use of ‘==’``. Equality in DAML is always value equality and we haven't written a function to check value equality for ``MyRecord`` values. But don't worry, you don't have to implement this rather obvious function yourself. The compiler is smart enough to do it for you, if you use ``deriving (Eq)``: +In the ``assert`` statements above, we always compared values of in-built types. If you wrote ``assert (my_record == my_record)`` in the script, you may be surprised to get an error message ``No instance for (Eq MyRecord) arising from a use of ‘==’``. Equality in Daml is always value equality and we haven't written a function to check value equality for ``MyRecord`` values. But don't worry, you don't have to implement this rather obvious function yourself. The compiler is smart enough to do it for you, if you use ``deriving (Eq)``: .. literalinclude:: daml/daml-intro-3/Record.daml :language: daml @@ -162,7 +162,7 @@ If you look at the resulting script view, you'll see that this still gives rise 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. +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. .. literalinclude:: daml/daml-intro-3/Variants.daml :language: daml @@ -171,7 +171,7 @@ Suppose now that you also wanted to keep track of cash in hand. Cash in hand doe The way to read the declaration of ``Location`` is "*A Location either has value* ``InHand`` *OR has a value* ``InAccount a`` *where* ``a`` *is of type Account*". This is quite an explicit way to say that there may or may not be an ``Account`` associated with a ``CashBalance`` and gives both cases suggestive names. -Another option is to use the built-in ``Optional`` type. The ``None`` value of type ``Optional a`` is the closest DAML has to a ``null`` value: +Another option is to use the built-in ``Optional`` type. The ``None`` value of type ``Optional a`` is the closest Daml has to a ``null`` value: .. literalinclude:: daml/daml-intro-3/Variants.daml :language: daml @@ -199,7 +199,7 @@ Manipulating 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? -All data in DAML is immutable, meaning once a value is created, it will never change. Rather than changing values, you create new values based on old ones with some changes applied: +All data in Daml is immutable, meaning once a value is created, it will never change. Rather than changing values, you create new values based on old ones with some changes applied: .. literalinclude:: daml/daml-intro-3/Record.daml :language: daml @@ -215,7 +215,7 @@ Throughout the script, ``eq_record`` never changes. The expression ``"Zero" :: e 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. +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. You have already met the type ``ContractId a``, which references a contract of type ``a``. The below shows a contract model where ``Account`` is split out into a separate template and referenced by ``ContractId``, but it also highlights a big problem with that kind of reference: just like data, contracts are immutable. They can only be created and archived, so if you want to change the data on a contract, you end up archiving the original contract and creating a new one with the changed data. That makes contract IDs very unstable, and can cause stale references. @@ -235,7 +235,7 @@ You can define *stable* keys for contracts using the ``key`` and ``maintainer`` :start-after: -- KEY_TEST_BEGIN :end-before: -- KEY_TEST_END -Since DAML is designed to run on distributed systems, you have to assume that there is no global entity that can guarantee uniqueness, which is why each ``key`` expression must come with a ``maintainer`` expression. ``maintainer`` takes one or several parties, all of which have to be signatories of the contract and be part of the key. That way the index can be partitioned amongst sets of maintainers, and each set of maintainers can independently ensure the uniqueness constraint on their piece of the index. The constraint that maintainers are part of the key is ensured by only having the variable `key` in each maintainer expression. +Since Daml is designed to run on distributed systems, you have to assume that there is no global entity that can guarantee uniqueness, which is why each ``key`` expression must come with a ``maintainer`` expression. ``maintainer`` takes one or several parties, all of which have to be signatories of the contract and be part of the key. That way the index can be partitioned amongst sets of maintainers, and each set of maintainers can independently ensure the uniqueness constraint on their piece of the index. The constraint that maintainers are part of the key is ensured by only having the variable `key` in each maintainer expression. Instead of calling ``queryContractId`` to get the contract arguments associated with a given contract identifier, we use ``fetchByKey @Account``. ``fetchByKey @Account`` takes a value of type ``AccountKey`` and returns a tuple ``(ContractId Account, Account)`` if the lookup was successful or fails the transaction otherwise. ``fetchByKey`` cannot be used directly in the list of commands sent to the ledger. Therefore we create a ``Helper`` template with a ``FetchAccountByKey`` choice and call that via ``createAndExerciseCmd``. We will learn more about choices in the :doc:`next section <4_Transformations>`. diff --git a/docs/source/daml/intro/4_Transformations.rst b/docs/source/daml/intro/4_Transformations.rst index 4bb6f9222c..40d86db055 100644 --- a/docs/source/daml/intro/4_Transformations.rst +++ b/docs/source/daml/intro/4_Transformations.rst @@ -101,7 +101,7 @@ If you open the script view in the IDE, you will notice that Bob sees the ``Cont 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. +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. A *transaction* is a list of *actions*, and there are just four kinds of action: ``create``, ``exercise``, ``fetch`` and ``key assertion``. @@ -197,4 +197,4 @@ Next up You can now store and transform data on the ledger, even giving other parties specific write access through choices. -In :doc:`5_Restrictions`, you will learn how to restrict data and transformations further. In that context, you will also learn about time on DAML ledgers, ``do`` blocks and ``<-`` notation within those. +In :doc:`5_Restrictions`, you will learn how to restrict data and transformations further. In that context, you will also learn about time on Daml ledgers, ``do`` blocks and ``<-`` notation within those. diff --git a/docs/source/daml/intro/5_Restrictions.rst b/docs/source/daml/intro/5_Restrictions.rst index d9c8db2edb..ff708ee7bc 100644 --- a/docs/source/daml/intro/5_Restrictions.rst +++ b/docs/source/daml/intro/5_Restrictions.rst @@ -4,14 +4,14 @@ 5 Adding 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: +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: - The ``ensure`` keyword. - The ``assert``, ``abort`` and ``error`` keywords. To make sense of the latter, you'll also learn more about the ``Update`` and ``Script`` types and ``do`` blocks, which will be good preparation for :doc:`7_Composing`, where you will use ``do`` blocks to compose choices into complex transactions. -Lastly, you will learn about time on the ledger and in DAML Script. +Lastly, you will learn about time on the ledger and in Daml Script. .. hint:: @@ -78,22 +78,22 @@ Similarly, you can write a ``Redeem`` choice, which allows the ``owner`` to rede :start-after: -- REDEEM_TEST_BEGIN :end-before: -- REDEEM_TEST_END -There are quite a few new time-related functions from the ``DA.Time`` and ``DA.Date`` libraries here. Their names should be reasonably descriptive so how they work won't be covered here, but given that DAML assumes it is run in a distributed setting, we will still discuss time in DAML. +There are quite a few new time-related functions from the ``DA.Time`` and ``DA.Date`` libraries here. Their names should be reasonably descriptive so how they work won't be covered here, but given that Daml assumes it is run in a distributed setting, we will still discuss time in Daml. 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. +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. -Each DAML ledger has a policy on the allowed difference between LT and RT called the *skew*. The participant has to take a good guess at what the record time will be. If it's too far off, the transaction will be rejected. +Each Daml ledger has a policy on the allowed difference between LT and RT called the *skew*. The participant has to take a good guess at what the record time will be. If it's too far off, the transaction will be rejected. ``getTime`` is an action that gets the LT from the ledger. In the above example, that time is taken apart into day of week and hour of day using standard library functions from ``DA.Date`` and ``DA.Time``. The hour of the day is checked to be in the range from 8 to 18. Consider the following example: Suppose that the ledger had a skew of 10 seconds. At 17:59:55, Alice submits a transaction to redeem an Iou. One second later, the transaction is assigned a LT of 17:59:56, but then takes 10 seconds to commit and is recorded on the ledger at 18:00:06. Even though it was committed after business hours, it would be a valid transaction and be committed successfully as ``getTime`` will return 17:59:56 so ``hrs == 17``. Since the RT is 18:00:06, ``LT - RT <= 10 seconds`` and the transaction won't be rejected. -Time therefore has to be considered slightly fuzzy in DAML, with the fuzziness depending on the skew parameter. +Time therefore has to be considered slightly fuzzy in Daml, with the fuzziness depending on the skew parameter. For details, see :ref:`Background concepts - time `. +.. [#f1] FYI Behind the scenes the Daml React hooks library uses the :doc:`Daml Ledger TypeScript library ` to communicate with a ledger implementation via the :doc:`HTTP JSON API `. diff --git a/docs/source/getting-started/first-feature.rst b/docs/source/getting-started/first-feature.rst index 895fdef7ad..b35071c4f7 100644 --- a/docs/source/getting-started/first-feature.rst +++ b/docs/source/getting-started/first-feature.rst @@ -5,7 +5,7 @@ Your First Feature ****************** Let's dive into implementing a new feature for our social network app. -This will give us a better idea how to develop DAML applications using our template. +This will give us a better idea how to develop Daml applications using our template. At the moment, our app lets us follow users in the network, but we have no way to communicate with them! Let's fix that by adding a *direct messaging* feature. @@ -15,20 +15,20 @@ This means: 1. You cannot send a message to someone unless they have given you the authority by following you back. 2. You cannot see a message unless you sent it or it was sent to you. -We will see that DAML lets us implement these guarantees in a direct and intuitive way. +We will see that Daml lets us implement these guarantees in a direct and intuitive way. There are three parts to building and running the messaging feature: - 1. Adding the necessary changes to the DAML model + 1. Adding the necessary changes to the Daml model 2. Making the corresponding changes in the UI 3. Running the app with the new feature. -As usual, we must start with the DAML model and base our UI changes on top of that. +As usual, we must start with the Daml model and base our UI changes on top of that. -DAML Changes +Daml Changes ============ -As mentioned in the :doc:`architecture ` section, the DAML code defines the *data* and *workflow* of the application. +As mentioned in the :doc:`architecture ` section, the Daml code defines the *data* and *workflow* of the application. The workflow aspect refers to the interactions between parties that are permitted by the system. In the context of a messaging feature, these are essentially the authorization and privacy concerns listed above. @@ -70,11 +70,11 @@ Running the New Feature Navigate to the terminal window where the ``daml start`` process is running and press 'r'. This will - - Compile our DAML code into a *DAR file containing the new feature* - - Update the JavaScript library under ``ui/daml.js`` to connect the UI with your DAML code + - Compile our Daml code into a *DAR file containing the new feature* + - Update the JavaScript library under ``ui/daml.js`` to connect the UI with your Daml code - Upload the *new DAR file* to the sandbox -As mentioned at the beginning of this *Getting Started with DAML* guide, DAML Sandbox uses an +As mentioned at the beginning of this *Getting Started with Daml* guide, Daml Sandbox uses an in-memory store, which means it loses its state when stopped or restarted. That means that all user data and follower relationships are lost. @@ -112,9 +112,9 @@ For each contract in the stream, we destructure the *payload* (the data as oppos Then we construct a ``ListItem`` UI element with the details of the message. There is one important point about privacy here. -No matter how we write our ``Message`` query in the UI code, it is impossible to break the privacy rules given by the DAML model. +No matter how we write our ``Message`` query in the UI code, it is impossible to break the privacy rules given by the Daml model. That is, it is impossible to see a ``Message`` contract of which you are not the ``sender`` or the ``receiver`` (the only parties that can observe the contract). -This is a major benefit of writing apps on DAML: the burden of ensuring privacy and authorization is confined to the DAML model. +This is a major benefit of writing apps on Daml: the burden of ensuring privacy and authorization is confined to the Daml model. MessageEdit Component --------------------- @@ -135,7 +135,7 @@ The prop will be passed down from the ``MainView`` component, reusing the work r You can see this ``followers`` field bound at the start of the ``MessageEdit`` component. We use the React ``useState`` hook to get and set the current choices of message ``receiver`` and ``content``. -The DAML-specific ``useLedger`` hook gives us an object we can use to perform ledger operations. +The Daml-specific ``useLedger`` hook gives us an object we can use to perform ledger operations. The call to ``ledger.exerciseByKey`` in ``submitMessage`` looks up the ``User`` contract with the receiver's username and exercises the ``SendMessage`` choice with the appropriate arguments. If the choice fails, the ``catch`` block reports the error in a dialog box. Additionally, ``submitMessage`` sets the ``isSubmitting`` state so that the *Send* button is disabled while the request is processed. @@ -209,8 +209,8 @@ You'll notice that new messages appear in the UI as soon as they are sent (due t Next Steps ========== -We've gone through the process of setting up a full-stack DAML app and implementing a useful feature end to end. -As the next step we encourage you to really dig into the fundamentals of DAML and understand its core concepts such as parties, signatories, observers, and controllers. +We've gone through the process of setting up a full-stack Daml app and implementing a useful feature end to end. +As the next step we encourage you to really dig into the fundamentals of Daml and understand its core concepts such as parties, signatories, observers, and controllers. You can do that either by :doc:`going through our docs ` or by taking an `online course `_. After you've got a good grip on these concepts learn :doc:`how to conduct end-to-end testing of your app `. diff --git a/docs/source/getting-started/index.rst b/docs/source/getting-started/index.rst index aec382ff80..5e380e5d2b 100644 --- a/docs/source/getting-started/index.rst +++ b/docs/source/getting-started/index.rst @@ -3,10 +3,10 @@ .. _new-quickstart: -Getting Started with DAML +Getting Started with Daml ######################### -The goal of this tutorial is to get you up and running with full-stack DAML development. +The goal of this tutorial is to get you up and running with full-stack Daml development. We do this through the example of a simple social networking application, showing you three things: @@ -14,20 +14,20 @@ showing you three things: 2. The design of its different components (:doc:`app-architecture`) 3. How to write a new feature for the app (:doc:`first-feature`) -We do not aim to be comprehensive in all DAML concepts and tools (covered in :doc:`Writing DAML `) or in all deployment options (see :doc:`Deploying `). -**For a quick overview of the most important DAML concepts used in this tutorial open** `the DAML cheat-sheet `_ **in a separate tab**. The goal is that by the end of this tutorial, +We do not aim to be comprehensive in all Daml concepts and tools (covered in :doc:`Writing Daml `) or in all deployment options (see :doc:`Deploying `). +**For a quick overview of the most important Daml concepts used in this tutorial open** `the Daml cheat-sheet `_ **in a separate tab**. The goal is that by the end of this tutorial, you'll have a good idea of the following: - 1. What DAML contracts and ledgers are - 2. How a user interface (UI) interacts with a DAML ledger - 3. How DAML helps you build a real-life application fast. + 1. What Daml contracts and ledgers are + 2. How a user interface (UI) interacts with a Daml ledger + 3. How Daml helps you build a real-life application fast. With that, let's get started! Prerequisites ************* -Please make sure that you have the DAML Connect SDK, Java 8 or higher, and Visual Studio Code (the only supported IDE) installed as per instructions from our :doc:`installation` page. +Please make sure that you have the Daml Connect SDK, Java 8 or higher, and Visual Studio Code (the only supported IDE) installed as per instructions from our :doc:`installation` page. You will also need some common software tools to build and interact with the template project. @@ -62,15 +62,15 @@ In one terminal, at the root of the ``create-daml-app`` directory, run the comma daml start -Any commands starting with ``daml`` are using the :doc:`DAML Assistant `, a -command line tool in the SDK for building and running DAML apps. +Any commands starting with ``daml`` are using the :doc:`Daml Assistant `, a +command line tool in the SDK for building and running Daml apps. You will know that the command has started successfully when you see the ``INFO com.daml.http.Main$ - Started server: ServerBinding(/127.0.0.1:7575)`` message in the terminal. The command does a few things: - 1. Compiles the DAML code to a DAR (DAML Archive) file. - 2. Generates a JavaScript library in ``ui/daml.js`` to connect the UI with your DAML code. + 1. Compiles the Daml code to a DAR (Daml Archive) file. + 2. Generates a JavaScript library in ``ui/daml.js`` to connect the UI with your Daml code. 3. Starts an instance of the :doc:`Sandbox `, an in-memory ledger useful for development, loaded with our DAR. - 4. Starts a server for the :doc:`HTTP JSON API `, a simple way to run commands against a DAML ledger (in this case the running Sandbox). + 4. Starts a server for the :doc:`HTTP JSON API `, a simple way to run commands against a Daml ledger (in this case the running Sandbox). We'll leave these processes running to serve requests from our UI. @@ -110,7 +110,7 @@ You'll notice that the users you just started following appear in the *Following However they do *not* yet appear in the *Network* panel. This is either because they have not signed up and are not parties on the ledger or they have not yet started followiong you. This social network is similar to Twitter and Instagram, where by following someone, say Alice, you make yourself visible to her but not vice versa. -We will see how we encode this in DAML in the next section. +We will see how we encode this in Daml in the next section. .. figure:: images/create-daml-app-bob-follows-alice.png :alt: In the create-daml-app users can follow each other in a similiar fashion as in Twitter or Instagram @@ -131,7 +131,7 @@ Just switch to the window where you are logged in as yourself - the network shou :alt: In the create-daml-app when the user you are following follows you back s/he reveals the list of people they are following Play around more with the app at your leisure: create new users and start following more users. -Observe when a user becomes visible to others - this will be important to understanding DAML's privacy model later. +Observe when a user becomes visible to others - this will be important to understanding Daml's privacy model later. When you're ready, let's move on to the :doc:`architecture of our app `. .. tip:: Congratulations on completing the first part of the Getting Started Guide! `Join our forum `_ and share a screenshot of your accomplishment to `get your first of 3 getting started badges `_! You can get the next one by :doc:`implementing your first feature `. diff --git a/docs/source/getting-started/installation.rst b/docs/source/getting-started/installation.rst index b45e3727a6..80e7e6b6ba 100644 --- a/docs/source/getting-started/installation.rst +++ b/docs/source/getting-started/installation.rst @@ -7,7 +7,7 @@ Installing the SDK 1. Install the dependencies *************************** -The DAML Connect SDK currently runs on Windows, macOS and Linux. +The Daml Connect SDK currently runs on Windows, macOS and Linux. You need to install: @@ -22,7 +22,7 @@ You need to install: Windows 10 ========== -Download and run the installer_, which will install DAML and set up your PATH. +Download and run the installer_, which will install Daml and set up your PATH. .. _mac-linux-sdk: @@ -43,7 +43,7 @@ Next steps ********** - Follow the :doc:`getting started guide `. -- Use ``daml --help`` to see all the commands that the DAML assistant (``daml``) provides. +- Use ``daml --help`` to see all the commands that the Daml assistant (``daml``) provides. - If the ``daml`` command is not available in your terminal after logging out and logging in again, you need to set the ``PATH`` environment variable manually. You can find instructions on how to do this :doc:`here `. - If you run into any other problems, you can use the :doc:`support page ` to get in touch with us. diff --git a/docs/source/getting-started/manual-download.rst b/docs/source/getting-started/manual-download.rst index ca91ef630a..194c7cd42f 100644 --- a/docs/source/getting-started/manual-download.rst +++ b/docs/source/getting-started/manual-download.rst @@ -4,7 +4,7 @@ Manually installing the SDK *************************** -If you require a higher level of security, you can instead install the DAML Connect SDK by manually downloading the compressed tarball, verifying its signature, extracting it and manually running the install script. +If you require a higher level of security, you can instead install the Daml Connect SDK by manually downloading the compressed tarball, verifying its signature, extracting it and manually running the install script. Note that the Windows installer is already signed (within the binary itself), and that signature is checked by Windows before starting it. Nevertheless, you can still follow the steps below to check its external signature file. diff --git a/docs/source/index.rst b/docs/source/index.rst index a5642b350f..e10c32aa27 100644 --- a/docs/source/index.rst +++ b/docs/source/index.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Documentation +Daml Documentation ################## .. toctree:: @@ -28,7 +28,7 @@ DAML Documentation :titlesonly: :maxdepth: 2 :hidden: - :caption: Writing DAML + :caption: Writing Daml daml/intro/0_Intro.rst daml/reference/index @@ -46,8 +46,8 @@ DAML Documentation app-dev/app-arch app-dev/bindings-ts/index json-api/index - DAML Script - DAML REPL + Daml Script + Daml REPL upgrade/index app-dev/authorization app-dev/ledger-api @@ -56,7 +56,7 @@ DAML Documentation :titlesonly: :maxdepth: 2 :hidden: - :caption: Deploying to DAML ledgers + :caption: Deploying to Daml ledgers deploy/index deploy/generic_ledger @@ -66,7 +66,7 @@ DAML Documentation :titlesonly: :maxdepth: 2 :hidden: - :caption: Operating DAML + :caption: Operating Daml ops/index @@ -119,7 +119,7 @@ DAML Documentation :titlesonly: :maxdepth: 2 :hidden: - :caption: DAML Ecosystem + :caption: Daml Ecosystem support/overview support/releases diff --git a/docs/source/json-api/index.rst b/docs/source/json-api/index.rst index fa073a31f2..7ef529772f 100644 --- a/docs/source/json-api/index.rst +++ b/docs/source/json-api/index.rst @@ -38,7 +38,7 @@ We welcome feedback about the JSON API on Running the JSON API ******************** -Start a DAML Ledger +Start a Daml Ledger =================== You can run the JSON API alongside any ledger exposing the gRPC Ledger API you want. If you don't have an existing ledger, you can start an in-memory sandbox: @@ -117,7 +117,7 @@ The JSON API essentially performs two separate tasks: 1. It talks to the Ledger API to get data it needs to operate, for this you need to *provide an access token* if your Ledger requires authorization. Learn more in the :doc:`/app-dev/authorization` docs. 2. It accepts requests from Parties and passes them on to the Ledger API, for this each party needs to provide an *access token with each request* it sends to the JSON API. -.. note:: By default, the DAML Sandbox does not does not require access tokens. In this case, you can omit the token used by the JSON API to request packages. However, you still need to provide a party-specific access token when submitting commands or queries as a party. The token will not be validated in this case but it will be decoded to extract information like the party submitting the command. +.. note:: By default, the Daml Sandbox does not does not require access tokens. In this case, you can omit the token used by the JSON API to request packages. However, you still need to provide a party-specific access token when submitting commands or queries as a party. The token will not be validated in this case but it will be decoded to extract information like the party submitting the command. Internal Access Token --------------------- @@ -146,7 +146,7 @@ Party-specific requests, i.e., command submissions and queries, require a JWT wi .. note:: While the JSON API receives the token it doesn't validate it itself. Upon receiving a token it will pass it, and all data contained within the request, on to the Ledger API's AuthService which will then determine if the token is valid and authorized. However, the JSON API does decode the token to extract the ledger id, application id and party so it requires that you use the JWT format documented below. -For a ledger without authorization, e.g., the default configuration of DAML Sandbox, you can use https://jwt.io (or the JWT library of your choice) to generate your +For a ledger without authorization, e.g., the default configuration of Daml Sandbox, you can use https://jwt.io (or the JWT library of your choice) to generate your token. You can use an arbitrary secret here. The default "header" is fine. Under "Payload", fill in: .. code-block:: json @@ -159,7 +159,7 @@ token. You can use an arbitrary secret here. The default "header" is fine. Und } } -The value of the ``ledgerId`` field has to match the ``ledgerId`` of your underlying DAML Ledger. +The value of the ``ledgerId`` field has to match the ``ledgerId`` of your underlying Daml Ledger. For the Sandbox this corresponds to the ``--ledgerid MyLedger`` flag. .. note:: The value of ``applicationId`` will be used for commands submitted using that token. @@ -383,7 +383,7 @@ Where: + ``"::"`` or + ``":"`` if contract template can be uniquely identified by its module and entity name. -- ``payload`` field contains contract fields as defined in the DAML template and formatted according to :doc:`lf-value-specification`. +- ``payload`` field contains contract fields as defined in the Daml template and formatted according to :doc:`lf-value-specification`. .. _create-response: @@ -481,7 +481,7 @@ Where: - ``templateId`` -- contract template identifier, same as in :ref:`create request `, - ``contractId`` -- contract identifier, the value from the :ref:`create response `, -- ``choice`` -- DAML contract choice, that is being exercised, +- ``choice`` -- Daml contract choice, that is being exercised, - ``argument`` -- contract choice argument(s). .. _exercise-response: @@ -581,7 +581,7 @@ Where: - ``templateId`` -- contract template identifier, same as in :ref:`create request `, - ``key`` -- contract key, formatted according to the :doc:`lf-value-specification`, -- ``choice`` -- DAML contract choice, that is being exercised, +- ``choice`` -- Daml contract choice, that is being exercised, - ``argument`` -- contract choice argument(s), empty, because ``Archive`` does not take any. HTTP Response @@ -622,8 +622,8 @@ HTTP Request Where: - ``templateId`` -- the initial contract template identifier, in the same format as in the :ref:`create request `, -- ``payload`` -- the initial contract fields as defined in the DAML template and formatted according to :doc:`lf-value-specification`, -- ``choice`` -- DAML contract choice, that is being exercised, +- ``payload`` -- the initial contract fields as defined in the Daml template and formatted according to :doc:`lf-value-specification`, +- ``choice`` -- Daml contract choice, that is being exercised, - ``argument`` -- contract choice argument(s). HTTP Response @@ -1008,7 +1008,7 @@ Please note that the order of the party objects in the response is not guarantee Where -- ``identifier`` -- a stable unique identifier of a DAML party, +- ``identifier`` -- a stable unique identifier of a Daml party, - ``displayName`` -- optional human readable name associated with the party. Might not be unique, - ``isLocal`` -- true if party is hosted by the backing participant. diff --git a/docs/source/json-api/lf-value-specification.rst b/docs/source/json-api/lf-value-specification.rst index 88e3f31900..2cd7f3be2a 100644 --- a/docs/source/json-api/lf-value-specification.rst +++ b/docs/source/json-api/lf-value-specification.rst @@ -1,11 +1,11 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML-LF JSON Encoding +Daml-LF JSON Encoding ##################### -We describe how to decode and encode DAML-LF values as JSON. For each -DAML-LF type we explain what JSON inputs we accept (decoding), and what +We describe how to decode and encode Daml-LF values as JSON. For each +Daml-LF type we explain what JSON inputs we accept (decoding), and what JSON output we produce (encoding). The output format is parameterized by two flags:: @@ -20,8 +20,8 @@ encode-as-String avoids this, as mentioned with respect to ``JSON.parse`` below. For that reason, the HTTP JSON API Service uses ``true`` for both flags. Note that throughout the document the decoding is type-directed. In -other words, the same JSON value can correspond to many DAML-LF values, -and the expected DAML-LF type is needed to decide which one. +other words, the same JSON value can correspond to many Daml-LF values, +and the expected Daml-LF type is needed to decide which one. ContractId ********** @@ -47,7 +47,7 @@ treated them as the equivalent JSON number:: Note that JSON numbers would be enough to represent all Decimals. However, we also accept strings because in many languages (most notably JavaScript) use IEEE Doubles to express JSON numbers, and -IEEE Doubles cannot express DAML-LF Decimals correctly. Therefore, we +IEEE Doubles cannot express Daml-LF Decimals correctly. Therefore, we also accept strings so that JavaScript users can use them to specify Decimals that do not fit in IEEE Doubles. @@ -158,7 +158,7 @@ risk that users pass in local times. Valid examples:: 0001-01-01T00:00:00Z 9999-12-31T23:59:59.999999Z -The timestamp must be between the bounds specified by DAML-LF and ISO +The timestamp must be between the bounds specified by Daml-LF and ISO 8601, [0001-01-01T00:00:00Z, 9999-12-31T23:59:59.999999Z]. JavaScript @@ -239,7 +239,7 @@ Represented as an ISO 8601 date rendered using the format 9999-12-31 0001-01-01 -The dates must be between the bounds specified by DAML-LF and ISO 8601, +The dates must be between the bounds specified by Daml-LF and ISO 8601, [0001-01-01, 9999-99-99]. Text @@ -266,7 +266,7 @@ And as arrays:: [ v₁, ..., vₙ ] -Note that DAML-LF record fields are ordered. So if we have +Note that Daml-LF record fields are ordered. So if we have :: @@ -278,8 +278,8 @@ fields in order:: [42, true] The motivation for the array format for records is to allow specifying -tuple types closer to what it looks like in DAML. Note that a DAML -tuple, i.e. (42, True), will be compiled to a DAML-LF record ``Tuple2 { +tuple types closer to what it looks like in Daml. Note that a Daml +tuple, i.e. (42, True), will be compiled to a Daml-LF record ``Tuple2 { _1 = 42, _2 = True }``. Output @@ -332,9 +332,9 @@ A few examples, using the form :: - JSON --> DAML-LF : Expected DAML-LF type + JSON --> Daml-LF : Expected Daml-LF type -to make clear what the target DAML-LF type is:: +to make clear what the target Daml-LF type is:: null --> None : Optional Int64 null --> None : Optional (Optional Int64) @@ -346,7 +346,7 @@ to make clear what the target DAML-LF type is:: ... Finally, if Optional values appear in records, they can be omitted to -represent None. Given DAML-LF types +represent None. Given Daml-LF types :: @@ -371,7 +371,7 @@ of key to determine what keys are present in the Map to begin with. Nor does it apply to the ``[f₁, ..., fₙ]`` record form; ``Depth1 None`` in the array notation must be written as ``[null]``. -Type variables may appear in the DAML-LF language, but are always +Type variables may appear in the Daml-LF language, but are always resolved before deciding on a JSON encoding. So, for example, even though ``Oa`` doesn't appear to contain a nested ``Optional``, it may contain a nested ``Optional`` by virtue of substituting the type @@ -415,14 +415,14 @@ These are all valid JSON encodings for values of type Foo:: {"tag": "Quux", "value": null} {"tag": "Quux", "value": 42} -Note that DAML data types with named fields are compiled by factoring +Note that Daml data types with named fields are compiled by factoring out the record. So for example if we have :: data Foo = Bar {f1: Int64, f2: Bool} | Baz -We'll get in DAML-LF +We'll get in Daml-LF :: diff --git a/docs/source/json-api/search-query-language.rst b/docs/source/json-api/search-query-language.rst index 4d5a37b2fc..71b8578f24 100644 --- a/docs/source/json-api/search-query-language.rst +++ b/docs/source/json-api/search-query-language.rst @@ -77,7 +77,7 @@ Appendix: Type-aware queries **This section is non-normative.** -This is not a *JSON* query language, it is a *DAML-LF* query +This is not a *JSON* query language, it is a *Daml-LF* query language. So, while we could theoretically treat queries (where not otherwise interpreted by the "may contain additional properties" rule above) without concern for what LF type (i.e. template) we're @@ -91,7 +91,7 @@ among an unbounded number of others:: variant C ↦ foo : Party | bar : Unit // NB: LF does not require any particular case for VariantCon or Field; - // these are perfectly legal types in DAML-LF packages + // these are perfectly legal types in Daml-LF packages In the cases of ``A`` and ``B``, ``"foo"`` is part of the query language, and only ``"bar"`` is treated as an LF value; in the case of diff --git a/docs/source/ops/index.rst b/docs/source/ops/index.rst index 325978328a..690f11bce7 100644 --- a/docs/source/ops/index.rst +++ b/docs/source/ops/index.rst @@ -3,46 +3,46 @@ .. ops-ref_index: -DAML Participant pruning +Daml Participant pruning ======================== .. HINT:: - DAML Participant pruning is currently an :doc:`Early Access Feature in Labs status ` + Daml Participant pruning is currently an :doc:`Early Access Feature in Labs status ` -The DAML Ledger API exposes an append-only ledger model; on the other hand, DAML Participants must be able to operate continuously for an indefinite amount of time on a limited amount of hot storage. +The Daml Ledger API exposes an append-only ledger model; on the other hand, Daml Participants must be able to operate continuously for an indefinite amount of time on a limited amount of hot storage. In addition, privacy demands [1]_ may require removing Personally Identifiable Information (PII) upon request. -To satisfy these requirements, the :ref:`Pruning Service ` Ledger API endpoint [2]_ allows DAML Participants to support pruning of DAML contracts and transactions that were respectively archived and submitted before or at a given ledger offset. +To satisfy these requirements, the :ref:`Pruning Service ` Ledger API endpoint [2]_ allows Daml Participants to support pruning of Daml contracts and transactions that were respectively archived and submitted before or at a given ledger offset. -Please refer to the specific DAML Driver information for details about its pruning support. +Please refer to the specific Daml Driver information for details about its pruning support. .. [1] For example, as enabled by provisions about the "right to be forgotten" of legislation such as `EU's GDPR `_. .. [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. +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. -Still, DAML applications may be affected in the following ways: +Still, Daml applications may be affected in the following ways: -- Pruning is potentially a long-running operation and demanding one in terms of system resources; as such, it may significantly reduce DAML Ledger API throughput and increase latency while it is being performed. It is thus strongly recommended to plan pruning invocations, preferably, when the system is offline or at least when very low system utilization is expected. +- Pruning is potentially a long-running operation and demanding one in terms of system resources; as such, it may significantly reduce Daml Ledger API throughput and increase latency while it is being performed. It is thus strongly recommended to plan pruning invocations, preferably, when the system is offline or at least when very low system utilization is expected. - Pruning may degrade the behavior of or abort in-progress requests if the pruning offset is too recent. In particular, the system might misbehave if command completions are pruned before the command trackers are able to process the completions. - Command deduplication and command tracker retention should always configured in such a way, that the associated windows don't overlap with the pruning window, so that their operation is unaffected by pruning. - Pruning may affect the behavior of Ledger API calls that allow to read data from the ledger: see the next sub-section for more information about API impacts. -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. +- 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. - Requesting information at offsets that predate pruning, including from the ledger's start, will result in a ``NOT_FOUND`` gRPC error. - - As a consequence, after pruning, a DAML application must bootstrap from the Active Contract Service and a recent offset [3]_. + - As a consequence, after pruning, a Daml application must bootstrap from the Active Contract Service and a recent offset [3]_. -Submission validation and DAML Ledger API endpoints that write to the ledger are generally not affected by pruning; an exception is that in-progress calls could abort while awaiting completion. +Submission validation and Daml Ledger API endpoints that write to the ledger are generally not affected by pruning; an exception is that in-progress calls could abort while awaiting completion. -Please refer to the :doc:`protobuf documentation of the API ` for details about the ``prune`` operation itself and the behavior of other DAML Ledger API endpoints when pruning is being or has been performed. +Please refer to the :doc:`protobuf documentation of the API ` 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 ----------------- @@ -75,14 +75,14 @@ Determining a suitable pruning offset The :ref:`Transaction Service ` and the :ref:`Active Contract Service ` provide offsets of the ledger end, as well as of transactions, and of Active Contracts snapshots respectively; such offsets can be passed unchanged to `prune` calls. -Scheduled jobs, applications and/or operator tools can be built on top of the DAML Ledger API to implement pruning automatically, for example at regular intervals, or on-demand, for example according to a user-initiated process. +Scheduled jobs, applications and/or operator tools can be built on top of the Daml Ledger API to implement pruning automatically, for example at regular intervals, or on-demand, for example according to a user-initiated process. For instance, pruning at regular intervals could be performed by a cron job that: 1. If a pruning interval has been saved to a well-known location: - a. Backs up the DAML Participant Index DB. + a. Backs up the Daml Participant Index DB. b. Performs pruning. - c. (If using PostgreSQL) Performs a `VACUUM FULL` command on the DAML Participant Index DB. + c. (If using PostgreSQL) Performs a `VACUUM FULL` command on the Daml Participant Index DB. 2. Queries the current ledger end and saves its offset. diff --git a/docs/source/support/compatibility.rst b/docs/source/support/compatibility.rst index 76c439e34f..2cf371131f 100644 --- a/docs/source/support/compatibility.rst +++ b/docs/source/support/compatibility.rst @@ -4,26 +4,26 @@ 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. +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. Application Portability - A DAML application should not depend on the underlying Database or DLT used by a DAML network. + A Daml application should not depend on the underlying Database or DLT used by a Daml network. Network Upgradeability - Ledger Operators should be able to upgrade DAML network or Participant Nodes seamlessly to stay up to date with the latest features and fixes. A DAML application should be able to operate without significant change across such Network Upgrades. + Ledger Operators should be able to upgrade Daml network or Participant Nodes seamlessly to stay up to date with the latest features and fixes. A Daml application should be able to operate without significant change across such Network Upgrades. -DAML Connect Upgradeability +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. +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. -Specifically, if a DAML Application is built against Ledger API version X.Y.Z and a Participant Node exposes Ledger API version X.Y2.Z2, the application is guaranteed to work as long as Y2.Z2 >= Y.Z. +Specifically, if a Daml Application is built against Ledger API version X.Y.Z and a Participant Node exposes Ledger API version X.Y2.Z2, the application is guaranteed to work as long as Y2.Z2 >= Y.Z. Participant Nodes advertise the Ledger API version they support via the :ref:`version service `. @@ -31,31 +31,31 @@ Participant Nodes advertise the Ledger API version they support via the :ref:`ve Before release 1.7, the Ledger API version exposed by the Participant Node matched the version of the integration kit and SDK they were released with. -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. +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. 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. +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. +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 +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. +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. -For example, an application built and compiled with DAML Connect 1.4.0 against Ledger API 1.4.0, it can still be compiled using SDK 1.6.0 and can be run against Ledger API 1.4.0 using 1.6.0 libraries and runtime components. +For example, an application built and compiled with Daml Connect 1.4.0 against Ledger API 1.4.0, it can still be compiled using SDK 1.6.0 and can be run against Ledger API 1.4.0 using 1.6.0 libraries and runtime components. .. _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. +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. Other than for hotfix releases, new releases of the Integration Components will only support the latest minor/patch version of each major Ledger API version. As a result we can make this overall statement: -**An application built using DAML Connect U.V.W against Ledger API X.Y.Z can be maintained using any DAML Connect version U2.V2.W2 >= U.V.W as long as Ledger API major version X is still supported at the time of release of U2.V2.W2, and run against any DAML Network with Participant Nodes exposing Ledger API X.Y2.Z2 >= X.Y.Z.** +**An application built using Daml Connect U.V.W against Ledger API X.Y.Z can be maintained using any Daml Connect version U2.V2.W2 >= U.V.W as long as Ledger API major version X is still supported at the time of release of U2.V2.W2, and run against any Daml Network with Participant Nodes exposing Ledger API X.Y2.Z2 >= X.Y.Z.** diff --git a/docs/source/support/component-statuses.rst b/docs/source/support/component-statuses.rst index c2c9e6ad9d..d609520be6 100644 --- a/docs/source/support/component-statuses.rst +++ b/docs/source/support/component-statuses.rst @@ -16,7 +16,7 @@ Ledger API * - Component/Feature - Status - Deprecated on - * - :doc:`Ledger API specification ` including all semantics of >= DAML-LF 1.6 + * - :doc:`Ledger API specification ` including all semantics of >= Daml-LF 1.6 - Stable - * - `Numbered (ie non-dev) Versions of Proto definitions distributed via GitHub Releases `_ @@ -70,7 +70,7 @@ Runtime components * - **Triggers** - - - * - :doc:`DAML API of individual Triggers ` + * - :doc:`Daml API of individual Triggers ` - Beta - * - :doc:`Development CLI to start individual triggers in dev environment ` (``daml trigger``) @@ -155,16 +155,16 @@ Libraries * - ``@daml/react`` :doc:`library and its public API ` - Stable - - * - **DAML Libraries** + * - **Daml Libraries** - - - * - :doc:`The DAML Standard Library ` + * - :doc:`The Daml Standard Library ` - Stable - - * - :doc:`The DAML Script Library ` + * - :doc:`The Daml Script Library ` - Stable - - * - :doc:`The DAML Trigger Library ` + * - :doc:`The Daml Trigger Library ` - Stable - @@ -209,7 +209,7 @@ Developer Tools * - Assistant commands to start Runtime Components: ``daml json-api``, ``daml trigger``, ``daml trigger-service``, and ``daml extractor``. - See :ref:`runtime-components`. - - * - **DAML Projects** + * - **Daml Projects** - - * - ``daml.yaml`` project specification @@ -218,7 +218,7 @@ Developer Tools * - Assistant commands ``new``, ``create-daml-app``, and ``init``. Note that the templates created by ``daml new`` and ``create-daml-app`` are considered example code, and are not covered by :ref:`semantic versioning `. - Stable - - * - **DAML Studio** + * - **Daml Studio** - - * - VSCode Extension @@ -239,16 +239,16 @@ Developer Tools * - ``daml sandbox`` assistant command and documented CLI under ``daml sandbox --help``. - Stable - - * - DAML Sandbox in Memory (ie without the ``--sql-backend-jdbcurl`` flag) + * - Daml Sandbox in Memory (ie without the ``--sql-backend-jdbcurl`` flag) - Stable - - * - DAML Sandbox on Postgres (iw with the ``--sql-backend-jdbcurl`` flag) + * - Daml Sandbox on Postgres (iw with the ``--sql-backend-jdbcurl`` flag) - Stable, Deprecated - 2020-12-16 - * - DAML Sandbox Classic and associated CLIs ``daml sandbox-classic``, ``daml start --sandbox-classic`` + * - Daml Sandbox Classic and associated CLIs ``daml sandbox-classic``, ``daml start --sandbox-classic`` - Stable, Deprecated - 2020-04-09 - * - **DAML Compiler** + * - **Daml Compiler** - - * - ``daml build`` CLI @@ -272,19 +272,19 @@ Developer Tools * - DAR File validation (``daml damlc validate-dar``) - Stable - - * - DAML Linter (``daml damlc lint``) + * - Daml Linter (``daml damlc lint``) - Stable - - * - DAML REPL (``daml damlc repl``) - - See DAML REPL heading below + * - Daml REPL (``daml damlc repl``) + - See Daml REPL heading below - - * - DAML Language Server CLI (``daml damlc ide``) + * - Daml Language Server CLI (``daml damlc ide``) - Labs - - * - DAML Documentation Generation (``daml damlc docs``) + * - Daml Documentation Generation (``daml damlc docs``) - Labs - - * - :doc:`DAML Model Visualization ` (``daml damlc visual`` and ``daml damlc visual-web``) + * - :doc:`Daml Model Visualization ` (``daml damlc visual`` and ``daml damlc visual-web``) - Labs - * - ``daml doctest`` @@ -293,19 +293,19 @@ Developer Tools * - **Scenarios and Script** - - - * - Scenario DAML API + * - Scenario Daml API - Stable - - * - :doc:`Script DAML API ` + * - :doc:`Script Daml API ` - Stable - - * - DAML Scenario IDE integration + * - Daml Scenario IDE integration - Stable - - * - DAML Script IDE integration + * - Daml Script IDE integration - Stable - - * - :doc:`DAML Script Library ` + * - :doc:`Daml Script Library ` - See :ref:`libraries` - * - ``daml test`` in-memory Script and Scenario test CLI @@ -320,7 +320,7 @@ Developer Tools * - **Navigator** - - - * - :doc:`DAML Navigator Development UI ` (``daml navigator server``) + * - :doc:`Daml Navigator Development UI ` (``daml navigator server``) - Stable - * - Navigator Config File Creation (``daml navigator create-config``) @@ -329,13 +329,13 @@ Developer Tools * - Navigator graphQL Schema (``daml navigator dump-graphql-schema``) - Labs - - * - **DAML REPL Interactive Shell** + * - **Daml REPL Interactive Shell** - - * - ``daml repl`` :doc:`CLI ` - Stable - - * - :doc:`DAML and meta-APIs of the REPL ` + * - :doc:`Daml and meta-APIs of the REPL ` - Stable - * - **Ledger Administration CLI** diff --git a/docs/source/support/overview.rst b/docs/source/support/overview.rst index cd5c97b77c..6f3000495f 100644 --- a/docs/source/support/overview.rst +++ b/docs/source/support/overview.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Ecosystem Overview +Daml Ecosystem Overview ======================= .. toctree:: @@ -10,7 +10,7 @@ DAML Ecosystem Overview status-definitions component-statuses -This page is intended to give you an overview of the components that constitute the DAML Ecosystem, what status they are in, and how they fit together. It lays out DAML's "public API" in the sense of :ref:`Semantic Versioning `, and is a prerequisite to understanding DAML's :doc:`compatibility`. +This page is intended to give you an overview of the components that constitute the Daml Ecosystem, what status they are in, and how they fit together. It lays out Daml's "public API" in the sense of :ref:`Semantic Versioning `, and is a prerequisite to understanding Daml's :doc:`compatibility`. The pages :doc:`status-definitions` and :doc:`component-statuses` give a fine-grained view of what labels like "Alpha" and "Beta" mean, which components expose public APIs and what status they are in. @@ -19,36 +19,36 @@ The pages :doc:`status-definitions` and :doc:`component-statuses` give a fine-gr 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. +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. .. figure:: architecture.png -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. +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 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 command line interface of `DAML for Postgres `_. It's a public interface, but specific to the Postgres driver. +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 `_. 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`. +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 `_. 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. +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 `_. 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. +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 +Daml Connect ~~~~~~~~~~~~ Runtime Components @@ -59,14 +59,14 @@ Runtime components are standalone components that run alongside Participant Node 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`. +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. +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`. +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`. diff --git a/docs/source/support/releases.rst b/docs/source/support/releases.rst index 4a5aa09c2b..a756d034ed 100644 --- a/docs/source/support/releases.rst +++ b/docs/source/support/releases.rst @@ -9,7 +9,7 @@ Releases and Versioning Versioning ---------- -All DAML components follow `Semantic Versioning `_. In short, this means that there is a well defined "public API", changes or breakages to which are indicated by the version number. +All Daml components follow `Semantic Versioning `_. In short, this means that there is a well defined "public API", changes or breakages to which are indicated by the version number. Stable releases have versions MAJOR.MINOR.PATCH. Segments of the version are incremented according to the following rules: @@ -17,18 +17,18 @@ Stable releases have versions MAJOR.MINOR.PATCH. Segments of the version are inc #. MINOR version when functionality is added in a backwards compatible manner, and #. PATCH version when there are only backwards compatible bug fixes. -DAML's "public API" is laid out in the :doc:`overview`. +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 `_ as well as some others. +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 `_ as well as some others. Stable versions are released once a month. See :ref:`release_process` below for the usual schedule. This schedule is a guide, not a guarantee, and additional releases may be made, or releases may be delayed for skipped entirely. No more than one major version is released every six months, barring exceptional circumstances. -Individual DAML drivers follow their own release cadence, using already released Integration Components as a dependency. +Individual Daml drivers follow their own release cadence, using already released Integration Components as a dependency. .. _support_duration: @@ -42,27 +42,27 @@ Major versions will be supported for a minimum of one year after a subsequent Ma Release Notes ------------- -Release notes for each release are published on the `Release Notes section of the DAML Driven blog `_. +Release notes for each release are published on the `Release Notes section of the Daml Driven blog `_. .. _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 `_, or subscribe to the mailing list or social media profiles on `https://daml.com/ `_ to stay up to date. +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 `_, or subscribe to the mailing list or social media profiles on `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 `_ so only the schedule for monthly releases is covered here. +Weekly snapshot and monthly stable releases follow a regular process and schedule. The process is documented `in the Daml repository `_ so only the schedule for monthly releases is covered here. Selecting a Release Candidate - This is done by the DAML core engineering teams on the **first Monday of every month**. + This is done by the Daml core engineering teams on the **first Monday of every month**. - The monthly releases are time-based, not scope-based. Furthermore, DAML development is fully HEAD-based so both the repository and every snapshot are intended to be in a fully releasable state at every point. The release process therefore starts with "selecting a release candidate". Typically the Snapshot from the preceding Wednesday is selected as the release candidate. + The monthly releases are time-based, not scope-based. Furthermore, Daml development is fully HEAD-based so both the repository and every snapshot are intended to be in a fully releasable state at every point. The release process therefore starts with "selecting a release candidate". Typically the Snapshot from the preceding Wednesday is selected as the release candidate. Release Notes and Candidate Review diff --git a/docs/source/support/status-definitions.rst b/docs/source/support/status-definitions.rst index 4f34a7d776..82256ecc96 100644 --- a/docs/source/support/status-definitions.rst +++ b/docs/source/support/status-definitions.rst @@ -9,7 +9,7 @@ Throughout the documentation, we use labels to mark features of APIs not yet dee Early Access Features --------------------- -Features or components covered by these docs are :ref:`Stable ` by default. :ref:`Stable ` features and components constitute DAML's "public API" in the sense of :ref:`Semantic Versioning `. Feature and components that are not :ref:`Stable ` are called "Early Access" and called out explicitly. +Features or components covered by these docs are :ref:`Stable ` by default. :ref:`Stable ` features and components constitute Daml's "public API" in the sense of :ref:`Semantic Versioning `. Feature and components that are not :ref:`Stable ` are called "Early Access" and called out explicitly. Early Access features are opt-in whenever possible, needing to be activated with special commands or flags needing to be started up separately, or requiring the use of additional endpoints, for example. @@ -32,14 +32,14 @@ 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`. -Deprecated features can be relied upon during the deprecation cycle to the same degree as their non-deprecated counterparts, but building on deprecated features may hinder an upgrade to new DAML versions following the deprecation cycle. +Deprecated features can be relied upon during the deprecation cycle to the same degree as their non-deprecated counterparts, but building on deprecated features may hinder an upgrade to new Daml versions following the deprecation cycle. .. _status_definitions: Comparison of Statuses ---------------------- -The table below gives a concise overview of the labels used for DAML features and components. +The table below gives a concise overview of the labels used for Daml features and components. .. list-table:: Feature Maturities :widths: 10 20 20 20 20 @@ -73,8 +73,8 @@ The table below gives a concise overview of the labels used for DAML features an * - Compatibility - Compatibility is covered by :doc:`compatibility`. - Compatibility is covered by :doc:`compatibility`. - - The feature may only work against specific DAML integrations, or specific API versions, including Early Access ones. - - The feature may only work against specific DAML integrations, or specific API versions, including Early Access ones. + - The feature may only work against specific Daml integrations, or specific API versions, including Early Access ones. + - The feature may only work against specific Daml integrations, or specific API versions, including Early Access ones. * - Stability & Error Recovery - The feature is long-term stable and supports recovery fit for a production system. - No known reproducible crashes which can't be recovered from. There is still an expectation that new issues may be discovered. diff --git a/docs/source/support/support.rst b/docs/source/support/support.rst index 8008d229b5..1e9e162884 100644 --- a/docs/source/support/support.rst +++ b/docs/source/support/support.rst @@ -24,10 +24,10 @@ For community users (ie on our Forum and Stack Overflow): - **Timing**: You can enjoy the support of the community, which is provided for you out of their own good will and free time. On top of that, a Digital Asset employee will try to reply to unanswered questions within two business days. - Business days are affected by public holidays. Engineers contributing to DAML are mostly located in Zurich and New York, so please be mindful of the public holidays in those locations (`timeanddate.com `_ maintains an unofficial list of holidays for both `Switzerland `_ and the `United States `_). + Business days are affected by public holidays. Engineers contributing to Daml are mostly located in Zurich and New York, so please be mindful of the public holidays in those locations (`timeanddate.com `_ maintains an unofficial list of holidays for both `Switzerland `_ and the `United States `_). - **Public support**: We offer public support in the ``Questions`` category `on our forum `_. We can't answer questions in private messages or over email, so please only ask questions in public forums. -- **Level of support**: We're happy to answer questions about error messages you're encountering, or discuss DAML design questions. However, we can't provide more extensive consultation on how to build your DAML application or the languages, frameworks, libraries and tools you may use to build it. +- **Level of support**: We're happy to answer questions about error messages you're encountering, or discuss Daml design questions. However, we can't provide more extensive consultation on how to build your Daml application or the languages, frameworks, libraries and tools you may use to build it. -If you need private support, or want consultation from Digital Asset about how to build your DAML application, they offer paid support. Please contact Digital Asset to ask about pricing. +If you need private support, or want consultation from Digital Asset about how to build your Daml application, they offer paid support. Please contact Digital Asset to ask about pricing. diff --git a/docs/source/tools/assistant.rst b/docs/source/tools/assistant.rst index 3f84ffc26a..84a855ed3c 100644 --- a/docs/source/tools/assistant.rst +++ b/docs/source/tools/assistant.rst @@ -1,23 +1,23 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Assistant (``daml``) +Daml Assistant (``daml``) ######################### ``daml`` is a command-line tool that does a lot of useful things related to the SDK. Using ``daml``, you can: -- Create new DAML projects: ``daml new `` +- Create new Daml projects: ``daml new `` - Create a new project based on `create-daml-app `_: ``daml create-daml-app `` -- Initialize a DAML project: ``daml init`` -- Compile a DAML project: ``daml build`` +- Initialize a Daml project: ``daml init`` +- Compile a Daml project: ``daml build`` - This builds the DAML project according to the project config file ``daml.yaml`` (see `Configuration files`_ below). + This builds the Daml project according to the project config file ``daml.yaml`` (see `Configuration files`_ below). - In particular, it will download and install the specified version of the DAML Connect SDK (the ``sdk-version`` field in ``daml.yaml``) if missing, and use that SDK version to resolve dependencies and compile the DAML project. + In particular, it will download and install the specified version of the Daml Connect SDK (the ``sdk-version`` field in ``daml.yaml``) if missing, and use that SDK version to resolve dependencies and compile the Daml project. - Launch the tools in the SDK: - - Launch :doc:`DAML Studio `: ``daml studio`` + - Launch :doc:`Daml Studio `: ``daml studio`` - Launch :doc:`Sandbox `, :doc:`Navigator ` and the :doc:`/json-api/index`: ``daml start`` You can disable the HTTP JSON API by passing ``--json-api-port none`` to ``daml start``. To specify additional options for sandbox/navigator/the HTTP JSON API you can use @@ -26,7 +26,7 @@ DAML Assistant (``daml``) - Launch Navigator: ``daml navigator`` - Launch :doc:`Extractor `: ``daml extractor`` - Launch the :doc:`/json-api/index`: ``daml json-api`` - - Run :doc:`DAML codegen `: ``daml codegen`` + - Run :doc:`Daml codegen `: ``daml codegen`` - Install new SDK versions manually: ``daml install `` @@ -42,10 +42,10 @@ To see information about any command, run it with ``--help``. Configuration files ******************* -The DAML assistant and the SDK are configured using two files: +The Daml assistant and the SDK are configured using two files: - The global config file, one per installation, which controls some options regarding SDK installation and updates -- The project config file, one per DAML project, which controls how the SDK builds and interacts with the project +- The project config file, one per Daml project, which controls how the SDK builds and interacts with the project Global config file (``daml-config.yaml``) ========================================= @@ -71,9 +71,9 @@ Here is an example ``daml-config.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. +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. -The existence of a ``daml.yaml`` file is what tells ``daml`` that this directory contains a DAML project, and lets you use project-aware commands like ``daml build`` and ``daml start``. +The existence of a ``daml.yaml`` file is what tells ``daml`` that this directory contains a Daml project, and lets you use project-aware commands like ``daml build`` and ``daml start``. ``daml init`` creates a ``daml.yaml`` in an existing folder, so ``daml`` knows it's a project folder. @@ -117,19 +117,19 @@ Here is what each field means: Sandbox, Sandbox classic and the HTTP JSON API both when invoked directly via ``daml sandbox`` as well as when invoked via ``daml start``. Changing the platform version is useful if you deploy to a ledger that is running on a different SDK version than you use locally and you want to make - sure that you catch any issues during testing. E.g., you might compile your DAML code using - SDK 1.3.0 so you get improvements in DAML Studio but deploy to DABL which could still be running + sure that you catch any issues during testing. E.g., you might compile your Daml code using + SDK 1.3.0 so you get improvements in Daml Studio but deploy to DABL which could still be running a ledger and the JSON API from SDK 1.2.0. In that case, you can set ``sdk-version: 1.3.0`` and ``platform-version: 1.2.0``. It is possible to override the platform version by setting the ``DAML_PLATFORM_VERSION`` environment variable. - ``name``: the name of the project. This determines the filename of the ``.dar`` file compiled by ``daml build``. -- ``source``: the root folder of your DAML source code files relative to the project root. +- ``source``: the root folder of your Daml source code files relative to the project root. - ``scenario``: the name of the scenario to run when using ``daml start``. -- ``init-script``: the name of the DAML script to run when using ``daml start``. +- ``init-script``: the name of the Daml script to run when using ``daml start``. - ``parties``: the parties to display in the Navigator when using ``daml start``. - ``version``: the project version. -- ``exposed-modules``: the DAML modules that are exposed by this project, which can be imported in other projects. +- ``exposed-modules``: the Daml modules that are exposed by this project, which can be imported in other projects. If this field is not specified all modules in the project are exposed. - ``dependencies``: library-dependencies of this project. See :doc:`/daml/reference/packages`. - ``data-dependencies``: Cross-SDK dependencies of this project See :doc:`/daml/reference/packages`. @@ -149,7 +149,7 @@ Here is what each field means: - ``sandbox-options``: a list of options that will be passed to Sandbox in ``daml start``. - ``navigator-options``: a list of options that will be passed to Navigator in ``daml start``. - ``json-api-options``: a list of options that will be passed to the HTTP JSON API in ``daml start``. -- ``script-options``: a list of options that will be passed to the DAML script +- ``script-options``: a list of options that will be passed to the Daml script runner when running the ``init-script`` as part of ``daml start``. - ``start-navigator``: Controls whether navigator is started as part of ``daml start``. Defaults to ``true``. If this is specified as a CLI argument, @@ -160,10 +160,10 @@ Here is what each field means: .. _assistant-manual-building-dars: -Building DAML projects +Building Daml projects ********************** -To compile your DAML source code into a DAML archive (a ``.dar`` file), run:: +To compile your Daml source code into a Daml archive (a ``.dar`` file), run:: daml build @@ -189,7 +189,7 @@ Managing releases You can manage SDK versions manually by using ``daml install``. -To download and install SDK of the latest stable DAML Connect version:: +To download and install SDK of the latest stable Daml Connect version:: daml install latest @@ -218,7 +218,7 @@ See ``daml install --help`` for a full list of options. Terminal Command Completion *************************** -The ``daml`` assistant comes with support for ``bash`` and ``zsh`` completions. These will be installed automatically on Linux and Mac when you install or upgrade the DAML assistant. +The ``daml`` assistant comes with support for ``bash`` and ``zsh`` completions. These will be installed automatically on Linux and Mac when you install or upgrade the Daml assistant. If you use the ``bash`` shell, and your ``bash`` supports completions, you can use the TAB key to complete many ``daml`` commands, such as ``daml install`` and ``daml version``. diff --git a/docs/source/tools/codegen.rst b/docs/source/tools/codegen.rst index 9004d7bd7e..5783617b8a 100644 --- a/docs/source/tools/codegen.rst +++ b/docs/source/tools/codegen.rst @@ -1,20 +1,20 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML codegen +Daml codegen ############ Introduction ============ -You can use the DAML codegen to generate Java, Scala, and JavaScript/TypeScript classes representing DAML contract templates. +You can use the Daml codegen to generate Java, Scala, and JavaScript/TypeScript classes representing Daml contract templates. 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 +Running the Daml codegen ======================== -The basic command to run the DAML codegen is:: +The basic command to run the Daml codegen is:: $ daml codegen [java|scala|js] [options] @@ -54,7 +54,7 @@ Help for each specific codegen:: Project file configuration (Java and Scala) ------------------------------------------- -The above settings can be configured in the ``codegen`` element of the DAML project file +The above settings can be configured in the ``codegen`` element of the Daml project file ``daml.yaml``. See `this issue `_ for status on this feature. diff --git a/docs/source/tools/extractor.rst b/docs/source/tools/extractor.rst index 05a1bca5a4..58fbc3d3cc 100644 --- a/docs/source/tools/extractor.rst +++ b/docs/source/tools/extractor.rst @@ -103,7 +103,7 @@ Authorize Extractor If you are running Extractor against a Ledger API server that verifies authorization, you must provide the access token when you start it. -The access token retrieval depends on the specific DAML setup you are working with: please refer to the ledger operator to learn how. +The access token retrieval depends on the specific Daml setup you are working with: please refer to the ledger operator to learn how. Once you have retrieved your access token, you can provide it to Extractor by storing it in a file and provide the path to it using the ``--access-token-file`` command line option. @@ -170,7 +170,7 @@ Output format To understand the format that Extractor outputs into a PostgreSQL database, you need to understand how the ledger stores data. -The DAML Ledger is composed of transactions, which contain events. Events can represent: +The Daml Ledger is composed of transactions, which contain events. Events can represent: - creation of contracts (“create event”), or - exercise of a choice on a contract (“exercise event”). @@ -195,7 +195,7 @@ Transactions are stored in the ``transaction table`` in the ``public`` schema, w - **transaction_id**: The transaction ID, as appears on the ledger. This is the primary key of the table. - **transaction_id**, **effective_at, workflow_id, ledger_offset**: These columns are the properties of the transaction on the ledger. For more information, see the `specification <../../app-dev/grpc/proto-docs.html#transactiontree>`__. -- **seq**: Transaction IDs should be treated as arbitrary text values: you can’t rely on them for ordering transactions in the database. However, transactions appear on the Ledger API transaction stream in the same order as they were accepted on the ledger. You can use this to work around the arbitrary nature of the transaction IDs, which is the purpose of the ``seq`` field: it gives you a total ordering of the transactions, as they happened from the perspective of the ledger. Be aware that ``seq`` is not the exact index of the given transaction on the ledger. Due to the privacy model of DAML Ledgers, the transaction stream won’t deliver a transaction which doesn’t concern the party which is subscribed. The transaction with ``seq`` of 100 might be the 1000th transaction on the ledger; in the other 900, the transactions contained only events which mustn’t be seen by you. +- **seq**: Transaction IDs should be treated as arbitrary text values: you can’t rely on them for ordering transactions in the database. However, transactions appear on the Ledger API transaction stream in the same order as they were accepted on the ledger. You can use this to work around the arbitrary nature of the transaction IDs, which is the purpose of the ``seq`` field: it gives you a total ordering of the transactions, as they happened from the perspective of the ledger. Be aware that ``seq`` is not the exact index of the given transaction on the ledger. Due to the privacy model of Daml Ledgers, the transaction stream won’t deliver a transaction which doesn’t concern the party which is subscribed. The transaction with ``seq`` of 100 might be the 1000th transaction on the ledger; in the other 900, the transactions contained only events which mustn’t be seen by you. - **extracted_at**: The ``extracted_at`` field means the date the transaction row and its events were inserted into the database. When extracting historical data, this field will point to a possibly much later time than ``effective_at``. Contracts @@ -268,7 +268,7 @@ JSON schema are instantiated as follows in Extractor: Examples of output ****************** -The following examples show you what output you should expect. The Sandbox has already run the scenarios of a DAML model that created two transactions: one creating a ``Main:RightOfUseOffer`` and one accepting it, thus archiving the original contract and creating a new ``Main:RightOfUseAgreement`` contract. We also added a new offer manually. +The following examples show you what output you should expect. The Sandbox has already run the scenarios of a Daml model that created two transactions: one creating a ``Main:RightOfUseOffer`` and one accepting it, thus archiving the original contract and creating a new ``Main:RightOfUseAgreement`` contract. We also added a new offer manually. This is how the ``transaction`` table looks after extracting data from the ledger: @@ -411,7 +411,7 @@ The only parameters that you can change between two sessions running against the Fault tolerance *************** -Once the Extractor connects to the Ledger Node and the database and creates the table structure from the fetched DAML packages, it wraps the transaction stream in a restart logic with an exponential backoff. This results in the Extractor not terminating even when the transaction stream is aborted for some reason (the ledger node is down, there’s a network partition, etc.). +Once the Extractor connects to the Ledger Node and the database and creates the table structure from the fetched Daml packages, it wraps the transaction stream in a restart logic with an exponential backoff. This results in the Extractor not terminating even when the transaction stream is aborted for some reason (the ledger node is down, there’s a network partition, etc.). Once the connection is back, it continues the stream from where it left off. If it can’t reach the node on the host/port pair the Extractor was started with, you need to manually stop it and restart with the updated address. diff --git a/docs/source/tools/ledger-api-test-tool/index.rst b/docs/source/tools/ledger-api-test-tool/index.rst index e93dbaef84..724d501f1a 100644 --- a/docs/source/tools/ledger-api-test-tool/index.rst +++ b/docs/source/tools/ledger-api-test-tool/index.rst @@ -6,13 +6,13 @@ Ledger API Test Tool The Ledger API Test Tool is a command line tool for testing the correctness of implementations of the :doc:`Ledger API `, -i.e. DAML ledgers. For example, it +i.e. Daml ledgers. For example, it will show you if there are consistency or conformance problem with your implementation. -Its intended audience are developers of DAML ledgers, who are using the -DAML Ledger Implementation Kit to develop -a DAML ledger on top of their distributed-ledger or database of choice. +Its intended audience are developers of Daml ledgers, who are using the +Daml Ledger Implementation Kit to develop +a Daml ledger on top of their distributed-ledger or database of choice. Use this tool to verify if your Ledger API endpoint conforms to the :doc:`DA Ledger Model `. @@ -155,11 +155,11 @@ The test run will also produce a short summary of statistics which is printed to standard output by default but that can be written to a specific file path using the ``--perf-tests-report`` command line option. -Try out the Ledger API Test Tool against DAML Sandbox +Try out the Ledger API Test Tool against Daml Sandbox ===================================================== If you wanted to test out the tool, you can run it against -:doc:`DAML Sandbox `. To do this: +:doc:`Daml Sandbox `. To do this: .. code-block:: console @@ -179,7 +179,7 @@ test fails, and it will return a failure exit code when all tests succeed: ``java -jar ledger-api-test-tool.jar --must-fail localhost:6865`` -This is useful during development of a DAML ledger implementation, when tool +This is useful during development of a Daml ledger implementation, when tool needs to be used against a known-to-be-faulty implementation (e.g. in CI). It will still print information about failed tests. @@ -190,7 +190,7 @@ Use the command line option ``--timeout-scale-factor`` to tune timeouts applied by the tool. - Set ``--timeout-scale-factor`` to a floating point value higher than 1.0 to make - the tool wait longer for expected events coming from the DAML ledger + the tool wait longer for expected events coming from the Daml ledger implementation under test. Conversely use values smaller than 1.0 to make it wait shorter. @@ -225,7 +225,7 @@ Retired tests A few tests can be retired over time as they could be deemed not providing the necessary signal to a developer or operator that an integration correctly -implements the DAML Ledger API. Those test will nominally be kept in the +implements the Daml Ledger API. Those test will nominally be kept in the test suite for a time to prevent unwanted breakages of existing CI pipelines. They will however not be run and they will eventually be removed. You are advised to remove any explicit reference to those tests while they are in diff --git a/docs/source/tools/navigator/index.rst b/docs/source/tools/navigator/index.rst index 57ff28a73f..0d61df3c71 100644 --- a/docs/source/tools/navigator/index.rst +++ b/docs/source/tools/navigator/index.rst @@ -4,26 +4,26 @@ Navigator ######### -The Navigator is a front-end that you can use to connect to any DAML Ledger and inspect and modify the ledger. You can use it during DAML development to explore the flow and implications of the DAML models. +The Navigator is a front-end that you can use to connect to any Daml Ledger and inspect and modify the ledger. You can use it during Daml development to explore the flow and implications of the Daml models. 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 *********************** -Connect Navigator to any DAML Ledger and use it to: +Connect Navigator to any Daml Ledger and use it to: - View templates - View active and archived contracts - Exercise choices on contracts -- Advance time (This option applies only when using Navigator with the DAML Sandbox ledger.) +- Advance time (This option applies only when using Navigator with the Daml Sandbox ledger.) Installing and starting Navigator ********************************* Navigator ships with the SDK. To launch it: -1. Start Navigator via a terminal window running :doc:`DAML Assistant ` by typing ``daml start`` +1. Start Navigator via a terminal window running :doc:`Daml Assistant ` by typing ``daml start`` 2. The Navigator web-app is automatically started in your browser. If it fails to start, open a browser window and point it to the Navigator URL @@ -86,7 +86,7 @@ To log out, click the name of the current party in the top-right corner of the s Viewing templates or contracts ****************************** -DAML *contract ​templates* are ​models ​that contain ​the ​agreement ​statement, ​all ​the ​applicable +Daml *contract ​templates* are ​models ​that contain ​the ​agreement ​statement, ​all ​the ​applicable parameters, ​and ​the ​choices ​that ​can ​be ​made ​in ​acting ​on ​that ​data. They ​specify ​acceptable input ​and ​the ​resulting ​output. ​A ​contract ​template ​contains ​placeholders ​rather ​than ​actual names, ​amounts, ​dates, ​and ​so ​on. In ​a *contract*, ​the ​placeholders ​have ​been ​replaced ​with ​actual ​data. @@ -233,7 +233,7 @@ You will see the loading and confirmation indicators, as pictured above in Creat Advancing time ============== -It is possible to advance time against the DAML Sandbox. (This is not true of all DAML Ledgers.) This advance-time functionality can be useful when testing, for example, when entering a trade on one date and settling it on a later date. +It is possible to advance time against the Daml Sandbox. (This is not true of all Daml Ledgers.) This advance-time functionality can be useful when testing, for example, when entering a trade on one date and settling it on a later date. To advance time: @@ -254,7 +254,7 @@ Authorizing Navigator If you are running Navigator against a Ledger API server that verifies authorization, you must provide the access token when you start the Navigator server. -The access token retrieval depends on the specific DAML setup you are working with: please refer to the ledger operator to learn how. +The access token retrieval depends on the specific Daml setup you are working with: please refer to the ledger operator to learn how. Once you have retrieved your access token, you can provide it to Navigator by storing it in a file and provide the path to it using the ``--access-token-file`` command line option. @@ -275,7 +275,7 @@ Customizable table views ======================== Customizable table views is an advanced rapid-prototyping feature, -intended for DAML developers who wish to customize the Navigator UI without +intended for Daml developers who wish to customize the Navigator UI without developing a custom application. .. COMMENT: Suggest changing para below to procedure format. @@ -347,11 +347,11 @@ To debug config file errors and learn more about the config file API, open the Navigator ``/config`` page in your browser (e.g., ``_). -Using Navigator with a DAML Ledger +Using Navigator with a Daml Ledger ================================== By default, Navigator is configured to use an unencrypted connection to the ledger. -To run Navigator against a secured DAML Ledger, +To run Navigator against a secured Daml Ledger, configure TLS certificates using the ``--pem``, ``--crt``, and ``--cacrt`` command line parameters. Details of these parameters are explained in the command line help:: diff --git a/docs/source/tools/sandbox.rst b/docs/source/tools/sandbox.rst index 87a5ee696e..e3d1059681 100644 --- a/docs/source/tools/sandbox.rst +++ b/docs/source/tools/sandbox.rst @@ -3,16 +3,16 @@ .. _sandbox-manual: -DAML Sandbox +Daml Sandbox ############ -The DAML Sandbox, or Sandbox for short, is a simple ledger implementation that enables rapid application prototyping by simulating a DAML Ledger. +The Daml Sandbox, or Sandbox for short, is a simple ledger implementation that enables rapid application prototyping by simulating a Daml Ledger. -You can start Sandbox together with :doc:`Navigator ` using the ``daml start`` command in a DAML project. This command will compile the DAML file and its dependencies as specified in the ``daml.yaml``. It will then launch Sandbox passing the just obtained DAR packages. Sandbox will also be given the name of the startup scenario specified in the project's ``daml.yaml``. Finally, it launches the navigator connecting it to the running Sandbox. +You can start Sandbox together with :doc:`Navigator ` using the ``daml start`` command in a Daml project. This command will compile the Daml file and its dependencies as specified in the ``daml.yaml``. It will then launch Sandbox passing the just obtained DAR packages. Sandbox will also be given the name of the startup scenario specified in the project's ``daml.yaml``. Finally, it launches the navigator connecting it to the running Sandbox. It is possible to execute the Sandbox launching step in isolation by typing ``daml sandbox``. -Note: Sandbox has switched to use Wall Clock Time mode by default. To use Static Time Mode you can provide the ``--static-time`` flag to the ``daml sandbox`` command or configure the time mode for ``daml start`` in ``sandbox-options:`` section of ``daml.yaml``. Please refer to :ref:`DAML configuration files ` for more information. +Note: Sandbox has switched to use Wall Clock Time mode by default. To use Static Time Mode you can provide the ``--static-time`` flag to the ``daml sandbox`` command or configure the time mode for ``daml start`` in ``sandbox-options:`` section of ``daml.yaml``. Please refer to :ref:`Daml configuration files ` for more information. Sandbox can also be run manually as in this example: @@ -33,7 +33,7 @@ Here, ``daml sandbox`` tells the SDK Assistant to run ``sandbox`` from the activ .. note:: - The scenario is used for testing and development only, and is not supported by production DAML Ledgers. It is therefore inadvisable to rely on scenarios for ledger initialization. + The scenario is used for testing and development only, and is not supported by production Daml Ledgers. It is therefore inadvisable to rely on scenarios for ledger initialization. ``submitMustFail`` is only supported by the test-ledger used by ``daml test`` and the IDE, not by the Sandbox. @@ -81,7 +81,7 @@ Running with persistence ************************ Note: Running Sandbox with persistence is deprecated as of SDK 1.8.0 (16th Dec 2020). You can use the -DAML Driver for PostgreSQL instead. +Daml Driver for PostgreSQL instead. By default, Sandbox uses an in-memory store, which means it loses its state when stopped or restarted. If you want to keep the state, you can use a Postgres database for persistence. This allows you to shut down Sandbox and start it up later, continuing where it left off. @@ -333,7 +333,7 @@ These metrics are: - ``.exec`` (timer): time to run the query and read the result - ``.query`` (timer): time to run the query - ``.commit`` (timer): time to perform the commit -- ``.translation`` (timer): if relevant, time necessary to turn serialized DAML-LF values into in-memory objects +- ``.translation`` (timer): if relevant, time necessary to turn serialized Daml-LF values into in-memory objects List of metrics =============== @@ -378,7 +378,7 @@ further sent to deduplication and interpretation. ---------------------------- A timer. Time to validate submitted commands before they are -fed to the DAML interpreter. +fed to the Daml interpreter. ``daml.commands..input_buffer_capacity`` ---------------------------------------------------- @@ -415,7 +415,7 @@ the CommandService for a given party. --------------------------------- A timer. Time spent by the engine fetching the packages of compiled -DAML code necessary for interpretation. +Daml code necessary for interpretation. ``daml.execution.lookup_active_contract_count_per_execution`` ------------------------------------------------------------- @@ -529,8 +529,8 @@ they are served via the party management service. ``daml.index.db.load_archive`` ------------------------------ -A database metric. Time spent loading a package of compiled DAML code -so that it's given to the DAML interpreter when +A database metric. Time spent loading a package of compiled Daml code +so that it's given to the Daml interpreter when needed. ``daml.index.db.load_configuration_entries`` @@ -570,7 +570,7 @@ has been ultimately allocated. ---------------------------------------- A database metric. Time to fetch one contract on the index to be used by -the DAML interpreter to evaluate a command into a +the Daml interpreter to evaluate a command into a transaction. ``daml.index.db.lookup_configuration`` @@ -583,7 +583,7 @@ served via the configuration management service. ---------------------------------------- A database metric. Time to lookup one contract key on the index to be used by -the DAML interpreter to evaluate a command into a +the Daml interpreter to evaluate a command into a transaction. ``daml.index.db.lookup_flat_transaction_by_id`` @@ -634,7 +634,7 @@ successfully interpreted and is final. ``daml.index.db.store_package_entry`` ------------------------------------- -A database metric. Time spent storing a DAML package uploaded through +A database metric. Time spent storing a Daml package uploaded through the package management service. ``daml.index.db.store_party_entry`` diff --git a/docs/source/tools/trigger-service.rst b/docs/source/tools/trigger-service.rst index fc15423b02..8ee4c615a6 100644 --- a/docs/source/tools/trigger-service.rst +++ b/docs/source/tools/trigger-service.rst @@ -6,7 +6,7 @@ Trigger Service The Trigger Service is currently an :doc:`Early Access Feature in Alpha status `. At this time, the documentation is limited to basic usage. As more features become available the documentation will be updated to include them. We welcome feedback about the Trigger Service on our `our issue tracker `_, or `on our forum `_. -The `DAML triggers <../triggers/index.html#running-a-daml-trigger>`_ documentation shows a simple method using the ``daml trigger`` command to arrange for the execution of a single trigger. Using this method, a dedicated process is launched to host the trigger. +The `Daml triggers <../triggers/index.html#running-a-daml-trigger>`_ documentation shows a simple method using the ``daml trigger`` command to arrange for the execution of a single trigger. Using this method, a dedicated process is launched to host the trigger. Complex workflows can require running many triggers for many parties and at a certain point, use of ``daml trigger`` with its process per trigger model becomes unwieldy. The Trigger Service provides the means to host multiple triggers for multiple parties running against a common ledger in a single process and provides a convenient interface for starting, stopping and monitoring them. diff --git a/docs/source/tools/visual.rst b/docs/source/tools/visual.rst index efb1309ca7..ceed73e2bb 100644 --- a/docs/source/tools/visual.rst +++ b/docs/source/tools/visual.rst @@ -1,12 +1,12 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -Visualizing DAML Contracts +Visualizing Daml Contracts ########################## -Visualizing DAML Contracts is currently an :doc:`Early Access Feature in Labs status `. +Visualizing Daml Contracts is currently an :doc:`Early Access Feature in Labs status `. -You can generate visual graphs for the contracts in your DAML project. To do this: +You can generate visual graphs for the contracts in your Daml project. To do this: 1. Install `Graphviz `_. 2. Generate a DAR from your project by running ``daml build``. @@ -33,7 +33,7 @@ Running the above should produce an image which looks something like this: -Visualizing DAML Contracts - Within IDE +Visualizing Daml Contracts - Within IDE ======================================= You can generate visual graphs from VS Code IDE. Open the daml project in VS Code and use `command palette `_. Should reveal a new window pane with dot image. Also visual generates only the currently open daml file and its imports. @@ -41,10 +41,10 @@ You can generate visual graphs from VS Code IDE. Open the daml project in VS Cod Note: You will need to install the Graphviz/dot packages as mentioned above. -Visualizing DAML Contracts - Interactive Graphs +Visualizing Daml Contracts - Interactive Graphs =============================================== -This does not require any packages installed. You can generate `D3 `_ graphs for the contracts in your DAML project. To do this +This does not require any packages installed. You can generate `D3 `_ graphs for the contracts in your Daml project. To do this 1. Generate a DAR from your project by running ``daml build`` 2. Generate HTML file ``daml damlc visual-web .daml/dist/quickstart-0.0.1.dar -o quickstart.html`` diff --git a/docs/source/triggers/index.rst b/docs/source/triggers/index.rst index 8bf4c351cd..adfd332fc6 100644 --- a/docs/source/triggers/index.rst +++ b/docs/source/triggers/index.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -DAML Triggers - Off-Ledger Automation in DAML +Daml Triggers - Off-Ledger Automation in Daml ############################################# .. toctree:: @@ -9,13 +9,13 @@ DAML Triggers - Off-Ledger Automation in DAML api/index -DAML Triggers are currently an :doc:`Early Access Feature in Alpha status `. -We welcome feedback about DAML triggers on -`our issue tracker `_, +Daml Triggers are currently an :doc:`Early Access Feature in Alpha status `. +We welcome feedback about Daml triggers on +`our issue tracker `_, or `our forum `_. -In addition to the actual DAML logic which is uploaded to the Ledger -and the UI, DAML applications often need to automate certain +In addition to the actual Daml logic which is uploaded to the Ledger +and the UI, Daml applications often need to automate certain interactions with the ledger. This is commonly done in the form of a ledger client that listens to the transaction stream of the ledger and when certain conditions are met, e.g., when a template of a given type @@ -25,12 +25,12 @@ creates a template of another type. It is possible to write these clients in a language of your choice, e.g., JavaScript, using the HTTP JSON API. However, that introduces an additional layer of friction: You now need to translate between the -template and choice types in DAML and a representation of those DAML -types in the language you are using for your client. DAML triggers +template and choice types in Daml and a representation of those Daml +types in the language you are using for your client. Daml triggers address this problem by allowing you to write certain kinds of -automation directly in DAML reusing all the DAML types and logic that -you have already defined. Note that while the logic for DAML triggers -is written in DAML, they act like any other ledger client: They are +automation directly in Daml reusing all the Daml types and logic that +you have already defined. Note that while the logic for Daml triggers +is written in Daml, they act like any other ledger client: They are executed separately from the ledger, they do not need to be uploaded to the ledger and they do not allow you to do anything that any other ledger client could not do. @@ -60,7 +60,7 @@ Second, we have a template called ``Subscriber``: :end-before: -- SUBSCRIBER_TEMPLATE_END This template allows the ``subscriber`` to subscribe to ``Original`` s where ``subscribedTo`` is the ``owner``. -For each of these ``Original`` s, our DAML trigger should then automatically create an instance of +For each of these ``Original`` s, our Daml trigger should then automatically create an instance of third template called ``Copy``: .. literalinclude:: ./template-root/src/CopyTrigger.daml @@ -73,11 +73,11 @@ that we need to archive ``Copy`` contracts if there is more than one for the sam ``Copy`` contracts if the corresponding ``Original`` has been archived and we need to archive all ``Copy`` s for a given subscriber if the corresponding ``Subscriber`` contract has been archived. -Implementing a DAML Trigger +Implementing a Daml Trigger --------------------------- -Having defined what our DAML trigger is supposed to do, we can now -move on to its implementation. A DAML trigger is a regular DAML +Having defined what our Daml trigger is supposed to do, we can now +move on to its implementation. A Daml trigger is a regular Daml project that you can build using ``daml build``. To get access to the API used to build a trigger, you need to add the ``daml-triggers`` library to the ``dependencies`` field in ``daml.yaml``. @@ -89,7 +89,7 @@ library to the ``dependencies`` field in ``daml.yaml``. In addition to that you also need to import the ``Daml.Trigger`` module. -DAML triggers automatically track the active contract set (ACS), i.e., the set of contracts +Daml triggers automatically track the active contract set (ACS), i.e., the set of contracts that have been created and have not been archived, and the commands in flight for you. In addition to that, they allow you to have user-defined state that is updated based on new transactions and @@ -114,11 +114,11 @@ set. The ``updateState`` function is called on new transactions and command completions and can be used to update your user-defined state based on -the ACS and the transaction or completion. Since our DAML trigger does +the ACS and the transaction or completion. Since our Daml trigger does not have any interesting user-defined state, we will not go into details here. -The ``rule`` function is the core of a DAML trigger. It defines which +The ``rule`` function is the core of a Daml trigger. It defines which commands need to be sent to the ledger based on the party the trigger is executed at, the current state of the ACS, and the user defined state. The type ``TriggerA`` allows you to emit commands that are then sent to @@ -138,14 +138,14 @@ Finally, you can specify an optional heartbeat interval at which the trigger will be sent a ``MHeartbeat`` message. This is useful if you want to ensure that the trigger is executed at a certain rate to issue timed commands. -For our DAML trigger, the definition looks as follows: +For our Daml trigger, the definition looks as follows: .. literalinclude:: ./template-root/src/CopyTrigger.daml :language: daml :start-after: -- TRIGGER_BEGIN :end-before: -- TRIGGER_END -Now we can move on to the most complex part of our DAML trigger, the implementation of ``copyRule``. +Now we can move on to the most complex part of our Daml trigger, the implementation of ``copyRule``. First let’s take a look at the signature: .. literalinclude:: ./template-root/src/CopyTrigger.daml @@ -161,14 +161,14 @@ the ``subscribedTo`` field and the ``Copy`` contracts where we are the The commands in flight, retrievable with ``getCommandsInFlight``, will be useful to avoid sending the same command multiple times if ``copyRule`` is run multiple times before we get the corresponding -transaction. Note that DAML triggers are expected to be designed such +transaction. Note that Daml triggers are expected to be designed such that they can cope with this, e.g., after a restart or a crash where the commands in flight do not contain commands in flight from before the restart, so this is an optimization rather than something required for them to function correctly. First, we get all ``Subscriber``, ``Original`` and ``Copy`` contracts -from the ACS. For that, the DAML trigger API provides a ``query`` +from the ACS. For that, the Daml trigger API provides a ``query`` function that will return a list of all contracts of a given template. .. literalinclude:: ./template-root/src/CopyTrigger.daml @@ -226,7 +226,7 @@ submission failed. Finally, we also need to create copies that do not already exists. We want to avoid creating copies for which there is already a command in -flight. The DAML Trigger API provides a ``dedupCreate`` helper for this +flight. The Daml Trigger API provides a ``dedupCreate`` helper for this which only sends the commands if it is not already in flight. .. literalinclude:: ./template-root/src/CopyTrigger.daml @@ -234,12 +234,12 @@ which only sends the commands if it is not already in flight. :start-after: -- CREATE_COPIES_BEGIN :end-before: -- CREATE_COPIES_END -Running a DAML Trigger +Running a Daml Trigger ---------------------- To try this example out, you can replicate it using ``daml new copy-trigger --template copy-trigger``. You first have to build the trigger like -you would build a regular DAML project using ``daml build``. +you would build a regular Daml project using ``daml build``. Then start the sandbox and navigator using ``daml start``. Now we are ready to run the trigger using ``daml trigger``: @@ -266,14 +266,14 @@ have created as ``Alice``. Once you archive the ``Subscriber`` contract, you can see that the ``Copy`` contract will also be archived. -When using DAML triggers against a Ledger with authentication, you can +When using Daml triggers against a Ledger with authentication, you can pass ``--access-token-file token.jwt`` to ``daml trigger`` which will read the token from the file ``token.jwt``. -When not to use DAML triggers +When not to use Daml triggers ============================= -DAML Triggers are not suited for automation that needs to interact +Daml Triggers are not suited for automation that needs to interact with services or data outside of the ledger. For those cases, you can write a ledger client using the :doc:`JavaScript bindings ` @@ -281,6 +281,6 @@ running against the HTTP JSON API or the :doc:`Java bindings` running against the gRPC Ledger API. -DAML triggers deliberately only allow you to express automation that +Daml triggers deliberately only allow you to express automation that listens for ledger events and reacts to them by sending commands to the ledger. diff --git a/docs/source/upgrade/automation.rst b/docs/source/upgrade/automation.rst index 04ba9bee5e..88fda17a23 100644 --- a/docs/source/upgrade/automation.rst +++ b/docs/source/upgrade/automation.rst @@ -7,8 +7,8 @@ Automating the Upgrade Process ############################## In this section, we are going to automate the upgrade of our carbon certificate -process using :doc:`DAML Script` and -:doc:`DAML Triggers `. Note that automation for upgrades is +process using :doc:`Daml Script` and +:doc:`Daml Triggers `. Note that automation for upgrades is specific to an individual application, just like the upgrade models. Nevertheless, we have found that the pattern shown here occurs frequently. @@ -38,19 +38,19 @@ There are three kinds of actions performed during the upgrade: Given those constraints, we are going to use the following tools for the upgrade: -#. A DAML script that will be executed once by Alice and creates an +#. A Daml script that will be executed once by Alice and creates an ``UpgradeCarbonCertProposal`` contract for each owner. #. Navigator to accept the ``UpgradeCarbonCertProposal`` as Bob. While we - could also use a DAML script to accept the proposal, this step will + could also use a Daml script to accept the proposal, this step will often be exposed as part of a web UI so doing it interactively in Navigator resembles that workflow more closely. -#. A long-running DAML trigger that upgrades all ``CarbonCert`` contracts +#. A long-running Daml trigger that upgrades all ``CarbonCert`` contracts for which there is a corresponding ``UpgradeCarbonCertAgreement``. -Implementation of the DAML Script +Implementation of the Daml Script ================================= -In our DAML Script, we are first going to query the ACS (Active Contract Set) to find all +In our Daml Script, we are first going to query the ACS (Active Contract Set) to find all ``CarbonCert`` contracts issued by us. Next, we are going to extract the owner of each of those contracts and remove any duplicates coming from multiple certificates issued to the same owner. Finally, we iterate over the @@ -61,7 +61,7 @@ owners and create an ``UpgradeCarbonCertAgreement`` contract for each owner. :start-after: -- INITIATE_UPGRADE_BEGIN :end-before: -- INITIATE_UPGRADE_END -Implementation of the DAML Trigger +Implementation of the Daml Trigger ================================== Our trigger does not need any custom user state and no heartbeat so @@ -93,7 +93,7 @@ certificates of that owner. Deploying and Executing the Upgrade =================================== -Now that we defined our DAML script and our trigger, it is time to use +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, stop it to clear out all data before continuing. @@ -106,7 +106,7 @@ and ``carbon-2.0.0``. $ cd example/carbon-upgrade $ daml sandbox .daml/dist/carbon-upgrade-1.0.0.dar -To simplify the setup here, we use a DAML script to create 3 parties +To simplify the setup here, we use a Daml script to create 3 parties Alice, Bob and Charlie and two ``CarbonCert`` contracts issues by Alice, one owned by Bob and one owned by Charlie. diff --git a/docs/source/upgrade/extend.rst b/docs/source/upgrade/extend.rst index 6a9abbb966..5ef5bf8ef7 100644 --- a/docs/source/upgrade/extend.rst +++ b/docs/source/upgrade/extend.rst @@ -1,19 +1,19 @@ .. Copyright (c) 2021 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. .. SPDX-License-Identifier: Apache-2.0 -Extending DAML applications +Extending Daml applications ########################### .. toctree:: :hidden: -**Note:** Cross-SDK extensions require DAML-LF 1.8 or newer. +**Note:** Cross-SDK extensions require Daml-LF 1.8 or newer. This is the default starting from SDK 1.0. For older releases add ``build-options: ["--target=1.8"]`` to your ``daml.yaml`` to select -DAML-LF 1.8. +Daml-LF 1.8. -Consider the following simple DAML model for carbon certificates: +Consider the following simple Daml model for carbon certificates: .. literalinclude:: example/carbon-1.0.0/daml/CarbonV1.daml :language: daml @@ -26,9 +26,9 @@ certificate. And a second template to create the `CarbonCert` via a Now we want to extend this model to add trust labels for certificates by third parties. We don't want to make any changes to the already deployed -model. Changes to a DAML model will result in changed package ID's for the -contained templates. This means that if a DAML model is already deployed, the -modified DAML code will not be able to reference contracts instantiated with the +model. Changes to a Daml model will result in changed package ID's for the +contained templates. This means that if a Daml model is already deployed, the +modified Daml code will not be able to reference contracts instantiated with the old package. To avoid this problem, it's best to put extensions in a new package. @@ -43,7 +43,7 @@ template like The `CarbonLabel` template references the `CarbonCert` contract of the `carbon-1.0.0` packages by contract ID. Hence, we need to import the CarbonV1 module and add the `carbon-1.0.0` to the dependencies in the `daml.yaml` file. -Because we want to be independent of the DAML SDK used for both packages, we +Because we want to be independent of the Daml SDK used for both packages, we import the `carbon-1.0.0` package as data dependency .. literalinclude:: example/carbon-label/daml.yaml @@ -59,6 +59,6 @@ localhost: daml ledger upload-dar --ledger-port 6865 --ledger-host localhost ./daml/dist/carbon-label-1.0.0.dar -If instead of just extending a DAML model you want to modify an already deployed -template of your DAML model, you need to perform an upgrade of your DAML +If instead of just extending a Daml model you want to modify an already deployed +template of your Daml model, you need to perform an upgrade of your Daml application. This is the content of the next section. diff --git a/docs/source/upgrade/index.rst b/docs/source/upgrade/index.rst index 2836073ded..a59b6006d9 100644 --- a/docs/source/upgrade/index.rst +++ b/docs/source/upgrade/index.rst @@ -1,7 +1,7 @@ .. Copyright (c) 2021 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:: @@ -14,10 +14,10 @@ Upgrading and Extending DAML applications Database schemas tend to evolve over time. A new feature in your application might need an additional choice in one of your templates. Or a change in your data model will make you application perform better. We distinguish two kinds of -changes to a DAML model: +changes to a Daml model: - - A DAML model extension - - A DAML model upgrade + - A Daml model extension + - A Daml model upgrade An *extension* adds new templates and data structures to your model, while leaving all previously written definitions unchanged. @@ -26,5 +26,5 @@ An *upgrade* changes previously defined data structures and templates. Whether extension or upgrade, your new code needs to be compatible with data that is already live in a production system. The next two sections show how to -extend and upgrade DAML models. The last section shows how to automate the data +extend and upgrade Daml models. The last section shows how to automate the data migration process. diff --git a/docs/source/upgrade/upgrade.rst b/docs/source/upgrade/upgrade.rst index c33961f06b..ed142780e9 100644 --- a/docs/source/upgrade/upgrade.rst +++ b/docs/source/upgrade/upgrade.rst @@ -3,16 +3,16 @@ .. _upgrade-overview: -Upgrading DAML applications +Upgrading Daml applications ########################### .. toctree:: :hidden: -**Note:** Cross-SDK upgrades require DAML-LF 1.8 or newer. +**Note:** Cross-SDK upgrades require Daml-LF 1.8 or newer. This is the default starting from SDK 1.0. For older releases add ``build-options: ["--target=1.8"]`` to your ``daml.yaml`` to select -DAML-LF 1.8. +Daml-LF 1.8. In applications backed by a centralized database controlled by a single operator, it is possible to upgrade an application in a single @@ -49,26 +49,26 @@ While upgrading this centralized database is simple and convenient, its data entries lack any kind of signature and hence proof of authenticity. The data consumers need to trust the operator. -In contrast, DAML templates always have at least one signatory. The -consequence is that the upgrade process for a DAML application needs +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 +In a Daml application running on a distributed ledger, the signatories of a contract have agreed to one specific version of a template. Changing the definition of a template, e.g., by extending it with a new data field or choice without agreement from its signatories would -completely break the authorization guarantees provided by DAML. +completely break the authorization guarantees provided by Daml. -Therefore, DAML takes a different approach to upgrades and +Therefore, Daml takes a different approach to upgrades and extensions. Rather than having a separate concept of data migration -that sidesteps the fundamental guarantees provided by DAML, *upgrades -are expressed as DAML contracts*. This means that the same guarantees -and rules that apply to other DAML contracts also apply to upgrades. +that sidesteps the fundamental guarantees provided by Daml, *upgrades +are expressed as Daml contracts*. This means that the same guarantees +and rules that apply to other Daml contracts also apply to upgrades. -In a DAML application, it thus makes sense to think of upgrades as an +In a Daml application, it thus makes sense to think of upgrades as an *extension of an existing application* instead of an operation that replaces existing contracts with a newer version. The existing templates stay on the ledger and can still be used. Contracts of @@ -82,7 +82,7 @@ Structuring upgrade contracts Upgrade contracts are specific to the templates that are being upgraded. But most of them share common patterns. Here is the -implementation of the above ``carbon_certs`` schema in DAML. We have +implementation of the above ``carbon_certs`` schema in Daml. We have some prescience that there will be future versions of *CarbonCert*, and so place the definition of ``CarbonCert`` in a module named ``CarbonV1`` @@ -149,7 +149,7 @@ First we'll need a sandbox ledger to which we can deploy. $ daml sandbox --port 6865 Now we'll setup the project for the original version of our -certificate. The project contains the DAML for just the ``CarbonCert`` +certificate. The project contains the Daml for just the ``CarbonCert`` template, along with a ``CarbonCertProposal`` template which will allow us to issue some coins in the example below. @@ -237,7 +237,7 @@ be: ``../carbon-1.0.0/.daml/dist/carbon-1.0.0.dar``. :start-after: # BEGIN :end-before: # END -The DAML for the upgrade contracts imports the modules for both the new +The Daml for the upgrade contracts imports the modules for both the new and old certificate versions. diff --git a/docs/theme/da_theme_skeleton/static/images/DAML_Logo_Blue.svg b/docs/theme/da_theme_skeleton/static/images/DAML_Logo_Blue.svg index b0b81cf13a..b3117d02a8 100644 --- a/docs/theme/da_theme_skeleton/static/images/DAML_Logo_Blue.svg +++ b/docs/theme/da_theme_skeleton/static/images/DAML_Logo_Blue.svg @@ -1,29 +1,35 @@ - - - - - - - - - - - - - - - - - - + + + + + + + + + + + + + + + + + + diff --git a/docs/theme/docs/conf.py b/docs/theme/docs/conf.py index c6c91b80e3..a211c2d4a8 100644 --- a/docs/theme/docs/conf.py +++ b/docs/theme/docs/conf.py @@ -3,7 +3,7 @@ # -*- coding: utf-8 -*- # -# DAML SDK documentation build configuration file, created by +# Daml SDK documentation build configuration file, created by # sphinx-quickstart on Wed Jul 5 17:39:28 2017. # # This file is execfile()d with the current directory set to its @@ -54,7 +54,7 @@ source_suffix = '.rst' master_doc = 'index' # General information about the project. -project = u'DAML SDK' +project = u'Daml SDK' copyright = u'© Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited.' author = u'Digital Asset' @@ -146,7 +146,7 @@ latex_elements = { # (source start file, target name, title, # author, documentclass [howto, manual, or own class]). latex_documents = [ - (master_doc, 'DigitalAssetSDK.tex', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK.tex', u'Daml SDK Documentation', u'Digital Asset', 'manual'), ] @@ -156,7 +156,7 @@ latex_documents = [ # One entry per manual page. List of tuples # (source start file, name, description, authors, manual section). man_pages = [ - (master_doc, 'digitalassetsdk', u'DAML SDK Documentation', + (master_doc, 'digitalassetsdk', u'Daml SDK Documentation', [author], 1) ] @@ -167,13 +167,13 @@ man_pages = [ # (source start file, target name, title, author, # dir menu entry, description, category) texinfo_documents = [ - (master_doc, 'DigitalAssetSDK', u'DAML SDK Documentation', + (master_doc, 'DigitalAssetSDK', u'Daml SDK Documentation', author, 'DigitalAssetSDK', 'One line description of project.', 'Miscellaneous'), ] -# Import the DAML lexer +# Import the Daml lexer def setup(sphinx): from pygments_daml_lexer import DAMLLexer sphinx.add_lexer("daml", DAMLLexer()) diff --git a/ghc-lib/new-working-on-ghc-lib.md b/ghc-lib/new-working-on-ghc-lib.md index fba0b422c6..d7a85ffa3e 100644 --- a/ghc-lib/new-working-on-ghc-lib.md +++ b/ghc-lib/new-working-on-ghc-lib.md @@ -3,9 +3,9 @@ SPDX-License-Identifier: (Apache-2.0 OR BSD-3-Clause) # Working on `ghc-lib` -If you need to build, test, deploy or develop [`ghc-lib`](https://github.com/digital-asset/ghc-lib) as used by DAML and utilizing the Digital Asset [GHC fork](https://github.com/digital-asset/ghc) these notes are for you. +If you need to build, test, deploy or develop [`ghc-lib`](https://github.com/digital-asset/ghc-lib) as used by Daml and utilizing the Digital Asset [GHC fork](https://github.com/digital-asset/ghc) these notes are for you. -Here are instructions for when working on DAML surface syntax, as implemented in the the digital-assert fork of `ghc`. (linked in via `ghc-lib`). +Here are instructions for when working on Daml surface syntax, as implemented in the the digital-assert fork of `ghc`. (linked in via `ghc-lib`). ### Cloning the digital-assert fork of `ghc` @@ -49,12 +49,12 @@ The quickest way to build and test is: 2. `./_build/stage1/bin/ghc ./Example.hs -ddump-parsed | tee desugar.out` -Step 1 gives immediate feedback on build failures, but takes about 2-3 minutes when successful. For Step 2 you need a DAML example file. The input file must end in `.hs` suffix. It must begin with the pragma: `{-# LANGUAGE DamlSyntax #-}` +Step 1 gives immediate feedback on build failures, but takes about 2-3 minutes when successful. For Step 2 you need a Daml example file. The input file must end in `.hs` suffix. It must begin with the pragma: `{-# LANGUAGE DamlSyntax #-}` ### Building `daml` following a change to `ghc` -Once you have the GHC patch you want to incorporate into the DAML repo, here's the steps you'll need to take: +Once you have the GHC patch you want to incorporate into the Daml repo, here's the steps you'll need to take: 1. Open a PR in the daml repo with the commit hash for the GHC patch in `ci/da-ghc-lib/compile.yml`. See [here](https://github.com/digital-asset/daml/pull/7489/commits/fedc456260f598f9924ce62d9765c3c09b8ad861) diff --git a/ghc-lib/template-desugaring.md b/ghc-lib/template-desugaring.md index 9ea904b421..2b4db4c0ab 100644 --- a/ghc-lib/template-desugaring.md +++ b/ghc-lib/template-desugaring.md @@ -1,14 +1,14 @@ -# DAML template syntax desugaring +# Daml template syntax desugaring Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All Rights Reserved. SPDX-License-Identifier: (Apache-2.0 OR BSD-3-Clause) ## Introduction -DAML syntax describes contracts and the choices that operate on them. When DAML syntax is interpreted, the first step is to parse it to Haskell abstract syntax trees. +Daml syntax describes contracts and the choices that operate on them. When Daml syntax is interpreted, the first step is to parse it to Haskell abstract syntax trees. -This note shows how DAML examples are desugared by showing their Haskell source equivalents, and should help you understand the connection between DAML and Haskell. +This note shows how Daml examples are desugared by showing their Haskell source equivalents, and should help you understand the connection between Daml and Haskell. -## How DAML syntax desugars +## How Daml syntax desugars ### Example (1) @@ -35,7 +35,7 @@ template Iou create this with owner = newOwner ``` -The `class Template` (defined by the DAML standard library) represents the set of all contract types: +The `class Template` (defined by the Daml standard library) represents the set of all contract types: ```haskell class Template t where @@ -94,7 +94,7 @@ instance Template Iou where _templateTypeRep = magic @"_templateTypeRep" ``` -When a type `t` is a `Template` instance, `class Choice` (defined by the DAML standard library) defines a (multi-parameter type class) relation on types `t`, `c` and `r` such that `r` is uniquely determined by the pair `(t, c)`: +When a type `t` is a `Template` instance, `class Choice` (defined by the Daml standard library) defines a (multi-parameter type class) relation on types `t`, `c` and `r` such that `r` is uniquely determined by the pair `(t, c)`: ```haskell class Template t => Choice t c r | t c -> r where @@ -139,7 +139,7 @@ _choice_IouTransfer ### Example (2) -The next contract exercises the "contract keys" feature of DAML. +The next contract exercises the "contract keys" feature of Daml. Contract key syntax desugars to `instance` declarations of the following typeclass. ```haskell diff --git a/infra/README.md b/infra/README.md index e38cde6f0a..16f39e5500 100644 --- a/infra/README.md +++ b/infra/README.md @@ -1,6 +1,6 @@ -# DAML +# Daml -This is the terraform code used by the DAML repository to deploy supporting +This is the terraform code used by the Daml repository to deploy supporting infrastructure such as the Bazel caches, Nix caches and Azure Pipeline (VSTS) Agents. diff --git a/language-support/hs/bindings/README.md b/language-support/hs/bindings/README.md index 4d4ec016d5..5ff9f739b0 100644 --- a/language-support/hs/bindings/README.md +++ b/language-support/hs/bindings/README.md @@ -56,7 +56,7 @@ Also, in the instructions below we export the `daml-ledger` package to `/tmp` wh eval $(dev-env/bin/dade-assist) language-support/hs/bindings/export-package.sh /tmp -## Write a DAML Ledger App in Haskell (or copy one!), and build it +## Write a Daml Ledger App in Haskell (or copy one!), and build it cd /tmp cp -rp /tmp/daml/language-support/hs/bindings/examples/nim nim diff --git a/language-support/hs/bindings/examples/group-chat/README.md b/language-support/hs/bindings/examples/group-chat/README.md index 67d8fabf1e..778428707b 100644 --- a/language-support/hs/bindings/examples/group-chat/README.md +++ b/language-support/hs/bindings/examples/group-chat/README.md @@ -1,7 +1,7 @@ # `group-chat` -DAML Chat Room model, with support for: +Daml Chat Room model, with support for: - Multiple Chat Groups. - Group entry by invitation. @@ -43,9 +43,9 @@ Messages: - A Message is authorised by it's Sender and Recipients. (See discussion below.) -## Modelling with DAML +## Modelling with Daml -`GroupChat.daml` formalizes the above features in DAML. The essence of the model is as follows: +`GroupChat.daml` formalizes the above features in Daml. The essence of the model is as follows: - A Message is modelled by a simple `Message` contract. - A Group is modelled by a series of `Group` contracts, only one being active at a time. @@ -106,7 +106,7 @@ Without recipient authority on the messages, we get only (a) but not (b). Do we need the concept of group identity? -With group identity, we can use DAML contract-keys to ensure every group has a unique identity, allowing discovery. +With group identity, we can use Daml contract-keys to ensure every group has a unique identity, allowing discovery. In addition, we can embed the group identity in each message sent. The identity might be constructed from the creator party and a group-name. diff --git a/language-support/hs/bindings/examples/group-chat/daml/GroupChat.daml b/language-support/hs/bindings/examples/group-chat/daml/GroupChat.daml index b3ef0915db..388012a98e 100644 --- a/language-support/hs/bindings/examples/group-chat/daml/GroupChat.daml +++ b/language-support/hs/bindings/examples/group-chat/daml/GroupChat.daml @@ -3,7 +3,7 @@ --- DAML chat-room model, with support for multiple chat-groups with entry by invitation. +-- Daml chat-room model, with support for multiple chat-groups with entry by invitation. module GroupChat where diff --git a/language-support/hs/bindings/examples/nim/demo.md b/language-support/hs/bindings/examples/nim/demo.md index 290b5c48d7..3edcb2a170 100644 --- a/language-support/hs/bindings/examples/nim/demo.md +++ b/language-support/hs/bindings/examples/nim/demo.md @@ -148,7 +148,7 @@ Both Alice and Charlie are informed and can see the updated game state. Alice> move 1 2 1 command rejected by ledger:... requires controllers: Charlie, but only Alice were given... -Important to note: The ledger app has blindly submitted the move from the player. The check and rejection is performed entirely by the ledger, not the ledger app: the game logic is contained solely in the DAML model. +Important to note: The ledger app has blindly submitted the move from the player. The check and rejection is performed entirely by the ledger, not the ledger app: the game logic is contained solely in the Daml model. We also see the rejection in the terminal where we are running the sandbox. @@ -192,7 +192,7 @@ Seen in everyone's console: Bob> accept 2 -This event is seen in everyone's console, but not everyone sees all information! In particular, Alice sees only that the offer has been accepted (by someone), but not that the game has been started. This is the sub-transaction privacy semantics of DAML in action. +This event is seen in everyone's console, but not everyone sees all information! In particular, Alice sees only that the offer has been accepted (by someone), but not that the game has been started. This is the sub-transaction privacy semantics of Daml in action. ## 17. Bob goes on holiday, so replace him with Robot Bob diff --git a/language-support/java/codegen/README.md b/language-support/java/codegen/README.md index 8cebbc2da2..f82250c263 100644 --- a/language-support/java/codegen/README.md +++ b/language-support/java/codegen/README.md @@ -8,7 +8,7 @@ The codegen code source is provided with two sets of tests: - The standard tests (under ``src/test/java-*`` directory) which are based on dar files produced by ``daml-lf-encoder``. Hence those test do not - dependent on DAML compilers. Those tests are designed to test the codegen + dependent on Daml compilers. Those tests are designed to test the codegen with precise features of LF, even if the compiler do not support them. - The integration tests (under ``src/it/java-*`` directory) which are based on diff --git a/language-support/scala/codegen-sample-app/README.md b/language-support/scala/codegen-sample-app/README.md index 3524fae28d..10cb9c0907 100644 --- a/language-support/scala/codegen-sample-app/README.md +++ b/language-support/scala/codegen-sample-app/README.md @@ -5,7 +5,7 @@ is not part of the project defined in `ledger-client/build.sbt`. _It is a standalone project_ -This project contains a sample DAML library (in `src/main/daml/Main.daml`) +This project contains a sample Daml library (in `src/main/daml/Main.daml`) and the Scala sources generated from that library. ## Regenerating the sources diff --git a/language-support/scala/codegen/README.md b/language-support/scala/codegen/README.md index 97ee511fa4..cd879933b2 100644 --- a/language-support/scala/codegen/README.md +++ b/language-support/scala/codegen/README.md @@ -1,14 +1,14 @@ -# Developer's guide to DAML Scala code generator +# Developer's guide to Daml Scala code generator For the User's guide to the Scala code generator see: `docs/daml-scala-code-gen-user-guide.rst` ## Introduction -The DAML Scala code generator produces wrapper classes that correspond to DAML -contract templates and DAML user defined types (records/variants that are the -right hand side of a DAML type synonym). They are intended to be used by application -developers and they provide the same level of type safety as the DAML langauge +The Daml Scala code generator produces wrapper classes that correspond to Daml +contract templates and Daml user defined types (records/variants that are the +right hand side of a Daml type synonym). They are intended to be used by application +developers and they provide the same level of type safety as the Daml langauge itself. ## Working with Scala macros diff --git a/language-support/scala/examples/iou-no-codegen/README.md b/language-support/scala/examples/iou-no-codegen/README.md index 40c5c5eeab..99ba4b2ac6 100644 --- a/language-support/scala/examples/iou-no-codegen/README.md +++ b/language-support/scala/examples/iou-no-codegen/README.md @@ -8,7 +8,7 @@ This example demonstrates how to: This examples requires a running sandbox. ## To start a sandbox running IOU example -- create a new DAML Assistant `quickstart-scala` project +- create a new Daml Assistant `quickstart-scala` project ``` $ daml new quickstart-scala --template quickstart-scala ``` diff --git a/language-support/scala/examples/quickstart-scala/README.md b/language-support/scala/examples/quickstart-scala/README.md index 3431708cb3..8cb82545ec 100644 --- a/language-support/scala/examples/quickstart-scala/README.md +++ b/language-support/scala/examples/quickstart-scala/README.md @@ -6,7 +6,7 @@ This example demonstrates how to: - how to exercise a choice and send a corresponding exercise command - subscribe to receive ledger events and decode them into generated Scala ADTs -All instructions below assume that you have the DAML Connect SDK installed. If you have not installed it yet, please follow these instructions: https://docs.daml.com/getting-started/installation.html +All instructions below assume that you have the Daml Connect SDK installed. If you have not installed it yet, please follow these instructions: https://docs.daml.com/getting-started/installation.html ## Create a quickstart-scala project ``` @@ -20,8 +20,8 @@ Where: - `./quickstart-scala` is a project directory name - `quickstart-scala` is a project template name, to see the entire list of available templates, run: `daml new --list` -## Compile the DAML project -The DAML code for the IOU example is located in the `./daml` folder. Run the following command to build it: +## Compile the Daml project +The Daml code for the IOU example is located in the `./daml` folder. Run the following command to build it: ``` $ cd ./quickstart-scala $ daml build @@ -32,7 +32,7 @@ Compiling quickstart to a DAR. Created .daml/dist/quickstart-0.0.1.dar. ``` -## Generate Scala classes representing DAML contract templates +## Generate Scala classes representing Daml contract templates ``` $ daml codegen scala ``` @@ -67,7 +67,7 @@ If example completes successfully, the above process should terminate and the ou [success] Total time: 7 s, completed Sep 12, 2019, 11:54:04 AM ``` -To run the quickstart-scala as a standalone project (not part of the DAML project), you can specify `da.sdk.version` JVM system properties: +To run the quickstart-scala as a standalone project (not part of the Daml project), you can specify `da.sdk.version` JVM system properties: ``` $ sbt -Dda.sdk.version= "application/runMain com.daml.quickstart.iou.IouMain localhost 6865" ``` diff --git a/language-support/ts/codegen/README.md b/language-support/ts/codegen/README.md index 3c8b70cc0d..7439a36913 100644 --- a/language-support/ts/codegen/README.md +++ b/language-support/ts/codegen/README.md @@ -1,6 +1,6 @@ # daml2js -This is a code generator for a TypeScript interface to a DAML package. To run it, you must execute +This is a code generator for a TypeScript interface to a Daml package. To run it, you must execute ```console $ bazel run //:daml2js Usage: daml2js DAR-FILE -o DIR @@ -70,7 +70,7 @@ bazel run //language-support/ts/codegen:daml2js -- -o ~/tmp/davl/daml2js ~/proje ## What `daml2js` generates -The DAML SDK documentation contains [a page](https://github.com/digital-asset/daml/tree/main/docs/source/daml2js) on `daml2js`. It is recommended that you start with this. The remainder of this section contains additional detail (mostly about serialization code). The code that `daml2js` generates uses the [@daml/types](https://github.com/digital-asset/daml/tree/main/language-support/ts/daml-types) and [@mojotech/json-type-validation](https://github.com/mojotech/json-type-validation) libraries. All TypeScript modules generated by `daml2js` begin with the following fragment: +The Daml SDK documentation contains [a page](https://github.com/digital-asset/daml/tree/main/docs/source/daml2js) on `daml2js`. It is recommended that you start with this. The remainder of this section contains additional detail (mostly about serialization code). The code that `daml2js` generates uses the [@daml/types](https://github.com/digital-asset/daml/tree/main/language-support/ts/daml-types) and [@mojotech/json-type-validation](https://github.com/mojotech/json-type-validation) libraries. All TypeScript modules generated by `daml2js` begin with the following fragment: ```typescript import * as jtv from '@mojotech/json-type-validation'; import * as daml from '@daml/types'; @@ -96,7 +96,7 @@ See the [SDK docs](https://github.com/digital-asset/daml/tree/main/docs/source/d #### Records -In DAML, define `Person` like so. +In Daml, define `Person` like so. ```haskell data Person = @@ -122,11 +122,11 @@ export const Person: daml.Serializable = ({ }), }) ``` -Two elements have been generated from the DAML type definition : (1) a TypeScript equivalent type and (2) a companion object for type-validating serialization over the json-api. +Two elements have been generated from the Daml type definition : (1) a TypeScript equivalent type and (2) a companion object for type-validating serialization over the json-api. #### Variants -A type of additive expressions in DAML. +A type of additive expressions in Daml. ```haskell data Expr a = Lit a @@ -217,7 +217,7 @@ Corresponding to the `Add2` constructor we see the definition of an `Add2` type #### Enums -A DAML enumeration. +A Daml enumeration. ```haskell data Color = Red | Blue | Yellow diff --git a/language-support/ts/daml-ledger/README.md b/language-support/ts/daml-ledger/README.md index 3fffc97d20..8e3005144c 100644 --- a/language-support/ts/daml-ledger/README.md +++ b/language-support/ts/daml-ledger/README.md @@ -1,7 +1,7 @@ # @daml/ledger -> Client side API implementation for a DAML based ledgers. This library implements the [JSON -> API](https://docs.daml.com/json-api/index.html) for a DAML ledger. +> Client side API implementation for a Daml based ledgers. This library implements the [JSON +> API](https://docs.daml.com/json-api/index.html) for a Daml ledger. ## Documentation @@ -10,19 +10,19 @@ Comprehensive documentation for `@daml/ledger` can be found ## Usage -The best way to get you started quickly is to look at [Create DAML +The best way to get you started quickly is to look at [Create Daml App](https://github.com/digital-asset/create-daml-app) and to read the [Quickstart Guide](https://docs.daml.com/getting-started/quickstart.html). We recommend to use the [React](https://reactjs.org) framework and the `@daml/react` library to -build frontends for DAML applications. If you choose a different Javascript based framework, please +build frontends for Daml applications. If you choose a different Javascript based framework, please take a look at the source of `@daml/react` and it's usage of the `@daml/ledger` library. The main export of `@daml/ledger` is the `Ledger` class. It's constructor takes an authentication token used to communicate with the [JSON API](https://docs.daml.com/json-api/index.html), an HTTP base URL and a websocket base URL. -An instance of the `Ledger` class provides the following methods to communicate with a DAML ledger. +An instance of the `Ledger` class provides the following methods to communicate with a Daml ledger. Please consult the [documentation](https://docs.daml.com/app-dev/bindings-ts/daml-ledger/classes/_index_.ledger.html) for their exact signatures. diff --git a/language-support/ts/daml-ledger/index.ts b/language-support/ts/daml-ledger/index.ts index d8045cf3bd..9920bb7e9a 100644 --- a/language-support/ts/daml-ledger/index.ts +++ b/language-support/ts/daml-ledger/index.ts @@ -267,7 +267,7 @@ export interface Stream { } /** - * Options for creating a handle to a DAML ledger. + * Options for creating a handle to a Daml ledger. */ type LedgerOptions = { /** JSON web token used for authentication. */ @@ -294,7 +294,7 @@ type LedgerOptions = { } /** - * An object of type `Ledger` represents a handle to a DAML ledger. + * An object of type `Ledger` represents a handle to a Daml ledger. */ class Ledger { private readonly token: string; diff --git a/language-support/ts/daml-react/README.md b/language-support/ts/daml-react/README.md index 5fc2b95609..d5ab0eb046 100644 --- a/language-support/ts/daml-react/README.md +++ b/language-support/ts/daml-react/README.md @@ -1,6 +1,6 @@ # @daml/react -> React framework for DAML applications +> React framework for Daml applications ## Documentation @@ -8,12 +8,12 @@ Comprehensive documentation for `@daml/react` can be found [here](https://docs.d ## Usage -The best way to get you started quickly is to look at [Create DAMLApp](https://github.com/digital-asset/create-daml-app) +The best way to get you started quickly is to look at [Create Daml App](https://github.com/digital-asset/create-daml-app) and to read the [QuickstartGuide](https://docs.daml.com/getting-started/quickstart.html). -To get an overview on how to build a DAML application, please read the [application architecture overview](https://docs.daml.com/app-dev/app-arch.html). +To get an overview on how to build a Daml application, please read the [application architecture overview](https://docs.daml.com/app-dev/app-arch.html). -To use `@daml/react` your application needs to be connected to the JSON API of a DAML ledger. If +To use `@daml/react` your application needs to be connected to the JSON API of a Daml ledger. If your JSON API server for the ledger runs on the local host on port 7575, set ``` json @@ -38,7 +38,7 @@ const App: React.FC = () => { }; ``` -Now you can use the following React hooks to interact with a DAML ledger: +Now you can use the following React hooks to interact with a Daml ledger: `useParty` ---------- @@ -50,7 +50,7 @@ const party = useParty(); `useLedger` ------------- -`useLedger` returns an instance of the `Ledger` class of [@daml/ledger](https://docs.daml.com/app-dev/bindings-ts/daml-ledger/index.html) to interact with the DAML +`useLedger` returns an instance of the `Ledger` class of [@daml/ledger](https://docs.daml.com/app-dev/bindings-ts/daml-ledger/index.html) to interact with the Daml ledger. ```typescript diff --git a/language-support/ts/daml-react/createLedgerContext.ts b/language-support/ts/daml-react/createLedgerContext.ts index 222a0d004f..d2971f93e8 100644 --- a/language-support/ts/daml-react/createLedgerContext.ts +++ b/language-support/ts/daml-react/createLedgerContext.ts @@ -18,7 +18,7 @@ type DamlLedgerState = { } /** - * React props to initiate a connect to a DAML ledger. + * React props to initiate a connect to a Daml ledger. */ export type LedgerProps = { token: string; @@ -57,7 +57,7 @@ export type FetchByKeysResult = { } /** - * A LedgerContext is a React context that stores information about a DAML Ledger + * A LedgerContext is a React context that stores information about a Daml Ledger * and hooks necessary to use it. */ export type LedgerContext = { diff --git a/language-support/ts/daml-react/defaultLedgerContext.ts b/language-support/ts/daml-react/defaultLedgerContext.ts index 4ee4ece76e..93bb669fc7 100644 --- a/language-support/ts/daml-react/defaultLedgerContext.ts +++ b/language-support/ts/daml-react/defaultLedgerContext.ts @@ -25,7 +25,7 @@ export function DamlLedger(props: React.PropsWithChildren): React.R export function useParty(): Party { return ledgerContext.useParty(); } /** - * React Hook that returns the Ledger instance to interact with the connected DAML ledger. + * React Hook that returns the Ledger instance to interact with the connected Daml ledger. */ export function useLedger(): Ledger { return ledgerContext.useLedger(); } diff --git a/language-support/ts/daml-types/README.md b/language-support/ts/daml-types/README.md index d4320e1176..03c517e2c9 100644 --- a/language-support/ts/daml-types/README.md +++ b/language-support/ts/daml-types/README.md @@ -1,6 +1,6 @@ # @daml/types -> Primitive types of the DAML language and their serialization. +> Primitive types of the Daml language and their serialization. ## Documentation @@ -9,11 +9,11 @@ Comprehensive documentation for `@daml/types` can be found ## Description -This library contains TypeScript types corresponding to primitive DAML data types, such as +This library contains TypeScript types corresponding to primitive Daml data types, such as `Template`, `ContractId`, `Int`, `Text` etc. as well as their encoders and decoders to interact with -the [JSON API](https://docs.daml.com/json-api/index.html) of a DAML ledger. +the [JSON API](https://docs.daml.com/json-api/index.html) of a Daml ledger. -For creating a DAML distributed application, you'll most likely want to use the +For creating a Daml distributed application, you'll most likely want to use the [@daml/react](https://www.npmjs.com/package/@daml/react) and [@daml/ledger](https://www.npmjs.com/package/@daml/ledger) packages. diff --git a/language-support/ts/daml-types/index.ts b/language-support/ts/daml-types/index.ts index fff8f7c2bd..a2f11af56f 100644 --- a/language-support/ts/daml-types/index.ts +++ b/language-support/ts/daml-types/index.ts @@ -21,8 +21,8 @@ export interface Serializable { } /** - * Interface for objects representing DAML templates. It is similar to the - * `Template` type class in DAML. + * Interface for objects representing Daml templates. It is similar to the + * `Template` type class in Daml. * * @typeparam T The template type. * @typeparam K The contract key type. @@ -47,7 +47,7 @@ export interface Template(template: Template): void export const lookupTemplate = (templateId: string): Template => { const template = registeredTemplates[templateId]; if (template === undefined) { - throw Error(`Failed to look up template ${templateId}. Make sure your @daml/types version agrees with the used DAML SDK version.`); + throw Error(`Failed to look up template ${templateId}. Make sure your @daml/types version agrees with the used Daml SDK version.`); } return template; } @@ -139,7 +139,7 @@ export function lazyMemo(mkDecoder: () => jtv.Decoder): jtv.Decoder { } /** - * The counterpart of DAML's `()` type. + * The counterpart of Daml's `()` type. */ // eslint-disable-next-line @typescript-eslint/no-empty-interface export interface Unit { @@ -161,7 +161,7 @@ export const Unit: Serializable = { } /** - * The counterpart of DAML's `Bool` type. + * The counterpart of Daml's `Bool` type. */ export type Bool = boolean; @@ -174,7 +174,7 @@ export const Bool: Serializable = { } /** - * The counterpart of DAML's `Int` type. + * The counterpart of Daml's `Int` type. * * We represent `Int`s as string in order to avoid a loss of precision. */ @@ -189,7 +189,7 @@ export const Int: Serializable = { } /** - * The counterpart of DAML's `Numeric` type. + * The counterpart of Daml's `Numeric` type. * * We represent `Numeric`s as string in order to avoid a loss of precision. The string must match * the regular expression `-?(?:0|[1-9]\d*)(?:\.\d+)?(?:[eE][+-]?\d+)?`. @@ -197,9 +197,9 @@ export const Int: Serializable = { export type Numeric = string; /** - * The counterpart of DAML's `Decimal` type. + * The counterpart of Daml's `Decimal` type. * - * In DAML, Decimal's are the same as Numeric with precision 10. + * In Daml, Decimal's are the same as Numeric with precision 10. * */ export type Decimal = Numeric; @@ -220,7 +220,7 @@ export const Numeric = (_: number): Serializable => export const Decimal: Serializable = Numeric(10) /** - * The counterpart of DAML's `Text` type. + * The counterpart of Daml's `Text` type. */ export type Text = string; @@ -233,7 +233,7 @@ export const Text: Serializable = { } /** - * The counterpart of DAML's `Time` type. + * The counterpart of Daml's `Time` type. * * We represent `Times`s as strings with format `YYYY-MM-DDThh:mm:ss[.ssssss]Z`. */ @@ -248,7 +248,7 @@ export const Time: Serializable