net.corda.core.node.services

## Interface VaultService

- All Known Implementing Classes:
    NodeVaultService

      public VaultService

  A `interface 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.

  See Also:
    `interface VaultService`

- - ### Nested Class Summary

    Nested Classes
    Modifier and Type | Interface and Description
    --- | ---
    `static class` | `VaultService.DefaultImpls` A `interface 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!

  - ### Method Summary

    All Methods Instance Methods Default Methods
    Modifier and Type | Method and Description
    --- | ---
    `void` | `addNoteToTransaction(SecureHash txnId, java.lang.String noteText)` Add a note to an existing LedgerTransaction given by its unique `class 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
    `void` | `authoriseContractUpgrade(StateAndRef<?> stateAndRef, java.lang.Class<? extends net.corda.core.contracts.UpgradedContract<?,?>> upgradedContractClass)` 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.
    `void` | `deauthoriseContractUpgrade(StateAndRef<?> stateAndRef)` Authorise a contract state upgrade. This will remove the upgrade authorisation from the vault.
    `kotlin.Pair<net.corda.core.transactions.TransactionBuilder,java.util.List>` | `generateSpend(TransactionBuilder tx, Amount<java.util.Currency> amount, CompositeKey to, java.util.Set<? extends net.corda.core.crypto.AbstractParty> onlyFromParties)` Generate a transaction that moves an amount of currency to the given pubkey.
    `java.lang.Class<? extends net.corda.core.contracts.UpgradedContract<?,?>>` | `getAuthorisedContractUpgrade(StateRef ref)` Get contracts we would be willing to upgrade the suggested contract to.
    `java.util.Map<java.util.Currency,net.corda.core.contracts.Amount>` | `getCashBalances()` 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.
    `rx.Observable<net.corda.core.node.services.Vault.Update>` | `getRawUpdates()` Prefer the use of updates unless you know why you want to use this instead.
    `java.lang.Iterable<java.lang.String>` | `getTransactionNotes(SecureHash txnId)`
    `rx.Observable<net.corda.core.node.services.Vault.Update>` | `getUpdates()` 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.
    `void` | `notify(WireTransaction tx)` Same as notifyAll but with a single transaction.
    `void` | `notifyAll(java.lang.Iterable<net.corda.core.transactions.WireTransaction> txns)` 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!
    `<T extends ContractState> java.util.List<net.corda.core.contracts.StateAndRef>` | `states(java.util.Set<java.lang.Class> clazzes, java.util.EnumSet<net.corda.core.node.services.Vault.StateStatus> statuses)` Return `interface ContractState`s of a given `interface Contract` type and list of `enum Vault.StateStatus`
    `java.util.Map<net.corda.core.contracts.StateRef,net.corda.core.contracts.TransactionState>` | `statesForRefs(java.util.List<net.corda.core.contracts.StateRef> refs)` Return unconsumed `interface ContractState`s for a given set of `class StateRef`s TODO: revisit and generalize this exposed API function.
    `kotlin.Pair<net.corda.core.node.services.Vault,rx.Observable>` | `track()` 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.
    `com.google.common.util.concurrent.ListenableFuture<net.corda.core.node.services.Vault.Update>` | `whenConsumed(StateRef ref)` Provide a Future for when a `class StateRef` is consumed, which can be very useful in building tests.

- - ### Method Detail

    - #### getRawUpdates

          rx.Observable<net.corda.core.node.services.Vault.Update> getRawUpdates()

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

      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 still be open and current. If for some reason the processing crosses outside of the database transaction (for example, the update is pushed outside the current JVM or across to another Thread which is executing in a different database transaction) then the Vault may not incorporate the update due to racing with committing the current database transaction.

      See Also:
        Thread

    - #### getUpdates

          rx.Observable<net.corda.core.node.services.Vault.Update> getUpdates()

      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.

    - #### getCashBalances

          java.util.Map<java.util.Currency,net.corda.core.contracts.Amount> getCashBalances()

      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.

    - #### track

          kotlin.Pair<net.corda.core.node.services.Vault,rx.Observable> track()

      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.

    - #### statesForRefs

          java.util.Map<net.corda.core.contracts.StateRef,net.corda.core.contracts.TransactionState> statesForRefs(java.util.List<net.corda.core.contracts.StateRef> refs)

      Return unconsumed `interface ContractState`s for a given set of `class StateRef`s TODO: revisit and generalize this exposed API function.

      See Also:
        `interface ContractState`, `class StateRef`

    - #### notifyAll

          void notifyAll(java.lang.Iterable<net.corda.core.transactions.WireTransaction> txns)

      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!

      TODO: Consider if there's a good way to enforce the must-be-verified requirement in the type system.

    - #### notify

          void notify(WireTransaction tx)

      Same as notifyAll but with a single transaction.

    - #### whenConsumed

          com.google.common.util.concurrent.ListenableFuture<net.corda.core.node.services.Vault.Update> whenConsumed(StateRef ref)

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

      See Also:
        Future, `class StateRef`

    - #### getAuthorisedContractUpgrade

          java.lang.Class<? extends net.corda.core.contracts.UpgradedContract<?,?>> getAuthorisedContractUpgrade(StateRef ref)

      Get contracts we would be willing to upgrade the suggested contract to.

    - #### authoriseContractUpgrade

          void authoriseContractUpgrade(StateAndRef<?> stateAndRef,
                                        java.lang.Class<? extends net.corda.core.contracts.UpgradedContract<?,?>> upgradedContractClass)

      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.

      See Also:
        ContractUpgradeFlow.Acceptor, state, ContractUpgradeFlow.Instigator

    - #### deauthoriseContractUpgrade

          void deauthoriseContractUpgrade(StateAndRef<?> stateAndRef)

      Authorise a contract state upgrade. This will remove the upgrade authorisation from the vault.

    - #### addNoteToTransaction

          void addNoteToTransaction(SecureHash txnId,
                                    java.lang.String noteText)

      Add a note to an existing LedgerTransaction given by its unique `class 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

      See Also:
        LedgerTransaction, `class SecureHash`, LedgerTransaction

    - #### getTransactionNotes

          java.lang.Iterable<java.lang.String> getTransactionNotes(SecureHash txnId)

    - #### generateSpend

          kotlin.Pair<net.corda.core.transactions.TransactionBuilder,java.util.List> generateSpend(TransactionBuilder tx,
                                                                                                   Amount<java.util.Currency> amount,
                                                                                                   CompositeKey to,
                                                                                                   java.util.Set<? extends net.corda.core.crypto.AbstractParty> onlyFromParties)

      Generate a transaction that moves an amount of currency to the given pubkey.

      Note: an `class Amount` of Currency is only fungible for a given Issuer Party within a `interface FungibleAsset`

      Parameters:
        `tx` - A builder, which may contain inputs, outputs and commands already. The relevant components needed to move the cash will be added on top.
        `amount` - How much currency to send.
        `to` - a key of the recipient.
        `onlyFromParties` - if non-null, the asset states will be filtered to only include those issued by the set of given parties. This can be useful if the party you're trying to pay has expectations about which type of asset claims they are willing to accept.
      Returns:
        A Pair of the same transaction builder passed in as tx, and the list of keys that need to sign the resulting transaction for it to be valid.
      Throws:
        - when a cash spending transaction fails because there is insufficient quantity for a given currency (and optionally set of Issuer Parties).
      See Also:
        `class Amount`, Currency, `interface FungibleAsset`

    - #### states

          <T extends ContractState> java.util.List<net.corda.core.contracts.StateAndRef> states(java.util.Set<java.lang.Class> clazzes,
                                                                                                java.util.EnumSet<net.corda.core.node.services.Vault.StateStatus> statuses)

      Return `interface ContractState`s of a given `interface Contract` type and list of `enum Vault.StateStatus`

      See Also:
        `interface ContractState`, `interface Contract`, `enum Vault.StateStatus`