DAML REPL¶
WARNING: DAML REPL is an early access feature that is actively being designed and is subject to breaking changes. We welcome feedback about the DAML REPL on our issue tracker or on our forum or on Slack.
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.
daml new script-example script-example # create a project called script-example based on the template
cd script-example # switch to the new project
Now, build the project and start DAML Sandbox, the in-memory
ledger included in the DAML SDK. Note that we are starting Sandbox in
wallclock mode. Static time is not supported in daml repl
.
daml build
daml sandbox --wall-clock-time --port=6865 .daml/dist/script-example-0.0.1.dar
Now that the ledger has been started, you can launch the REPL in a separate terminal using the following command.
daml repl --ledger-host=localhost --ledger-port=6865 .daml/dist/script-example-0.0.1.dar
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.
You should now see a prompt looking like
daml>
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 ignoring the result. - 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.
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"
.
daml> alice <- allocatePartyWithHint "Alice" (PartyIdHint "alice")
daml> bob <- allocatePartyWithHint "Bob" (PartyIdHint "bob")
Next, create a CoinProposal
from Alice
to Bob
daml> submit alice (createCmd (CoinProposal (Coin alice 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.
daml> proposals <- query @CoinProposal bob
daml> debug proposals
[Daml.Script:39]: [(<contract-id>,CoinProposal {coin = Coin {issuer = 'alice', owner = 'bob'}})]
Finally, accept all proposals using the forA
function to iterate
over them.
daml> forA proposals $ \(contractId, _) -> submit bob (exerciseCmd contractId Accept)
Using the query
function we can now verify that there is one
Coin
and no CoinProposal
:
daml> coins <- query @Coin bob
daml> debug coins
[Daml.Script:39]: [(<contract-id>,Coin {issuer = 'alice', owner = 'bob'})]
daml> proposals <- query @CoinProposal bob
[Daml.Script:39]: []
To exit daml repl
press Control-D
.
What is in scope at the prompt?¶
In the prompt, all modules from the main dalf of the DAR passed to
daml repl
are imported. In addition to that the Daml.Script
module is imported and gives you access to the DAML Script API.
You can use import declarations at the prompt to import additional modules.
daml> import DA.Time
daml> debug (days 1)
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 Authentication¶
If your ledger requires an authentication token you can pass it via
--access-token-file
.