I need more scenario examples

Mod note: As of SDK 1.5.0 Scenarios have been superseded by the more powerful Daml Script. We now recommend using that for all purposes. For more information, and to learn how to use Script please check out @Andreas’ post on our blog.

The scenario examples only seem to cover how to setup parties for the scenario do statements.
What if my contract has text values and integers, I don’t know how create the data declarations for those so that I can test scenario results.

I checked the prelude DAML documentation and the scenario reference, but I don’t know how to get started. Is it possible to have more scenario examples in the documentation that includes things other than parties in the scenario statements?

Hi @krmmalik,

First off, I really encourage you to use Script instead of Scenario. It may feel a little bit more restrictive (because it is!), but it is much closer in its API to the way external applications would interact with your Daml application.

With that out of the way, here is a slightly modified version of the default daml new template:

module Main where

import Daml.Script

type AssetId = ContractId Asset

template Asset
  with
    issuer : Party
    owner  : Party
    name   : Text
  where
    ensure name /= ""
    signatory issuer
    controller owner can
      Give : AssetId
        with
          newOwner : Party
        do
          create this with
            owner = newOwner

setup : Script ()
setup = script do
  alice <- allocatePartyWithHint "Alice" (PartyIdHint "Alice")
  bob <- allocatePartyWithHint "Bob" (PartyIdHint "Bob")

  aliceTV <- submit alice do
    createCmd Asset with
      issuer = alice
      owner = alice
      name = "TV"

  bobsTV <- submit alice do
    exerciseCmd aliceTV Give with newOwner = bob

  bobs_assets <- query @Asset bob
  alices_assets <- query @Asset alice

  -- They can both see the asset, Alice because she is the signatory, Bob because he is the controller of a choice
  assert $ bobs_assets == [(bobsTV, Asset with issuer = alice, owner = bob, name = "TV")]
  assert $ alices_assets == [(bobsTV, Asset with issuer = alice, owner = bob, name = "TV")]

  return ()

By default, a script will fail if you try to do an operation on the ledger that fails with submit (or if an operation succeeds with submitMustFail). This is often enough, but sometimes you want a more direct inspection of the state of the ledger. For these cases, you can use the query family of functions (docs here).

The syntax is slightly unusual, as you have to explicitly provide the type of template your are querying for. That is, query @A p will fetch all the contracts on the ledger that are visible to party p and are of the template type A.

The return type is a list of pairs, where the first item is a contract ID and the second item is a contract payload. You do not need to make a separate data declaration to represent contract payloads; one is automatically derived for you by the compiler from the corresponding template declaration. This is why, in the snippet above, I can directly construct an Asset payload in the arguments to assert.

The data declarations automatically derived from template declarations always derive Show and Eq instances, meaning they can be compared for equality (and, in scripts and scenarios, printed with debug).

So the short answer is, in the general case, you do not need to create data declarations just to test the contents of the ledger.

3 Likes

OK, thanks for the write-up. Just to test it very quickly, once I understood what you meant about data declarations for testing the content of the ledger, I did a simple test with my exact scenario code just to see if it would actually produce results, which it did.

I’ve seen other posts on this forum (i think) encouraging the move away from scripts to scenarios which is why I went down that route. I also love the scenario codelens.

1 Like

As far as I’m aware Scenarios existed first, and ever since we’ve considered Scripts “ready” we’ve been recommending people switch to them. I’m not aware of any period where DA recommended moving back from Scripts to Scenarios.

If you can remember such an instance, would you mind pointing me to it? It probably needs updating.

1 Like

It was this: Running scenarios in VSCode

but I’ve just re-read it and realised that it was me that has had incorrectly recalled it.
My apologies.

I’m going to try and use Scripts from now on.
They still show results in the codelens in a similar way to Scenarios right?

1 Like

Yes, they do. The experience should be just as good. The main difference is that you need to append Cmd to some commands (e.g. createCmd instead of create).

2 Likes