From 96fb3be3e31338dd9bc0febf1bdc9c5c78d96d52 Mon Sep 17 00:00:00 2001 From: Stefano Baghino <43749967+stefanobaghino-da@users.noreply.github.com> Date: Wed, 26 Oct 2022 18:02:13 +0200 Subject: [PATCH] Add intro page for off-ledger automation with Daml (#15362) * Add intro page for off-ledger automation with Daml This is meant as a page to introduce Daml Script (as an off-ledger automation tool) and Daml Triggers. This will require this page to be added to the table of contents in the appropriate place in a separate PR in the documentation repository. changelog_begin changelog_end * Apply suggestions from code review Co-authored-by: carrielaben-da <91496516+carrielaben-da@users.noreply.github.com> * Rephrase, reformat Co-authored-by: carrielaben-da <91496516+carrielaben-da@users.noreply.github.com> --- docs/source/daml-off-ledger.rst | 31 +++++++++++++++++++++++++++++++ 1 file changed, 31 insertions(+) create mode 100644 docs/source/daml-off-ledger.rst diff --git a/docs/source/daml-off-ledger.rst b/docs/source/daml-off-ledger.rst new file mode 100644 index 0000000000..ff9b6f4246 --- /dev/null +++ b/docs/source/daml-off-ledger.rst @@ -0,0 +1,31 @@ +.. Copyright (c) 2022 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. +.. SPDX-License-Identifier: Apache-2.0 + +Write Off-Ledger Automation Using Daml +====================================== + +The Daml smart contract language is mostly meant to provide a way to define on-ledger logic, i.e. +code that defines how a transaction happens on ledger. Daml is not meant to be used as a general +purpose language that can interact with your file system or network; instead, the templates and +choices defined with Daml are available to be used by off-ledger logic that interacts with the +ledger API. Usually this off-ledger logic is written in a general-purpose language like Java or +JavaScript and the codegen allows to interact with models defined in Daml without boilerplate. + +However, there are times when it would be nice to write your off-ledger logic in Daml. For +relatively simple automations that don't require full access to your system's capabilities, +using Daml means that you don't have to map from your on-ledger Daml types and their +representation on a separate off-ledger general purpose language (either through the codegen +or by manipulating the Protobuf representation of Daml types directly). + +There are two tools that allow you to use Daml as an off-ledger language: + +- :doc:`Daml Script` allows you to write automations that can be triggered + by any off-ledger condition, such as the availability of a file in a folder, a message + coming from a broker or a user interacting with the system directly. + +- :doc:`Daml Triggers` allow a similar approach but + triggered by on-ledger events, such as the creation of a contract. + +In their interactions with a traditional database system Daml Scripts and Daml +Triggers are analogous to SQL scripts and SQL triggers. +