TransactionBuilder - corda

corda / net.corda.core.transactions / TransactionBuilder

# TransactionBuilder

`open 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.

### 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 ContractState – a TransactionState with this notary specified will be generated automatically.

### Constructors

#### <init> | `TransactionBuilder(notary: Party? = null, lockId: UUID = defaultLockId(), inputs: MutableList<StateRef> = arrayListOf(), attachments: MutableList<AttachmentId> = arrayListOf(), outputs: MutableList<TransactionState<ContractState>> = arrayListOf(), commands: MutableList<Command<*>> = arrayListOf(), window: TimeWindow? = null, privacySalt: PrivacySalt = PrivacySalt())` `TransactionBuilder(notary: Party)` 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. `TransactionBuilder(notary: Party? = null, lockId: UUID = defaultLockId(), inputs: MutableList<StateRef> = arrayListOf(), attachments: MutableList<AttachmentId> = arrayListOf(), outputs: MutableList<TransactionState<ContractState>> = arrayListOf(), commands: MutableList<Command<*>> = arrayListOf(), window: TimeWindow? = null, privacySalt: PrivacySalt = PrivacySalt(), references: MutableList<StateRef> = arrayListOf(), serviceHub: ServiceHub? = (Strand.currentStrand() as? FlowStateMachine<*>)?.serviceHub)`

### Properties

#### attachments | `val attachments: MutableList<AttachmentId>`
#### commands | `val commands: MutableList<Command<*>>`
#### inputs | `val inputs: MutableList<StateRef>`
#### lockId | `var lockId: UUID`
#### 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 ContractState – a TransactionState with this notary specified will be generated automatically. `var notary: Party?`
#### outputs | `val outputs: MutableList<TransactionState<ContractState>>`
#### privacySalt | `var privacySalt: PrivacySalt`
#### references | `val references: MutableList<StateRef>`
#### serviceHub | `val serviceHub: ServiceHub?`
#### window | `var window: TimeWindow?`

### Functions

#### addAttachment | Adds an attachment with the specified hash to the TransactionBuilder. `fun addAttachment(attachmentId: AttachmentId): TransactionBuilder`
#### addCommand | Adds a Command to the transaction. `fun addCommand(arg: Command<*>): TransactionBuilder` Adds a Command to the transaction, specified by the encapsulated CommandData object and required list of signing PublicKeys. `fun addCommand(data: CommandData, vararg keys: PublicKey): TransactionBuilder` `fun addCommand(data: CommandData, keys: List<PublicKey>): TransactionBuilder`
#### addInputState | Adds an input StateRef to the transaction. `open fun addInputState(stateAndRef: StateAndRef<*>): TransactionBuilder`
#### addOutputState | Adds an output state to the transaction. `fun addOutputState(state: TransactionState<*>): TransactionBuilder` Adds an output state, with associated contract code (and constraints), and notary, to the transaction. `fun addOutputState(state: ContractState, contract: ContractClassName = requireNotNullContractClassName(state), notary: Party, encumbrance: Int? = null, constraint: AttachmentConstraint = AutomaticPlaceholderConstraint): TransactionBuilder` Adds an output state. A default notary must be specified during builder construction to use this method `fun addOutputState(state: ContractState, contract: ContractClassName = requireNotNullContractClassName(state), constraint: AttachmentConstraint = AutomaticPlaceholderConstraint): TransactionBuilder` Adds an output state with the specified constraint. `fun addOutputState(state: ContractState, constraint: AttachmentConstraint): TransactionBuilder`
#### addReferenceState | Adds a reference input StateRef to the transaction. `open fun addReferenceState(referencedStateAndRef: ReferencedStateAndRef<*>): TransactionBuilder`
#### attachments | Returns an immutable list of attachment hashes. `fun attachments(): List<AttachmentId>`
#### commands | Returns an immutable list of Commands. `fun commands(): List<Command<*>>`
#### copy | Creates a copy of the builder. `fun copy(): TransactionBuilder`
#### inputStates | Returns an immutable list of input StateRefs. `fun inputStates(): List<StateRef>`
#### outputStates | Returns an immutable list of output TransactionStates. `fun outputStates(): List<TransactionState<*>>`
#### referenceStates | Returns an immutable list of reference input StateRefs. `fun referenceStates(): List<StateRef>`
#### setPrivacySalt | `fun setPrivacySalt(privacySalt: PrivacySalt): TransactionBuilder`
#### setTimeWindow | Sets the TimeWindow for this transaction, replacing the existing 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. `fun setTimeWindow(timeWindow: TimeWindow): TransactionBuilder` The 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. `fun setTimeWindow(time: Instant, timeTolerance: Duration): TransactionBuilder`
#### toLedgerTransaction | `fun toLedgerTransaction(services: ServiceHub): LedgerTransaction`
#### toSignedTransaction | Sign the built transaction and return it. This is an internal function for use by the service hub, please use ServiceHub.signInitialTransaction instead. `fun toSignedTransaction(keyManagementService: KeyManagementService, publicKey: PublicKey, signatureMetadata: SignatureMetadata, services: ServicesForResolution): SignedTransaction`
#### toWireTransaction | Generates a WireTransaction from this builder, resolves any AutomaticPlaceholderConstraint, and selects the attachments to use for this transaction. `fun toWireTransaction(services: ServicesForResolution): WireTransaction` `fun toWireTransaction(services: ServicesForResolution, schemeId: Int): WireTransaction` `fun toWireTransaction(services: ServicesForResolution, schemeId: Int, properties: Map<Any, Any>): WireTransaction`
#### verify | `fun verify(services: ServiceHub): Unit`
#### withItems | A more convenient way to add items to this transaction that calls the add* methods for you based on type `fun withItems(vararg items: Any): TransactionBuilder`