Daml Ledger Model: what exactly are top-level actions?

I’m (re)reading the Daml Ledger Model part of the docs.

The Actions and Transactions part says:

A transaction is a list of actions. Thus, the consequences of an exercise form a transaction.

The Ledger part says:

The transaction structure records the contents of the changes, but not who requested them . This information is added by the notion of a commit : a transaction paired with the parties that requested it, called the requesters of the commit. A commit may have one or more requesters. Given a commit (p, tx) with transaction tx = act1, …, actn, every acti is called a top-level action of the commit. A ledger is a sequence of commits. A top-level action of any ledger commit is also a top-level action of the ledger.

My understanding of the text is that if I request the exercise of a choice through the API, all the consequences of this choice form a transaction, so they are all top-level actions.

Is that correct?

If so, what are non top-level actions?

I’m not 100% sure about the formalism used to describe the idea, but I believe here by top-level actions the ledger model document describes what’s called a “root event” in the Ledger API, i.e. the events triggered explicitly by a command. Since exercise commands can be trees, their consequences (or “child events” in the Ledger API) are not top-level actions.

Ok, follow-up question:

As far as remember, you cannot submit a request through the ledger API which contains multiple actions forming an atomic transaction (correct me if I’m wrong).

If this is so, then the following sentence:

Given a commit (p, tx) with transaction tx = act1, …, actn, every acti is called a top-level action of the commit.

only describes a theoretical possibility in the Ledger Model, which is not implemented in the Daml platform?

gyorgybalazsi:

which contains multiple actions forming an atomic transaction (correct me if I’m wrong)

I’m not sure, but I think this is possible in the ledger API : Ledger API Reference — Daml SDK 2.7.6 documentation

You can also achieve this through a Script by submitting multiple createCmd/exerciseCmd/etc in a single Applicative do block.

Not certain the JSON API supports this though …

Oh yes, maybe the submitted actions cannot depend on each other?

That’s correct ; hence the Applicative.

Understood, thanks!