Interface UtxoLedgerService
-
- All Implemented Interfaces:
@DoNotImplement() public interface UtxoLedgerService
Defines UTXO ledger services.
-
-
Method Summary
Modifier and Type Method Description abstract UtxoTransactionBuilder
createTransactionBuilder()
Gets a UTXO transaction builder. abstract void
verify(UtxoLedgerTransaction ledgerTransaction)
Verifies UtxoLedgerTransaction. abstract <T extends ContractState> List<StateAndRef<T>>
resolve(@NotNull() Iterable<StateRef> stateRefs)
Resolves the specified StateRef instances into StateAndRef instances of the specified ContractState type. abstract <T extends ContractState> StateAndRef<T>
resolve(@NotNull() StateRef stateRef)
Resolves the specified StateRef instance into a StateAndRef instance of the specified ContractState type. abstract UtxoSignedTransaction
findSignedTransaction(@NotNull() SecureHash id)
Finds a UtxoSignedTransaction in the vault by the specified transaction ID. abstract UtxoLedgerTransaction
findLedgerTransaction(@NotNull() SecureHash id)
Finds a UtxoLedgerTransaction in the vault by the specified transaction ID. abstract Map<SecureHash, UtxoFilteredTransactionAndSignatures>
findFilteredTransactionsAndSignatures(@NotNull() UtxoSignedTransaction signedTransaction)
Finds matching UtxoFilteredTransaction and the notary signatures for a given signed transaction in the vault. abstract UtxoFilteredTransactionBuilder
filterSignedTransaction(@NotNull() UtxoSignedTransaction transaction)
Filters a UtxoSignedTransaction to create a UtxoFilteredTransaction that only contains the components specified by the UtxoFilteredTransactionBuilder output from this method. abstract <T extends ContractState> List<StateAndRef<T>>
findUnconsumedStatesByType(@NotNull() Class<T> type)
Finds unconsumed states that are concrete implementations or subclasses of type
.abstract <T extends ContractState> PagedQuery.ResultSet<StateAndRef<T>>
findUnconsumedStatesByExactType(@NotNull() Class<T> type, @NotNull() Integer limit, @NotNull() Instant createdTimestampLimit)
Finds unconsumed states of the specified ContractState type in the vault. abstract FinalizationResult
finalize(@NotNull() UtxoSignedTransaction transaction, @NotNull() List<FlowSession> sessions)
Verifies, signs, collects signatures, records and broadcasts a UtxoSignedTransaction to participants and observers. abstract FinalizationResult
receiveFinality(@NotNull() FlowSession session, @NotNull() UtxoTransactionValidator validator)
Verifies, signs and records a UtxoSignedTransaction. abstract UtxoTransactionBuilder
sendAndReceiveTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends a transaction builder to another session, waits for the other side to propose transaction builder components, applies the proposed components to a copy of the original builder, and returns that new builder. abstract UtxoTransactionBuilder
receiveTransactionBuilder(@NotNull() FlowSession session)
Receives a transaction builder from another session. abstract void
sendUpdatedTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends the difference between the current transaction builder and the originally received one to another session with all dependent back chains. abstract void
sendTransaction(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends the transaction to counterparty sessions. abstract void
sendTransactionWithBackchain(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends the transaction to counterparty sessions and forces backchain resolution. abstract UtxoSignedTransaction
receiveTransaction(@NotNull() FlowSession session)
Receives a verified transaction from the counterparty session and persists it to the vault. abstract void
sendLedgerTransaction(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends an unsigned copy of the base LedgerTransaction to counterparty sessions. abstract UtxoLedgerTransaction
receiveLedgerTransaction(@NotNull() FlowSession session)
Receives a ledger transaction from the counterparty session. abstract <R> VaultNamedParameterizedQuery<R>
query(@NotNull() String queryName, @NotNull() Class<R> resultClass)
Creates a query object for a vault named query with the given name. abstract void
persistDraftSignedTransaction(@NotNull() UtxoSignedTransaction utxoSignedTransaction)
Persists a non-finalized (draft) transaction. abstract UtxoSignedTransaction
findDraftSignedTransaction(@NotNull() SecureHash id)
Finds a draft UtxoSignedTransaction in the vault by the specified transaction ID. -
-
Method Detail
-
createTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder createTransactionBuilder()
Gets a UTXO transaction builder.
- Returns:
Returns a new UtxoTransactionBuilder instance.
-
verify
@Suspendable() abstract void verify(UtxoLedgerTransaction ledgerTransaction)
Verifies UtxoLedgerTransaction.
- Parameters:
ledgerTransaction
- The UtxoLedgerTransaction to verify.
-
resolve
@NotNull()@Suspendable() abstract <T extends ContractState> List<StateAndRef<T>> resolve(@NotNull() Iterable<StateRef> stateRefs)
Resolves the specified StateRef instances into StateAndRef instances of the specified ContractState type.
- Parameters:
stateRefs
- The StateRef instances to resolve.- Returns:
Returns a List of StateAndRef of the specified ContractState type.
-
resolve
@NotNull()@Suspendable() abstract <T extends ContractState> StateAndRef<T> resolve(@NotNull() StateRef stateRef)
Resolves the specified StateRef instance into a StateAndRef instance of the specified ContractState type.
- Parameters:
stateRef
- The StateRef instances to resolve.- Returns:
Returns a StateAndRef of the specified ContractState type.
-
findSignedTransaction
@Nullable()@Suspendable() abstract UtxoSignedTransaction findSignedTransaction(@NotNull() SecureHash id)
Finds a UtxoSignedTransaction in the vault by the specified transaction ID.
- Parameters:
id
- The ID of the UtxoSignedTransaction to find.- Returns:
Returns the UtxoSignedTransaction if it has been recorded previously, or null if no transaction could be found.
-
findLedgerTransaction
@Nullable()@Suspendable() abstract UtxoLedgerTransaction findLedgerTransaction(@NotNull() SecureHash id)
Finds a UtxoLedgerTransaction in the vault by the specified transaction ID.
- Parameters:
id
- The ID of the UtxoLedgerTransaction to find.- Returns:
Returns the UtxoLedgerTransaction if it has been recorded previously, or null if no transaction could be found.
-
findFilteredTransactionsAndSignatures
@NotNull()@Suspendable() abstract Map<SecureHash, UtxoFilteredTransactionAndSignatures> findFilteredTransactionsAndSignatures(@NotNull() UtxoSignedTransaction signedTransaction)
Finds matching UtxoFilteredTransaction and the notary signatures for a given signed transaction in the vault.
- Parameters:
signedTransaction
- A new transaction of dependencies to find.- Returns:
Returns the map of past transactions, containing only notary signatures in the objects.
-
filterSignedTransaction
@NotNull()@Suspendable() abstract UtxoFilteredTransactionBuilder filterSignedTransaction(@NotNull() UtxoSignedTransaction transaction)
Filters a UtxoSignedTransaction to create a UtxoFilteredTransaction that only contains the components specified by the UtxoFilteredTransactionBuilder output from this method.
- Parameters:
transaction
- The UtxoSignedTransaction to filter.- Returns:
Returns the UtxoFilteredTransactionBuilder that filters the UtxoSignedTransaction.
-
findUnconsumedStatesByType
@Deprecated(since = "5.1", forRemoval = true)@NotNull()@Suspendable() abstract <T extends ContractState> List<StateAndRef<T>> findUnconsumedStatesByType(@NotNull() Class<T> type)
Finds unconsumed states that are concrete implementations or subclasses of
type
.- Parameters:
type
- The ContractState type to find in the vault.- Returns:
Returns a List of StateAndRef of unconsumed states of the specified type, or an empty list if no states could be found.
-
findUnconsumedStatesByExactType
@NotNull()@Suspendable() abstract <T extends ContractState> PagedQuery.ResultSet<StateAndRef<T>> findUnconsumedStatesByExactType(@NotNull() Class<T> type, @NotNull() Integer limit, @NotNull() Instant createdTimestampLimit)
Finds unconsumed states of the specified ContractState type in the vault.
This version supports paging, limiting the number of results returned in a single query call by setting the `limit` argument.
Example usage:
- Kotlin:
val resultSet = utxoLedgerService.findUnconsumedStatesByExactType(MyState::class.java, 10, Instant.now()) processResultsWithApplicationLogic(resultSet.results) while (resultSet.hasNext()) { val results = resultSet.next() processResultsWithApplicationLogic(results) }
- Java:
PagedQuery.ResultSet<StateAndRef<MyState>> resultSet = utxoLedgerService.query(MyState.class, 10, Instant.now()) processResultsWithApplicationLogic(resultSet.getResults()); while (resultSet.hasNext()) { List<Integer> results = resultSet.next(); processResultsWithApplicationLogic(results); }
- Parameters:
type
- The ContractState type to find in the vault.limit
- The size of each page.createdTimestampLimit
- The timestamp limit the underlying query enforces.- Returns:
Returns a ResultSet of StateAndRef of unconsumed states of the specified type.
- Kotlin:
-
finalize
@NotNull()@Suspendable() abstract FinalizationResult finalize(@NotNull() UtxoSignedTransaction transaction, @NotNull() List<FlowSession> sessions)
Verifies, signs, collects signatures, records and broadcasts a UtxoSignedTransaction to participants and observers.
- Parameters:
transaction
- The UtxoSignedTransaction to verify, finalize and record.sessions
- The FlowSession instances of the participants or observers of the transaction.- Returns:
Returns the FinalizationResult containing a fully signed UtxoSignedTransaction that was recorded.
-
receiveFinality
@NotNull()@Suspendable() abstract FinalizationResult receiveFinality(@NotNull() FlowSession session, @NotNull() UtxoTransactionValidator validator)
Verifies, signs and records a UtxoSignedTransaction.
This method should be called in response to finalize.
- Parameters:
session
- The FlowSession of the counter-party finalizing the UtxoSignedTransaction.validator
- Validates the received UtxoSignedTransaction.- Returns:
Returns the FinalizationResult containing a fully signed UtxoSignedTransaction that was received and recorded.
-
sendAndReceiveTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder sendAndReceiveTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends a transaction builder to another session, waits for the other side to propose transaction builder components, applies the proposed components to a copy of the original builder, and returns that new builder.
It supports similar workflows to the following:
Initiator:
val updatedTxBuilder = utxoLedgerService.sendAndReceiveTransactionBuilder(txBuilder, session)
The notary and time window from the proposal will get discarded and the original will be kept if both the original and the proposal have these components set. Duplications of input staterefs, reference staterefs, and signatories will be discarded.
Receiver:
val proposedTxBuilder = utxoLedgerService.receiveTransactionBuilder(session) proposedTxBuilder.add...(...) proposedTxBuilder.add...(...) proposedTxBuilder.add...(...) utxoLedgerService.replyTransactionBuilderProposal(proposedTxBuilder, session)
- Parameters:
transactionBuilder
- The UtxoTransactionBuilder to send.session
- The receiver FlowSession.- Returns:
A new merged builder of the original and proposed components.
-
receiveTransactionBuilder
@NotNull()@Suspendable() abstract UtxoTransactionBuilder receiveTransactionBuilder(@NotNull() FlowSession session)
Receives a transaction builder from another session.
- Parameters:
session
- The FlowSession to receive the UtxoTransactionBuilder from.
-
sendUpdatedTransactionBuilder
@Suspendable() abstract void sendUpdatedTransactionBuilder(@NotNull() UtxoTransactionBuilder transactionBuilder, @NotNull() FlowSession session)
Sends the difference between the current transaction builder and the originally received one to another session with all dependent back chains. It works only with UtxoTransactionBuilders created from receiveTransactionBuilder which tracks the differences internally. If it is called with anything else, it throws InvalidParameterException.
- Parameters:
transactionBuilder
- The UtxoTransactionBuilder to send.session
- The receiver FlowSession.
-
sendTransaction
@Suspendable() abstract void sendTransaction(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends the transaction to counterparty sessions.
- Parameters:
signedTransaction
- The UtxoSignedTransaction to send.sessions
- The counterparties who receive the transaction.
-
sendTransactionWithBackchain
@Suspendable() abstract void sendTransactionWithBackchain(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends the transaction to counterparty sessions and forces backchain resolution.
- Parameters:
signedTransaction
- The UtxoSignedTransaction to send.sessions
- The counterparties who receive the transaction.
-
receiveTransaction
@NotNull()@Suspendable() abstract UtxoSignedTransaction receiveTransaction(@NotNull() FlowSession session)
Receives a verified transaction from the counterparty session and persists it to the vault.
- Parameters:
session
- The counterparty to receive a transaction from.- Returns:
the UtxoSignedTransaction received from counterparty.
-
sendLedgerTransaction
@Suspendable() abstract void sendLedgerTransaction(@NotNull() UtxoSignedTransaction signedTransaction, @NotNull() List<FlowSession> sessions)
Sends an unsigned copy of the base LedgerTransaction to counterparty sessions.
- Parameters:
signedTransaction
- The UtxoSignedTransaction whose correspondent UtxoLedgerTransaction will be sent.sessions
- The counterparties who receive the transaction.
-
receiveLedgerTransaction
@NotNull()@Suspendable() abstract UtxoLedgerTransaction receiveLedgerTransaction(@NotNull() FlowSession session)
Receives a ledger transaction from the counterparty session.
- Parameters:
session
- The counterparty to receive a transaction from.- Returns:
the UtxoLedgerTransaction received from counterparty.
-
query
@Suspendable()@NotNull() abstract <R> VaultNamedParameterizedQuery<R> query(@NotNull() String queryName, @NotNull() Class<R> resultClass)
Creates a query object for a vault named query with the given name. This query can be executed later by calling execute.
The vault named queries executed by this method must be defined within a VaultNamedQueryFactory.
Example usage:
- Kotlin:
val query = utxoLedgerService.query("FIND_BY_TEST_FIELD", Int::class.java) .setParameter("testField", "value") .setParameter("participants", listOf("something")) .setParameter("contractStateType", ContractState::class.java.name) .setParameter("in-memory-filter-parameter", "parameter") .setCreatedTimestampLimit(Instant.now()) .setOffset(0) .setLimit(100) val resultSet = query.execute() processResultsWithApplicationLogic(resultSet.results) while (resultSet.hasNext()) { val results = resultSet.next() processResultsWithApplicationLogic(results) }
- Java:
ParameterizedQuery<Integer> query = utxoLedgerService.query("FIND_BY_TEST_FIELD", Integer.class) .setParameter("testField", "value") .setParameter("participants", List.of("something")) .setParameter("contractStateType", ContractState.class.getName()) .setParameter("in-memory-filter-parameter", "parameter") .setTimestampLimit(Instant.now()) .setOffset(0) .setLimit(100); PagedQuery.ResultSet<Integer> resultSet = query.execute(); processResultsWithApplicationLogic(resultSet.getResults()); while (resultSet.hasNext()) { List<Integer> results = resultSet.next(); processResultsWithApplicationLogic(results); }
- Parameters:
queryName
- The name of the named ledger query to use.resultClass
- Type that the query should return when executed.- Returns:
A VaultNamedParameterizedQuery query object that can be executed or modified further on.
- Kotlin:
-
persistDraftSignedTransaction
@Suspendable() abstract void persistDraftSignedTransaction(@NotNull() UtxoSignedTransaction utxoSignedTransaction)
Persists a non-finalized (draft) transaction. It executes the same checks as the finalization does before its initial persist. So the transaction and all of its signatures need to be valid, but there may be missing signatures.
- Parameters:
utxoSignedTransaction
- The UtxoSignedTransaction to persist.
-
findDraftSignedTransaction
@Nullable()@Suspendable() abstract UtxoSignedTransaction findDraftSignedTransaction(@NotNull() SecureHash id)
Finds a draft UtxoSignedTransaction in the vault by the specified transaction ID. Draft transactions have not been finalized, so they may have missing signatures.
- Parameters:
id
- The ID of the UtxoSignedTransaction to find.- Returns:
Returns the UtxoSignedTransaction if it has been recorded previously, or null if no transaction could be found.
-
-
-
-