For our commercial paper contract however, the things that can be done with it are quite simple. Let’s start with a method to wrap up the issuance process:
fun craftIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): PartialTransaction {
+fun craftIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): TransactionBuilder {
val state = State(issuance, issuance.party.owningKey, faceValue, maturityDate)
- return PartialTransaction(state, WireCommand(Commands.Issue, issuance.party.owningKey))
+ return TransactionBuilder(state, WireCommand(Commands.Issue, issuance.party.owningKey))
}
We take a reference that points to the issuing party (i.e. the caller) and which can contain any internal
bookkeeping/reference numbers that we may require. Then the face value of the paper, and the maturity date. It
-returns a PartialTransaction. A PartialTransaction is one of the few mutable classes the platform provides.
+returns a TransactionBuilder. A TransactionBuilder is one of the few mutable classes the platform provides.
It allows you to add inputs, outputs and commands to it and is designed to be passed around, potentially between
multiple contracts.
Note
Crafting methods should ideally be written to compose with each other, that is, they should take a
-PartialTransaction as an argument instead of returning one, unless you are sure it doesn’t make sense to
+TransactionBuilder as an argument instead of returning one, unless you are sure it doesn’t make sense to
combine this type of transaction with others. In this case, issuing CP at the same time as doing other things
would just introduce complexity that isn’t likely to be worth it, so we return a fresh object each time: instead,
an issuer should issue the CP (starting out owned by themselves), and then sell it in a separate transaction.
The returned partial transaction has a WireCommand object as a parameter. This is a container for any object
that implements the Command interface, along with a key that is expected to sign this transaction. In this case,
issuance requires that the issuing party sign, so we put the key of the party there.
The PartialTransaction constructor we used above takes a variable argument list for convenience. You can pass in
+
The TransactionBuilder constructor we used above takes a variable argument list for convenience. You can pass in
any ContractStateRef (input), ContractState (output) or Command objects and it’ll build up the transaction
for you.
What about moving the paper, i.e. reassigning ownership to someone else?
fun craftMove(tx: PartialTransaction, paper: StateAndRef<State>, newOwner: PublicKey) {
+fun craftMove(tx: TransactionBuilder, paper: StateAndRef<State>, newOwner: PublicKey) {
tx.addInputState(paper.ref)
tx.addOutputState(paper.state.copy(owner = newOwner))
tx.addArg(WireCommand(Commands.Move, paper.state.owner))
@@ -780,7 +780,7 @@ for you.
Here, the method takes a pre-existing PartialTransaction and adds to it. This is correct because typically
+
Here, the method takes a pre-existing TransactionBuilder and adds to it. This is correct because typically
you will want to combine a sale of CP atomically with the movement of some other asset, such as cash. So both
craft methods should operate on the same transaction. You can see an example of this being done in the unit tests
for the commercial paper contract.
Finally, we can do redemption.
@Throws(InsufficientBalanceException::class)
-fun craftRedeem(tx: PartialTransaction, paper: StateAndRef<State>, wallet: List<StateAndRef<Cash.State>>) {
+fun craftRedeem(tx: TransactionBuilder, paper: StateAndRef<State>, wallet: List<StateAndRef<Cash.State>>) {
// Add the cash movement using the states in our wallet.
Cash().craftSpend(tx, paper.state.faceValue, paper.state.owner, wallet)
tx.addInputState(paper.ref)
@@ -813,10 +813,10 @@ from the issuer of the commercial paper to the current owner. If we don’t
an exception is thrown. And then we add the paper itself as an input, but, not an output (as we wish to delete it
from the ledger permanently). Finally, we add a Redeem command that should be signed by the owner of the commercial
paper.
-A PartialTransaction is not by itself ready to be used anywhere, so first, we must convert it to something that
+
A TransactionBuilder is not by itself ready to be used anywhere, so first, we must convert it to something that
is recognised by the network. The most important next step is for the participating entities to sign it using the
signWith() method. This takes a keypair, serialises the transaction, signs the serialised form and then stores the
-signature inside the PartialTransaction. Once all parties have signed, you can call PartialTransaction.toSignedTransaction()
+signature inside the TransactionBuilder. Once all parties have signed, you can call TransactionBuilder.toSignedTransaction()
to get a SignedWireTransaction object. This is an immutable form of the transaction that’s ready for timestamping.
Note
diff --git a/docs/source/protocol-state-machines.rst b/docs/source/protocol-state-machines.rst
index 69705fe896..3cc0149344 100644
--- a/docs/source/protocol-state-machines.rst
+++ b/docs/source/protocol-state-machines.rst
@@ -353,7 +353,7 @@ OK, let's do the same for the buyer side:
// the state we are being offered! For now, just assume validity!
// Generate the shared transaction that both sides will sign, using the data we have.
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
// Add input and output states for the movement of cash, by using the Cash contract
// to generate the states.
val wallet = serviceHub.walletService.currentWallet
diff --git a/docs/source/tutorial.rst b/docs/source/tutorial.rst
index d649e35247..7b77bc6846 100644
--- a/docs/source/tutorial.rst
+++ b/docs/source/tutorial.rst
@@ -662,19 +662,19 @@ a method to wrap up the issuance process:
.. sourcecode:: kotlin
- fun craftIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): PartialTransaction {
+ fun craftIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): TransactionBuilder {
val state = State(issuance, issuance.party.owningKey, faceValue, maturityDate)
- return PartialTransaction(state, WireCommand(Commands.Issue, issuance.party.owningKey))
+ return TransactionBuilder(state, WireCommand(Commands.Issue, issuance.party.owningKey))
}
We take a reference that points to the issuing party (i.e. the caller) and which can contain any internal
bookkeeping/reference numbers that we may require. Then the face value of the paper, and the maturity date. It
-returns a ``PartialTransaction``. A ``PartialTransaction`` is one of the few mutable classes the platform provides.
+returns a ``TransactionBuilder``. A ``TransactionBuilder`` is one of the few mutable classes the platform provides.
It allows you to add inputs, outputs and commands to it and is designed to be passed around, potentially between
multiple contracts.
.. note:: Crafting methods should ideally be written to compose with each other, that is, they should take a
- ``PartialTransaction`` as an argument instead of returning one, unless you are sure it doesn't make sense to
+ ``TransactionBuilder`` as an argument instead of returning one, unless you are sure it doesn't make sense to
combine this type of transaction with others. In this case, issuing CP at the same time as doing other things
would just introduce complexity that isn't likely to be worth it, so we return a fresh object each time: instead,
an issuer should issue the CP (starting out owned by themselves), and then sell it in a separate transaction.
@@ -687,7 +687,7 @@ The returned partial transaction has a ``WireCommand`` object as a parameter. Th
that implements the ``Command`` interface, along with a key that is expected to sign this transaction. In this case,
issuance requires that the issuing party sign, so we put the key of the party there.
-The ``PartialTransaction`` constructor we used above takes a variable argument list for convenience. You can pass in
+The ``TransactionBuilder`` constructor we used above takes a variable argument list for convenience. You can pass in
any ``ContractStateRef`` (input), ``ContractState`` (output) or ``Command`` objects and it'll build up the transaction
for you.
@@ -697,13 +697,13 @@ What about moving the paper, i.e. reassigning ownership to someone else?
.. sourcecode:: kotlin
- fun craftMove(tx: PartialTransaction, paper: StateAndRef, newOwner: PublicKey) {
+ fun craftMove(tx: TransactionBuilder, paper: StateAndRef, newOwner: PublicKey) {
tx.addInputState(paper.ref)
tx.addOutputState(paper.state.copy(owner = newOwner))
tx.addArg(WireCommand(Commands.Move, paper.state.owner))
}
-Here, the method takes a pre-existing ``PartialTransaction`` and adds to it. This is correct because typically
+Here, the method takes a pre-existing ``TransactionBuilder`` and adds to it. This is correct because typically
you will want to combine a sale of CP atomically with the movement of some other asset, such as cash. So both
craft methods should operate on the same transaction. You can see an example of this being done in the unit tests
for the commercial paper contract.
@@ -719,7 +719,7 @@ Finally, we can do redemption.
.. sourcecode:: kotlin
@Throws(InsufficientBalanceException::class)
- fun craftRedeem(tx: PartialTransaction, paper: StateAndRef, wallet: List>) {
+ fun craftRedeem(tx: TransactionBuilder, paper: StateAndRef, wallet: List>) {
// Add the cash movement using the states in our wallet.
Cash().craftSpend(tx, paper.state.faceValue, paper.state.owner, wallet)
tx.addInputState(paper.ref)
@@ -740,10 +740,10 @@ an exception is thrown. And then we add the paper itself as an input, but, not a
from the ledger permanently). Finally, we add a Redeem command that should be signed by the owner of the commercial
paper.
-A ``PartialTransaction`` is not by itself ready to be used anywhere, so first, we must convert it to something that
+A ``TransactionBuilder`` is not by itself ready to be used anywhere, so first, we must convert it to something that
is recognised by the network. The most important next step is for the participating entities to sign it using the
``signWith()`` method. This takes a keypair, serialises the transaction, signs the serialised form and then stores the
-signature inside the ``PartialTransaction``. Once all parties have signed, you can call ``PartialTransaction.toSignedTransaction()``
+signature inside the ``TransactionBuilder``. Once all parties have signed, you can call ``TransactionBuilder.toSignedTransaction()``
to get a ``SignedWireTransaction`` object. This is an immutable form of the transaction that's ready for *timestamping*.
.. note:: Timestamping and passing around of partial transactions for group signing is not yet fully implemented.
diff --git a/src/main/kotlin/contracts/Cash.kt b/src/main/kotlin/contracts/Cash.kt
index aad70dbb54..0515d05165 100644
--- a/src/main/kotlin/contracts/Cash.kt
+++ b/src/main/kotlin/contracts/Cash.kt
@@ -151,7 +151,7 @@ class Cash : Contract {
/**
* Puts together an issuance transaction for the specified amount that starts out being owned by the given pubkey.
*/
- fun craftIssue(tx: PartialTransaction, amount: Amount, at: PartyReference, owner: PublicKey) {
+ fun craftIssue(tx: TransactionBuilder, amount: Amount, at: PartyReference, owner: PublicKey) {
check(tx.inputStates().isEmpty())
check(tx.outputStates().sumCashOrNull() == null)
tx.addOutputState(Cash.State(at, amount, owner))
@@ -167,7 +167,7 @@ class Cash : Contract {
* about which type of cash claims they are willing to accept.
*/
@Throws(InsufficientBalanceException::class)
- fun craftSpend(tx: PartialTransaction, amount: Amount, to: PublicKey,
+ fun craftSpend(tx: TransactionBuilder, amount: Amount, to: PublicKey,
cashStates: List>, onlyFromParties: Set? = null): List {
// Discussion
//
diff --git a/src/main/kotlin/contracts/CommercialPaper.kt b/src/main/kotlin/contracts/CommercialPaper.kt
index 2a4eda81bc..b76848209f 100644
--- a/src/main/kotlin/contracts/CommercialPaper.kt
+++ b/src/main/kotlin/contracts/CommercialPaper.kt
@@ -117,15 +117,15 @@ class CommercialPaper : Contract {
* an existing transaction because you aren't able to issue multiple pieces of CP in a single transaction
* at the moment: this restriction is not fundamental and may be lifted later.
*/
- fun craftIssue(issuance: PartyReference, faceValue: Amount, maturityDate: Instant): PartialTransaction {
+ fun craftIssue(issuance: PartyReference, faceValue: Amount, maturityDate: Instant): TransactionBuilder {
val state = State(issuance, issuance.party.owningKey, faceValue, maturityDate)
- return PartialTransaction().withItems(state, Command(Commands.Issue(), issuance.party.owningKey))
+ return TransactionBuilder().withItems(state, Command(Commands.Issue(), issuance.party.owningKey))
}
/**
* Updates the given partial transaction with an input/output/command to reassign ownership of the paper.
*/
- fun craftMove(tx: PartialTransaction, paper: StateAndRef, newOwner: PublicKey) {
+ fun craftMove(tx: TransactionBuilder, paper: StateAndRef, newOwner: PublicKey) {
tx.addInputState(paper.ref)
tx.addOutputState(paper.state.copy(owner = newOwner))
tx.addCommand(Commands.Move(), paper.state.owner)
@@ -139,7 +139,7 @@ class CommercialPaper : Contract {
* @throws InsufficientBalanceException if the wallet doesn't contain enough money to pay the redeemer
*/
@Throws(InsufficientBalanceException::class)
- fun craftRedeem(tx: PartialTransaction, paper: StateAndRef, wallet: List>) {
+ fun craftRedeem(tx: TransactionBuilder, paper: StateAndRef, wallet: List>) {
// Add the cash movement using the states in our wallet.
Cash().craftSpend(tx, paper.state.faceValue, paper.state.owner, wallet)
tx.addInputState(paper.ref)
diff --git a/src/main/kotlin/contracts/CrowdFund.kt b/src/main/kotlin/contracts/CrowdFund.kt
index 4985350264..6b98fd92ec 100644
--- a/src/main/kotlin/contracts/CrowdFund.kt
+++ b/src/main/kotlin/contracts/CrowdFund.kt
@@ -142,16 +142,16 @@ class CrowdFund : Contract {
* Returns a transaction that registers a crowd-funding campaing, owned by the issuing institution's key. Does not update
* an existing transaction because it's not possible to register multiple campaigns in a single transaction
*/
- fun craftRegister(owner: PartyReference, fundingTarget: Amount, fundingName: String, closingTime: Instant): PartialTransaction {
+ fun craftRegister(owner: PartyReference, fundingTarget: Amount, fundingName: String, closingTime: Instant): TransactionBuilder {
val campaign = Campaign(owner = owner.party.owningKey, name = fundingName, target = fundingTarget, closingTime = closingTime)
val state = State(campaign)
- return PartialTransaction().withItems(state, Command(Commands.Register(), owner.party.owningKey))
+ return TransactionBuilder().withItems(state, Command(Commands.Register(), owner.party.owningKey))
}
/**
* Updates the given partial transaction with an input/output/command to fund the opportunity.
*/
- fun craftPledge(tx: PartialTransaction, campaign: StateAndRef, subscriber: PublicKey) {
+ fun craftPledge(tx: TransactionBuilder, campaign: StateAndRef, subscriber: PublicKey) {
tx.addInputState(campaign.ref)
tx.addOutputState(campaign.state.copy(
pledges = campaign.state.pledges + CrowdFund.Pledge(subscriber, 1000.DOLLARS)
@@ -159,7 +159,7 @@ class CrowdFund : Contract {
tx.addCommand(Commands.Pledge(), subscriber)
}
- fun craftClose(tx: PartialTransaction, campaign: StateAndRef, wallet: List>) {
+ fun craftClose(tx: TransactionBuilder, campaign: StateAndRef, wallet: List>) {
tx.addInputState(campaign.ref)
tx.addOutputState(campaign.state.copy(closed = true))
tx.addCommand(Commands.Close(), campaign.state.campaign.owner)
diff --git a/src/main/kotlin/contracts/protocols/TwoPartyTradeProtocol.kt b/src/main/kotlin/contracts/protocols/TwoPartyTradeProtocol.kt
index 940bf83d6c..3f1858f85a 100644
--- a/src/main/kotlin/contracts/protocols/TwoPartyTradeProtocol.kt
+++ b/src/main/kotlin/contracts/protocols/TwoPartyTradeProtocol.kt
@@ -155,7 +155,7 @@ private class TwoPartyTradeProtocolImpl(private val smm: StateMachineManager) :
// For now, just assume validity!
// Generate the shared transaction that both sides will sign, using the data we have.
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
// Add input and output states for the movement of cash, by using the Cash contract to generate the states.
val wallet = serviceHub.walletService.currentWallet
val cashStates = wallet.statesOfType()
diff --git a/src/main/kotlin/core/Transactions.kt b/src/main/kotlin/core/Transactions.kt
index 936bb07bad..93dda34c73 100644
--- a/src/main/kotlin/core/Transactions.kt
+++ b/src/main/kotlin/core/Transactions.kt
@@ -31,7 +31,7 @@ import java.util.*
* keypairs. Note that a sighash is not the same thing as a *transaction id*, which is the hash of a SignedWireTransaction
* i.e. the outermost serialised form with everything included.
*
- * A PartialTransaction is a transaction class that's mutable (unlike the others which are all immutable). It is
+ * 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 or modifying the existing set.
* Then once the states and commands are right, this class can be used as a holding bucket to gather signatures from
* multiple parties.
@@ -67,7 +67,7 @@ data class WireTransaction(val inputStates: List,
class NotOnTimeException : Exception()
/** A mutable transaction that's in the process of being built, before all signatures are present. */
-class PartialTransaction(private val inputStates: MutableList = arrayListOf(),
+class TransactionBuilder(private val inputStates: MutableList = arrayListOf(),
private val outputStates: MutableList = arrayListOf(),
private val commands: MutableList = arrayListOf()) {
@@ -92,7 +92,7 @@ class PartialTransaction(private val inputStates: MutableList
}
/** A more convenient way to add items to this transaction that calls the add* methods for you based on type */
- public fun withItems(vararg items: Any): PartialTransaction {
+ public fun withItems(vararg items: Any): TransactionBuilder {
for (t in items) {
when (t) {
is ContractStateRef -> inputStates.add(t)
diff --git a/src/test/kotlin/contracts/CashTests.kt b/src/test/kotlin/contracts/CashTests.kt
index a9b41aa942..2bce05032e 100644
--- a/src/test/kotlin/contracts/CashTests.kt
+++ b/src/test/kotlin/contracts/CashTests.kt
@@ -103,7 +103,7 @@ class CashTests {
this.accepts()
}
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
Cash().craftIssue(ptx, 100.DOLLARS, MINI_CORP.ref(12,34), owner = DUMMY_PUBKEY_1)
assertTrue(ptx.inputStates().isEmpty())
val s = ptx.outputStates()[0] as Cash.State
@@ -312,7 +312,7 @@ class CashTests {
)
fun makeSpend(amount: Amount, dest: PublicKey): WireTransaction {
- val tx = PartialTransaction()
+ val tx = TransactionBuilder()
Cash().craftSpend(tx, amount, dest, WALLET)
return tx.toWireTransaction()
}
@@ -327,7 +327,7 @@ class CashTests {
@Test
fun craftSimpleSpendWithParties() {
- val tx = PartialTransaction()
+ val tx = TransactionBuilder()
Cash().craftSpend(tx, 80.DOLLARS, ALICE, WALLET, setOf(MINI_CORP))
assertEquals(WALLET[2].ref, tx.inputStates()[0])
}
diff --git a/src/test/kotlin/contracts/CommercialPaperTests.kt b/src/test/kotlin/contracts/CommercialPaperTests.kt
index 77ca095c79..c1f1177c63 100644
--- a/src/test/kotlin/contracts/CommercialPaperTests.kt
+++ b/src/test/kotlin/contracts/CommercialPaperTests.kt
@@ -149,7 +149,7 @@ class CommercialPaperTests {
// Alice pays $9000 to MiniCorp to own some of their debt.
val moveTX: LedgerTransaction = run {
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
Cash().craftSpend(ptx, 9000.DOLLARS, MINI_CORP_PUBKEY, alicesWallet)
CommercialPaper().craftMove(ptx, issueTX.outRef(0), ALICE)
ptx.signWith(MINI_CORP_KEY)
@@ -165,7 +165,7 @@ class CommercialPaperTests {
)
fun makeRedeemTX(time: Instant): LedgerTransaction {
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
ptx.setTime(time, DummyTimestampingAuthority.identity, 30.seconds)
CommercialPaper().craftRedeem(ptx, moveTX.outRef(1), corpWallet)
ptx.signWith(ALICE_KEY)
diff --git a/src/test/kotlin/contracts/CrowdFundTests.kt b/src/test/kotlin/contracts/CrowdFundTests.kt
index e42e3132cb..8880e141a5 100644
--- a/src/test/kotlin/contracts/CrowdFundTests.kt
+++ b/src/test/kotlin/contracts/CrowdFundTests.kt
@@ -125,7 +125,7 @@ class CrowdFundTests {
// Alice pays $1000 to MiniCorp to fund their campaign.
val pledgeTX: LedgerTransaction = run {
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
CrowdFund().craftPledge(ptx, registerTX.outRef(0), ALICE)
Cash().craftSpend(ptx, 1000.DOLLARS, MINI_CORP_PUBKEY, aliceWallet)
ptx.setTime(TEST_TX_TIME, DummyTimestampingAuthority.identity, 30.seconds)
@@ -143,7 +143,7 @@ class CrowdFundTests {
)
// MiniCorp closes their campaign.
fun makeFundedTX(time: Instant): LedgerTransaction {
- val ptx = PartialTransaction()
+ val ptx = TransactionBuilder()
ptx.setTime(time, DUMMY_TIMESTAMPER.identity, 30.seconds)
CrowdFund().craftClose(ptx, pledgeTX.outRef(0), miniCorpWallet)
ptx.signWith(MINI_CORP_KEY)
diff --git a/src/test/kotlin/core/serialization/TransactionSerializationTests.kt b/src/test/kotlin/core/serialization/TransactionSerializationTests.kt
index add4682705..fc95173c94 100644
--- a/src/test/kotlin/core/serialization/TransactionSerializationTests.kt
+++ b/src/test/kotlin/core/serialization/TransactionSerializationTests.kt
@@ -25,11 +25,11 @@ class TransactionSerializationTests {
val changeState = Cash.State(depositRef, 400.POUNDS, TestUtils.keypair.public)
val fakeStateRef = ContractStateRef(SecureHash.sha256("fake tx id"), 0)
- lateinit var tx: PartialTransaction
+ lateinit var tx: TransactionBuilder
@Before
fun setup() {
- tx = PartialTransaction().withItems(
+ tx = TransactionBuilder().withItems(
fakeStateRef, outputState, changeState, Command(Cash.Commands.Move(), arrayListOf(TestUtils.keypair.public))
)
}
@@ -75,7 +75,7 @@ class TransactionSerializationTests {
// If the signature was replaced in transit, we don't like it.
assertFailsWith(SignatureException::class) {
- val tx2 = PartialTransaction().withItems(fakeStateRef, outputState, changeState,
+ val tx2 = TransactionBuilder().withItems(fakeStateRef, outputState, changeState,
Command(Cash.Commands.Move(), TestUtils.keypair2.public))
tx2.signWith(TestUtils.keypair2)