From dfc15a6babb74a66493d31b8776a35d1473cce64 Mon Sep 17 00:00:00 2001 From: Mike Hearn Date: Thu, 25 Feb 2016 13:29:28 +0100 Subject: [PATCH] Regen docsite --- docs/build/html/.buildinfo | 2 +- .../html/_sources/protocol-state-machines.txt | 365 +++++++++++------ .../_sources/running-the-trading-demo.txt | 18 +- docs/build/html/_sources/tutorial.txt | 29 +- docs/build/html/_static/css/custom.css | 4 + docs/build/html/codestyle.html | 8 +- docs/build/html/data-model.html | 9 +- docs/build/html/genindex.html | 8 +- docs/build/html/getting-set-up.html | 9 +- docs/build/html/index.html | 11 +- docs/build/html/inthebox.html | 8 +- docs/build/html/messaging.html | 13 +- docs/build/html/objects.inv | Bin 257 -> 260 bytes docs/build/html/protocol-state-machines.html | 367 ++++++++++++------ docs/build/html/roadmap.html | 9 +- docs/build/html/running-the-trading-demo.html | 22 +- docs/build/html/search.html | 8 +- docs/build/html/searchindex.js | 2 +- docs/build/html/tutorial.html | 41 +- docs/build/html/visualiser.html | 9 +- 20 files changed, 614 insertions(+), 328 deletions(-) diff --git a/docs/build/html/.buildinfo b/docs/build/html/.buildinfo index 0b7323fd16..947b4cc446 100644 --- a/docs/build/html/.buildinfo +++ b/docs/build/html/.buildinfo @@ -1,4 +1,4 @@ # Sphinx build info version 1 # This file hashes the configuration used when building these files. When it is not found, a full rebuild will be done. -config: b79bc8e267991c90208eba2e06b900db +config: ad139b05c69c728d506a9770157eaa25 tags: 645f666f9bcd5a90fca523b33c5a78b7 diff --git a/docs/build/html/_sources/protocol-state-machines.txt b/docs/build/html/_sources/protocol-state-machines.txt index 57c54148aa..8667a91c80 100644 --- a/docs/build/html/_sources/protocol-state-machines.txt +++ b/docs/build/html/_sources/protocol-state-machines.txt @@ -65,7 +65,7 @@ We use continuations for the following reasons: * It allows us to write code that is free of callbacks, that looks like ordinary sequential code. * A suspended continuation takes far less memory than a suspended thread. It can be as low as a few hundred bytes. - In contrast a suspended Java stack can easily be 1mb in size. + In contrast a suspended Java thread stack can easily be 1mb in size. * It frees the developer from thinking (much) about persistence and serialisation. A *state machine* is a piece of code that moves through various *states*. These are not the same as states in the data @@ -86,10 +86,10 @@ Our protocol has two parties (B and S for buyer and seller) and will proceed as 1. S sends a ``StateAndRef`` pointing to the state they want to sell to B, along with info about the price they require B to pay. -2. B sends to S a ``SignedWireTransaction`` that includes the state as input, B's cash as input, the state with the new +2. B sends to S a ``SignedTransaction`` that includes the state as input, B's cash as input, the state with the new owner key as output, and any change cash as output. It contains a single signature from B but isn't valid because it lacks a signature from S authorising movement of the asset. -3. S signs it and hands the now finalised ``SignedWireTransaction`` back to B. +3. S signs it and hands the now finalised ``SignedTransaction`` back to B. You can find the implementation of this protocol in the file ``contracts/protocols/TwoPartyTradeProtocol.kt``. @@ -111,7 +111,7 @@ each side. fun runSeller(smm: StateMachineManager, timestampingAuthority: LegallyIdentifiableNode, otherSide: SingleMessageRecipient, assetToSell: StateAndRef, price: Amount, - myKeyPair: KeyPair, buyerSessionID: Long): ListenableFuture> { + myKeyPair: KeyPair, buyerSessionID: Long): ListenableFuture { val seller = Seller(otherSide, timestampingAuthority, assetToSell, price, myKeyPair, buyerSessionID) smm.add("$TRADE_TOPIC.seller", seller) return seller.resultFuture @@ -119,46 +119,46 @@ each side. fun runBuyer(smm: StateMachineManager, timestampingAuthority: LegallyIdentifiableNode, otherSide: SingleMessageRecipient, acceptablePrice: Amount, typeToBuy: Class, - sessionID: Long): ListenableFuture> { + sessionID: Long): ListenableFuture { val buyer = Buyer(otherSide, timestampingAuthority.identity, acceptablePrice, typeToBuy, sessionID) smm.add("$TRADE_TOPIC.buyer", buyer) return buyer.resultFuture } - class Seller(val otherSide: SingleMessageRecipient, - val timestampingAuthority: LegallyIdentifiableNode, - val assetToSell: StateAndRef, - val price: Amount, - val myKeyPair: KeyPair, - val buyerSessionID: Long) : ProtocolStateMachine>() { - @Suspendable - override fun call(): Pair { - TODO() - } - } - // This object is serialised to the network and is the first protocol message the seller sends to the buyer. - private class SellerTradeInfo( + class SellerTradeInfo( val assetForSale: StateAndRef, val price: Amount, val sellerOwnerKey: PublicKey, val sessionID: Long ) + class SignaturesFromSeller(val timestampAuthoritySig: DigitalSignature.WithKey, val sellerSig: DigitalSignature.WithKey) + + class Seller(val otherSide: SingleMessageRecipient, + val timestampingAuthority: LegallyIdentifiableNode, + val assetToSell: StateAndRef, + val price: Amount, + val myKeyPair: KeyPair, + val buyerSessionID: Long) : ProtocolLogic() { + @Suspendable + override fun call(): SignedTransaction { + TODO() + } + } class UnacceptablePriceException(val givenPrice: Amount) : Exception() class AssetMismatchException(val expectedTypeName: String, val typeName: String) : Exception() { override fun toString() = "The submitted asset didn't match the expected type: $expectedTypeName vs $typeName" } - // The buyer's side of the protocol. See note above Seller to learn about the caveats here. class Buyer(val otherSide: SingleMessageRecipient, val timestampingAuthority: Party, val acceptablePrice: Amount, val typeToBuy: Class, - val sessionID: Long) : ProtocolStateMachine>() { + val sessionID: Long) : ProtocolLogic() { @Suspendable - override fun call(): Pair { + override fun call(): SignedTransaction { TODO() } } @@ -167,7 +167,7 @@ each side. Let's unpack what this code does: - It defines a several classes nested inside the main ``TwoPartyTradeProtocol`` singleton, and a couple of methods, one - to run the buyer side of the protocol and one to run the seller side. + to run the buyer side of the protocol and one to run the seller side. Some of the classes are simply protocol messages. - It defines the "trade topic", which is just a string that namespaces this protocol. The prefix "platform." is reserved by the DLG, but you can define your own protocols using standard Java-style reverse DNS notation. - The ``runBuyer`` and ``runSeller`` methods take a number of parameters that specialise the protocol for this run, @@ -205,7 +205,8 @@ to either runBuyer or runSeller, depending on who we are, and then call ``.get() block the calling thread until the protocol has finished. Or we could register a callback on the returned future that will be invoked when it's done, where we could e.g. update a user interface. -Finally, we define a couple of exceptions, and a class that will be used as a protocol message called ``SellerTradeInfo``. +Finally, we define a couple of exceptions, and two classes that will be used as a protocol message called +``SellerTradeInfo`` and ``SignaturesFromSeller``. Suspendable methods ------------------- @@ -244,13 +245,72 @@ Let's implement the ``Seller.call`` method. This will be invoked by the platform .. sourcecode:: kotlin - val sessionID = random63BitValue() + val partialTX: SignedTransaction = receiveAndCheckProposedTransaction() - // Make the first message we'll send to kick off the protocol. - val hello = SellerTradeInfo(assetToSell, price, myKeyPair.public, sessionID) + // These two steps could be done in parallel, in theory. Our framework doesn't support that yet though. + val ourSignature = signWithOurKey(partialTX) + val tsaSig = subProtocol(TimestampingProtocol(timestampingAuthority, partialTX.txBits)) - val partialTX = sendAndReceive(TRADE_TOPIC, buyerSessionID, sessionID, hello, SignedWireTransaction::class.java) - logger().trace { "Received partially signed transaction" } + val stx: SignedTransaction = sendSignatures(partialTX, ourSignature, tsaSig) + + return stx + +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, request a timestamping authority to assert with another signature that the +timestamp in the transaction (if any) is valid, and finally we send back both our signature and the TSA's signature. +Finally, we hand back to the code that invoked the protocol the finished transaction in a couple of different forms. + +.. note:: ``ProtocolLogic`` classes can be composed together. Here, we see the use of the ``subProtocol`` method, which + is given an instance of ``TimestampingProtocol``. This protocol will run to completion and yield a result, almost + as if it's a regular method call. In fact, under the hood, all the ``subProtocol`` method does is pass the current + fiber object into the newly created object and then run ``call()`` on it ... so it basically _is_ just a method call. + This is where we can see the benefits of using continuations/fibers as a programming model. + +Let's fill out the ``receiveAndCheckProposedTransaction()`` method. + +.. container:: codeset + + .. sourcecode:: kotlin + + @Suspendable + open fun receiveAndCheckProposedTransaction(): SignedTransaction { + val sessionID = random63BitValue() + + // Make the first message we'll send to kick off the protocol. + val hello = SellerTradeInfo(assetToSell, price, myKeyPair.public, sessionID) + + val maybeSTX = sendAndReceive(TRADE_TOPIC, otherSide, buyerSessionID, sessionID, hello) + + maybeSTX.validate { + // Check that the tx proposed by the buyer is valid. + val missingSigs = it.verify(throwIfSignaturesAreMissing = false) + if (missingSigs != setOf(myKeyPair.public, timestampingAuthority.identity.owningKey)) + throw SignatureException("The set of missing signatures is not as expected: $missingSigs") + + val wtx: WireTransaction = it.tx + logger.trace { "Received partially signed transaction: ${it.id}" } + + checkDependencies(it) + + // This verifies that the transaction is contract-valid, even though it is missing signatures. + serviceHub.verifyTransaction(wtx.toLedgerTransaction(serviceHub.identityService)) + + if (wtx.outputs.sumCashBy(myKeyPair.public) != price) + throw IllegalArgumentException("Transaction is not sending us the right amounnt of cash") + + // There are all sorts of funny games a malicious secondary might play here, we should fix them: + // + // - This tx may attempt to send some assets we aren't intending to sell to the secondary, if + // we're reusing keys! So don't reuse keys! + // - This tx may include output states that impose odd conditions on the movement of the cash, + // once we implement state pairing. + // + // but the goal of this code is not to be fully secure (yet), but rather, just to find good ways to + // express protocol state machines on top of the messaging layer. + + return it + } + } That's pretty straightforward. We generate a session ID to identify what's happening on the seller side, fill out the initial protocol message, and then call ``sendAndReceive``. This function takes a few arguments: @@ -260,7 +320,7 @@ the initial protocol message, and then call ``sendAndReceive``. This function ta - The thing to send. It'll be serialised and sent automatically. - Finally a type argument, which is the kind of object we're expecting to receive from the other side. -Once sendAndReceive is called, the call method will be suspended into a continuation. When it gets back we'll do a log +Once ``sendAndReceive`` is called, the call method will be suspended into a continuation. When it gets back we'll do a log message. The buyer is supposed to send us a transaction with all the right inputs/outputs/commands in return, with their cash put into the transaction and their signature on it authorising the movement of the cash. @@ -273,51 +333,70 @@ cash put into the transaction and their signature on it authorising the movement doing things like creating threads from inside these calls would be a bad idea. They should only contain business logic. -OK, let's keep going: +You get back a simple wrapper class, ``UntrustworthyData``, which is just a marker class that reminds +us that the data came from a potentially malicious external source and may have been tampered with or be unexpected in +other ways. It doesn't add any functionality, but acts as a reminder to "scrub" the data before use. Here, our scrubbing +simply involves checking the signatures on it. Then we go ahead and check all the dependencies of this partial +transaction for validity. Here's the code to do that: .. container:: codeset .. sourcecode:: kotlin - partialTX.verifySignatures() - val wtx = partialTX.txBits.deserialize() - - requireThat { - "transaction sends us the right amount of cash" by (wtx.outputStates.sumCashBy(args.myKeyPair.public) == args.price) - // There are all sorts of funny games a malicious secondary might play here, we should fix them: - // - // - This tx may attempt to send some assets we aren't intending to sell to the secondary, if - // we're reusing keys! So don't reuse keys! - // - This tx may not be valid according to the contracts of the input states, so we must resolve - // and fully audit the transaction chains to convince ourselves that it is actually valid. - // - This tx may include output states that impose odd conditions on the movement of the cash, - // once we implement state pairing. + @Suspendable + private fun checkDependencies(stx: SignedTransaction) { + // Download and check all the transactions that this transaction depends on, but do not check this + // transaction itself. + val dependencyTxIDs = stx.tx.inputs.map { it.txhash }.toSet() + subProtocol(ResolveTransactionsProtocol(dependencyTxIDs, otherSide)) } - val ourSignature = args.myKeyPair.signWithECDSA(partialTX.txBits.bits) - val fullySigned: SignedWireTransaction = partialTX.copy(sigs = partialTX.sigs + ourSignature) - fullySigned.verify() - val timestamped: TimestampedWireTransaction = fullySigned.toTimestampedTransaction(serviceHub.timestampingService) - logger().trace { "Built finished transaction, sending back to secondary!" } +This is simple enough: we mark the method as ``@Suspendable`` because we're going to invoke a sub-protocol, extract the +IDs of the transactions the proposed transaction depends on, and then uses a protocol provided by the system to download +and check them all. This protocol does a breadth-first search over the dependency graph, bottoming out at issuance +transactions that don't have any inputs themselves. Once the node has audited the transaction history, all the dependencies +are committed to the node's local database so they won't be checked again next time. - send(TRADE_TOPIC, sessionID, timestamped) +.. note:: Transaction dependency resolution assumes that the peer you got the transaction from has all of the + dependencies itself. It must do, otherwise it could not have convinced itself that the dependencies were themselves + valid. It's important to realise that requesting only the transactions we require is a privacy leak, because if + we don't download a transaction from the peer, they know we must have already seen it before. Fixing this privacy + leak will come later. - return Pair(timestamped, timestamped.verifyToLedgerTransaction(serviceHub.timestampingService, serviceHub.identityService)) +After the dependencies, we check the proposed trading transaction for validity by running the contracts for that as +well (but having handled the fact that some signatures are missing ourselves). -Here, we see some assertions and signature checking to satisfy ourselves that we're not about to sign something -incorrect. Once we're happy, we calculate a signature over the transaction to authorise the movement of the asset -we are selling, and then we verify things to make sure it's all OK. Finally, we request timestamping of the -transaction, in case the contracts governing the asset we're selling require it, and send the now finalised and -validated transaction back to the buyer. +Here's the rest of the code: + +.. container:: codeset + + .. sourcecode:: kotlin + + open fun signWithOurKey(partialTX: SignedTransaction) = myKeyPair.signWithECDSA(partialTX.txBits) + + @Suspendable + open fun sendSignatures(partialTX: SignedTransaction, ourSignature: DigitalSignature.WithKey, + tsaSig: DigitalSignature.LegallyIdentifiable): SignedTransaction { + val fullySigned = partialTX + tsaSig + ourSignature + + logger.trace { "Built finished transaction, sending back to secondary!" } + + send(TRADE_TOPIC, otherSide, buyerSessionID, SignaturesFromSeller(tsaSig, ourSignature)) + return fullySigned + } + +It's should be all pretty straightforward: here, ``txBits`` is the raw byte array representing the transaction. + +In ``sendSignatures``, we take the two signatures we calculated, then add them to the partial transaction we were sent. +We provide an overload for the + operator so signatures can be added to a SignedTransaction easily. Finally, we wrap the +two signatures in a simple wrapper message class and send it back. The send won't block waiting for an acknowledgement, +but the underlying message queue software will retry delivery if the other side has gone away temporarily. .. warning:: This code is **not secure**. Other than not checking for all possible invalid constructions, if the seller stops before sending the finalised transaction to the buyer, the seller is left with a valid transaction but the buyer isn't, so they can't spend the asset they just purchased! This sort of thing will be fixed in a future version of the code. -Finally, the call function returns with the result of the protocol: in our case, the final transaction in two different -forms. - Implementing the buyer ---------------------- @@ -328,82 +407,99 @@ OK, let's do the same for the buyer side: .. sourcecode:: kotlin @Suspendable - override fun call(): Pair { + override fun call(): SignedTransaction { + val tradeRequest = receiveAndValidateTradeRequest() + val (ptx, cashSigningPubKeys) = assembleSharedTX(tradeRequest) + val stx = signWithOurKeys(cashSigningPubKeys, ptx) + val signatures = swapSignaturesWithSeller(stx, tradeRequest.sessionID) + + logger.trace { "Got signatures from seller, verifying ... "} + val fullySigned = stx + signatures.timestampAuthoritySig + signatures.sellerSig + fullySigned.verify() + + logger.trace { "Fully signed transaction was valid. Trade complete! :-)" } + return fullySigned + } + + @Suspendable + open fun receiveAndValidateTradeRequest(): SellerTradeInfo { // Wait for a trade request to come in on our pre-provided session ID. - val tradeRequest = receive(TRADE_TOPIC, args.sessionID, SellerTradeInfo::class.java) + val maybeTradeRequest = receive(TRADE_TOPIC, sessionID) - // What is the seller trying to sell us? - val assetTypeName = tradeRequest.assetForSale.state.javaClass.name - logger().trace { "Got trade request for a $assetTypeName" } + maybeTradeRequest.validate { + // What is the seller trying to sell us? + val asset = it.assetForSale.state + val assetTypeName = asset.javaClass.name + logger.trace { "Got trade request for a $assetTypeName: ${it.assetForSale}" } - // Check the start message for acceptability. - check(tradeRequest.sessionID > 0) - if (tradeRequest.price > acceptablePrice) - throw UnacceptablePriceException(tradeRequest.price) - if (!typeToBuy.isInstance(tradeRequest.assetForSale.state)) - throw AssetMismatchException(typeToBuy.name, assetTypeName) + // Check the start message for acceptability. + check(it.sessionID > 0) + if (it.price > acceptablePrice) + throw UnacceptablePriceException(it.price) + if (!typeToBuy.isInstance(asset)) + throw AssetMismatchException(typeToBuy.name, assetTypeName) - // TODO: Either look up the stateref here in our local db, or accept a long chain - // of states and validate them to audit the other side and ensure it actually owns - // the state we are being offered! For now, just assume validity! + // Check the transaction that contains the state which is being resolved. + // We only have a hash here, so if we don't know it already, we have to ask for it. + subProtocol(ResolveTransactionsProtocol(setOf(it.assetForSale.ref.txhash), otherSide)) - // Generate the shared transaction that both sides will sign, using the data we have. - val ptx = TransactionBuilder() - // Add input and output states for the movement of cash, by using the Cash contract - // to generate the states. - val wallet = serviceHub.walletService.currentWallet - val cashStates = wallet.statesOfType() - val cashSigningPubKeys = Cash().craftSpend(ptx, tradeRequest.price, - tradeRequest.sellerOwnerKey, cashStates) - // Add inputs/outputs/a command for the movement of the asset. - ptx.addInputState(tradeRequest.assetForSale.ref) - // Just pick some new public key for now. - val freshKey = serviceHub.keyManagementService.freshKey() - val (command, state) = tradeRequest.assetForSale.state.withNewOwner(freshKey.public) - ptx.addOutputState(state) - ptx.addArg(WireCommand(command, tradeRequest.assetForSale.state.owner)) + return it + } + } + @Suspendable + open fun swapSignaturesWithSeller(stx: SignedTransaction, theirSessionID: Long): SignaturesFromSeller { + logger.trace { "Sending partially signed transaction to seller" } + + // TODO: Protect against the seller terminating here and leaving us in the lurch without the final tx. + + return sendAndReceive(TRADE_TOPIC, otherSide, theirSessionID, sessionID, stx, SignaturesFromSeller::class.java).validate { it } + } + + open fun signWithOurKeys(cashSigningPubKeys: List, ptx: TransactionBuilder): SignedTransaction { // Now sign the transaction with whatever keys we need to move the cash. for (k in cashSigningPubKeys) { val priv = serviceHub.keyManagementService.toPrivate(k) ptx.signWith(KeyPair(k, priv)) } - val stx = ptx.toSignedTransaction(checkSufficientSignatures = false) - stx.verifySignatures() // Verifies that we generated a signed transaction correctly. + return ptx.toSignedTransaction(checkSufficientSignatures = false) + } - // TODO: Could run verify() here to make sure the only signature missing is the sellers. + open fun assembleSharedTX(tradeRequest: SellerTradeInfo): Pair> { + val ptx = TransactionBuilder() + // Add input and output states for the movement of cash, by using the Cash contract to generate the states. + val wallet = serviceHub.walletService.currentWallet + val cashStates = wallet.statesOfType() + val cashSigningPubKeys = Cash().generateSpend(ptx, tradeRequest.price, tradeRequest.sellerOwnerKey, cashStates) + // Add inputs/outputs/a command for the movement of the asset. + ptx.addInputState(tradeRequest.assetForSale.ref) + // Just pick some new public key for now. This won't be linked with our identity in any way, which is what + // we want for privacy reasons: the key is here ONLY to manage and control ownership, it is not intended to + // reveal who the owner actually is. The key management service is expected to derive a unique key from some + // initial seed in order to provide privacy protection. + val freshKey = serviceHub.keyManagementService.freshKey() + val (command, state) = tradeRequest.assetForSale.state.withNewOwner(freshKey.public) + ptx.addOutputState(state) + ptx.addCommand(command, tradeRequest.assetForSale.state.owner) - logger().trace { "Sending partially signed transaction to seller" } - - // TODO: Protect against the buyer terminating here and leaving us in the lurch without - // the final tx. - // TODO: Protect against a malicious buyer sending us back a different transaction to - // the one we built. - val fullySigned = sendAndReceive(TRADE_TOPIC, tradeRequest.sessionID, sessionID, stx, - TimestampedWireTransaction::class.java) - - logger().trace { "Got fully signed transaction, verifying ... "} - - val ltx = fullySigned.verifyToLedgerTransaction(serviceHub.timestampingService, - serviceHub.identityService) - - logger().trace { "Fully signed transaction was valid. Trade complete! :-)" } - - return Pair(fullySigned, ltx) + // And add a request for timestamping: it may be that none of the contracts need this! But it can't hurt + // to have one. + ptx.setTime(Instant.now(), timestampingAuthority, 30.seconds) + return Pair(ptx, cashSigningPubKeys) } This code is longer but still fairly straightforward. Here are some things to pay attention to: 1. We do some sanity checking on the received message to ensure we're being offered what we expected to be offered. -2. We create a cash spend in the normal way, by using ``Cash().craftSpend``. See the contracts tutorial if this isn't +2. We create a cash spend in the normal way, by using ``Cash().generateSpend``. See the contracts tutorial if this isn't clear. 3. We access the *service hub* when we need it to access things that are transient and may change or be recreated whilst a protocol is suspended, things like the wallet or the timestamping service. Remember that a protocol may be suspended when it waits to receive a message across node or computer restarts, so objects representing a service or data which may frequently change should be accessed 'just in time'. -4. Finally, we send the unfinsished, invalid transaction to the seller so they can sign it. They are expected to send - back to us a ``TimestampedWireTransaction``, which once we verify it, should be the final outcome of the trade. +4. Finally, we send the unfinished, invalid transaction to the seller so they can sign it. They are expected to send + back to us a ``SignaturesFromSeller``, which once we verify it, should be the final outcome of the trade. As you can see, the protocol logic is straightforward and does not contain any callbacks or network glue code, despite the fact that it takes minimal resources and can survive node restarts. @@ -415,3 +511,52 @@ the fact that it takes minimal resources and can survive node restarts. this problem doesn't occur. It's also restored for you when a protocol state machine is restored after a node restart. +Progress tracking +----------------- + +Not shown in the code snippets above is the usage of the ``ProgressTracker`` API. Progress tracking exports information +from a protocol about where it's got up to in such a way that observers can render it in a useful manner to humans who +may need to be informed. It may be rendered via an API, in a GUI, onto a terminal window, etc. + +A ``ProgressTracker`` is constructed with a series of ``Step`` objects, where each step is an object representing a +stage in a piece of work. It is therefore typical to use singletons that subclass ``Step``, which may be defined easily +in one line when using Kotlin. Typical steps might be "Waiting for response from peer", "Waiting for signature to be +approved", "Downloading and verifying data" etc. + +Each step exposes a label. By default labels are fixed, but by subclassing ``RelabelableStep`` +you can make a step that can update its label on the fly. That's useful for steps that want to expose non-structured +progress information like the current file being downloaded. By defining your own step types, you can export progress +in a way that's both human readable and machine readable. + +Progress trackers are hierarchical. Each step can be the parent for another tracker. By altering the +``ProgressTracker.childrenFor[step] = tracker`` map, a tree of steps can be created. It's allowed to alter the hierarchy +at runtime, on the fly, and the progress renderers will adapt to that properly. This can be helpful when you don't +fully know ahead of time what steps will be required. If you _do_ know what is required, configuring as much of the +hierarchy ahead of time is a good idea, as that will help the users see what is coming up. + +Every tracker has not only the steps given to it at construction time, but also the singleton +``ProgressTracker.UNSTARTED`` step and the ``ProgressTracker.DONE`` step. Once a tracker has become ``DONE`` its +position may not be modified again (because e.g. the UI may have been removed/cleaned up), but until that point, the +position can be set to any arbitrary set both forwards and backwards. Steps may be skipped, repeated, etc. Note that +rolling the current step backwards will delete any progress trackers that are children of the steps being reversed, on +the assumption that those subtasks will have to be repeated. + +Trackers provide an `Rx observable `_ which streams changes to the hierarchy. The top level +observable exposes all the events generated by its children as well. The changes are represented by objects indicating +whether the change is one of position (i.e. progress), structure (i.e. new subtasks being added/removed) or some other +aspect of rendering (i.e. a step has changed in some way and is requesting a re-render). + +The protocol framework is somewhat integrated with this API. Each ``ProtocolLogic`` may optionally provide a tracker by +overriding the ``protocolTracker`` property (``getProtocolTracker`` method in Java). If the +``ProtocolLogic.subProtocol`` method is used, then the tracker of the sub-protocol will be made a child of the current +step in the parent protocol automatically, if the parent is using tracking in the first place. The framework will also +automatically set the current step to ``DONE`` for you, when the protocol is finished. + +Because a protocol may sometimes wish to configure the children in its progress hierarchy _before_ the sub-protocol +is constructed, for sub-protocols that always follow the same outline regardless of their parameters it's conventional +to define a companion object/static method (for Kotlin/Java respectively) that constructs a tracker, and then allow +the sub-protocol to have the tracker it will use be passed in as a parameter. This allows all trackers to be built +and linked ahead of time. + +In future, the progress tracking framework will become a vital part of how exceptions, errors, and other faults are +surfaced to human operators for investigation and resolution. \ No newline at end of file diff --git a/docs/build/html/_sources/running-the-trading-demo.txt b/docs/build/html/_sources/running-the-trading-demo.txt index c8cf802e14..ffb35587f1 100644 --- a/docs/build/html/_sources/running-the-trading-demo.txt +++ b/docs/build/html/_sources/running-the-trading-demo.txt @@ -9,20 +9,20 @@ let us know. Now, open two terminals, and in the first run::: - ./gradlew runDemoBuyer + ./scripts/trader-demo.sh buyer -It will create a directory named "buyer" and ask you to edit the configuration file inside. Open up ``buyer/config`` -in your favourite text editor and give the node a legal identity of "Big Buyer Corp, Inc" or whatever else you feel like. -The actual text string is not important. Now run the gradle command again, and it should start up and wait for -a seller to connect. +It will compile things, if necessary, then create a directory named "buyer" with a bunch of files inside and start +the node. You should see it waiting for a trade to begin. In the second terminal, run:: - ./gradlew runDemoSeller - -and repeat the process, this time calling the node ... something else. + ./scripts/trader-demo.sh seller You should see some log lines scroll past, and within a few seconds the messages "Purchase complete - we are a happy customer!" and "Sale completed - we have a happy customer!" should be printed. -If it doesn't work, jump on the mailing list and let us know. \ No newline at end of file +If it doesn't work, jump on the mailing list and let us know. + +For Windows users, the contents of the shell script are very trivial and can easily be done by hand from a command +window. Essentially, it just runs Gradle to create the startup scripts, and then starts the node with one set of +flags or another. \ No newline at end of file diff --git a/docs/build/html/_sources/tutorial.txt b/docs/build/html/_sources/tutorial.txt index dd5faf2b73..88541d8a84 100644 --- a/docs/build/html/_sources/tutorial.txt +++ b/docs/build/html/_sources/tutorial.txt @@ -636,22 +636,22 @@ again to ensure the third transaction fails with a message that contains "must h the exact message). -Adding a crafting API to your contract --------------------------------------- +Adding a generation API to your contract +---------------------------------------- Contract classes **must** provide a verify function, but they may optionally also provide helper functions to simplify -their usage. A simple class of functions most contracts provide are *crafting functions*, which either generate or +their usage. A simple class of functions most contracts provide are *generation functions*, which either create or modify a transaction to perform certain actions (an action is normally mappable 1:1 to a command, but doesn't have to be so). -Crafting may involve complex logic. For example, the cash contract has a ``craftSpend`` method that is given a set of +Generation may involve complex logic. For example, the cash contract has a ``generateSpend`` method that is given a set of cash states and chooses a way to combine them together to satisfy the amount of money that is being sent. In the immutable-state model that we are using ledger entries (states) can only be created and deleted, but never modified. Therefore to send $1200 when we have only $900 and $500 requires combining both states together, and then creating two new output states of $1200 and $200 back to ourselves. This latter state is called the *change* and is a concept that should be familiar to anyone who has worked with Bitcoin. -As another example, we can imagine code that implements a netting algorithm may craft complex transactions that must +As another example, we can imagine code that implements a netting algorithm may generate complex transactions that must be signed by many people. Whilst such code might be too big for a single utility method (it'd probably be sized more like a module), the basic concept is the same: preparation of a transaction using complex logic. @@ -662,7 +662,7 @@ a method to wrap up the issuance process: .. sourcecode:: kotlin - fun craftIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): TransactionBuilder { + fun generateIssue(issuance: InstitutionReference, faceValue: Amount, maturityDate: Instant): TransactionBuilder { val state = State(issuance, issuance.party.owningKey, faceValue, maturityDate) return TransactionBuilder(state, WireCommand(Commands.Issue, issuance.party.owningKey)) } @@ -673,7 +673,7 @@ returns a ``TransactionBuilder``. A ``TransactionBuilder`` is one of the few mut It allows you to add inputs, outputs and commands to it and is designed to be passed around, potentially between multiple contracts. -.. note:: Crafting methods should ideally be written to compose with each other, that is, they should take a +.. note:: Generation methods should ideally be written to compose with each other, that is, they should take a ``TransactionBuilder`` as an argument instead of returning one, unless you are sure it doesn't make sense to combine this type of transaction with others. In this case, issuing CP at the same time as doing other things would just introduce complexity that isn't likely to be worth it, so we return a fresh object each time: instead, @@ -697,7 +697,7 @@ What about moving the paper, i.e. reassigning ownership to someone else? .. sourcecode:: kotlin - fun craftMove(tx: TransactionBuilder, paper: StateAndRef, newOwner: PublicKey) { + fun generateMove(tx: TransactionBuilder, paper: StateAndRef, newOwner: PublicKey) { tx.addInputState(paper.ref) tx.addOutputState(paper.state.copy(owner = newOwner)) tx.addArg(WireCommand(Commands.Move, paper.state.owner)) @@ -705,7 +705,7 @@ What about moving the paper, i.e. reassigning ownership to someone else? Here, the method takes a pre-existing ``TransactionBuilder`` and adds to it. This is correct because typically you will want to combine a sale of CP atomically with the movement of some other asset, such as cash. So both -craft methods should operate on the same transaction. You can see an example of this being done in the unit tests +generate methods should operate on the same transaction. You can see an example of this being done in the unit tests for the commercial paper contract. The paper is given to us as a ``StateAndRef`` object. This is exactly what it sounds like: @@ -719,9 +719,9 @@ Finally, we can do redemption. .. sourcecode:: kotlin @Throws(InsufficientBalanceException::class) - fun craftRedeem(tx: TransactionBuilder, paper: StateAndRef, wallet: List>) { + fun generateRedeem(tx: TransactionBuilder, paper: StateAndRef, wallet: List>) { // Add the cash movement using the states in our wallet. - Cash().craftSpend(tx, paper.state.faceValue, paper.state.owner, wallet) + Cash().generateSpend(tx, paper.state.faceValue, paper.state.owner, wallet) tx.addInputState(paper.ref) tx.addArg(WireCommand(CommercialPaper.Commands.Redeem, paper.state.owner)) } @@ -744,10 +744,9 @@ A ``TransactionBuilder`` is not by itself ready to be used anywhere, so first, w is recognised by the network. The most important next step is for the participating entities to sign it using the ``signWith()`` method. This takes a keypair, serialises the transaction, signs the serialised form and then stores the signature inside the ``TransactionBuilder``. Once all parties have signed, you can call ``TransactionBuilder.toSignedTransaction()`` -to get a ``SignedWireTransaction`` object. This is an immutable form of the transaction that's ready for *timestamping*. - -.. note:: Timestamping and passing around of partial transactions for group signing is not yet fully implemented. - This tutorial will be updated once it is. +to get a ``SignedTransaction`` object. This is an immutable form of the transaction that's ready for *timestamping*, +which can be done using a ``TimestamperClient``. To learn more about that, please refer to the +:doc:`protocol-state-machines` document. You can see how transactions flow through the different stages of construction by examining the commercial paper unit tests. diff --git a/docs/build/html/_static/css/custom.css b/docs/build/html/_static/css/custom.css index 114952e8e2..d4c211d508 100644 --- a/docs/build/html/_static/css/custom.css +++ b/docs/build/html/_static/css/custom.css @@ -25,3 +25,7 @@ .codeset > .highlight-java { display: none; } + +.wy-nav-content { + max-width: 1000px; +} \ No newline at end of file diff --git a/docs/build/html/codestyle.html b/docs/build/html/codestyle.html index 55fe724b88..1abd344073 100644 --- a/docs/build/html/codestyle.html +++ b/docs/build/html/codestyle.html @@ -8,7 +8,7 @@ - Code style guide — R3 Prototyping 0.1 documentation + Code style guide — R3 Prototyping latest documentation @@ -30,7 +30,7 @@ - + @@ -59,7 +59,7 @@
- 0.1 + latest
@@ -326,7 +326,7 @@ really necessary. In other words, don’t do this:

@@ -59,7 +59,7 @@
- 0.1 + latest
@@ -179,7 +179,7 @@ @@ -58,7 +58,7 @@
- 0.1 + latest
@@ -182,7 +182,7 @@