Although Corda’s API was stabilised with the release of Corda V1.0, we continue to add new APIs based on the requirements of our users (as expressed in our Slack channel and elsewhere). In Corda V2.0, we added the Observable State feature, which gives nodes flexibility in deciding whether to track a state.
The Vault in Corda V1.0
In Corda, shared facts are modelled as states. States can represent any kind of agreement, from traditional asset ownership to a bill of sale or legal contract. Nodes store these states in their vault. The vault is akin to a Bitcoin wallet — it allows a node to track its states on the Corda ledger.
In Corda V1.0, when a node records a new transaction, the node decides whether to add the transaction’s states to its vault as follows:
- If the state is an OwnableState, the node stores the state if the node is the state’s owner
- Otherwise, the node stores the state if it is one of the state’s participants (the participants are the nodes that can consume the state in a valid transaction)
If neither of these conditions is met, the node stores the transaction itself, but it won’t extract the transaction’s states and store them in its vault. Nodes only track states that they can consume.
The vault in Corda V2.0
However, we knew that there were legitimate use-cases that required nodes to track states that they couldn’t spend themselves:
- Regulatory nodes wanting to track the movement of assets on the ledger
- Public companies wanting to track the movement of their shares
We addressed this requirement in Corda V2.0 by introducing the Observable State feature. This feature allows a node to choose to store a transaction’s states in its vault when recording a transaction, even if it can’t consume those states.
Data privacy with Observable States
The Observable State feature is implemented to be compatible with Corda’s privacy-first design:
- Because Corda transactions are only propagated around the network on a need-to-know basis, nodes can only observe a transaction’s states if they are sent the transaction itself. A node cannot “register” to observe the states of a transaction it is not a party to
- The Observable State feature is compatible with the Confidential Identities feature introduced in Corda V1.0. If a transaction uses confidential identities to identify its participants, these identities can also be kept confidential from any observers
The Observable State API
Let’s take a look at the Observable State feature by defining a pair of flows.
The initiating flow, BroadcastTransactionToObservers, sends a transaction to everyone on the network map (in practice, we’d almost always restrict the broadcast to a specific subset of the network participants):
The response flow will be RecordTransactionAsObserver. This flow will receive the transaction and store in its vault even if it isn’t a participant, by setting statesToRecord = StatesToRecord.ALL_VISIBLE.
Note how the node running the response flow can only choose to observe a transaction if the node running the initiating flow chooses to send it to them. On the other hand, for any transaction it receives, it is up to the node running the response flow whether they choose to become an “observer” by storing the transaction’s states in their vault.
Observable State in use
If you want to find out more about the Observable State feature, take a look at the Crowdfunding CorDapp, which shows the feature in use. We dissect this CorDapp in a segment from our bi-weekly Corda Architectural Group call. You can register to attend the Corda Architectural Group calls here.
There are still two important pieces of work remaining on Observable States:
- Currently, nodes have the choice between observing all a transaction’s states, or none of them. You can track the work to allow partial observation of a transaction’s states here
- The vault’s coin-selection algorithm for selecting a set of unconsumed states doesn’t yet have the ability to distinguish between consumable and observed states. You can see a discussion of potential solutions here.
To use the Observable State feature in your own CorDapps, you can upgrade to Corda V2.0 by following the instructions here (and if you’re worried that this will be difficult, check out the one-line PR that was required to upgrade the CorDapp template from V1.0 to V2.0).