Can we reverse Daml transactions?
TLDR; The short answer: no. A little bit longer answer: it depends. An even longer answer: Reversing business transactions, implemented in a Daml model, is as easy or difficult as finding the correct legal construct for the reversal. Non-functional requirements can further limit the range of viable options.
Daml transactions vs business transactions
An important distinction: Daml transactions are not the same as business transactions.
A Daml transaction is a bundle of ledger actions where the actions are accepted or rejected in an “all or nothing” manner. The way the actions are bundled is determined by the Daml model. The results of the actions on the ledger, once accepted, are called events. The actions can belong to one of four types: contract creation, exercise of a choice on an existing contract, contract fetching and key assertion.
The term “business transaction” on the other hand, is a vague term. Usually, it refers to a bundle of business actions, where the meaning of “action” and “bundle” is also vaguely defined. The intent behind calling a set of business actions a business transaction may be similar to what we call a Daml transaction, but there is no guarantee for a correct translation.
What “reversal” means — Daml transactions
Similarly to the difference between Daml transactions and business transactions, there is a difference between speaking about reversing a Daml transaction or about reversing a business transaction.
The Daml transaction case is simple: a Daml transaction cannot be reversed.
A Daml ledger is a growing array of committed transactions. Nothing can be deleted from the ledger. Any right or obligation previously recorded on the ledger in the form of one or more Daml contracts, can be eliminated only by recording consuming events with regards to those contracts. Of course, whether or not such a consuming event can be recorded on the ledger depends on the Daml model and the set of active contracts.
Let’s see an example, the ledger which is the result of the setup script of the skeleton template (the Daml model you get by default after creating a new Daml project by issuing the commanddaml new <your-project-name>). The ledger aggregates the result of three changes: 1) Alice creating a TV asset, 2) Alice giving the asset to Bob, 3) Bob giving the asset back to Alice. All these changes are recorded by not changing or deleting previously recorded events but adding new events, some of which consume previously created contracts.
The nodes of the graph below represent events recorded on the ledger. In the top row you can see the top level events, which were directly requested by ledger parties. The events situated in the same column and having the same id prefix are the events which belong to the same atomic transaction. The blue nodes stand for choice exercises which don’t appear in the active contract set but constitute the glue between contracts; the red nodes stand for contract creation events for such contracts which were later declared consumed by choice exercise events so they were previously but are not currently part of the active contract set; the green node stands for the creation of the contract which currently constitutes the active contract set:
What “reversal” means — business transactions
The exact meaning of “reversing” a business transaction, similarly to the very notion of a business transaction, is vague. We might mean by that e.g. the “restoration of the original state” in some sense, where “original” means some previous point in time, and “state” is a set of parameters which need to be specified.
Whether of not this is possible on a Daml ledger, and if possible how difficult it is, depends on whether or not the “restoration of the original state” can be defined in correct legal terms as the creation/elimination of rights and obligations, and if yes how difficult it is.
The Daml constraints are the constraints of contract law
A Daml model implements the legal architecture of a business model.
On a Daml ledger we can only represent relationships between ledger parties in accordance with the offer-acceptance pattern of contract law.
The principles of legal rights and obligations are expressed in Daml terms as follows (see more info in the Daml docs section linked below):
- Obligations need consent.
- Consent is needed to take away on-ledger rights.
- On-ledger obligations cannot be unilaterally escaped.
This means that if a business transaction established/eliminated some rights and/or obligations for some ledger party or parties, the reversal, that is the elimination/re-establishment of these rights/obligations respectively can also happen only by observing these rules.
Easy use case #1: give back the asset
There are some use cases where implementing a correct legal model (and a viable Daml model accordingly) for the reversal of business transactions is not too difficult. Some additional off-ledger complexity may arise as a result, as we will see. I will briefly describe three such use cases.
We can notice that the bare-bones use case implemented by the skeleton template used above as illustration already contains the possibility to reverse the business transaction which consists of giving away the asset: the new owner can give it back to the original owner.
We can also notice that the decision about reversing the business transaction is totally in the hands of the new owner though. The old owner can take no on-ledger action to facilitate this. This “good faith” based reversal option may or may not be what your business model actually requires.
Easy use case #2: result contract with „reverse” choice
If you want to give control about the reversal of the business transaction in the hands of the old owner of the asset, you can extend the Daml model with a contract expressing the result of giving away the asset, containing an option for the old owner to reverse it by consuming the given asset and creating an identical one for the old owner.
The challenge here is that the new owner may give the asset away to a third ledger party before the old owner decides to take it back. In this case the reversal will be rejected by the ledger.
A more advanced version can be that the result contract with the reversal option locks the asset, preventing the new owner from giving it away (the locking can be easily implemented by including a fetch step in the give choice) — but in this case giving away the asset actually doesn’t give control about it to the new owner. From a business perspective though, this can be ok, if the ownership of the asset yields some other benefits to the owner. A middle ground can be that the reversal option and the locking effect has an expiration or is deleted/released by some trigger.
Easy use case #3: purely additive delta events
Yet another use case where the reversal of the business transaction is easy to implement when we record delta events on the ledger rather than states. This is what happens e.g. in double-entry bookkeeping where we record credit and debit events. In this case the effect of a debit or credit event can be offset by recording a reverse event: credit for debit and debit for credit. The controller of the reversal of the business transaction may be the same ledger party which was the controller of the original transaction.
While this pattern is easy to implement in a Daml model, creates additional complexity on the client side. The balance of accounts is not stored on the ledger, but needs to be computed every time by aggregating the debit and credit events by a client application. This can be a problem when a large number of accounts needs to be processed within a short period of time.
