corda / net.corda.core.node.services / VaultService

VaultService

@DoNotImplement interface VaultService

A VaultService is responsible for securely and safely persisting the current state of a vault to storage. The vault service vends immutable snapshots of the current vault for working with: if you build a transaction based on a vault that isn't current, be aware that it may end up being invalid if the states that were used have been consumed by someone else first!

Note that transactions we've seen are held by the storage service, not the vault.

Properties

rawUpdates

abstract val rawUpdates: Observable<Update<ContractState>>

Prefer the use of updates unless you know why you want to use this instead.

updates

abstract val updates: Observable<Update<ContractState>>

Get a synchronous Observable of updates. When observations are pushed to the Observer, the Vault will already incorporate the update and the database transaction associated with the update will have been committed and closed.

Functions

_queryBy

abstract fun <T : ContractState> _queryBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort, contractStateType: Class<out T>): Page<T>

Generic vault query function which takes a QueryCriteria object to define filters, optional PageSpecification and optional Sort modification criteria (default unsorted), and returns a Vault.Page object containing the following:

_trackBy

abstract fun <T : ContractState> _trackBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort, contractStateType: Class<out T>): DataFeed<Page<T>, Update<T>>

Generic vault query function which takes a QueryCriteria object to define filters, optional PageSpecification and optional Sort modification criteria (default unsorted), and returns a DataFeed object containing:

addNoteToTransaction

abstract fun addNoteToTransaction(txnId: SecureHash, noteText: String): Unit

Add a note to an existing LedgerTransaction given by its unique SecureHash id. Multiple notes may be attached to the same LedgerTransaction. These are additively and immutably persisted within the node local vault database in a single textual field. using a semi-colon separator.

getTransactionNotes

abstract fun getTransactionNotes(txnId: SecureHash): Iterable<String>

queryBy

open fun <T : ContractState> queryBy(contractStateType: Class<out T>): Page<T>
open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria): Page<T>
open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification): Page<T>
open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, sorting: Sort): Page<T>
open fun <T : ContractState> queryBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): Page<T>

softLockRelease

abstract fun softLockRelease(lockId: UUID, stateRefs: NonEmptySet<StateRef>? = null): Unit

Release all or an explicitly specified set of StateRef for a given UUID unique identifier. A Vault soft-lock manager is automatically notified from flows that are terminated, such that any soft locked states may be released. In the case of coin selection, soft-locks are automatically released once previously gathered unconsumed input refs are consumed as part of cash spending.

softLockReserve

abstract fun softLockReserve(lockId: UUID, stateRefs: NonEmptySet<StateRef>): Unit

Reserve a set of StateRef for a given UUID unique identifier. Typically, the unique identifier will refer to a FlowLogic.runId's UUID associated with an in-flight flow. In this case if the flow terminates the locks will automatically be freed, even if there is an error. However, the user can specify their own UUID and manage this manually, possibly across the lifetime of multiple flows, or from other thread contexts e.g. CordaService instances. In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs.

trackBy

open fun <T : ContractState> trackBy(contractStateType: Class<out T>): DataFeed<Page<T>, Update<T>>
open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria): DataFeed<Page<T>, Update<T>>
open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification): DataFeed<Page<T>, Update<T>>
open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, sorting: Sort): DataFeed<Page<T>, Update<T>>
open fun <T : ContractState> trackBy(contractStateType: Class<out T>, criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): DataFeed<Page<T>, Update<T>>

tryLockFungibleStatesForSpending

abstract fun <T : FungibleAsset<U>, U : Any> tryLockFungibleStatesForSpending(lockId: UUID, eligibleStatesQuery: QueryCriteria, amount: Amount<U>, contractStateType: Class<out T>): List<StateAndRef<T>>

Helper function to determine spendable states and soft locking them. Currently performance will be worse than for the hand optimised version in Cash.unconsumedCashStatesForSpending. However, this is fully generic and can operate with custom FungibleAsset states.

whenConsumed

open fun whenConsumed(ref: StateRef): CordaFuture<Update<ContractState>>

Provide a CordaFuture for when a StateRef is consumed, which can be very useful in building tests.

Extension Functions

contextLogger

fun Any.contextLogger(): Logger

When called from a companion object, returns the logger for the enclosing class.

queryBy

fun <T : ContractState> VaultService.queryBy(): Page<T>
fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria): Page<T>
fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, paging: PageSpecification): Page<T>
fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, sorting: Sort): Page<T>
fun <T : ContractState> VaultService.queryBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): Page<T>

trackBy

fun <T : ContractState> VaultService.trackBy(): DataFeed<Page<T>, Update<T>>
fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria): DataFeed<Page<T>, Update<T>>
fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, paging: PageSpecification): DataFeed<Page<T>, Update<T>>
fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, sorting: Sort): DataFeed<Page<T>, Update<T>>
fun <T : ContractState> VaultService.trackBy(criteria: QueryCriteria, paging: PageSpecification, sorting: Sort): DataFeed<Page<T>, Update<T>>