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

VaultService

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

cashBalances	`abstract val cashBalances: Map<Currency, Amount<Currency>>` Returns a map of how much cash we have in each currency, ignoring details like issuer. Note: currencies for which we have no cash evaluate to null (not present in map), not 0.
rawUpdates	`abstract val rawUpdates: Observable<Update>` Prefer the use of updates unless you know why you want to use this instead.
updates	`abstract val updates: Observable<Update>` 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.
updatesPublisher	`abstract val updatesPublisher: PublishSubject<Update>` Enable creation of observables of updates.

Functions

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
authoriseContractUpgrade	`abstract fun authoriseContractUpgrade(stateAndRef: StateAndRef<>, upgradedContractClass: Class<out UpgradedContract<, *>>): Unit` Authorise a contract state upgrade. This will store the upgrade authorisation in the vault, and will be queried by ContractUpgradeFlow.Acceptor during contract upgrade process. Invoking this method indicate the node is willing to upgrade the state using the upgradedContractClass. This method will NOT initiate the upgrade process. To start the upgrade process, see ContractUpgradeFlow.Instigator.
deauthoriseContractUpgrade	`abstract fun deauthoriseContractUpgrade(stateAndRef: StateAndRef<*>): Unit` Authorise a contract state upgrade. This will remove the upgrade authorisation from the vault.
generateSpend	`abstract fun generateSpend(tx: TransactionBuilder, amount: Amount<Currency>, to: AbstractParty, onlyFromParties: Set<AbstractParty>? = null): Pair<TransactionBuilder, List<PublicKey>>` Generate a transaction that moves an amount of currency to the given pubkey.
getAuthorisedContractUpgrade	`abstract fun getAuthorisedContractUpgrade(ref: StateRef): Class<out UpgradedContract<, >>?` Get contracts we would be willing to upgrade the suggested contract to.
getTransactionNotes	`abstract fun getTransactionNotes(txnId: SecureHash): Iterable<String>`
notify	`open fun notify(tx: WireTransaction): Unit` Same as notifyAll but with a single transaction.
notifyAll	`abstract fun notifyAll(txns: Iterable<WireTransaction>): Unit` Possibly update the vault by marking as spent states that these transactions consume, and adding any relevant new states that they create. You should only insert transactions that have been successfully verified here!
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 of a Flows that are terminated, such that any soft locked states may be released. In the case of coin selection, softLock 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 Flow lockId associated with a Transaction in an in-flight flow. In the case of coin selection, soft locks are automatically taken upon gathering relevant unconsumed input refs.
softLockedStates	`abstract fun <T : ContractState> softLockedStates(lockId: UUID? = null): List<StateAndRef<T>>` Retrieve softLockStates for a given UUID or return all softLockStates in vault for a given ContractState type
states	`abstract fun <T : ContractState> states(clazzes: Set<Class<T>>, statuses: EnumSet<StateStatus>, includeSoftLockedStates: Boolean = true): Iterable<StateAndRef<T>>` Return ContractStates of a given Contract type and Iterable of Vault.StateStatus. Optionally may specify whether to include StateRef that have been marked as soft locked (default is true)
statesForRefs	`abstract fun statesForRefs(refs: List<StateRef>): Map<StateRef, TransactionState<*>?>` Return unconsumed ContractStates for a given set of StateRefs
track	`abstract fun track(): DataFeed<Vault<ContractState>, Update>` Atomically get the current vault and a stream of updates. Note that the Observable buffers updates until the first subscriber is registered so as to avoid racing with early updates.
unconsumedStatesForSpending	`abstract fun <T : ContractState> unconsumedStatesForSpending(amount: Amount<Currency>, onlyFromIssuerParties: Set<AbstractParty>? = null, notary: Party? = null, lockId: UUID, withIssuerRefs: Set<OpaqueBytes>? = null): List<StateAndRef<T>>` TODO: this function should be private to the vault, but currently Cash Exit functionality is implemented in a separate module (finance) and requires access to it.
whenConsumed	`open fun whenConsumed(ref: StateRef): ListenableFuture<Update>` Provide a Future for when a StateRef is consumed, which can be very useful in building tests.

Extension Functions

consumedStates	`fun <T : ContractState> VaultService.consumedStates(): Iterable<StateAndRef<T>>`
dealsWith	`fun <T : DealState> VaultService.dealsWith(party: AbstractParty): List<StateAndRef<T>>`
declaredField	`fun <T> Any.declaredField(name: String): DeclaredField<T>` Returns a DeclaredField wrapper around the declared (possibly non-public) instance field of the receiver object. `fun <T> Any.declaredField(clazz: KClass<*>, name: String): DeclaredField<T>` Returns a DeclaredField wrapper around the (possibly non-public) instance field of the receiver object, but declared in its superclass clazz.
linearHeadsOfType	`fun <T : LinearState> VaultService.linearHeadsOfType(): Map<UniqueIdentifier, StateAndRef<T>>` Returns the linearState heads only when the type of the state would be considered an 'instanceof' the given type.
unconsumedStates	`fun <T : ContractState> VaultService.unconsumedStates(includeSoftLockedStates: Boolean = true): Iterable<StateAndRef<T>>`

Inheritors

NodeVaultService

class NodeVaultService : SingletonSerializeAsToken, VaultService

Currently, the node vault service is a very simple RDBMS backed implementation. It will change significantly when we add further functionality as the design for the vault and vault service matures.