Updating docs w.r.t. new FilteredTransaction and TransactionSignature (#1678)

docs/source/oracles.rst

@@ -112,13 +112,13 @@ Here is an extract from the ``NodeInterestRates.Oracle`` class and supporting ty
    class Oracle {
        fun query(queries: List<FixOf>, deadline: Instant): List<Fix>
 
-       fun sign(ftx: FilteredTransaction, txId: SecureHash): DigitalSignature.WithKey
+       fun sign(ftx: FilteredTransaction, txId: SecureHash): TransactionSignature
    }
 
 Because the fix contains a timestamp (the ``forDay`` field), that identifies the version of the data being requested,
 there can be an arbitrary delay between a fix being requested via ``query`` and the signature being requested via ``sign``
 as the Oracle can know which, potentially historical, value it is being asked to sign for.  This is an important
-technique for continously varying data.
+technique for continuously varying data.
 
 The ``query`` method takes a deadline, which is a point in time the requester is willing to wait until for the necessary
 data to be available.  Not every oracle will need this.  This can be useful where data is expected to be available on a

docs/source/tutorial-building-transactions.rst

@@ -67,7 +67,7 @@ different ``SignedTransaction``. For instance in a foreign exchange
 scenario we shouldn't send a ``SignedTransaction`` with only our sell
 side populated as that could be used to take the money without the
 expected return of the other currency. Also, it is best practice for
-flows to receive back the ``DigitalSignature.WithKey`` of other parties
+flows to receive back the ``TransactionSignature`` of other parties
 rather than a full ``SignedTransaction`` objects, because otherwise we
 have to separately check that this is still the same
 ``SignedTransaction`` and not a malicious substitute.

docs/source/tutorial-tear-offs.rst

@@ -36,16 +36,18 @@ IRSDemo example. Then we can construct ``FilteredTransaction``:
 In the Oracle example this step takes place in ``RatesFixFlow`` by overriding ``filtering`` function, see:
 :ref:`filtering_ref`.
 
-``FilteredTransaction`` holds ``filteredLeaves`` (data that we wanted to reveal) and Merkle branch for them.
+Both ``WireTransaction`` and ``FilteredTransaction`` inherit from ``TraversableTransaction``, so access to the
+transaction components is exactly the same. Note that unlike ``WireTransaction``,
+``FilteredTransaction`` only holds data that we wanted to reveal (after filtering).
 
 .. container:: codeset
 
    .. sourcecode:: kotlin
 
-        // Direct accsess to included commands, inputs, outputs, attachments etc.
+        // Direct access to included commands, inputs, outputs, attachments etc.
-        val cmds: List<Command> = ftx.filteredLeaves.commands
+        val cmds: List<Command> = ftx.commands
-        val ins: List<StateRef> = ftx.filteredLeaves.inputs
+        val ins: List<StateRef> = ftx.inputs
-        val timeWindow: TimeWindow? = ftx.filteredLeaves.timeWindow
+        val timeWindow: TimeWindow? = ftx.timeWindow
         ...
 
 .. literalinclude:: ../../samples/irs-demo/src/main/kotlin/net/corda/irs/api/NodeInterestRates.kt
@@ -54,8 +56,8 @@ In the Oracle example this step takes place in ``RatesFixFlow`` by overriding ``
     :end-before: DOCEND 1
 
 Above code snippet is taken from ``NodeInterestRates.kt`` file and implements a signing part of an Oracle. You can
-check only leaves using ``leaves.checkWithFun { check(it) }`` and then verify obtained ``FilteredTransaction`` to see
+check only leaves using ``ftx.checkWithFun { check(it) }`` and then verify obtained ``FilteredTransaction`` to see
-if data from ``PartialMerkleTree`` belongs to ``WireTransaction`` with provided ``id``. All you need is the root hash
+if its data belongs to ``WireTransaction`` with provided ``id``. All you need is the root hash
 of the full transaction:
 
 .. container:: codeset
@@ -74,7 +76,11 @@ Or combine the two steps together:
 
         ftx.verifyWithFunction(merkleRoot, ::check)
 
-.. note:: The way the ``FilteredTransaction`` is constructed ensures that after signing of the root hash it's impossible to add or remove
+.. note:: The way the ``FilteredTransaction`` is constructed ensures that after signing of the root hash it's impossible
-    leaves. However, it can happen that having transaction with multiple commands one party reveals only subset of them to the Oracle.
+to add or remove components (leaves). However, it can happen that having transaction with multiple commands one party
-    As signing is done now over the Merkle root hash, the service signs all commands of given type, even though it didn't see
+reveals only subset of them to the Oracle. As signing is done now over the Merkle root hash, the service signs all
-    all of them. This issue will be handled after implementing partial signatures.
+commands of given type, even though it didn't see all of them. In the case however where all of the commands should be
+visible to an Oracle, one can type ``ftx.checkAllComponentsVisible(COMMANDS_GROUP)`` before invoking ``ftx.verify``.
+``checkAllComponentsVisible`` is using a sophisticated underlying partial Merkle tree check to guarantee that all of
+the components of a particular group that existed in the original ``WireTransaction`` are included in the received
+``FilteredTransaction``.