Witness, informee and similar concepts

Hi!
I’m new to Daml and when I’m reading docs, I see a few concepts like actors or witnesses.
I have a problem to find the difference between these ideas.
I can’t see any good explanation in documentation, so I have a few questions:

What is informee, witness or actor exactly?
Is signatory of a contract is also actor on this contract?
Is choice observer a stakeholder too?
What is a difference between controllers and actors?

Signatories, observers, stakeholders and maintainers are pretty simple for me (they have good explanation in docs).
Can we say that witness is always an informee? (like square is always a rectangle?)
Is there any simple schema about this?

I found these pages in docs, but I’m not sure that is there all informations and that I understand it correctly.
(info about witnesses) Ledger API Reference — Daml SDK 2.2.0 documentation
(info about informees) Privacy — Daml SDK 2.2.0 documentation

I would be grateful for any tips

Let’s break it down. First off, some of these concepts apply to a contract, whereas others apply to an action, where an action is a “ledger event”, i.e. “things that happen”.

For example, a signatory of a contract is a “static” property of the contract, as it stands registered on the ledger. On the other hand, an actor is a “dynamic” property: you are only an actor “during” a transaction, while things are happening.

The concept of a stakeholder is defined in the glossary as:

Stakeholder is not a term used within the Daml language, but the concept refers to the signatories and observers collectively. That is, it means all of the parties that are interested in a contract.

This includes all of the observers, which in turn includes choice observers. So “stakeholders” is defined based on the data on a contract (“static”) and includes all of the parties that are explicitly included in signatory, all of the parties that are explicitly included in observer, and all of the parties that are implicitly observers by virtue of being controllers on a controller can-syntax choice (which is deprecated, but still valid; those are called “choice observers”, and, in addition to being observers on the contract itself, they will be informed of all the consequences of the choice).

Informee, witness and actor are properties of a transaction rather than a contract; they are “dynamic” properties.

An actor is a party exercising a choice. Note that with multi-party submission, there may be multiple actors for a single choice being exercised through the API.

Based on the privacy link you gave, we know that:

a party p is an informee of an action A if one of the following holds:

  • A is a Create on a contract c and p is a stakeholder of c.
  • A is a consuming Exercise on a contract c, and p is a stakeholder of c or an actor on A. Note that a Daml “flexible controller” can be an exercise actor without being a contract stakeholder.
  • A is a non-consuming Exercise on a contract c, and p is a signatory of c or an actor on A.
  • A is an Exercise action and p is a choice observer on A.
  • A is a Fetch on a contract c, and p is a signatory of c or an actor on A.
  • A is a NoSuchKey k assertion and p is a maintainer of k.

Note that in all of these, “A” is an action, not a contract.

Which leaves witnesses. From the same page:

More precisely, every action act on c is shown to all informees of all ancestor actions of act. These informees are called the witnesses of act. If one of the witnesses W is not a stakeholder on c, then act and c are said to be divulged to W. Note that only Exercise actions can be ancestors of other actions.

So, for a given action, the witnesses are the informees of that action and the informees of all of the ancestors of that action. There may be cases where the informees of the ancestor actions are not stakeholders of the contract, and thus need to be divulged the contract. In most cases where the term witness is used, it is referring specifically to these non-stakeholder informees.

3 Likes

It’s much more understandable now.
Thanks!

It’s worth noting that the Ledger API was developed while the ledger model was being formalized. As such, it’s not uncommon for certain terms to not exactly match across these two (e.g. witness_parties on the Ledger API are a separate concept from witness as described in the ledger model and I strong recommend to form your understanding of witness_parties based on the explanation provided in the Ledger API reference documentation). My recommendation in general is not to try to match those two together 1:1 terminology-wise but to try to map the concepts from the model to the implementation. Another example of such a misalignment is what are referred to as contract state changes in the ledger model, which are called either transactions or flat transactions on the Ledger API, depending on the context. This is an unfortunate historical artifact due to their development happening in parallel and our strong commitment to backward compatibility, which makes naming changes very hard.

1 Like