TransactionBuilder
Keywords: net.corda.core.transactions.TransactionBuilder class
Date: 2023-09-18

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` – a`class 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.serialize`when 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 StateRef`s.

      See Also:
        `class StateRef`

    - #### referenceStates

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

      Returns an immutable list of reference input `class StateRef`s.

      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 TransactionState`s.

      See Also:
        `class TransactionState`

    - #### commands

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

      Returns an immutable list of `class Command`s.

      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` – a`class 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` – a`class 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` – a`class 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()