DAML SDK Documentation Digital Asset Version : 1.3.0-snapshot.20200706.4664.0.5db06051 0 Copyright 2020 Digital Asset (Switzerland) GmbH and/or its affiliates. All rights reserved. Any unauthorized use, duplication or distribution is strictly prohibited. Table of contents Table of contents i 1 Getting started 1 1.1 Installing the SDK ............................................. 1 1.1.1 1. Install the dependencies .................................. 1 1.1.2 2. Install the SDK ......................................... 3 1.1.3 Next steps ............................................. 3 1.1.4 Alternative: manual download ................................ 3 1.2 Getting Started with DAML ........................................ 5 1.2.1 Prerequisites ........................................... 5 1.2.2 Running the app ......................................... 5 1.3 Testing Your App .............................................. 8 1.3.1 Setting up our tests ....................................... 9 1.3.2 Example: Logging in and out ................................. 9 1.3.3 Accessing UI elements ..................................... 10 1.3.4 Writing CSS Selectors ...................................... 10 1.3.5 The Full Test Suite ........................................ 10 2 Writing DAML 12 2.1 An introduction to DAML ......................................... 12 2.1.1 1 Basic contracts ......................................... 12 2.1.2 2 Testing templates using scenarios ............................ 14 2.1.3 3 Data types ............................................ 19 2.1.4 4 Transforming data using choices ............................. 34 2.1.5 5 Adding constraints to a contract ............................. 40 2.1.6 6 Parties and authority ..................................... 49 2.1.7 7 Composing choices ...................................... 58 2.2 Language reference docs ......................................... 66 2.2.1 Overview: template structure ................................. 66 2.2.2 Reference: templates ...................................... 69 2.2.3 Reference: choices ........................................ 72 2.2.4 Reference: updates ....................................... 76 2.2.5 Reference: data types ...................................... 80 2.2.6 Reference: built-in functions ................................. 86 2.2.7 Reference: expressions ..................................... 88 2.2.8 Reference: functions ...................................... 91 2.2.9 Reference: scenarios ...................................... 93 2.2.10 Reference: DAML file structure ................................ 94 2.2.11 Reference: DAML packages .................................. 95 2.2.12 Contract keys ........................................... 102 i 2.3 DAML Studio ................................................. 108 2.3.1 Installing .............................................. 108 2.3.2 Creating your first DAML file ................................. 108 2.3.3 Supported features ....................................... 110 2.3.4 Common scenario errors .................................... 113 2.3.5 Working with multiple packages .............................. 116 2.4 Testing using scenarios ......................................... 117 2.4.1 Scenario syntax .......................................... 118 2.4.2 Running scenarios in DAML Studio ............................. 118 2.4.3 Examples .............................................. 118 2.5 Troubleshooting ............................................... 120 2.5.1 Error: 0<X> is not authorized to commit an update0 .................. 120 2.5.2 Error 0Argument is not of serializable type0 ....................... 121 2.5.3 Modelling questions ....................................... 121 2.5.4 Testing questions ........................................ 123 2.6 Good design patterns ........................................... 124 2.6.1 Initiate and Accept ........................................ 124 2.6.2 Multiple party agreement ................................... 126 2.6.3 Delegation ............................................. 128 2.6.4 Authorization ........................................... 131 2.6.5 Locking ............................................... 133 2.6.6 Diagram legends ......................................... 141 3 Building applications 143 3.1 Application architecture ......................................... 143 3.1.1 Backend .............................................. 145 3.1.2 Frontend .............................................. 145 3.1.3 Authentication .......................................... 146 3.1.4 Developer workflow ....................................... 146 3.2 JavaScript Client Libraries ........................................ 148 3.2.1 JavaScript Code Generator ................................... 148 3.2.2 @daml/react ........................................... 153 3.2.3 @daml/ledger ........................................... 153 3.2.4 @daml/types ........................................... 153 3.3 HTTP JSON API Service ........................................... 153 3.3.1 DAML-LF JSON Encoding .................................... 154 3.3.2 Query language .......................................... 160 3.3.3 How to start ............................................ 162 3.3.4 Example session ......................................... 165 3.3.5 Choosing a party ......................................... 165 3.3.6 Error Reporting .......................................... 166 3.3.7 Create a new Contract ...................................... 168 3.3.8 Create a new Contract with an optional meta field ................... 169 3.3.9 Exercise by Contract ID ..................................... 170 3.3.10 Exercise by Contract Key .................................... 171 3.3.11 Create and Exercise in the Same Transaction ...................... 172 3.3.12 Fetch Contract by Contract ID ................................. 174 3.3.13 Fetch Contract by Key ...................................... 175 3.3.14 Contract Search, All Templates ................................ 176 3.3.15 Contract Search ......................................... 177 3.3.16 Fetch Parties by Identifiers .................................. 179 3.3.17 Fetch All Known Parties ..................................... 180 3.3.18 Allocate a New Party ....................................... 180 3.3.19 List All DALF Packages ..................................... 181 3.3.20 Download a DALF Package ................................... 181 3.3.21 Upload a DAR File ......................................... 182 3.3.22 Streaming API ........................................... 183 3.4 DAML Script ................................................. 188 3.4.1 DAML Script Library ....................................... 188 3.4.2 Usage ................................................ 190 3.4.3 Using DAML Script for Ledger Initialization ........................ 194 3.4.4 Using DAML Script in Distributed Topologies ....................... 194 3.4.5 Running DAML Script against Authenticated Ledgers ................. 195 3.4.6 Running DAML Script against the HTTP JSON API .................... 195 3.5 Upgrading and extending DAML applications ........................... 196 3.5.1 Automating the Upgrade Process .............................. 196 3.5.2 Structuring upgrade contracts ................................ 199 3.5.3 Building and deploying coin-1.0.0 .............................. 201 3.5.4 Create some coin-1.0.0 coins ................................. 201 3.5.5 Building and deploying coin-2.0.0 .............................. 202 3.5.6 Building and deploying coin-upgrade ........................... 202 3.5.7 Upgrade existing coins from coin-1.0.0 to coin-2.0.0 .................. 203 3.5.8 Further Steps ........................................... 203 3.6 Authentication ............................................... 203 3.6.1 Introduction ............................................ 203 3.6.2 Access tokens and claims ................................... 205 3.6.3 Getting access tokens ..................................... 205 3.6.4 Using access tokens ...................................... 206 3.7 The Ledger API ................................................ 206 3.7.1 The Ledger API services ..................................... 206 3.7.2 gRPC ................................................. 210 3.7.3 Ledger API Reference ...................................... 212 3.7.4 How DAML types are translated to protobuf ........................ 246 3.7.5 How DAML types are translated to DAML-LF ........................ 252 3.7.6 Java bindings ........................................... 256 3.7.7 Scala bindings .......................................... 288 3.7.8 Node.js bindings ......................................... 292 3.7.9 Creating your own bindings .................................. 292 3.7.10 What’s in the Ledger API .................................... 295 3.7.11 DAML-LF ............................................... 296 4 Deploying to DAML ledgers 297 4.1 Overview of DAML ledgers ........................................ 297 4.1.1 Commercial Integrations ................................... 297 4.1.2 Open Source Integrations ................................... 297 4.1.3 DAML Ledgers in Development ................................ 297 4.2 Deploying to a generic DAML ledger .................................. 298 4.2.1 Connecting via TLS ........................................ 299 4.3 DAML Ledger Topologies ........................................