Encumbrance States in Corda
Encumbrance is a claim against an asset by a party that is not the owner. An encumbrance can impact the transferability of the asset and restrict its free use until it is lifted. Most common forms of encumbrance include mortgages, easements, and property tax liens.
What is encumbrance in Corda
Like in the real world, Encumbrance in Corda restricts the free use of states in Corda. It creates a dependency between two or more states in Corda which are outputs of the same transaction. Such states cannot be individually consumed in any other transaction.
The TransactionState class in Corda has an optional field named encumbrance of type Int. This field is used to encumber states in Corda. If you want to encumber an output state of a transaction, encumbrance field for that transaction should point to an output index of any other state in the same transaction you want to encumber the state with.
Consider a transaction that has two output states, State A and State B. The encumbrance field of State A points to the output index of State B present in the same transaction. In this case the State A is said to be encumbered by encumbrance state, State B.
Consider the first output state from the code snippet above. The output index of it is 0 and value of encumbrance field is 1, that means the first output state at index 0 is encumbered by output state at index 1 that is the 2 nd output state of the transaction. Similarly all the states in the above code snippet are encumbered by the next output state in following order.1->2->3->4->1 .
Encumbrance imposes the constraint that an encumbered state when being consumed must have its encumbrance state consumed in the same transaction. Otherwise the transaction is considered invalid.
Due to the above constraint the encumbrance state will force additional controls over the encumbered state, since the platform checks that the encumbrance state is present as an input in the same transaction that consumes the encumbered state, and the contract code and rules of the encumbrance state will also be verified during the execution of the transaction/when encumbered state is consumed. Encumbrance state can be used in Corda to force additional contract checks on state that are required only in certain scenarios but should not be applied on all the states of a type.
Bidirectional Encumbrance in Corda
Assume you have State A (the encumbered state) to be encumbered by State B (the encumbrance/encumbering state). The encumbrance state, if present, forces additional controls over the encumbered state. You cannot spend encumbered state without the encumbrance state.
However it does not stop you from spending the encumbrance state when encumbered state is not a part of the transaction. So a malicious user could easily freeze State A as it requires State B.
The above issue is fixed by always requiring circular encumbrance links by Corda. State A encumbered by State B, State B encumbered by State A. That is A->B->A , therefore B cannot be spent without State A.
If you try to encumber a state without using circular encumbrance you will get an Exception in Corda.
Encumbered states can only point to one encumbrance state, but that state can itself point to another and so on, resulting in a chain of encumbrances all of which must be satisfied.
The GitHub repository mentioned below has an example that demonstrate the use encumbrance by Locking an Asset for a given time using encumbrance state.
The above Cordapp has two states, AssetState that is encumbered and LockState that is used as encumbrance state. The LockState is used to lock an AssetState for a given time period. Once the AssetState is locked it can only be consumed after the time period has passed.
The above Cordapp has flows to create and encumber the AssetState, Transfer the asset, unlock encumbered asset and transfer etc . The Cordapp also has flow tests which try some scenarios with the encumbered state.
Some Uses of Encumbrance States in Corda
Re-issuance of States in Corda
When creating a new transaction, input states are included in the proposed transaction by reference. These input state references link transactions together over time, forming a transaction back-chain.
Long transaction back-chains are undesirable for two reasons:
- performance — resolution along the chain slows down significantly
- privacy — all back-chain transactions are shared with the new owner
To resolve this problem the states need to be reissued in such a way that there is no link between the consumed and reissued state. In case where the issuer of an asset is trustworthy, the state can simply be exited from the ledger and then re-issued in a separate transaction.
In the above scenario it is possible for the issuer not to re-issue the state. To eliminate that risk, encumbrance states are used in Reissuance Cordapp. The idea is to re-issue encumbered (locked) state before the original state is deleted from the ledger and allow the requester to unlock re-issued state only after the proof of deletion of original state is provided by the owner.
The GitHub repository mentioned below has the reissuance Cordapp source code.
Atomic Swaps
Atomic swaps are automatic exchange contracts that allow two parties to trade tokens from two different blockchains. For example swap Asset1 for Asset2 in a scenario where initially Asset1 belongs to Party A in Corda Network1 and Asset2 belongs to Party B in Corda Network2.
For such a swap to be atomic it requires a way to lock the assets that are about to be swapped (i.e., Asset1 and Asset2).
Encumbrances come to rescue because they provide a mechanism to link states together and require that two (or more) linked states must be consumed together. Thus, one can use an encumbrance to lock a state (e.g., Asset1) and dictate additional rules (contract constraints) for the state’s consumption in the contract code of the lock. The original state (e.g., Asset1) and its contract remains unchanged.
Time-lock States
Time-lock refers to freezing an asset until a particular time is reached. A time lock contract can define a state that contains the time at which the lock on encumbered state expires, and a simple contract that just compares that time against the transaction timestamp.
The asset state can be included in a spend-to-self transaction that doesn’t change the ownership of the asset but does include a time lock state in the outputs. Now if the asset state is used, the time lock state must also be used, and that triggers the execution of the time lock contract.
Limitations
- Currently, encumbrances should not be used with reference states. In the case where a state is encumbered by an encumbrance state, the encumbrance state should also be referenced in the same transaction that references the encumbered state. This is because the data referenced may take on a different meaning when encumbered. For example, a token state referenced for collateral reporting purposes may have been “seized” and thus encumbered by a regulator, thus cannot be counted.
- The means to query states from vault based on following criteria that is states that are encumbered and states that are not encumbered is not available, the result needs to be filtered. This might be required in situation where you select tokens present in vault and try to transfer the tokens to another party, if the encumbered tokens are selected the transfer would fail as it imposes additional constraints.
