Ledger Model documentation improvements

Questions Features & Bugs
1

I’m having a read through the ledger model docs (Structure - Structure — Daml SDK 1.12.0 documentation), and noticed there’s some inconsistency in the diagrams. some of the diagrams add which choice is being exercised afterwards

Exc A (IOU Bank A) “transfer”

where some leave out “transfer”.

It would also be good in the diagrams to highlight which parts of the diagram makes them impermissible:

  • That Exc A (IOU Bank A) has its transfer choice exercised twice (circle the two exercises)
  • Alice not including the transfer (circle the missing transfer, possibly greyed out? not sure of the best way to represent this visually)
  • A requested the PaintOffer with P’s content (highlight A requested and P on the contract)
  • P requested the transfer of A’s IOU without consent (highlight P requested and A on the contract)
  • The NoSuchKey example seems clear enough, but it’s not clear how P might be able to prevent the key from existing if it does.
  • The same reference number is used twice (highlight the reference numbers in both)
2 Likes
2

Another change that would help those reading on small screens, if at the end of each section a link to the next section could be added that’d make navigation much easier.

2 Likes
3

Thanks for all those suggestions @Axman6-da. I agree with all of them for readability and have created GitHub issues #6700 and #6701 to track them.

For interest, note that the definition of an Exercise node in the Ledger Model has no “tag” that would identify it as a “transfer”:

Action       ::= 'Create' contract
                 | 'Exercise' party* contract Kind Transaction
                 | 'Fetch' party* contract
                 | 'NoSuchKey' key
Transaction  ::= Action*
Kind         ::= 'Consuming' | 'NonConsuming'

The Ledger Model merely says that there is a “Contract Model” which determines the “conformant” transactions. In practice, that Contract Model is specified through DAML, which uses the arguments to an Exercise to “tag” the node with its type, like Transfer. So on the one hand I understand why the authors did what they did on that page, but on the other hand I think that consistently tagging the nodes with names would aid readability quite a bit.

2 Likes
4

Agreed, this is not the first time that we get the comment that the lack of tags on actions (even though they are not really important for the semantics) makes it less readable.

Any two consuming exercises on the IOU would make the example impermissible, not just two transfers. I suspect you’re aware of this, but I just wanted to clarify it for the benefit of other readers.

1 Like