mirror of
https://github.com/corda/corda.git
synced 2024-12-19 13:08:04 +00:00
6f05f639fb
* Added more docs for reference states to key concepts and api docs. * Updated with requested changes
71 lines
2.7 KiB
ReStructuredText
71 lines
2.7 KiB
ReStructuredText
States
|
|
======
|
|
|
|
.. topic:: 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*
|
|
|
|
.. only:: htmlmode
|
|
|
|
Video
|
|
-----
|
|
.. raw:: html
|
|
|
|
<iframe src="https://player.vimeo.com/video/213812054" width="640" height="360" frameborder="0" webkitallowfullscreen mozallowfullscreen allowfullscreen></iframe>
|
|
<p></p>
|
|
|
|
|
|
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:
|
|
|
|
.. image:: resources/state.png
|
|
:scale: 25%
|
|
:align: center
|
|
|
|
Specifically, this state represents an IOU of £10 from Alice to Bob.
|
|
|
|
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 :doc:`key-concepts-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:
|
|
|
|
.. image:: resources/state-sequence.png
|
|
:scale: 25%
|
|
:align: center
|
|
|
|
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:
|
|
|
|
.. image:: resources/vault-simple.png
|
|
:scale: 25%
|
|
:align: center
|
|
|
|
We can think of the ledger from each node's point of view as the set of all the current (i.e. non-historic) states that
|
|
it is aware of.
|
|
|
|
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 :doc:`key-concepts-transactions` for
|
|
more details. |