Daml REPL¶
The Daml REPL allows you to use the Daml Script API interactively. This is useful for debugging and for interactively inspecting and manipulating a ledger.
Usage¶
First create a new project based on the script-example
template. Take a look at the documentation for
Daml Script for details on this template.
Now, build the project and start Daml Sandbox, the in-memory
ledger included in the SDK. Note that we are starting Sandbox in
wallclock mode. Static time is not supported in daml repl
.
Now that the ledger has been started, you can launch the REPL in a separate terminal using the following command.
The --ledger-host
and --ledger-port
parameters point to the
host and port your ledger is running on. In addition to that, you also
need to pass in the name of a DAR containing the templates and other
definitions that will be accessible in the REPL. We also specify that we want
to import all modules from the script-example
package. If your modules
provide colliding definitions you can also import modules individually from
within the REPL. Note that you can also specify multiple DARs and they
will all be available.
You should now see a prompt looking like
You can think of this prompt like a line in a do
-block of the
Script
action. Each line of input has to have one of the following
two forms:
- An expression
expr
of typeScript a
for some typea
. This will execute the script and print the result ifa
is an instance ofShow
and not()
. - A pure expression
expr
of typea
for some typea
wherea
is an instance ofShow
. This will evaluateexpr
and print the result. If you are only interest in pure expressions you can also use Daml REPL without connecting to a ledger. - A binding of the form
pat <- expr
wherepat
is pattern, e.g., a variable namex
to bind the result to andexpr
is an expression of typeScript a
. This will execute the script and match the result against the patternpat
bindings the matches to the variables in the pattern. You can then use those variables on subsequent lines. - A
let
binding of the formlet pat = y
, wherepat
is a pattern andy
is a pure expression orlet f x = y
to define a function. The bound variables can be used on subsequent lines. - 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"
and the party id "alice"
and a party with the display name
"Bob"
and the party id "bob"
.
Next, create a CoinProposal
from Alice
to Bob
As Bob, you can now get the list of active CoinProposal
contracts
using the query
function. The debug : Show a => a -> Script ()
function can be used to print values.
Finally, accept all proposals using the forA
function to iterate
over them.
Using the query
function we can now verify that there is one
Coin
and no CoinProposal
:
To exit daml repl
press Control-D
.
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.
You can use the commands :module + ModA ModB …
to import additional modules
and :module - ModA ModB …
to remove previously added imports. Modules can
also be imported using regular import declarations instead of module +
.
The command :show imports
lists the currently active imports.
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.,
submit
will result in the following error:
Connecting via TLS¶
You can connect to a ledger that requires TLS by passing --tls
. A
custom root certificate used for validating the server certificate can
be set via --cacrt
. Finally, you can also enable client
authentication by passing --pem client.key --crt client.crt
. If
--cacrt
or --pem
and --crt
are passed TLS is automatically
enabled so --tls
is redundant.
Connection to a Ledger With Authorization¶
If your ledger requires an authorization token you can pass it via
--access-token-file
.
Using Daml REPL to Convert to JSON¶
Using the :json
command you can encode serializable Daml expressions as
JSON. For example using the definitions and imports from above: