This section addresses the question of who can request which changes.
At the core is the concept of a valid ledger; changes are permissible if adding the corresponding commit to the ledger results in a valid ledger. Valid ledgers are those that fulfill three conditions:
- Exercises on inactive contracts are not allowed, i.e. contracts that have not yet been created or have already been consumed by an exercise.
- Only a restricted set of actions is allowed on a given contract.
- The parties who may request a particular change are restricted.
Only the last of these conditions is dependent on the party (or parties) requesting the change; the other two are general.
Intuitively, consistency requires contracts to be created before they are used, and that they cannot be used once they are consumed. To define this precisely, notions of “before” and “after” are needed. These are given by putting all actions in a sequence. Technically, the sequence is obtained by a pre-order traversal of the ledger’s actions, noting that these actions form an (ordered) forest. Intuitively, it is obtained by always picking parent actions before their proper subactions, and otherwise always picking the actions on the left before the actions on the right. The image below depicts the resulting order on the paint offer example:
In the image, an action act happens before action act’ if there is a (non-empty) path from act to act’. Then, act’ happens after act. A ledger is consistent for a contract c if all of the following holds for all actions act on c:
- either act is itself Create c or a Create c happens before act
- act does not happen before any Create c action
- act does not happen after any exercise consuming c.
A ledger is consistent if it is consistent for all contracts.
The consistency condition rules out the double spend example. As the red path below indicates, the second exercise in the example happens after a consuming exercise on the same contract, violating the consistency criteria.
The above consistency requirement is too strong for actions and transactions in isolation. For example, the acceptance transaction from the paint offer example is not consistent, because PaintOffer A P Bank and the Iou Bank A contracts are used without being created before:
However, the transaction can still be appended to a ledger that creates these contracts and yield a consistent ledger. Such transactions are said to be internally consistent, and contracts such as the PaintOffer A P Bank and Iou Bank A are called input contracts of the transaction. Dually, output contracts of a transactions are the contracts that a transactions creates and does not archive.
- Definition »internal consistency«
A transaction is internally consistent for a contract c if the following holds for all of its subactions act on the contract c
- act does not happen before any Create c action
- act does not happen after any exercise consuming c.
A transaction is internally consistent if it is internally consistent for all contracts c.
- Definition »input contract«
- For an internally consistent transaction, a contract c is an input contract of the transaction if the transaction contains an Exercise or a Fetch action on c but not a Create c action.
- Definition »output contract«
- For an internally consistent transaction, a contract c is an output contract of the transaction if the transaction contains a Create c action, but no a consuming Exercise action on c.
Note that the input and output contracts are undefined for transactions that are not internally consistent. The image below shows some examples of internally consistent and inconsistent transactions.
In addition to the consistency notions, the before-after relation on actions can also be used to define the notion of contract state at any point in a given transaction. The contract state is changed by creating the contract and by exercising it consumingly. At any point in a transaction, we can then define the latest state change in the obvious way. Then, given a point in a transaction, the contract state of c is:
- active, if the latest state change of c was a create;
- archived, if the latest state change of c was a consuming exercise was;
- inexistent, if c never changed state.
A ledger is consistent for c exactly if Exercise and Fetch actions on c happen only when c is active, and Create actions only when c is inexistent. The figures below visualize the state of different contracts at all points in the example ledger.
The notion of order can be defined on all the different ledger structures: actions, transactions, lists of transactions, and ledgers. Thus, the notions of (internal) consistency, inputs and outputs, and contract state can also all be defined on all these structures. The active contract set of a ledger is the set of all contracts that are active on the ledger. For the example above, it consists of contracts Iou Bank P and PaintAgree P A.
The conformance condition constrains the actions that may occur on the ledger. This is done by considering a contract model M (or a model for short), which specifies the set of all possible actions. A ledger is conformant to M (or conforms to M) if all top-level actions on the ledger are members of M. Like consistency, the notion of conformance does not depend on the requesters of a commit, so it can also be applied to transactions and lists of transactions.
For example, the set of allowed actions on IOU contracts could be described as follows.
The boxes in the image are templates in the sense that the contract parameters in a box (such as obligor or owner) can be instantiated by arbitrary values of the appropriate type. To facilitate understanding, each box includes a label describing the intuitive purpose of the corresponding set of actions. As the image suggest, the transfer box imposes the constraint that the bank must remain the same both in the exercised IOU contract, and in the newly created IOU contract. However, the owner can change arbitrarily. In contrast, in the settle actions, both the bank and the owner must remain the same. Furthermore, to be conformant, the actor of a transfer action must be the same as the owner of the contract.
Of course, the constraints on the relationship between the parameters can be arbitrary complex, and cannot conveniently be reproduced in this graphical representation. This is the role of DAML – it provides a much more convenient way of representing contract models. The link between DAML and contract models is explained in more detail in a later section.
To see the conformance criterion in action, assume that the contract model allows only the following actions on PaintOffer and MustPaint contracts.
The problem with example where Alice changes the offer’s outcome to avoid transferring the money now becomes apparent.
A’s commit is not conformant to the contract model, as the model does not contain the top-level action she is trying to commit.
Valid Ledgers, Obligations, Offers and Rights¶
DA ledgers are designed to mimic real-world interactions between parties, which are governed by contract law. The validity conditions on the ledgers, and the information contained in contract models have several subtle links to the concepts of the contract law that are worth pointing out.
First, in addition to the explicit off-ledger obligations specified in the agreement text, contracts also specify implicit on-ledger obligations, which result from consequences of the exercises on contracts. For example, the PaintOffer contains an on-ledger obligation for A to transfer her IOU in case she accepts the offer. Agreement texts are therefore only necessary to specify obligations that are not already modeled as permissible actions on the ledger. For example, P’s obligation to paint the house cannot be sensibly modeled on the ledger, and must thus be specified by the agreement text.
Second, every contract on a DA ledger can simultaneously model both:
- a real-world offer, whose consequences (both on- and off-ledger) are specified by the Exercise actions on the contract allowed by the contract model, and
- a real-world contract “proper”, specified through the contract’s (optional) agreement text.
Third, in DA ledgers, as in the real world, one person’s rights are another person’s obligations. For example, A’s right to accept the PaintOffer is P’s obligation to paint her house in case she accepts. In DA ledgers, a party’s rights according to a contract model are the exercise actions the party can perform according to the authorization and conformance rules.
Finally, validity conditions ensure three important properties of the DA ledger model, that mimic the contract law.
Obligations need consent. DA ledgers follow the offer-acceptance pattern of the contract law, and thus ensures that all ledger contracts are formed voluntarily. For example, the following ledger is not valid.
Consent is needed to take away on-ledger rights. As only Exercise actions consume contracts, the rights cannot be taken away from the actors; the contract model specifies exactly who the actors are, and the authorization rules require them to approve the contract consumption.
In the examples, Alice had the right to transfer her IOUs; painter’s attempt to take that right away from her, by performing a transfer himself, was not valid.
Parties can still delegate their rights to other parties. For example, assume that Alice, instead of accepting painter’s offer, decides to make him a counteroffer instead. The painter can then accept this counteroffer, with the consequences as before:
Here, by creating the CounterOffer contract, Alice delegates her right to transfer the IOU contract to the painter. In case of delegation, prior to submission, the requester must get informed about the contracts that are part of the requested transaction, but where the requester is not a signatory. In the example above, the painter must learn about the existence of the IOU for Alice before he can request the acceptance of the CounterOffer. The concepts of observers and divulgence, introduced in the next section, enable such scenarios.
On-ledger obligations cannot be unilaterally escaped. Once an obligation is recorded on a DA ledger, it can only be removed in accordance with the contract model. For example, assuming the IOU contract model shown earlier, if the ledger records the creation of a MustPay contract, the bank cannot later simply record an action that consumes this contract:
That is, this ledger is invalid, as the action above is not conformant to the contract model.