From c8fc1b624b7d34f38bc305a0af6e0078960a15d8 Mon Sep 17 00:00:00 2001 From: Konstantinos Chalkias Date: Wed, 27 Sep 2017 15:51:44 +0100 Subject: [PATCH] Updating docs w.r.t. new FilteredTransaction and TransactionSignature (#1678) --- docs/source/oracles.rst | 4 +-- .../source/tutorial-building-transactions.rst | 2 +- docs/source/tutorial-tear-offs.rst | 28 +++++++++++-------- 3 files changed, 20 insertions(+), 14 deletions(-) diff --git a/docs/source/oracles.rst b/docs/source/oracles.rst index c8c6de060a..177da9a320 100644 --- a/docs/source/oracles.rst +++ b/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, deadline: Instant): List - 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 diff --git a/docs/source/tutorial-building-transactions.rst b/docs/source/tutorial-building-transactions.rst index b8c25bf04a..3a7586dbb9 100644 --- a/docs/source/tutorial-building-transactions.rst +++ b/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. diff --git a/docs/source/tutorial-tear-offs.rst b/docs/source/tutorial-tear-offs.rst index 5187aaac42..12a1ec8512 100644 --- a/docs/source/tutorial-tear-offs.rst +++ b/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. - val cmds: List = ftx.filteredLeaves.commands - val ins: List = ftx.filteredLeaves.inputs - val timeWindow: TimeWindow? = ftx.filteredLeaves.timeWindow + // Direct access to included commands, inputs, outputs, attachments etc. + val cmds: List = ftx.commands + val ins: List = ftx.inputs + 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 -if data from ``PartialMerkleTree`` belongs to ``WireTransaction`` with provided ``id``. All you need is the root hash +check only leaves using ``ftx.checkWithFun { check(it) }`` and then verify obtained ``FilteredTransaction`` to see +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 - leaves. However, it can happen that having transaction with multiple commands one party reveals only subset of them to the Oracle. - As signing is done now over the Merkle root hash, the service signs all commands of given type, even though it didn't see - all of them. This issue will be handled after implementing partial signatures. +.. note:: The way the ``FilteredTransaction`` is constructed ensures that after signing of the root hash it's impossible +to add or remove components (leaves). However, it can happen that having transaction with multiple commands one party +reveals only subset of them to the Oracle. As signing is done now over the Merkle root hash, the service signs all +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``.