DAML Script – Scenarios 2.0

 

Developers benefit greatly from a fast feedback loop. The less time you have to wait between writing code and seeing whether it does what you expect the better. DAML Studio provides immediate feedback for compiler errors and warnings in your code. Scenarios allow you to test your templates against an emulated ledger and can be run directly from within DAML Studio providing you with live updates as you change your code.

Scenarios provide a great way to test and develop your DAML models. However, scenarios do have important shortcomings: They do not interact with an actual ledger. This means that you cannot use scenario code to initialize arbitrary ledgers, for automation or to test other ledger clients, such as your UI or DAML triggers. Scenarios also allow you to do things that are not possible on an actual ledger while on the other hand, they are missing functionality that ledgers do provide (e.g., querying all active contracts). This means that it is easy to design DAML models that are usable in scenarios but do not expose the necessary APIs to use them via the Ledger API.

Scenarios provide a great way to test and develop your DAML models. However, scenarios do have important shortcomings: They do not interact with an actual ledger.
Scenarios provide a great way to test and develop your DAML models.

Because Scenarios allowed operations that are simply not possible via the Ledger API, there was no way forward for them that didn’t involve fundamentally breaking existing Scenarios. So a more powerful replacement is needed.

DAML Script – One API to rule them all

DAML Script addresses the shortcomings of scenarios by providing you with an API that provides more features,but also imposes the same restrictions as the Ledger API, and is fundamentally designed to work against it. Unlike Scenarios, we designed DAML Script to be a universal scripting language for DAML so we started with the most restrictive use-case: Since SDK 0.13.55 you have been able to use DAML Script to run a script in a DAR against an actual ledger and lots of people have used it successfully for ledger initialization, automaton and testing.

We designed DAML Script to be a universal scripting language for DAML so we started with the most restrictive use-case

However, you still had to rely on scenarios to get the interactive experience in DAML Studio. Since the APIs for scenarios and DAML Script are different (for good reasons since as mentioned before, scenarios provide things that cannot be executed against actual ledgers), it was not easily possible to share code between your scenario test cases and DAML Scripts which resulted in a lot of code duplication and made it harder to develop DAML Scripts due to the lack of interactive feedback.

Now in SDK 1.5.0 this is changing! In this post we are happy to announce two recent additions that improve the interactive development experience even further, and complete our quest to offer a more universal alternative to Scenarios: DAML Script in DAML Studio, and the DAML REPL. With these new features, DAML Script now not only allows you to interact with a real ledger but it also provides you with the interactive development experience you know and love from scenarios all within a single language.

DAML Script in the IDE

DAML Scripts are now executed in DAML Studio providing you with the same functionality that you know and love from scenarios. You don’t have to enable anything for this. Write a script and you will see the “Script results” button that you can click on to see the ledger state as well as the transaction view. The functionality for inspecting the results is identical to scenarios. With this change, you can now rely on DAML Script exclusively for interactive feedback in DAML Studio, unit tests executed via `daml test`, interacting with an actual ledger via the `daml script` command as well as using it interactively via `daml repl`.

You can now rely on DAML Script exclusively for interactive feedback in DAML Studio

If you have used scenarios this will look very familiar but you might notice a few differences:

  • script instead of scenario
  • allocateParty instead of getParty.
  • createCmd and exerciseCmd instead of create and exercise.
  • queryContractId instead of fetch.

The last item in particular highlights the difference between scenarios and DAML script. The fetch function is only available within Updates and is not available on the ledger API. When you are converting scenarios to DAML Script that contains more complex Updates then you may need to define new templates and choices that allow you to execute this code on the ledger.

You can also use the exact same DAML Script and run it against an actual ledger with the `daml script` command. You can find the full example at

DAML REPL

In SDK 1.4..0, we introduced the new DAML REPL which allows you to use the familiar DAML Script API interactively. This is great for one-off tasks, interactive exploration of a ledger but also for exploring pure code without any ledger, e.g., to better understand the DAML standard library. You can start daml repl anywhere and start typing! If you are interacting with the JSON API, you might also enjoy the new functionality in SDK 1.5.0 to display the JSON representation of a DAML value.

you might also enjoy the new functionality in SDK 1.5.0 to display the JSON representation of a DAML value.
You might also enjoy the new functionality in SDK 1.5.0 to display the JSON representation of a DAML value.

If you would like to interact with your contracts in DAML REPL then you can start it in your project, connecting against a ledger using the --ledger-host and --ledger-port flags. Following the example from above

Try it out and if you have any feedback or questions ask them on our forum!

Ask questions in the forum

Newsletter

Join the DAML mailinglist to get occasional updates on announcements and new releases