From 3e94fc19214af8e26017837dc3a5417a3773d29d Mon Sep 17 00:00:00 2001 From: Mike Hearn Date: Fri, 26 Aug 2016 13:05:26 +0200 Subject: [PATCH] More review fixes --- docs/source/data-model.rst | 2 +- docs/source/event-scheduling.rst | 8 ++++---- docs/source/protocol-state-machines.rst | 14 +++++++------- docs/source/tutorial-contract.rst | 14 +++++++------- 4 files changed, 19 insertions(+), 19 deletions(-) diff --git a/docs/source/data-model.rst b/docs/source/data-model.rst index e8b5336480..0ba274072d 100644 --- a/docs/source/data-model.rst +++ b/docs/source/data-model.rst @@ -113,7 +113,7 @@ Differences: * A Bitcoin script can only be given a fixed set of byte arrays as the input. This means there's no way for a contract to examine the structure of the entire transaction, which severely limits what contracts can do. * Our contracts are Turing-complete and can be written in any ordinary programming language that targets the JVM. -* Our transactions and contracts get their time from an attached timestamp rather than a block chain. This is +* Our transactions and contracts get their time from an attached timestamp rather than a block. This is important given that we use block-free conflict resolution algorithms. The timestamp can be arbitrarily precise. * We use the term "contract" to refer to a bundle of business logic that may handle various different tasks, beyond transaction verification. For instance, currently our contracts also include code for creating valid transactions diff --git a/docs/source/event-scheduling.rst b/docs/source/event-scheduling.rst index c1d6b07a9e..94ed2b2189 100644 --- a/docs/source/event-scheduling.rst +++ b/docs/source/event-scheduling.rst @@ -90,10 +90,10 @@ business process and to take on those roles. That ``ProtocolLogic`` will be han rate swap ``State`` in question, as well as a tolerance ``Duration`` of how long to wait after the activity is triggered for the interest rate before indicating an error. -.. note:: Observe the use of the factory to create a ``ProtocolLogicRef`` instance to embed in the ``ScheduledActivity``. - This is a way to create a reference to the ``ProtocolLogic`` class and it's constructor parameters to instantiate - that can be checked against a per node whitelist of approved and allowable types as part of our overall - security sandboxing. +.. note:: This is a way to create a reference to the ProtocolLogic class and its constructor parameters to + instantiate. The reference can be checked against a per-node whitelist of approved and allowable types as + part of our overall security sandboxing. + As previously mentioned, we currently need a small network handler to assist with session setup until the work to automate that is complete. See the interest rate swap specific implementation ``FixingSessionInitiationHandler`` which diff --git a/docs/source/protocol-state-machines.rst b/docs/source/protocol-state-machines.rst index 9ad2c5e303..802ea563a7 100644 --- a/docs/source/protocol-state-machines.rst +++ b/docs/source/protocol-state-machines.rst @@ -157,7 +157,7 @@ Let's unpack what this code does: - It defines a several classes nested inside the main ``TwoPartyTradeProtocol`` singleton. Some of the classes are simply protocol messages or exceptions. The other two represent the buyer and seller side of the protocol. - It defines the "trade topic", which is just a string that namespaces this protocol. The prefix "platform." is reserved - by Corda, but you can define your own protocols using standard Java-style reverse DNS notation. + by Corda, but you can define your own protocol namespaces using standard Java-style reverse DNS notation. Going through the data needed to become a seller, we have: @@ -182,13 +182,13 @@ And for the buyer: Alright, so using this protocol shouldn't be too hard: in the simplest case we can just create a Buyer or Seller with the details of the trade, depending on who we are. We then have to start the protocol in some way. Just -calling the ``call`` method ourselves won't work: instead we need to ask the framework to start the protocol for +calling the ``call`` function ourselves won't work: instead we need to ask the framework to start the protocol for us. More on that in a moment. -Suspendable methods -------------------- +Suspendable functions +--------------------- -The ``call`` method of the buyer/seller classes is marked with the ``@Suspendable`` annotation. What does this mean? +The ``call`` function of the buyer/seller classes is marked with the ``@Suspendable`` annotation. What does this mean? As mentioned above, our protocol framework will at points suspend the code and serialise it to disk. For this to work, any methods on the call stack must have been pre-marked as ``@Suspendable`` so the bytecode rewriter knows to modify @@ -213,7 +213,7 @@ see ":doc:`event-scheduling`" to learn more about this. Or they can be triggered be triggered directly via the Java-level node APIs from your app code. You request a protocol to be invoked by using the ``ServiceHub.invokeProtocolAsync`` method. This takes a -Java reflection ``Class`` object that describes the protocol class to use (in this case, either Buyer or Seller). +Java reflection ``Class`` object that describes the protocol class to use (in this case, either ``Buyer`` or ``Seller``). It also takes a set of arguments to pass to the constructor. Because it's possible for protocol invocations to be requested by untrusted code (e.g. a state that you have been sent), the types that can be passed into the protocol are checked against a whitelist, which can be extended by apps themselves at load time. @@ -241,7 +241,7 @@ Let's implement the ``Seller.call`` method. This will be run when the protocol i Here we see the outline of the procedure. We receive a proposed trade transaction from the buyer and check that it's valid. Then we sign with our own key and request a notary to assert with another signature that the -timestamp in the transaction (if any) is valid and there are no double spends, and finally we send back both +timestamp in the transaction (if any) is valid and there are no double spends, and send back both our signature and the notaries signature. Finally, we hand back to the code that invoked the protocol the finished transaction. diff --git a/docs/source/tutorial-contract.rst b/docs/source/tutorial-contract.rst index 6f2d8628c4..c3b1b4ca75 100644 --- a/docs/source/tutorial-contract.rst +++ b/docs/source/tutorial-contract.rst @@ -19,7 +19,7 @@ Kotlin syntax works. Where to put your code ---------------------- -A Cordapp is a collection of contracts, state definitions, protocols and other ways to extend the server. To create +A CorDapp is a collection of contracts, state definitions, protocols and other ways to extend the server. To create one you would just create a Java-style project as normal, with your choice of build system (Maven, Gradle, etc). Then add a dependency on ``com.r3corda:core:0.X`` where X is the milestone number you are depending on. The core module defines the base classes used in this tutorial. @@ -250,7 +250,7 @@ Let's define a few commands now: } We define a simple grouping interface or static class, this gives us a type that all our commands have in common, -then we go ahead and create three commands: Move, Redeem, Issue. ``TypeOnlyCommandData`` is a helpful utility +then we go ahead and create three commands: ``Move``, ``Redeem``, ``Issue``. ``TypeOnlyCommandData`` is a helpful utility for the case when there's no data inside the command; only the existence matters. It defines equals and hashCode such that any instances always compare equal and hash to the same value. @@ -519,7 +519,7 @@ If the command is a ``Redeem`` command, then the requirements are more complex: 3. The commercial paper must *not* be propagated by this transaction: it must be deleted, by the group having no output state. This prevents the same CP being considered redeemable multiple times. -To calculate how much cash is moving, we use the ``sumCashBy`` utility method. Again, this is an extension method, +To calculate how much cash is moving, we use the ``sumCashBy`` utility function. Again, this is an extension function, so in Kotlin code it appears as if it was a method on the ``List`` type even though JDK provides no such method. In Java we see its true nature: it is actually a static method named ``CashKt.sumCashBy``. This method simply returns an ``Amount`` object containing the sum of all the cash states in the transaction outputs that are owned by @@ -603,7 +603,7 @@ The function we define creates a ``CommercialPaper.State`` object that mostly ju but it fills out the owner field of the state to be the same public key as the issuing party. The returned partial transaction has a ``Command`` object as a parameter. This is a container for any object -that implements the ``CommandData`` interface, along with a key that is expected to sign this transaction. In this case, +that implements the ``CommandData`` interface, along with a list of keys that are 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 ``TransactionBuilder`` has a convenience ``withItems`` method that takes a variable argument list. You can pass in @@ -660,13 +660,13 @@ issuer (i.e. the caller) must gather cash from its wallet and send the face valu .. note:: This contract has no explicit concept of rollover. -The *wallet* is a concept that may be familiar from Bitcoin and Ethereum. It is simply a set of cash states that are +The *wallet* is a concept that may be familiar from Bitcoin and Ethereum. It is simply a set of states (such as cash) that are owned by the caller. Here, we use the wallet to update the partial transaction we are handed with a movement of cash from the issuer of the commercial paper to the current owner. If we don't have enough quantity of cash in our wallet, -an exception is thrown. And then we add the paper itself as an input, but, not an output (as we wish to remove it +an exception is thrown. Then we add the paper itself as an input, but, not an output (as we wish to remove it from the ledger). Finally, we add a Redeem command that should be signed by the owner of the commercial paper. -.. warning:: The amount we pass to the ``generateSpend`` method has to be treated first with ``withoutIssuer``. +.. warning:: The amount we pass to the ``generateSpend`` function has to be treated first with ``withoutIssuer``. This reflects the fact that the way we handle issuer constraints is still evolving; the commercial paper contract requires payment in the form of a currency issued by a specific party (e.g. the central bank, or the issuers own bank perhaps). But the wallet wants to assemble spend transactions using cash states from