Docs: adjust the docsite to reflect the tx types refactoring

docs/source/data-model.rst

@@ -23,8 +23,8 @@ States contain arbitrary data, but they always contain at minimum a hash of the
 Contract code (or just "contracts" in the rest of this document) are globally shared pieces of business logic.
 
 Contracts define a **verify function**, which is a pure function given the entire transaction as input. To be considered
-valid, the transaction must be **accepted** by the verify function of every contract pointed to by the
-input and output states.
+valid, the transaction must be **accepted** by the verify function of every contract pointed to by the input and output
+states.
 
 Beyond inputs and outputs, transactions may also contain **commands**, small data packets that
 the platform does not interpret itself, but which can parameterise execution of the contracts. They can be thought of as

docs/source/transaction-data-types.rst

@@ -77,6 +77,31 @@ in place of the attachments themselves (see also :doc:`data-model`). Once signed
 resolving the attachment references to the attachments. Commands with valid signatures are encapsulated in the
 ``AuthenticatedObject`` type.
 
+When constructing a new transaction from scratch, you use ``TransactionBuilder``, which is a mutable transaction that
+can be signed once modification of the internals is complete. It is typical for contract classes to expose helper
+methods that can contribute to a ``TransactionBuilder``.
+
+Here's an example of building a transaction that creates an issuance of bananas (note that bananas are not a real
+contract type in the library):
+
+.. container:: codeset
+
+   .. sourcecode:: kotlin
+
+      val notaryToUse: Party = ...
+      val txb = TransactionBuilder(notary = notaryToUse).withItems(BananaState(Amount(20, Bananas), fromCountry = "Elbonia"))
+      txb.signWith(myKey)
+      txb.setTime(Instant.now(), notaryToUse, 30.seconds)
+      // We must disable the check for sufficient signatures, because this transaction is not yet notarised.
+      val stx = txb.toSignedTransaction(checkSufficientSignatures = false)
+      // Alternatively, let's just check it verifies pretending it was fully signed. To do this, we get
+      // a WireTransaction, which is what the SignedTransaction wraps. Thus by verifying that directly we
+      // skip signature checking.
+      txb.toWireTransaction().toLedgerTransaction(services).verify()
+
+In a unit test, you would typically use a freshly created ``UnitTestServices`` object, or more realistically, you would
+write your tests using the :doc:`domain specific language for writing tests <tutorial-test-dsl>`.
+
 Party and PublicKey
 -------------------
 

docs/source/tutorial-test-dsl.rst

@@ -43,7 +43,7 @@ We start with the empty ledger:
         }
 
 The DSL keyword ``ledger`` takes a closure that can build up several transactions and may verify their overall
-correctness.
+correctness. A ledger is effectively a fresh world with no pre-existing transactions or services within it.
 
 Let's add a Cash transaction:
 
@@ -54,7 +54,7 @@ Let's add a Cash transaction:
         @Test
         fun simpleCashDoesntCompile() {
             val inState = Cash.State(
-                    amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
+                    amount = 1000.DOLLARS `issued by` DUMMY_CASH_ISSUER,
                     owner = DUMMY_PUBKEY_1
             )
             ledger {
@@ -69,7 +69,7 @@ Let's add a Cash transaction:
         @Test
         public void simpleCashDoesntCompile() {
             Cash.State inState = new Cash.State(
-                    issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
+                    issuedBy(DOLLARS(1000), getDUMMY_CASH_ISSUER()),
                     getDUMMY_PUBKEY_1()
             );
             ledger(l -> {
@@ -139,7 +139,10 @@ last line of ``transaction``:
 
 The code finally compiles. When run, it produces the following error::
 
-    com.r3corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalArgumentException: Failed requirement: for deposit [0101] at issuer MegaCorp the amounts balance
+    com.r3corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalArgumentException: Failed requirement: for deposit [01] at issuer Snake Oil Issuer the amounts balance
+
+.. note:: The reference here to the 'Snake Oil Issuer' is because we are using the pre-canned ``DUMMY_CASH_ISSUER``
+    identity as the issuer of our cash.
 
 The transaction verification failed, because the sum of inputs does not equal the sum of outputs. We can specify that
 this is intended behaviour by changing ``this.verifies()`` to ``this `fails with` "the amounts balance"``: