ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-03-21 19:45:21 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

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

Browse Source
This commit is contained in:
Konstantinos Chalkias 2017-09-27 15:51:44 +01:00 committed by GitHub
parent 72cff032e6
commit c8fc1b624b
3 changed files with 20 additions and 14 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

4
docs/source/oracles.rst
View File

@ -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

2
docs/source/tutorial-building-transactions.rst
View File

@ -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.

28
docs/source/tutorial-tear-offs.rst
View File

@ -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<Command> = ftx.filteredLeaves.commands
val ins: List<StateRef> = ftx.filteredLeaves.inputs
val timeWindow: TimeWindow? = ftx.filteredLeaves.timeWindow
// Direct access to included commands, inputs, outputs, attachments etc.
val cmds: List<Command> = ftx.commands
val ins: List<StateRef> = 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``.