corda/docs/source/key-concepts-vault.rst
josecoll ac1d14464c Key Concepts rewrite for open source day ()
First draft

Re-structured Key Concepts; added plenty of diagrams; additional content.

Added references to other security docs.

Re-structured Key Concepts; added plenty of diagrams; additional content.

Added references to other security docs.

Updated information, indexes and images.

Incorporated feedback from PR review comments (RGB, RW)

Reformatted diagrams and incorporated feedback from PR reviewers.

Addressed formatting problems.

Updated Flow Framework diagram

Added colour coding to Flow Framework diagram to aid readibility.

Small clarification to vault unconsumed state usage.

Added tutorial reference as suggested by RGB

Updated TOC tree.

Updates following PR review comment from Roger

First pass updates following PR review comments from MH.

Further updates following PR review (including 2 edited diagrams)

Diagram changes and minor text edits following review with MGB

Remove unused diagrams.

Fixed spurious indentation errors.

Changes following review and feedback from JD.
Added clauses and merkle-trees back into TOC.
Added small sub-section on transaction representation in Data Model.
Added future work as note in Vault.

Minor updates to diagrams following MH review.

Updated Corda Ecosystem diagram.

Minor changes to Core & Financial docs following PR review by MH.

Updated following review by MBG.
2017-01-26 15:46:40 +00:00

3.7 KiB
Raw Blame History

Vault

The vault contains data extracted from the ledger that is considered relevant to the nodes owner, stored in a relational model that can be easily queried and worked with.

The vault keeps track of both unconsumed and consumed states:

  • Unconsumed (or unspent) states represent fungible states available for spending (including spend-to-self transactions) and linear states available for evolution (eg. in response to a lifecycle event on a deal) or transfer to another party.
  • Consumed (or spent) states represent ledger immutable state for the purpose of transaction reporting, audit and archival, including the ability to perform joins with app-private data (like customer notes)

By fungible we refer to assets of measurable quantity (eg. a cash currency, units of stock) which can be combined together to represent a single ledger state.

Like with a cryptocurrency wallet, the Corda vault can create transactions that send value (eg. transfer of state) to someone else by combining fungible states and possibly adding a change output that makes the values balance (this process is usually referred to as coin selection). Vault spending ensures that transactions respect the fungibility rules in order to ensure that the issuer and reference data is preserved as the assets pass from hand to hand.

Note

Basic 'coin selection' is currently implemented. Future work includes fungible state optimisation (splitting and merging of states in the background), 'soft locking' (ability to automatically or explicitly reserve states to prevent multiple transactions trying to use the same output simultaneously), 'state re-issuance' (sending of states back to the issuer for re-issuance, thus pruning long transaction chains and improving privacy).

There is also a facility for attaching descriptive textual notes against any transaction stored in the vault.

The vault supports the management of data in both authoritative ("on-ledger") form and, where appropriate, shadow ("off-ledger") form:

  • "On-ledger" data refers to distributed ledger state (cash, deals, trades) to which a firm is participant.
  • "Off-ledger" data refers to a firm's internal reference, static and systems data.

The following diagram illustrates the breakdown of the vault into sub-system components:

image

Note the following:

  • the vault "On Ledger" store tracks unconsumed state and is updated internally by the node upon recording of a transaction on the ledger (following successful smart contract verification and signature by all participants)
  • the vault "Off Ledger" store refers to additional data added by the node owner subsequent to transaction recording
  • the vault performs fungible state spending (and in future, fungible state optimisation management including merging, splitting and re-issuance)
  • vault extensions represent additional custom plugin code a developer may write to query specific custom contract state attributes.
  • customer "Off Ledger" (private store) represents internal organisational data that may be joined with the vault data to perform additional reporting or processing
  • a vault query API is exposed to developers using standard Corda RPC and CorDapp plugin mechanisms
  • a vault update API is internally used by transaction recording flows.
  • the vault database schemas are directly accessible via JDBC for customer joins and queries

Section 8 of the Technical white paper describes features of the vault yet to be implemented including private key managament, soft state locking, state splitting and merging, asset re-issuance and node event scheduling.