States

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, such as, stocks, bonds, loans, KYC data, and identity information.

For example, this state represents an IOU—an agreement that Alice owes Bob £5:

state

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.

States in the Corda 5 Developer Preview

In the Corda 5 Developer Preview, the main principles of states, transactions, and contracts remain the same as they were in Corda 4. However, as your CorDapp’s external interactions are performed via HTTP-RPC REST APIs (and the node returns information in the same way), when writing states you must add a JsonRepresentable.

State sequences

As states are immutable, they cannot be modified directly to reflect a change to a shared fact. Instead, the lifecycle of a shared fact over time is represented by a state sequence. When a shared fact changes, you must create a new version of the state (which represents the updated fact) and mark the existing state as historic. See transactions for more information.

This sequence of state replacements gives you a full view of the evolution of the shared fact over time:

state sequence

The vault

Each node on the network maintains a vault—a database which tracks all the current and historic states that the node is aware of and considers to be relevant (to itself):

vault simple

The ledger is all the current (non-historic) states that a particular node is aware of.

Reference states

Not all states need to be updated by the parties which use them. In the case of reference data, a party creates it, and it 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 differently by Corda transactions. See transactions for more details.

Reissuing states

You can break transaction backchains by reissuing states with a guaranteed state replacement.

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.