States
Summary

- States represent on-ledger facts
- States are evolved by marking the current state as historic and creating an updated state
- Each node has a vault where it stores any relevant states to itself
Video

Overview

A state is an immutable object representing a fact known by one or more Corda nodes at a specific point in time. States can contain arbitrary data, allowing them to represent facts of any kind (e.g. stocks, bonds, loans, KYC data, identity information…).
For example, the following state represents an IOU - an agreement that Alice owes Bob an amount X:
As well as any information about the fact itself, the state also contains a reference to the contract that governs the evolution of the state over time. We discuss contracts in Contracts.
State sequences

As states are immutable, they cannot be modified directly to reflect a change in the state of the world.
Instead, the lifecycle of a shared fact over time is represented by a state sequence. When a state needs to be updated, we create a new version of the state representing the new state of the world, and mark the existing state as historic.
This sequence of state replacements gives us a full view of the evolution of the shared fact over time. We can picture this situation as follows:

The vault

Each node on the network maintains a vault - a database where it tracks all the current and historic states that it is aware of, and which it considers to be relevant to itself:
Reference states

Not all states need to be updated by the parties which use them. In the case of reference data, there is a common pattern where one party creates reference data, which is then used (but not updated) by other parties. For this use-case, the states containing reference data are referred to as “reference states”. Syntactically, reference states are no different to regular states. However, they are treated different by Corda transactions. See Transactions for more details.
Reissuing states

See Reissuing states for information about reissuing states with a guaranteed state replacement, which allows you to break transaction backchains.
Was this page helpful?
Thanks for your feedback!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.
We're sorry this page wasn't helpful. Let us know how we can make it better!
Chat with us
Chat with us on our #docs channel on slack. You can also join a lot of other slack channels there and have access to 1-on-1 communication with members of the R3 team and the online community.
Create an issue
Create a new GitHub issue in this repository - submit technical feedback, draw attention to a potential documentation bug, or share ideas for improvement and general feedback.
Propose documentation improvements directly
Help us to improve the docs by contributing directly. It's simple - just fork this repository and raise a PR of your own - R3's Technical Writers will review it and apply the relevant suggestions.