mirror of
https://github.com/corda/corda.git
synced 2024-12-22 06:17:55 +00:00
8c3b9ac589
* Added queryBy(QueryCriteria) Vault API and Junit tests. * Minor fix following rebase. * Spit out Vault Query tests into separate source file. * WIP * Enable composition of QueryCriteria specifications. Additional JUnit test cases to validate API. * Added Deprecating annotations. Added QueryCriteria for set of contractStateTypes * Minor tweaks and additional JUnit test cases (chain of linear id) * Added Java Junit tests and QueryCriteria builder support. * Added API documentation (including coding snippets and examples). * Added @JvmOverloads to QueryCriteria classes for easy of use from Java. * Refactored QueryCriteria API to use composition via sealed data classes. * Enable infix notation. * Fixed typo. * Clarified future work to enforce DB level permissioning. * Moved PageSpec and Order from QueryCriteria to become parameters of Query itself. * Moved PageSpec and Order from QueryCriteria to become parameters of Query itself. * TokenType now specified as set of <Class> (was non extensible enum). * Exposed new Vault Query API functions via RPC. * Fixed compiler error in java test. * Addressed a couple of minor PR review scomments from MH. * Major updates following PR discussion and recommendations. * All pagination and sorting arguments are optional (and constructed with sensible defaults). Added Java helper functions for queryBy and trackBy interfaces. Added Java trackBy unit tests. Miscellaneous cleanup. * Added Generic Index schema mapping and query support. * Query criteria referencing Party now references a String (until Identity framework built out). Added participants attribute to general query criteria. * Fleshed our IndexCriteria including PR recommendation to define column aliases for index mappings. * Removed all directly exposed API dependencies on requery. * Updated documentation. * Provide sensible defaults for all Query arguments. Add RPC Java helpers and increase range of Vault Service helpers. * Further improvements (upgrading notes) and updates to documentation. * RST documentation updates. * Updates to address RP latest set of review comments. * Updates to address MH latest set of review comments. * Updated to highlight use of VaultIndexQueryCriteria to directly reference a JPA-annotated entity (versus the indirect, explicitly mapped attribute to GenericIndexSchema approach) * Aesthetic updates requested by MH * Reverted Indexing approach: removed all references to VaultIndexedQueryCriteria and GenericVaultIndexSchemaV1 scheme. * Final clean-up and minor updates prior to merge. * Fixed compiler warnings (except deprecation warnings) * Reverted all changes to Vault Schemas (except simple illustrative VaultLinearState used in VaultQueryTests) * Reverted all changes to Vault Schemas (except simple illustrative VaultLinearState used in VaultQueryTests) * Commented out @Deprecated annotations (as a hedge against us releasing M12 with the work half-done) * Renamed RPC JavaHelper functions as RPCDispatcher does not allow more than one method with same name.
57 lines
3.9 KiB
ReStructuredText
57 lines
3.9 KiB
ReStructuredText
Vault
|
||
=====
|
||
|
||
The vault contains data extracted from the ledger that is considered relevant to the node’s 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.
|
||
|
||
A feature called **soft locking** provides the ability to automatically or explicitly reserve states to prevent
|
||
multiple transactions within the same node from trying to use the same output simultaneously. Whilst this scenario would
|
||
ultimately be detected by a notary, *soft locking* provides a mechanism of early detection for such unwarranted and
|
||
invalid scenarios. :doc:`soft-locking` describes this feature in detail.
|
||
|
||
.. note:: Basic 'coin selection' is currently implemented. Future work includes fungible state optimisation (splitting and
|
||
merging of states in the background), and '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:: resources/vault.png
|
||
|
||
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 :doc:`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, state splitting and merging, asset re-issuance and node event scheduling.
|
||
|
||
.. _`Technical white paper`: _static/corda-technical-whitepaper.pdf
|
||
|