corda / net.corda.core.node / ServiceHub

ServiceHub

interface ServiceHub : ServicesForResolution

A service hub is the starting point for most operations you can do inside the node. You are provided with one when a class annotated with CordaService is constructed, and you have access to one inside flows. Most RPCs simply forward to the services found here after some access checking.

The APIs are organised roughly by category, with a few very important top level APIs available on the ServiceHub itself. Inside a flow, it's safe to keep a reference to services found here on the stack: checkpointing will do the right thing (it won't try to serialise the internals of the service).

In unit test environments, some of those services may be missing or mocked out.

Properties

clock

abstract val clock: Clock

A Clock representing the node's current time. This should be used in preference to directly accessing the clock so the current time can be controlled during unit testing.

contractUpgradeService

abstract val contractUpgradeService: ContractUpgradeService

The ContractUpgradeService is responsible for securely upgrading contract state objects according to a specified and mutually agreed (amongst participants) contract version.

keyManagementService

abstract val keyManagementService: KeyManagementService

The key management service is responsible for storing and using private keys to sign things. An implementation of this may, for example, call out to a hardware security module that enforces various auditing and frequency-of-use requirements.

myInfo

abstract val myInfo: NodeInfo

The NodeInfo object corresponding to our own entry in the network map.

networkMapCache

abstract val networkMapCache: NetworkMapCache

A network map contains lists of nodes on the network along with information about their identity keys, services they provide and host names or IP addresses where they can be connected to. The cache wraps around a map fetched from an authoritative service, and adds easy lookup of the data stored within it. Generally it would be initialised with a specified network map service, which it fetches data from and then subscribes to updates of.

validatedTransactions

abstract val validatedTransactions: TransactionStorage

A map of hash->tx where tx has been signature/contract validated and the states are known to be correct. The signatures aren't technically needed after that point, but we keep them around so that we can relay the transaction data to other nodes that need it.

vaultService

abstract val vaultService: VaultService

The vault service lets you observe, soft lock and add notes to states that involve you or are relevant to your node in some way. Additionally you may query and track states that correspond to various criteria.

Inherited Properties

attachments

abstract val attachments: AttachmentStorage

Provides access to storage of arbitrary JAR files (which may contain only data, no code).

cordappProvider

abstract val cordappProvider: CordappProvider

Provides access to anything relating to cordapps including contract attachment resolution and app context

identityService

abstract val identityService: IdentityService

An identity service maintains a directory of parties by their associated distinguished name/public keys and thus supports lookup of a party given its key, or name. The service also manages the certificates linking confidential identities back to the well known identity (i.e. the identity in the network map) of a party.

networkParameters

abstract val networkParameters: NetworkParameters

Returns the network parameters the node is operating under.

Functions

addSignature

open fun addSignature(signedTransaction: SignedTransaction, publicKey: PublicKey): SignedTransaction

Helper method to append an additional signature to an existing (partially) SignedTransaction.

open fun addSignature(signedTransaction: SignedTransaction): SignedTransaction

Helper method to append an additional signature for an existing (partially) SignedTransaction using the default identity signing key of the node.

cordaService

abstract fun <T : SerializeAsToken> cordaService(type: Class<T>): T

Return the singleton instance of the given Corda service type. This is a class that is annotated with CordaService and will have automatically been registered by the node.

createSignature

open fun createSignature(signedTransaction: SignedTransaction, publicKey: PublicKey): TransactionSignature

Helper method to create an additional signature for an existing (partially) SignedTransaction. Additional SignatureMetadata, including the platform version used during signing and the cryptographic signature scheme use, is added to the signature.

open fun createSignature(signedTransaction: SignedTransaction): TransactionSignature

Helper method to create a signature for an existing (partially) SignedTransaction using the default identity signing key of the node. The legal identity key is used to sign. Additional SignatureMetadata, including the platform version used during signing and the cryptographic signature scheme use, is added to the signature.

open fun createSignature(filteredTransaction: FilteredTransaction, publicKey: PublicKey): TransactionSignature

Helper method to create a signature for a FilteredTransaction. Additional SignatureMetadata, including the platform version used during signing and the cryptographic signature scheme use, is added to the signature.

open fun createSignature(filteredTransaction: FilteredTransaction): TransactionSignature

Helper method to create a signature for a FilteredTransaction using the default identity signing key of the node. The legal identity key is used to sign. Additional SignatureMetadata, including the platform version used during signing and the cryptographic signature scheme use, is added to the signature.

jdbcSession

abstract fun jdbcSession(): Connection

Exposes a JDBC connection (session) object using the currently configured database. Applications can use this to execute arbitrary SQL queries (native, direct, prepared, callable) against its Node database tables (including custom contract tables defined by extending net.corda.core.schemas.QueryableState).

recordTransactions

open fun recordTransactions(notifyVault: Boolean, txs: Iterable<SignedTransaction>): Unit
open fun recordTransactions(notifyVault: Boolean, first: SignedTransaction, vararg remaining: SignedTransaction): Unit

Stores the given SignedTransactions in the local transaction storage and then sends them to the vault for further processing if notifyVault is true. This is expected to be run within a database transaction.

abstract fun recordTransactions(statesToRecord: StatesToRecord, txs: Iterable<SignedTransaction>): Unit

Stores the given SignedTransactions in the local transaction storage and then sends them to the vault for further processing if statesToRecord is not StatesToRecord.NONE. This is expected to be run within a database transaction.

open fun recordTransactions(first: SignedTransaction, vararg remaining: SignedTransaction): Unit
open fun recordTransactions(txs: Iterable<SignedTransaction>): Unit

Stores the given SignedTransactions in the local transaction storage and then sends them to the vault for further processing. This is expected to be run within a database transaction.

registerUnloadHandler

abstract fun registerUnloadHandler(runOnStop: () -> Unit): Unit

Allows the registration of a callback that may inform services when the app is shutting down.

signInitialTransaction

open fun signInitialTransaction(builder: TransactionBuilder, publicKey: PublicKey): SignedTransaction

Helper method to construct an initial partially signed transaction from a TransactionBuilder using keys stored inside the node. Signature metadata is added automatically.

open fun signInitialTransaction(builder: TransactionBuilder): SignedTransaction

Helper method to construct an initial partially signed transaction from a TransactionBuilder using the default identity key contained in the node. The legal identity key is used to sign.

open fun signInitialTransaction(builder: TransactionBuilder, signingPubKeys: Iterable<PublicKey>): SignedTransaction

Helper method to construct an initial partially signed transaction from a TransactionBuilder using a set of keys all held in this node.

toStateAndRef

open fun <T : ContractState> toStateAndRef(stateRef: StateRef): StateAndRef<T>

Converts the given StateRef into a StateAndRef object.

Inherited Functions

loadState

abstract fun loadState(stateRef: StateRef): TransactionState<*>

Given a StateRef loads the referenced transaction and looks up the specified output ContractState.

loadStates

abstract fun loadStates(stateRefs: Set<StateRef>): Set<StateAndRef<ContractState>>

Given a Set of StateRef's loads the referenced transaction and looks up the specified output ContractState.

Extension Functions

contextLogger

fun Any.contextLogger(): Logger

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

getCashBalance

fun ServiceHub.getCashBalance(currency: Currency): Amount<Currency>

getCashBalances

fun ServiceHub.getCashBalances(): Map<Currency, Amount<Currency>>

ledger

fun ServiceHub.ledger(notary: Party = TestIdentity.fresh("ledger notary").party, script: LedgerDSL<TestTransactionDSLInterpreter, TestLedgerDSLInterpreter>.() -> Unit): LedgerDSL<TestTransactionDSLInterpreter, TestLedgerDSLInterpreter>

Creates and tests a ledger built by the passed in dsl.

transaction

fun ServiceHub.transaction(notary: Party = TestIdentity.fresh("transaction notary").party, script: TransactionDSL<TransactionDSLInterpreter>.() -> EnforceVerifyOrFail): LedgerDSL<TestTransactionDSLInterpreter, TestLedgerDSLInterpreter>

Creates a ledger with a single transaction, built by the passed in dsl.

Inheritors

AppServiceHub

interface AppServiceHub : ServiceHub

A CordaService annotated class requires a constructor taking a single parameter of type AppServiceHub. With the AppServiceHub parameter a CordaService is able to access to privileged operations. In particular such a CordaService can initiate and track flows marked with net.corda.core.flows.StartableByService.

MockServices

open class MockServices : ServiceHub

An implementation of ServiceHub that is designed for in-memory unit tests of contract validation logic. It has enough functionality to do tests of code that queries the vault, inserts to the vault, and constructs/checks transactions. However it isn't enough to test flows and other aspects of an app that require a network. For that you should investigate MockNetwork.