net.corda.core.transactions

Class TransactionBuilder

net.corda.core.transactions.TransactionBuilder

public class TransactionBuilder

A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

Field Detail

Companion

public static net.corda.core.transactions.TransactionBuilder.Companion Companion

Deprecated.

Constructor Detail

TransactionBuilder

public TransactionBuilder(@Nullable
                          Party notary,
                          @NotNull
                          java.util.UUID lockId,
                          @NotNull
                          java.util.List<net.corda.core.contracts.StateRef> inputs,
                          @NotNull
                          java.util.List<net.corda.core.crypto.SecureHash> attachments,
                          @NotNull
                          java.util.List<net.corda.core.contracts.TransactionState> outputs,
                          @NotNull
                          java.util.List<net.corda.core.contracts.Command> commands,
                          @Nullable
                          TimeWindow window,
                          @NotNull
                          PrivacySalt privacySalt,
                          @NotNull
                          java.util.List<net.corda.core.contracts.StateRef> references,
                          @Nullable
                          ServiceHub serviceHub)

A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

Parameters:

notary - Notary used for the transaction. If null, this indicates the transaction DOES NOT have a notary.When this is set to a non-null value, an output state can be added by just passing in a interface ContractState – aclass TransactionState with this notary specified will be generated automatically.

TransactionBuilder

public TransactionBuilder()

A TransactionBuilder is a transaction class that's mutable (unlike the others which are all immutable). It is intended to be passed around contracts that may edit it by adding new states/commands. Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from multiple parties.

The builder can be customised for specific transaction types, e.g. where additional processing is needed before adding a state/command.

TransactionBuilder

public TransactionBuilder(@Nullable
                          Party notary,
                          @NotNull
                          java.util.UUID lockId,
                          @NotNull
                          java.util.List<net.corda.core.contracts.StateRef> inputs,
                          @NotNull
                          java.util.List<net.corda.core.crypto.SecureHash> attachments,
                          @NotNull
                          java.util.List<net.corda.core.contracts.TransactionState> outputs,
                          @NotNull
                          java.util.List<net.corda.core.contracts.Command> commands,
                          @Nullable
                          TimeWindow window,
                          @NotNull
                          PrivacySalt privacySalt)

TransactionBuilder

public TransactionBuilder(@NotNull
                          Party notary)

Method Detail

copy

@NotNull
public TransactionBuilder copy()

Creates a copy of the builder.

withItems

@NotNull
public TransactionBuilder withItems(@NotNull
                                             java.lang.Object... items)

A more convenient way to add items to this transaction that calls the add* methods for you based on type

toWireTransaction

@NotNull
public WireTransaction toWireTransaction(@NotNull
                                                  ServicesForResolution services)

Generates a class WireTransaction from this builder, resolves any class AutomaticPlaceholderConstraint, and selects the attachments to use for this transaction.

Throws:

ZoneVersionTooLowException - if there are reference states and the zone minimum platform version is less than 4.

See Also:

class WireTransaction, class AutomaticPlaceholderConstraint

toWireTransaction

@NotNull
public WireTransaction toWireTransaction(@NotNull
                                                  ServicesForResolution services,
                                                  int schemeId)

Generates a class WireTransaction from this builder, resolves any class AutomaticPlaceholderConstraint, and selects the attachments to use for this transaction.

Parameters:

schemeId - is used to specify the interface CustomSerializationScheme used to serialize each component of the componentGroups of the class WireTransaction.This is an experimental feature.

Throws:

ZoneVersionTooLowException - if there are reference states and the zone minimum platform version is less than 4.

See Also:

class WireTransaction, class AutomaticPlaceholderConstraint

toWireTransaction

@NotNull
public WireTransaction toWireTransaction(@NotNull
                                                  ServicesForResolution services,
                                                  int schemeId,
                                                  @NotNull
                                                  java.util.Map<java.lang.Object,? extends java.lang.Object> properties)

Generates a class WireTransaction from this builder, resolves any class AutomaticPlaceholderConstraint, and selects the attachments to use for this transaction.

Parameters:

schemeId - is used to specify the interface CustomSerializationScheme used to serialize each component of the componentGroups of the class WireTransaction.This is an experimental feature.

properties - a list of properties to add to the interface SerializationSchemeContext these properties can be accessed in CustomSerializationScheme.serializewhen serializing the componentGroups of the wire transaction but might not be available when deserializing.

Throws:

ZoneVersionTooLowException - if there are reference states and the zone minimum platform version is less than 4.

See Also:

class WireTransaction, class AutomaticPlaceholderConstraint

toLedgerTransaction

@NotNull
public LedgerTransaction toLedgerTransaction(@NotNull
                                                      ServiceHub services)

verify

public void verify(@NotNull
                   ServiceHub services)

addReferenceState

@NotNull
public TransactionBuilder addReferenceState(@NotNull
                                                     ReferencedStateAndRef<?> referencedStateAndRef)

Adds a reference input class StateRef to the transaction.

Note: Reference states are only supported on Corda networks running a minimum platform version of 4. toWireTransaction will throw an IllegalStateException if called in such an environment.

See Also:

class StateRef, toWireTransaction, IllegalStateException

addInputState

@NotNull
public TransactionBuilder addInputState(@NotNull
                                                 StateAndRef<?> stateAndRef)

Adds an input class StateRef to the transaction.

See Also:

class StateRef

addAttachment

@NotNull
public TransactionBuilder addAttachment(@NotNull
                                                 SecureHash attachmentId)

Adds an attachment with the specified hash to the TransactionBuilder.

addOutputState

@NotNull
public TransactionBuilder addOutputState(@NotNull
                                                  TransactionState<?> state)

Adds an output state to the transaction.

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 java.lang.String contract,
                                                                 @NotNull
                                                                 Party notary,
                                                                 @Nullable
                                                                 java.lang.Integer encumbrance,
                                                                 @NotNull
                                                                 AttachmentConstraint constraint)

Adds an output state, with associated contract code (and constraints), and notary, to the transaction.

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 java.lang.String contract,
                                                                 @NotNull
                                                                 Party notary,
                                                                 @Nullable
                                                                 java.lang.Integer encumbrance)

Adds an output state, with associated contract code (and constraints), and notary, to the transaction.

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 java.lang.String contract,
                                                                 @NotNull
                                                                 Party notary)

Adds an output state, with associated contract code (and constraints), and notary, to the transaction.

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 Party notary)

Adds an output state, with associated contract code (and constraints), and notary, to the transaction.

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 java.lang.String contract,
                                                                 @NotNull
                                                                 AttachmentConstraint constraint)

Adds an output state. A default notary must be specified during builder construction to use this method

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state,
                                                                 @NotNull
                                                                 java.lang.String contract)

Adds an output state. A default notary must be specified during builder construction to use this method

addOutputState

@JvmOverloads
 @NotNull
public TransactionBuilder addOutputState(@NotNull
                                                                 ContractState state)

Adds an output state. A default notary must be specified during builder construction to use this method

addOutputState

@NotNull
public TransactionBuilder addOutputState(@NotNull
                                                  ContractState state,
                                                  @NotNull
                                                  AttachmentConstraint constraint)

Adds an output state with the specified constraint.

addCommand

@NotNull
public TransactionBuilder addCommand(@NotNull
                                              Command<?> arg)

Adds a class Command to the transaction.

See Also:

class Command

addCommand

@NotNull
public TransactionBuilder addCommand(@NotNull
                                              CommandData data,
                                              @NotNull
                                              java.security.PublicKey... keys)

Adds a class Command to the transaction, specified by the encapsulated interface CommandData object and required list of signing PublicKeys.

See Also:

class Command, interface CommandData, PublicKey

addCommand

@NotNull
public TransactionBuilder addCommand(@NotNull
                                              CommandData data,
                                              @NotNull
                                              java.util.List<? extends java.security.PublicKey> keys)

setTimeWindow

@NotNull
public TransactionBuilder setTimeWindow(@NotNull
                                                 TimeWindow timeWindow)

Sets the class TimeWindow for this transaction, replacing the existing class TimeWindow if there is one. To be valid, the transaction must then be signed by the notary service within this window of time. In this way, the notary acts as the Timestamp Authority.

See Also:

class TimeWindow, class TimeWindow

setTimeWindow

@NotNull
public TransactionBuilder setTimeWindow(@NotNull
                                                 java.time.Instant time,
                                                 @NotNull
                                                 java.time.Duration timeTolerance)

The class TimeWindow for the transaction can also be defined as time +/- timeTolerance. The tolerance should be chosen such that your code can finish building the transaction and sending it to the Timestamp Authority within that window of time, taking into account factors such as network latency. Transactions being built by a group of collaborating parties may therefore require a higher time tolerance than a transaction being built by a single node.

See Also:

class TimeWindow, time, timeTolerance

setPrivacySalt

@NotNull
public TransactionBuilder setPrivacySalt(@NotNull
                                                  PrivacySalt privacySalt)

inputStates

@NotNull
public java.util.List<net.corda.core.contracts.StateRef> inputStates()

Returns an immutable list of input class StateRefs.

See Also:

class StateRef

referenceStates

@NotNull
public java.util.List<net.corda.core.contracts.StateRef> referenceStates()

Returns an immutable list of reference input class StateRefs.

See Also:

class StateRef

attachments

@NotNull
public java.util.List<net.corda.core.crypto.SecureHash> attachments()

Returns an immutable list of attachment hashes.

outputStates

@NotNull
public java.util.List<net.corda.core.contracts.TransactionState> outputStates()

Returns an immutable list of output class TransactionStates.

See Also:

class TransactionState

commands

@NotNull
public java.util.List<net.corda.core.contracts.Command> commands()

Returns an immutable list of class Commands.

See Also:

class Command

toSignedTransaction

@NotNull
public SignedTransaction toSignedTransaction(@NotNull
                                                      KeyManagementService keyManagementService,
                                                      @NotNull
                                                      java.security.PublicKey publicKey,
                                                      @NotNull
                                                      SignatureMetadata signatureMetadata,
                                                      @NotNull
                                                      ServicesForResolution services)

Sign the built transaction and return it. This is an internal function for use by the service hub, please use ServiceHub.signInitialTransaction instead.

getNotary

@Nullable
public Party getNotary()

Notary used for the transaction.

If null, this indicates the transaction DOES NOT have a notary.When this is set to a non-null value, an output state can be added by just passing in a interface ContractState – aclass TransactionState with this notary specified will be generated automatically.

See Also:

interface ContractState, class TransactionState

setNotary

public void setNotary(@Nullable
                      Party p)

Notary used for the transaction.

If null, this indicates the transaction DOES NOT have a notary.When this is set to a non-null value, an output state can be added by just passing in a interface ContractState – aclass TransactionState with this notary specified will be generated automatically.

Parameters:

p - Notary used for the transaction. If null, this indicates the transaction DOES NOT have a notary.When this is set to a non-null value, an output state can be added by just passing in a interface ContractState – aclass TransactionState with this notary specified will be generated automatically.

See Also:

interface ContractState, class TransactionState

getLockId

@NotNull
public java.util.UUID getLockId()

setLockId

public void setLockId(@NotNull
                      java.util.UUID p)

getInputs

@NotNull
protected java.util.List<net.corda.core.contracts.StateRef> getInputs()

getAttachments

@NotNull
protected java.util.List<net.corda.core.crypto.SecureHash> getAttachments()

getOutputs

@NotNull
protected java.util.List<net.corda.core.contracts.TransactionState> getOutputs()

getCommands

@NotNull
protected java.util.List<net.corda.core.contracts.Command> getCommands()

getWindow

@Nullable
protected TimeWindow getWindow()

setWindow

protected void setWindow(@Nullable
                         TimeWindow p)

getPrivacySalt

@NotNull
protected PrivacySalt getPrivacySalt()

setPrivacySalt

protected void setPrivacySalt(@NotNull
                              PrivacySalt p)

getReferences

@NotNull
protected java.util.List<net.corda.core.contracts.StateRef> getReferences()

getServiceHub

@Nullable
protected ServiceHub getServiceHub()