ExternalVendorCode/corda
1
0
Fork 0
mirror of https://github.com/corda/corda.git synced 2025-06-16 22:28:15 +00:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

Rename com.r3corda -> net.corda

Browse Source
This commit is contained in:
Mike Hearn
2016-11-10 14:14:38 +01:00
parent 91c5f2ff57
commit ce99f354cb
4022 changed files with 2476 additions and 158936 deletions
Download Patch File Download Diff File Expand all files Collapse all files

54
docs/build/html/_sources/building-the-docs.txt vendored
View File

@ -1,54 +0,0 @@
Building the documentation
==========================
The documentation is under the ``docs`` folder, and is written in reStructuredText format. Documentation in HTML format
is pre-generated, as well as code documentation, and this can be done automatically via a provided script.
Requirements
------------
To build the documentation, you will need:
* GNU Make
* Python and pip (tested with Python 2.7.10)
* Dokka: https://github.com/Kotlin/dokka
* Sphinx: http://www.sphinx-doc.org/
* sphinx_rtd_theme: https://github.com/snide/sphinx_rtd_theme
The Dokka JAR file needs to be placed under the ``lib`` directory within the ``r3prototyping`` directory, in order for the
script to find it, as in:
.. sourcecode:: shell
r3prototyping/lib/dokka.jar
Note that to install under OS X El Capitan, you will need to tell pip to install under ``/usr/local``, which can be
done by specifying the installation target on the command line:
.. sourcecode:: shell
sudo -H pip install --install-option '--install-data=/usr/local' Sphinx
sudo -H pip install --install-option '--install-data=/usr/local' sphinx_rtd_theme
Build
-----
Once the requirements are installed, you can automatically build the HTML format user documentation and the API
documentation by running the following script:
.. sourcecode:: shell
docs/generate-docsite.sh
Alternatively you can build non-HTML formats from the ``docs`` folder. Change directory to the folder and then run the
following to see a list of all available formats:
.. sourcecode:: shell
make
For example to produce the documentation in HTML format:
.. sourcecode:: shell
make html

85
docs/build/html/_sources/clientrpc.txt vendored
View File

@ -1,85 +0,0 @@
Client RPC
==========
There are multiple ways to interact with a node from a *client program*, but if your client is written in a JVM
compatible language the easiest way to do so is using the client library. The library connects to your running
node using a message queue protocol and then provides a simple RPC interface to interact with it. You make calls
on a Java object as normal, and the marshalling back and forth is handled for you.
The starting point for the client library is the `CordaRPCClient`_ class. This provides a ``proxy`` method that
returns an implementation of the `CordaRPCOps`_ interface. A timeout parameter can be specified, and observables that
are returned by RPCs can be subscribed to in order to receive an ongoing stream of updates from the node. More
detail on how to use this is provided in the docs for the proxy method.
.. warning:: The returned object is somewhat expensive to create and consumes a small amount of server side
resources. When you're done with it, cast it to ``Closeable`` or ``AutoCloseable`` and close it. Don't create
one for every call you make - create a proxy and reuse it.
For a brief tutorial on how one can use the RPC API see :doc:`tutorial-clientrpc-api`.
Security
--------
Users wanting to use the RPC library are first required to authenticate themselves with the node using a valid username
and password. These are kept in ``rpc-users.properties`` in the node base directory. This file also specifies
permissions for each user, which the RPC implementation can use to control access. The file format is described in
:doc:`corda-configuration-files`.
Observables
-----------
The RPC system handles observables in a special way. When a method returns an observable, whether directly or
as a sub-object of the response object graph, an observable is created on the client to match the one on the
server. Objects emitted by the server-side observable are pushed onto a queue which is then drained by the client.
The returned observable may even emit object graphs with even more observables in them, and it all works as you
would expect.
This feature comes with a cost: the server must queue up objects emitted by the server-side observable until you
download them. Therefore RPCs that use this feature are marked with the ``@RPCReturnsObservables`` annotation, and
you are expected to subscribe to all the observables returned. If you don't want an observable then subscribe
then unsubscribe immediately to clear the buffers and indicate that you aren't interested. If your app quits then
server side resources will be freed automatically.
When all the observables returned by an RPC are unsubscribed on the client side, that unsubscription propagates
through to the server where the corresponding server-side observables are also unsubscribed.
.. warning:: If you leak an observable or proxy on the client side and it gets garbage collected, you will get
a warning printed to the logs and the proxy will be closed for you. But don't rely on this, as garbage
collection is non-deterministic.
Versioning
----------
The client RPC protocol is versioned with a simple incrementing integer. When a proxy is created the server is
queried for its protocol version, and you can specify your minimum requirement. Methods added in later versions
are tagged with the ``@RPCSinceVersion`` annotation. If you try to use a method that the server isn't advertising
support of, an ``UnsupportedOperationException`` is thrown. If you want to know the version of the server, just
use the ``protocolVersion`` property (i.e. ``getProtocolVersion`` in Java).
Thread safety
-------------
A proxy is thread safe, blocking, and will only allow a single RPC to be in flight at once. Any observables that
are returned and you subscribe to will have objects emitted on a background thread. Observables returned as part
of one RPC and observables returned from another may have their callbacks invoked in parallel, but observables
returned as part of the same specific RPC invocation are processed serially and will not be invoked in parallel.
If you want to make multiple calls to the server in parallel you can do that by creating multiple proxies, but
be aware that the server itself may *not* process your work in parallel even if you make your requests that way.
Error handling
--------------
If something goes wrong with the RPC infrastructure itself, an ``RPCException`` is thrown. If you call a method that
requires a higher version of the protocol than the server supports, ``UnsupportedOperationException`` is thrown.
Otherwise, if the server implementation throws an exception, that exception is serialised and rethrown on the client
side as if it was thrown from inside the called RPC method. These exceptions can be caught as normal.
Wire protocol
-------------
The client RPC wire protocol is not currently documented. To use it you must use the client library provided.
This is likely to change in a future release.
.. _CordaRPCClient: api/com.r3corda.client/-corda-r-p-c-client/index.html
.. _CordaRPCOps: api/com.r3corda.node.services.messaging/-corda-r-p-c-ops/index.html

222
docs/build/html/_sources/codestyle.txt vendored
View File

@ -1,222 +0,0 @@
Code style guide
================
This document explains the coding style used in the R3 prototyping repository. You will be expected to follow these
recommendations when submitting patches for review. Please take the time to read them and internalise them, to save
time during code review.
What follows are *recommendations* and not *rules*. They are in places intentionally vague, so use your good judgement
when interpreting them.
.. note:: Parts of the codebase may not follow this style guide yet. If you see a place that doesn't, please fix it!
1. General style
################
We use the standard Java coding style from Sun, adapted for Kotlin in ways that should be fairly intuitive.
Files no longer have copyright notices at the top, and license is now specified in the global README.md file.
We do not mark classes with @author Javadoc annotations.
In Kotlin code, KDoc is used rather than JavaDoc. It's very similar except it uses Markdown for formatting instead
of HTML tags.
We target Java 8 and use the latest Java APIs whenever convenient. We use ``java.time.Instant`` to represent timestamps
and ``java.nio.file.Path`` to represent file paths.
Never apply any design pattern religiously. There are no silver bullets in programming and if something is fashionable,
that doesn't mean it's always better. In particular:
* Use functional programming patterns like map, filter, fold only where it's genuinely more convenient. Never be afraid
to use a simple imperative construct like a for loop or a mutable counter if that results in more direct, English-like
code.
* Use immutability when you don't anticipate very rapid or complex changes to the content. Immutability can help avoid
bugs, but over-used it can make code that has to adjust fields of an immutable object (in a clone) hard to read and
stress the garbage collector. When such code becomes a widespread pattern it can lead to code that is just generically
slow but without hotspots.
* The tradeoffs between various thread safety techniques are complex, subtle, and no technique is always superior to
the others. Our code uses a mix of locks, worker threads and messaging depending on the situation.
1.1 Line Length and Spacing
---------------------------
We aim for line widths of no more than 120 characters. That is wide enough to avoid lots of pointless wrapping but
narrow enough that with a widescreen monitor and a 12 point fixed width font (like Menlo) you can fit two files
next to each other. This is not a rigidly enforced rule and if wrapping a line would be excessively awkward, let it
overflow. Overflow of a few characters here and there isn't a big deal: the goal is general convenience.
Where the number of parameters in a function, class, etc. causes an overflow past the end of the first line, they should
be structured one parameter per line.
Code is vertically dense, blank lines in methods are used sparingly. This is so more code can fit on screen at once.
We use spaces and not tabs.
1.2 Naming
----------
Naming generally follows Java standard style (pascal case for class names, camel case for methods, properties and
variables). Where a class name describes a tuple, "And" should be included in order to clearly indicate the elements are
individual parts, for example ``PartyAndReference``, not ``PartyReference`` (which sounds like a reference to a
``Party``).
2. Comments
###########
We like them as long as they add detail that is missing from the code. Comments that simply repeat the story already
told by the code are best deleted. Comments should:
* Explain what the code is doing at a higher level than is obtainable from just examining the statement and
surrounding code.
* Explain why certain choices were made and the tradeoffs considered.
* Explain how things can go wrong, which is a detail often not easily seen just by reading the code.
* Use good grammar with capital letters and full stops. This gets us in the right frame of mind for writing real
explanations of things.
When writing code, imagine that you have an intelligent colleague looking over your shoulder asking you questions
as you go. Think about what they might ask, and then put your answers in the code.
Don’t be afraid of redundancy, many people will start reading your code in the middle with little or no idea of what
it’s about, eg, due to a bug or a need to introduce a new feature. It’s OK to repeat basic facts or descriptions in
different places if that increases the chance developers will see something important.
API docs: all public methods, constants and classes should have doc comments in either JavaDoc or KDoc. API docs should:
* Explain what the method does in words different to how the code describes it.
* Always have some text, annotation-only JavaDocs don’t render well. Write “Returns a blah blah blah” rather
than “@returns blah blah blah” if that's the only content (or leave it out if you have nothing more to say than the
code already says).
* Illustrate with examples when you might want to use the method or class. Point the user at alternatives if this code
is not always right.
* Make good use of {@link} annotations.
Bad JavaDocs look like this:
.. sourcecode:: java
/** @return the size of the Bloom filter. */
public int getBloomFilterSize() {
return block;
}
Good JavaDocs look like this:
.. sourcecode:: java
/**
* Returns the size of the current {@link BloomFilter} in bytes. Larger filters have
* lower false positive rates for the same number of inserted keys and thus lower privacy,
* but bandwidth usage is also correspondingly reduced.
*/
public int getBloomFilterSize() { ... }
We use C-style (``/** */``) comments for API docs and we use C++ style comments (``//``) for explanations that are
only intended to be viewed by people who read the code.
When writing multi-line TODO comments, indent the body text past the TODO line, for example:
.. sourcecode:: java
// TODO: Something something
// More stuff to do
// Etc. etc.
3. Threading
############
Classes that are thread safe should be annotated with the ``@ThreadSafe`` annotation. The class or method comments
should describe how threads are expected to interact with your code, unless it's obvious because the class is
(for example) a simple immutable data holder.
Code that supports callbacks or event listeners should always accept an ``Executor`` argument that defaults to
``MoreExecutors.directThreadExecutor()`` (i.e. the calling thread) when registering the callback. This makes it easy
to integrate the callbacks with whatever threading environment the calling code expects, e.g. serialised onto a single
worker thread if necessary, or run directly on the background threads used by the class if the callback is thread safe
and doesn't care in what context it's invoked.
In the prototyping code it's OK to use synchronised methods i.e. with an exposed lock when the use of locking is quite
trivial. If the synchronisation in your code is getting more complex, consider the following:
1. Is the complexity necessary? At this early stage, don't worry too much about performance or scalability, as we're
exploring the design space rather than making an optimal implementation of a design that's already nailed down.
2. Could you simplify it by making the data be owned by a dedicated, encapsulated worker thread? If so, remember to
think about flow control and what happens if a work queue fills up: the actor model can often be useful but be aware
of the downsides and try to avoid explicitly defining messages, prefer to send closures onto the worker thread
instead.
3. If you use an explicit lock and the locking gets complex, and *always* if the class supports callbacks, use the
cycle detecting locks from the Guava library.
4. Can you simplify some things by using thread-safe collections like ``CopyOnWriteArrayList`` or ``ConcurrentHashMap``?
These data structures are more expensive than their non-thread-safe equivalents but can be worth it if it lets us
simplify the code.
Immutable data structures can be very useful for making it easier to reason about multi-threaded code. Kotlin makes it
easy to define these via the "data" attribute, which auto-generates a copy() method. That lets you create clones of
an immutable object with arbitrary fields adjusted in the clone. But if you can't use the data attribute for some
reason, for instance, you are working in Java or because you need an inheritance heirarchy, then consider that making
a class fully immutable may result in very awkward code if there's ever a need to make complex changes to it. If in
doubt, ask. Remember, never apply any design pattern religiously.
We have an extension to the ``Executor`` interface called ``AffinityExecutor``. It is useful when the thread safety
of a piece of code is based on expecting to be called from a single thread only (or potentially, a single thread pool).
``AffinityExecutor`` has additional methods that allow for thread assertions. These can be useful to ensure code is not
accidentally being used in a multi-threaded way when it didn't expect that.
4. Assertions and errors
########################
We use them liberally and we use them at runtime, in production. That means we avoid the "assert" keyword in Java,
and instead prefer to use the ``check()`` or ``require()`` functions in Kotlin (for an ``IllegalStateException`` or
``IllegalArgumentException`` respectively), or the Guava ``Preconditions.check`` method from Java.
We define new exception types liberally. We prefer not to provide English language error messages in exceptions at
the throw site, instead we define new types with any useful information as fields, with a toString() method if
really necessary. In other words, don't do this:
.. sourcecode:: java
throw new Exception("The foo broke")
instead do this
.. sourcecode:: java
class FooBrokenException extends Exception {}
throw new FooBrokenException()
The latter is easier to catch and handle if later necessary, and the type name should explain what went wrong.
Note that Kotlin does not require exception types to be declared in method prototypes like Java does.
5. Properties
#############
Where we want a public property to have one super-type in public and another sub-type in private (or internal), perhaps
to expose additional methods with a greater level of access to the code within the enclosing class, the style should be:
.. sourcecode:: kotlin
class PrivateFoo : PublicFoo
private val _foo = PrivateFoo()
val foo: PublicFoo get() = _foo
Notably:
* The public property should have an explicit and more restrictive type, most likely a super class or interface.
* The private, backed property should begin with underscore but otherwise have the same name as the public property.
The underscore resolves a potential property name clash, and avoids naming such as "privateFoo". If the type or use
of the private property is different enough that there is no naming collision, prefer the distinct names without
an underscore.
* The underscore prefix is not a general pattern for private properties.
* The public property should not have an additional backing field but use "get()" to return an appropriate copy of the
private field.
* The public property should optionally wrap the returned value in an immutable wrapper, such as Guava's immutable
collection wrappers, if that is appropriate.
* If the code following "get()" is succinct, prefer a one-liner formatting of the public property as above, otherwise
put the "get()" on the line below, indented.
6. Compiler warnings
####################
We do not allow compiler warnings, except in the experimental module where the usual standards do not apply and warnings
are suppressed. If a warning exists it should be either fixed or suppressed using @SuppressWarnings and if suppressed
there must be an accompanying explanation in the code for why the warning is a false positive.

195
docs/build/html/_sources/consensus.txt vendored
View File

@ -1,195 +0,0 @@
Consensus model
===============
The fundamental unit of consensus in Corda is the **state**. The concept of consensus can be divided into two parts:
1. Consensus over state **validity** -- parties can reach certainty that a transaction defining output states is accepted by the contracts pointed to by the states and has all the required signatures. This is achieved by parties independently running the same contract code and validation logic (as described in :doc:`data model <data-model>`)
2. Consensus over state **uniqueness** -- parties can reach certainty the output states created in a transaction are the unique successors to the input states consumed by that transaction (in other words -- a state has not been used as an input by more than one transaction)
This article presents an initial model for addressing the **uniqueness** problem.
.. note:: The current model is still a **work in progress** and everything described in this article can and is likely to change
Notary
------
We introduce the concept of a **notary**, which is an authority responsible for attesting that for a given transaction, it had not signed another transaction consuming any of its input states.
The data model is extended so that every **state** has an appointed notary:
.. sourcecode:: kotlin
/**
* A wrapper for [ContractState] containing additional platform-level state information.
* This is the definitive state that is stored on the ledger and used in transaction outputs
*/
data class TransactionState<out T : ContractState>(
/** The custom contract state */
val data: T,
/** Identity of the notary that ensures the state is not used as an input to a transaction more than once */
val notary: Party) {
...
}
All transactions have to be signed by their input state notary for the output states to be **valid** (apart from *issue* transactions, containing no input states).
.. note:: The notary is a logical concept and can itself be a distributed entity, potentially a cluster maintained by mutually distrusting parties
When the notary is requested to sign a transaction, it either signs over it, attesting that the outputs are the **unique** successors of the inputs,
or provides conflict information for any input state that had been consumed by another transaction it had signed before.
In doing so, the notary provides the point of finality in the system. Until the notary signature is obtained, parties cannot be sure that an equally valid, but conflicting transaction,
will not be regarded as confirmed. After the signature is obtained, the parties know that the inputs to this transaction have been uniquely consumed by this transaction.
Hence it is the point at which we can say finality has occurred.
Multiple notaries
~~~~~~~~~~~~~~~~~
More than one notary can exist in the network. This gives the following benefits:
* **Custom behaviour**. We can have both validating and privacy preserving Notaries -- parties can make a choice based on their specific requirements
* **Load balancing**. Spreading the transaction load over multiple Notaries will allow higher transaction throughput in the platform overall
* **Low latency**. Latency could be minimised by choosing a notary physically closer the transacting parties
A transaction should only be signed by a notary if all of its input states point to it.
In cases where a transaction involves states controlled by multiple notaries, the states first have to be repointed to the same notary.
This is achieved by using a special type of transaction that doesn't modify anything but the notary pointer of the state.
Ensuring that all input states point to the same notary is the responsibility of each involved party
(it is another condition for an output state of the transaction to be **valid**)
Changing notaries
~~~~~~~~~~~~~~~~~
To change the notary for an input state, use the ``NotaryChangeProtocol``. For example:
.. sourcecode:: kotlin
@Suspendable
fun changeNotary(originalState: StateAndRef<ContractState>,
newNotary: Party): StateAndRef<ContractState> {
val protocol = NotaryChangeProtocol.Instigator(originalState, newNotary)
return subProtocol(protocol)
}
The protocol will:
1. Construct a transaction with the old state as the input and the new state as the output
2. Obtain signatures from all *participants* (a participant is any party that is able to consume this state in a valid transaction, as defined by the state itself)
3. Obtain the *old* notary signature
4. Record and distribute the final transaction to the participants so that everyone possesses the new state
.. note:: Eventually this will be handled automatically on demand.
Validation
----------
One of the design decisions for a notary is whether or not to **validate** a transaction before committing its input states.
If a transaction is not checked for validity, it opens the platform to "denial of state" attacks, where anyone can build an invalid transaction consuming someone else's states and submit it to the notary to get the states "blocked".
However, validation of a transaction requires the notary to be able to see the full contents of the transaction in question and its dependencies.
This is an obvious privacy leak.
Our platform is flexible and we currently support both validating and non-validating notary implementations -- a party can select which one to use based on its own privacy requirements.
.. note:: In the non-validating model the "denial of state" attack is partially alleviated by requiring the calling
party to authenticate and storing its identity for the request. The conflict information returned by the notary
specifies the consuming transaction ID along with the identity of the party that had requested the commit. If the
conflicting transaction is valid, the current one gets aborted; if not – a dispute can be raised and the input states
of the conflicting invalid transaction are "un-committed" (to be covered by legal process).
.. note:: At present all notaries can see the entire contents of a transaction, but we have a separate piece of work to
replace the parts of the transaction it does not require knowing about with hashes (only input references, timestamp
information, overall transaction ID and the necessary digests of the rest of the transaction to prove that the
referenced inputs/timestamps really do form part of the stated transaction ID should be visible).
Timestamping
------------
In this model the notary also acts as a *timestamping authority*, verifying the transaction timestamp command.
For a timestamp to be meaningful, its implications must be binding on the party requesting it.
A party can obtain a timestamp signature in order to prove that some event happened before/on/or after a particular point in time.
However, if the party is not also compelled to commit to the associated transaction, it has a choice of whether or not to reveal this fact until some point in the future.
As a result, we need to ensure that the notary either has to also sign the transaction within some time tolerance,
or perform timestamping *and* notarisation at the same time, which is the chosen behaviour for this model.
There will never be exact clock synchronisation between the party creating the transaction and the notary.
This is not only due to physics, network latencies etc but because between inserting the command and getting the
notary to sign there may be many other steps, like sending the transaction to other parties involved in the trade
as well, or even requesting human signoff. Thus the time observed by the notary may be quite different to the
time observed in step 1.
For this reason, times in transactions are specified as time *windows*, not absolute times. Time windows can be
open-ended, i.e. specify only one of "before" and "after" or they can be fully bounded. If a time window needs to
be converted to an absolute time for e.g. display purposes, there is a utility method on ``Timestamp`` to
calculate the mid point - but in a distributed system there can never be "true time", only an approximation of it.
In this way we express that the *true value* of the fact "the current time" is actually unknowable. Even when both before and
after times are included, the transaction could have occurred at any point between those two timestamps. Here
"occurrence" could mean the execution date, the value date, the trade date etc ... the notary doesn't care what precise
meaning the timestamp has to the contract.
By creating a range that can be either closed or open at one end, we allow all of the following facts to be modelled:
* This transaction occurred at some point after the given time (e.g. after a maturity event)
* This transaction occurred at any time before the given time (e.g. before a bankruptcy event)
* This transaction occurred at some point roughly around the given time (e.g. on a specific day)
.. note:: It is assumed that the time feed for a notary is GPS/NaviStar time as defined by the atomic
clocks at the US Naval Observatory. This time feed is extremely accurate and available globally for free.
Running a notary service
------------------------
At present we have two basic implementations that store committed input states in memory:
- ``SimpleNotaryService`` -- commits the provided transaction without any validation
- ``ValidatingNotaryService`` -- retrieves and validates the whole transaction history (including the given transaction) before committing
Obtaining a signature
---------------------
Once a transaction is built and ready to be finalised, normally you would call ``FinalityProtocol`` passing in a
``SignedTransaction`` (including signatures from the participants) and a list of participants to notify. This requests a
notary signature if needed, and then sends a copy of the notarised transaction to all participants for them to store.
``FinalityProtocol`` delegates to ``NotaryProtocol.Client`` followed by ``BroadcastTransactionProtocol`` to do the
actual work of notarising and broadcasting the transaction. For example:
.. sourcecode:: kotlin
fun finaliseTransaction(serviceHub: ServiceHubInternal, ptx: TransactionBuilder, participants: Set<Party>)
: ListenableFuture<Unit> {
// We conclusively cannot have all the signatures, as the notary has not signed yet
val tx = ptx.toSignedTransaction(checkSufficientSignatures = false)
// The empty set would be the trigger events, which are not used here
val protocol = FinalityProtocol(tx, emptySet(), participants)
return serviceHub.startProtocol("protocol.finalisation", protocol)
}
To manually obtain a signature from a notary you can call ``NotaryProtocol.Client`` directly. The protocol will work out
which notary needs to be called based on the input states and the timestamp command. For example, the following snippet
can be used when writing a custom protocol:
.. sourcecode:: kotlin
fun getNotarySignature(wtx: WireTransaction): DigitalSignature.LegallyIdentifiable {
return subProtocol(NotaryProtocol.Client(wtx))
}
On conflict the ``NotaryProtocol`` with throw a ``NotaryException`` containing the conflict details:
.. sourcecode:: kotlin
/** Specifies the consuming transaction for the conflicting input state */
data class Conflict(val stateHistory: Map<StateRef, ConsumingTx>)
/**
* Specifies the transaction id, the position of the consumed state in the inputs, and
* the caller identity requesting the commit
*/
data class ConsumingTx(val id: SecureHash, val inputIndex: Int, val requestingParty: Party)
Conflict handling and resolution is currently the responsibility of the protocol author.

74
docs/build/html/_sources/contract-catalogue.txt vendored
View File

@ -1,74 +0,0 @@
Contract catalogue
==================
There are a number of contracts supplied with Corda, which cover both core functionality (such as cash on ledger) and
provide examples of how to model complex contracts (such as interest rate swaps). There is also a ``Dummy`` contract.
However it does not provide any meaningful functionality, and is intended purely for testing purposes.
Cash
----
The ``Cash`` contract's state objects represent an amount of some issued currency, owned by some party. Any currency
can be issued by any party, and it is up to the recipient to determine whether they trust the issuer. Generally nodes
are expected to have criteria (such as a whitelist) that issuers must fulfil for cash they issue to be accepted.
Cash state objects implement the ``FungibleAsset`` interface, and can be used by the commercial paper and obligation
contracts as part of settlement of an outstanding debt. The contracts' verification functions require that cash state
objects of the correct value are received by the beneficiary as part of the settlement transaction.
The cash contract supports issuing, moving and exiting (destroying) states. Note, however, that issuance cannot be part
of the same transaction as other cash commands, in order to minimise complexity in balance verification.
Cash shares a common superclass, ``OnChainAsset``, with the Commodity contract. This implements common behaviour of
assets which can be issued, moved and exited on chain, with the subclasses handling asset-specific data types and
behaviour.
Commodity
---------
The ``Commodity`` contract is an early stage example of a non-currency contract whose states implement the ``FungibleAsset``
interface. This is used as a proof of concept for non-cash obligations.
Commercial Paper
----------------
``CommercialPaper`` is a very simple obligation to pay an amount of cash at some future point in time (the maturity
date), and exists primarily as a simplified contract for use in tutorials. Commercial paper supports issuing, moving
and redeeming (settling) states. Unlike the full obligation contract it does not support locking the state so it cannot
be settled if the obligor defaults on payment, or netting of state objects. All commands are exclusive of the other
commercial paper commands. Use the ``Obligation`` contract for more advanced functionality.
Interest Rate Swap
------------------
The Interest Rate Swap (IRS) contract is a bilateral contract to implement a vanilla fixed / floating same currency
interest rate swap. In general, an IRS allows two counterparties to modify their exposure from changes in the underlying
interest rate. They are often used as a hedging instrument, convert a fixed rate loan to a floating rate loan, vice
versa etc.
See ":doc:`contract-irs`" for full details on the IRS contract.
Obligation
----------
The obligation contract's state objects represent an obligation to provide some asset, which would generally be a
cash state object, but can be any contract state object fulfilling the ``FungibleAsset`` interface, including other
obligations. The obligation contract uses objects referred to as ``Terms`` to group commands and state objects together.
Terms are a subset of an obligation state object, including details of what should be paid, when, and to whom.
Obligation state objects can be issued, moved and exited as with any fungible asset. The contract also supports state
object netting and lifecycle changes (marking the obligation that a state object represents as having defaulted, or
reverting it to the normal state after marking as having defaulted). The ``Net`` command cannot be included with any
other obligation commands in the same transaction, as it applies to state objects with different beneficiaries, and
as such applies across multiple terms.
All other obligation contract commands specify obligation terms (what is to be delivered, by whom and by when)
which are used as a grouping key for input/output states and commands. Issuance and lifecyle commands are mutually
exclusive of other commands (move/exit) which apply to the same obligation terms, but multiple commands can be present
in a single transaction if they apply to different terms. For example, a contract can have two different ``Issue``
commands as long as they apply to different terms, but could not have an ``Issue`` and a ``Net``, or an ``Issue`` and
``Move`` that apply to the same terms.
Netting of obligations supports close-out netting (which can be triggered by either obligor or beneficiary, but is
limited to bilateral netting), and payment netting (which requires signatures from all involved parties, but supports
multilateral netting).

107
docs/build/html/_sources/contract-irs.txt vendored
View File

@ -1,107 +0,0 @@
Interest Rate Swaps
===================
The Interest Rate Swap (IRS) Contract (source: IRS.kt, IRSUtils.kt, IRSExport.kt) is a bilateral contract to implement a
vanilla fixed / floating same currency IRS.
In general, an IRS allows two counterparties to modify their exposure from changes in the underlying interest rate. They
are often used as a hedging instrument, convert a fixed rate loan to a floating rate loan, vice versa etc.
The IRS contract exists over a period of time (normally measurable in years). It starts on its value date
(although this is not the agreement date), and is considered to be no longer active after its maturity date. During that
time, there is an exchange of cash flows which are calculated by looking at the economics of each leg. These are based
upon an amount that is not actually exchanged but notionally used for the calculation (and is hence known as the notional
amount), and a rate that is either fixed at the creation of the swap (for the fixed leg), or based upon a reference rate
that is retrieved during the swap (for the floating leg). An example reference rate might be something such as 'LIBOR 3M'.
The fixed leg has its rate computed and set in advance, whereas the floating leg has a fixing process whereas the rate
for the next period is fixed with relation to a reference rate. Then, a calculation is performed such that the interest
due over that period multiplied by the notional is paid (normally at the end of the period). If these two legs have the
same payment date, then these flows can be offset against each other (in reality there are normally a number of these
swaps that are live between two counterparties, so that further netting is performed at counterparty level).
The fixed leg and floating leg do not have to have the same period frequency. In fact, conventional swaps do not have
the same period.
Currently, there is no notion of an actual payment or obligation being performed in the contract code we have written;
it merely represents that the payment needs to be made.
Consider the diagram below; the x-axis represents time and the y-axis the size of the leg payments (not to scale), from
the view of the floating leg receiver / fixed leg payer. The enumerated documents represent the versions of the IRS as
it progresses (note that, the first version exists before the value date), the dots on the "y=0" represent an interest
rate value becoming available and then the curved arrow indicates to which period the fixing applies.
.. image:: contract-irs.png
Two days (by convention, although this can be modified), before the value date (ie the start of the swap) in the red
period the reference rate is observed from an oracle and fixed in the instance at 1.1%. At the end of the accrual period,
there is an obligation from the floating leg payer of 1.1% * notional amount * days in the accrual period / 360.
(Also note that the result of "days in the accrual period / 360" is also known as the day count factor, although other
conventions are allowed and will be supported). This amount is then paid at a determined time at the end of the accrual period.
Again, two working days before the blue period, the rate is fixed (this time at 0.5% - however in reality, the rates
would not be so significantly different), and the same calculation is performed to evaluate the payment that will be due
at the end of this period.
This process continues until the swap reaches maturity and the final payments are calculated.
Creating an instance and lifecycle
----------------------------------
There are two valid operations on an IRS. The first is to generate via the ``Agree`` command (signed by both parties)
and the second (and repeated operation) is ``Fix`` to apply a rate fixing.
To see the minimum dataset required for the creation of an IRS, refer to ``IRSTests.kt`` which has two examples in the
function ``IRSTests.createDummyIRS()``. Implicitly, when the agree function is called, the floating leg and fixed
leg payment schedules are created (more details below) and can be queried.
Once an IRS hase been agreed, then the the only valid operation is to apply a fixing on one of the entries in the
``Calculation.floatingLegPaymentSchedule`` map. Fixes do not have to be applied in order (although it does make most
sense to do them so).
Examples of applying fixings to rates can been seen in ``IRSTests.generateIRSandFixSome()`` which loops through the next
fixing date of an IRS that is created with the above example function and then applies a fixing of 0.052% to each floating
event.
Currently, there are no matured, termination or dispute operations.
Technical Details
-----------------
The contract itself comprises of 4 data state classes, ``FixedLeg``, ``FloatingLeg``, ``Common`` and ``Calculation``.
Recall that the platform model is strictly immutable. To further that, between states, the only class that is modified
is the ``Calculation`` class.
The ``Common`` data class contains all data that is general to the entire swap, e.g. data like trade identifier,
valuation date, etc.
The Fixed and Floating leg classes derive from a common base class ``CommonLeg``. This is due to the simple reason that
they share a lot of common fields.
The ``CommonLeg`` class contains the notional amount, a payment frequency, the effective date (as well as an adjustment
option), a termination date (and optional adjustment), the day count basis for day factor calculation, the payment delay
and calendar for the payment as well as the accrual adjustment options.
The ``FixedLeg`` contains all the details for the ``CommonLeg`` as well as payer details, the rate the leg is fixed at
and the date roll convention (ie what to do if the calculated date lands on a bank holiday or weekend).
The ``FloatingLeg`` contains all the details for the CommonLeg and payer details, roll convention, the fixing roll
convention, which day of the month the reset is calculated, the frequency period of the fixing, the fixing calendar and
the details for the reference index (source and tenor).
The ``Calculation`` class contains an expression (that can be evaluated via the ledger using variables provided and also
any members of the contract) and two schedules - a ``floatingLegPaymentSchedule`` and a ``fixedLegPaymentSchedule``.
The fixed leg schedule is obviously pre-ordained, however, during the lifetime of the swap, the floating leg schedule is
regenerated upon each fixing being presented.
For this reason, there are two helper functions on the floating leg. ``Calculation.getFixing`` returns the date of the
earliest unset fixing, and ``Calculation.applyFixing`` returns a new Calculation object with the revised fixing in place.
Note that both schedules are, for consistency, indexed by payment dates, but the fixing is (due to the convention of
taking place two days previously) not going to be on that date.
.. note:: Payment events in the ``floatingLegPaymentSchedule`` that start as a ``FloatingRatePaymentEvent`` (which is a
representation of a payment for a rate that has not yet been finalised) are replaced in their entirety with an
equivalent ``FixedRatePaymentEvent`` (which is the same type that is on the ``FixedLeg``).

116
docs/build/html/_sources/corda-configuration-files.txt vendored
View File

@ -1,116 +0,0 @@
The Corda Configuration File
============================
Configuration File Location
---------------------------
The Corda all-in-one ``corda.jar`` file is generated by the ``gradle buildCordaJAR`` task and defaults to reading configuration from a ``node.conf`` file in the present working directory.
This behaviour can be overidden using the ``--config-file`` command line option to target configuration files with different names, or different file location (relative paths are relative to the current working directory).
Also, the ``--base-directory`` command line option alters the Corda node workspace location and if specified a ``node.conf`` configuration file is then expected in the root of the workspace.
The configuration file templates used for the ``gradle installTemplateNodes`` task are to be found in the ``/config/dev`` folder. Also note that there is a basic set of defaults loaded from
the built in resource file ``/node/src/main/resources/reference.conf`` of the ``:node`` gradle module. All properties in this can be overidden in the file configuration
and for rarely changed properties this defaulting allows the property to be excluded from the configuration file.
Configuration File Format
-------------------------
Corda uses the Typesafe configuration library to parse the configuration see the `typesafe config on Github <https://github.com/typesafehub/config/>`_ the format of the configuration files can be simple JSON, but for the more powerful substitution features
uses HOCON format see `HOCON documents <https://github.com/typesafehub/config/blob/master/HOCON.md>`_
Configuration File Examples
---------------------------
General node configuration file for hosting the IRSDemo services.
.. code-block:: text
basedir : "./nodea"
myLegalName : "Bank A"
nearestCity : "London"
keyStorePassword : "cordacadevpass"
trustStorePassword : "trustpass"
dataSourceProperties : {
dataSourceClassName : org.h2.jdbcx.JdbcDataSource
"dataSource.url" : "jdbc:h2:"${basedir}"/persistence"
"dataSource.user" : sa
"dataSource.password" : ""
}
artemisAddress : "localhost:31337"
webAddress : "localhost:31339"
extraAdvertisedServiceIds: "corda.interest_rates"
networkMapAddress : "localhost:12345"
useHTTPS : false
NetworkMapService plus Simple Notary configuration file.
.. code-block:: text
basedir : "./nameserver"
myLegalName : "Notary Service"
nearestCity : "London"
keyStorePassword : "cordacadevpass"
trustStorePassword : "trustpass"
artemisAddress : "localhost:12345"
webAddress : "localhost:12346"
extraAdvertisedServiceIds: ""
useHTTPS : false
Configuration File Fields
-------------------------
:basedir: This specifies the node workspace folder either as an absolute path, or relative to the current working directory. It can be overidden by the ``--base-directory`` command line option, in which case the the value in the file is ignored and a ``node.conf`` file is expected in that workspace directory as the configuration source.
:myLegalName: The legal identity of the node acts as a human readable alias to the node's public key and several demos use this to lookup the NodeInfo.
:nearestCity: The location of the node as used to locate coordinates on the world map when running the network simulator demo. See :doc:`network-simulator`.
:keyStorePassword:
The password to unlock the KeyStore file (``<workspace>/certificates/sslkeystore.jks``) containing the node certificate and private key.
note:: This is the non-secret value for the development certificates automatically generated during the first node run. Longer term these keys will be managed in secure hardware devices.
:trustStorePassword:
The password to unlock the Trust store file (``<workspace>/certificates/truststore.jks``) containing the R3 Corda root certificate. This is the non-secret value for the development certificates automatically generated during the first node run.
.. note:: Longer term these keys will be managed in secure hardware devices.
:dataSourceProperties:
This section is used to configure the jdbc connection and database driver used for the nodes persistence. Currently the defaults in ``/node/src/main/resources/reference.conf`` are as shown in the first example. This is currently the only configuration that has been tested, although in the future full support for other storage layers will be validated.
:artemisAddress:
The host and port on which the node is available for protocol operations over ArtemisMQ.
.. note:: In practice the ArtemisMQ messaging services bind to all local addresses on the specified port. However, note that the host is the included as the advertised entry in the NetworkMapService. As a result the value listed here must be externally accessible when running nodes across a cluster of machines.
:messagingServerAddress:
The address of the ArtemisMQ broker instance. If not provided the node will run one locally.
:webAddress:
The host and port on which the node is available for web operations.
.. note:: If HTTPS is enabled then the browser security checks will require that the accessing url host name is one of either the machine name, fully qualified machine name, or server IP address to line up with the Subject Alternative Names contained within the development certificates. This is addition to requiring the ``/config/dev/corda_dev_ca.cer`` root certificate be installed as a Trusted CA.
:extraAdvertisedServiceIds: A list of ServiceType id strings to be advertised to the NetworkMapService and thus be available when other nodes query the NetworkMapCache for supporting nodes. This can also include plugin services loaded from .jar files in the plugins folder.
:networkMapAddress: If `null`, or missing the node is declaring itself as the NetworkMapService host. Otherwise the configuration value is the remote HostAndPort string for the ArtemisMQ service on the hosting node.
:useHTTPS: If false the node's web server will be plain HTTP. If true the node will use the same certificate and private key from the ``<workspace>/certificates/sslkeystore.jks`` file as the ArtemisMQ port for HTTPS. If HTTPS is enabled then unencrypted HTTP traffic to the node's **webAddress** port is not supported.
RPC Users File
==============
Corda also uses the ``rpc-users.properties`` file, found in the base directory, to control access to the RPC subsystem.
This is a Java properties file (details can be found in the `Javadocs <https://docs.oracle.com/javase/8/docs/api/java/util/Properties.html#load-java.io.Reader->`_)
which specifies a list of users with their password and list of permissions they're enabled for.
.. code-block:: text
:caption: Sample
admin=notsecure,ADMIN
user1=letmein,CASH,PAPER
In this example ``user1`` has password ``letmein`` and has permissions for ``CASH`` and ``PAPER``. The permissions are
free-form strings which can be used by the RPC methods to control access.
If ``rpc-users.properties`` is empty or doesn't exist then the RPC subsystem is effectively locked down.

246
docs/build/html/_sources/creating-a-cordapp.txt vendored
View File

@ -1,246 +0,0 @@
Creating a Cordapp
==================
A Cordapp is an application that runs on the Corda platform using the platform APIs and plugin system. They are self
contained in separate JARs from the node server JAR that are created and distributed.
App Plugins
-----------
.. note:: Currently apps are only supported for JVM languages.
To create an app plugin you must you must extend from `CordaPluginRegistry`_. The JavaDoc contains
specific details of the implementation, but you can extend the server in the following ways:
1. Required protocols: Specify which protocols will be whitelisted for use in your web APIs.
2. Service plugins: Register your services (see below).
3. Web APIs: You may register your own endpoints under /api/ of the built-in web server.
4. Static web endpoints: You may register your own static serving directories for serving web content.
Services
--------
Services are classes which are constructed after the node has started. It is provided a `ServiceHubInternal`_ which
allows a richer API than the `ServiceHub`_ exposed to contracts. It enables adding protocols, registering
message handlers and more. The service does not run in a separate thread, so the only entry point to the service is during
construction, where message handlers should be registered and threads started.
Starting Nodes
--------------
To use an app you must also have a node server. To create a node server run the gradle installTemplateNodes task.
This will output the node JAR to ``build/libs/corda.jar`` and several sample/standard
node setups to ``build/nodes``. For now you can use the ``build/nodes/nodea`` configuration as a template.
Each node server by default must have a ``node.conf`` file in the current working directory. After first
execution of the node server there will be many other configuration and persistence files created in a node workspace directory. This is specified as the basedir property of the node.conf file, or else can be overidden using ``--base-directory=<workspace>``.
.. note:: Outside of development environments do not store your node directories in the build folder.
.. warning:: Also note that the bootstrapping process of the ``corda.jar`` unpacks the Corda dependencies into a temporary folder. It is therefore suggested that the CAPSULE_CACHE_DIR environment variable be set before starting the process to control this location.
Installing Apps
---------------
Once you have created your app JAR you can install it to a node by adding it to ``<node_dir>/plugins/``. In this
case the ``node_dir`` is the location where your node server's JAR and configuration file is.
.. note:: If the directory does not exist you can create it manually.
Starting your Node
------------------
Now you have a node server with your app installed, you can run it by navigating to ``<node_dir>`` and running
java -jar corda.jar
The plugin should automatically be registered and the configuration file used.
.. warning:: If your working directory is not ``<node_dir>`` your plugins and configuration will not be used.
The configuration file and workspace paths can be overidden on the command line e.g.
``java -jar corda.jar --config-file=test.conf --base-directory=/opt/r3corda/nodes/test``.
Otherwise the workspace folder for the node is created based upon the ``basedir`` property in the ``node.conf`` file and if this is relative it is applied relative to the current working path.
Debugging your Node
-------------------
To enable remote debugging of the corda process use a command line such as:
``java -Dcapsule.jvm.args="-agentlib:jdwp=transport=dt_socket,server=y,suspend=y,address=5005" -jar corda.jar``
This command line will start the debugger on port 5005 and pause the process awaiting debugger attachment.
Viewing persisted state of your Node
------------------------------------
To make examining the persisted contract states of your node or the internal node database tables easier, and providing you are
using the default database configuration used for demos, you should be able to connect to the internal node database over
a JDBC connection at the URL that is output to the logs at node start up. That URL will be of the form ``jdbc:h2:tcp://<host>:<port>/node``.
The user name and password for the login are as per the node data source configuration.
The name and column layout of the internal node tables is in a state of flux and should not be relied upon to remain static
at the present time, and should certainly be treated as read-only.
.. _CordaPluginRegistry: api/com.r3corda.core.node/-corda-plugin-registry/index.html
.. _ServiceHubInternal: api/com.r3corda.node.services.api/-service-hub-internal/index.html
.. _ServiceHub: api/com.r3corda.node.services.api/-service-hub/index.html
Building Against Corda
----------------------
.. warning:: This feature is subject to rapid change
Corda now supports publishing to Maven local to build against it. To publish to Maven local run the following in the
root directory of Corda
.. code-block:: shell
./gradlew install
This will publish corda-$version.jar, finance-$version.jar, core-$version.jar and node-$version.jar to the
group com.r3corda. You can now depend on these as you normally would a Maven dependency.
Gradle Plugins for Cordapps
===========================
There are several Gradle plugins that reduce your build.gradle boilerplate and make development of Cordapps easier.
The available plugins are in the gradle-plugins directory of the Corda repository.
Building Gradle Plugins
-----------------------
To install to your local Maven repository the plugins that Cordapp gradle files require, run the following from the
root of the Corda project:
.. code-block:: text
./gradlew install
The plugins will now be installed to your local Maven repository in ~/.m2 on Unix and %HOMEPATH%\.m2 on Windows.
Using Gradle Plugins
--------------------
To use the plugins, if you are not already using the Cordapp template project, you must modify your build.gradle. Add
the following segments to the relevant part of your build.gradle.
Template build.gradle
---------------------
To build against Corda and the plugins that cordapps use, update your build.gradle to contain the following:
.. code-block:: groovy
buildscript {
ext.corda_version = '<enter the corda version you build against here>'
... your buildscript ...
repositories {
... other repositories ...
mavenLocal()
}
dependencies {
... your dependencies ...
classpath "com.r3corda.plugins:cordformation:$corda_version"
classpath "com.r3corda.plugins:quasar-utils:$corda_version"
classpath "com.r3corda.plugins:publish-utils:$corda_version"
}
}
apply plugin: 'com.r3corda.plugins.cordformation'
apply plugin: 'com.r3corda.plugins.quasar-utils'
apply plugin: 'com.r3corda.plugins.publish-utils'
repositories {
mavenLocal()
... other repositories here ...
}
dependencies {
compile "com.r3corda:core:$corda_version"
compile "com.r3corda:finance:$corda_version"
compile "com.r3corda:node:$corda_version"
compile "com.r3corda:corda:$corda_version"
... other dependencies here ...
}
... your tasks ...
// Sets the classes for Quasar to scan. Loaded by the the quasar-utils plugin.
quasarScan.dependsOn('classes', ... your dependent subprojects...)
// Standard way to publish Cordapps to maven local with the maven-publish and publish-utils plugin.
publishing {
publications {
jarAndSources(MavenPublication) {
from components.java
// The two lines below are the tasks added by this plugin.
artifact sourceJar
artifact javadocJar
}
}
}
Cordformation
-------------
Cordformation is the local node deployment system for Cordapps, the nodes generated are intended to be used for
experimenting, debugging, and testing node configurations and setups but not intended for production or testnet
deployment.
To use this gradle plugin you must add a new task that is of the type ``com.r3corda.plugins.Cordform`` to your
build.gradle and then configure the nodes you wish to deploy with the Node and nodes configuration DSL.
This DSL is specified in the `JavaDoc <api/index.html>`_. An example of this is in the template-cordapp and below
is a three node example;
.. code-block:: text
task deployNodes(type: com.r3corda.plugins.Cordform, dependsOn: ['build']) {
directory "./build/nodes" // The output directory
networkMap "Controller" // The artemis address of the node named here will be used as the networkMapAddress on all other nodes.
node {
name "Controller"
dirName "controller"
nearestCity "London"
advertisedServices = [ "corda.notary.validating" ]
artemisPort 12345
webPort 12346
cordapps []
}
node {
name "NodeA"
dirName "nodea"
nearestCity "London"
advertisedServices = []
artemisPort 31337
webPort 31339
cordapps []
}
node {
name "NodeB"
dirName "nodeb"
nearestCity "New York"
advertisedServices = []
artemisPort 31338
webPort 31340
cordapps []
}
}
You can create more configurations with new tasks that extend Cordform.
New nodes can be added by simply adding another node block and giving it a different name, directory and ports. When you
run this task it will install the nodes to the directory specified and a script will be generated (for UNIX users only
at present) to run the nodes with one command.
Other cordapps can also be specified if they are already specified as classpath or compile dependencies in your
``build.gradle``.

278
docs/build/html/_sources/data-model.txt vendored
View File

@ -1,278 +0,0 @@
Data model
==========
This article covers the data model: how *states*, *transactions* and *code contracts* interact with each other and
how they are represented in software. It doesn't attempt to give detailed design rationales or information on future
design elements: please refer to the R3 wiki for background information.
Overview
--------
We begin with the idea of a global ledger. In our model although the ledger is shared, it is not always the case that
transactions and ledger entries are globally visible. In cases where a set of transactions stays within a small subgroup of
users it should be possible to keep the relevant data purely within that group.
To ensure consistency in a global, shared system where not all data may be visible to all participants, we rely
heavily on secure hashes like SHA-256 to identify things. The ledger is defined as a set of immutable **states**, which
are created and destroyed by digitally signed **transactions**. Each transaction points to a set of states that it will
consume/destroy, these are called **inputs**, and contains a set of new states that it will create, these are called
**outputs**.
States contain arbitrary data, but they always contain at minimum a hash of the bytecode of a
**contract code** file, which is a program expressed in JVM byte code that runs sandboxed inside a Java virtual machine.
Contract code (or just "contracts" in the rest of this document) are globally shared pieces of business logic.
.. note:: In the current code dynamic loading of contracts is not implemented, so states currently point at
statically created object instances. This will change in the near future.
Contracts define a **verify function**, which is a pure function given the entire transaction as input. To be considered
valid, the transaction must be **accepted** by the verify function of every contract pointed to by the input and output
states.
Beyond inputs and outputs, transactions may also contain **commands**, small data packets that
the platform does not interpret itself but which can parameterise execution of the contracts. They can be thought of as
arguments to the verify function. Each command has a list of **public keys** associated with it. The platform ensures
that the transaction is signed by every key listed in the commands before the contracts start to execute. Thus, a verify
function can trust that all listed keys have signed the transaction but is responsible for verifying that any keys required
for the transaction to be valid from the verify function's perspective are included in the list. Public keys
may be random/identityless for privacy, or linked to a well known legal identity, for example via a
*public key infrastructure* (PKI).
.. note:: Linkage of keys with identities via a PKI is only partially implemented in the current code.
Commands are always embedded inside a transaction. Sometimes, there's a larger piece of data that can be reused across
many different transactions. For this use case, we have **attachments**. Every transaction can refer to zero or more
attachments by hash. Attachments are always ZIP/JAR files, which may contain arbitrary content. These files are
then exposed on the classpath and so can be opened by contract code in the same manner as any JAR resources
would be loaded.
.. note:: Attachments must be opened explicitly in the current code.
Note that there is nothing that explicitly binds together specific inputs, outputs, commands or attachments. Instead
it's up to the contract code to interpret the pieces inside the transaction and ensure they fit together correctly. This
is done to maximise flexibility for the contract developer.
Transactions may sometimes need to provide a contract with data from the outside world. Examples may include stock
prices, facts about events or the statuses of legal entities (e.g. bankruptcy), and so on. The providers of such
facts are called **oracles** and they provide facts to the ledger by signing transactions that contain commands they
recognise, or by creating signed attachments. The commands contain the fact and the signature shows agreement to that fact.
Time is also modelled as a fact, with the signature of a special kind of service called a **notary**. A notary is
a (very likely) decentralised service which fulfils the role that miners play in other blockchain systems:
notaries ensure only one transaction can consume any given output. Additionally they may verify a **timestamping
command** placed inside the transaction, which specifies a time window in which the transaction is considered
valid for notarisation. The time window can be open ended (i.e. with a start but no end or vice versa). In this
way transactions can be linked to the notary's clock.
It is possible for a single Corda network to have multiple competing notaries. Each state points to the notary that
controls it. Whilst a single transaction may only consume states if they are all controlled by the same notary,
a special type of transaction is provided that moves a state (or set of states) from one notary to another.
.. note:: Currently the platform code will not re-assign states to a single notary as needed for you, in case of
a mismatch. This is a future planned feature.
As the same terminology often crops up in different distributed ledger designs, let's compare this to other
systems you may be familiar with. You can find more detailed design rationales for why the platform
differs from existing systems in `the R3 wiki <https://r3-cev.atlassian.net/wiki/display/AWG/Platform+Stream%3A+Corda>`_,
but to summarise, the driving factors are:
* Improved contract flexibility vs Bitcoin
* Improved scalability vs Ethereum, as well as ability to keep parts of the transaction graph private (yet still uniquely addressable)
* No reliance on proof of work
* Re-use of existing sandboxing virtual machines
* Use of type safe GCd implementation languages
* Simplified auditing
Comparison with Bitcoin
-----------------------
Similarities:
* The basic notion of immutable states that are consumed and created by transactions is the same.
* The notion of transactions having multiple inputs and outputs is the same. Bitcoin sometimes refers to the ledger
as the unspent transaction output set (UTXO set) as a result.
* Like in Bitcoin, a contract is pure function. Contracts do not have storage or the ability to interact with anything.
Given the same transaction, a contract's accept function always yields exactly the same result.
* Bitcoin output scripts are parameterised by the input scripts in the spending transaction. This is somewhat similar
to our notion of a *command*.
* Bitcoin has a global distributed notary service; that's the famous block chain. However, there is only one. Whilst
there is a notion of a "side chain", this isn't integrated with the core Bitcoin data model and thus adds large
amounts of additional complexity meaning in practice side chains are not used.
* Bitcoin transactions, like ours, refer to the states they consume by using a (txhash, index) pair. The Bitcoin
protocol calls these "outpoints". In our code they are known as ``StateRefs`` but the concept is identical.
* Bitcoin transactions have an associated timestamp (the time at which they are mined).
Differences:
* A Bitcoin transaction has a single, rigid data format. A "state" in Bitcoin is always a (quantity of bitcoin, script)
pair and cannot hold any other data. Some people have been known to try and hack around this limitation by embedding
data in semi-standardised places in the contract code so the data can be extracted through pattern matching, but this
is a poor approach. Our states can include arbitrary typed data.
* A Bitcoin transaction's acceptance is controlled only by the contract code in the consumed input states. In practice
this has proved limiting. Our transactions invoke not only input contracts but also the contracts of the outputs.
* 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. 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
(this is often called "wallet code" in Bitcoin).
Comparison with Ethereum
------------------------
Similarities:
* Like Ethereum, code runs inside a relatively powerful virtual machine and can contain complex logic. Non-assembly
based programming languages can be used for contract programming.
* They are both intended for the modelling of many different kinds of financial contract.
Differences:
* The term "contract" in Ethereum refers to an *instantiation* of a program that is replicated and maintained by
every participating node. This instantiation is very much like an object in an OO program: it can receive and send
messages, update local storage and so on. In contrast, we use the term "contract" to refer to a set of functions, only
one of which is a part of keeping the system synchronised (the verify function). That function is pure and
stateless i.e. it may not interact with any other part of the system whilst executing.
* There is no notion of an "account", as there is in Ethereum.
* As contracts don't have any kind of mutable storage, there is no notion of a "message" as in Ethereum.
* Ethereum claims to be a platform not only for financial logic, but literally any kind of application at all. Our
platform considers non-financial applications to be out of scope.
Rationale for and tradeoffs in adopting a UTXO-style model
----------------------------------------------------------
As discussed above, Corda uses the so-called "UTXO set" model (unspent transaction output). In this model, the database
does not track accounts or balances. Instead all database entries are immutable. An entry is either spent or not spent
but it cannot be changed. In Bitcoin, spentness is implemented simply as deletion – the inputs of an accepted transaction
are deleted and the outputs created.
This approach has some advantages and some disadvantages, which is why some platforms like Ethereum have tried
(or are trying) to abstract this choice away and support a more traditional account-like model. We have explicitly
chosen *not* to do this and our decision to adopt a UTXO-style model is a deliberate one. In the section below,
the rationale for this decision and its pros and cons of this choice are outlined.
Rationale
---------
Corda, in common with other blockchain-like platforms, is designed to bring parties to shared sets of data into
consensus as to the existence, content and allowable evolutions of those data sets. However, Corda is designed with the
explicit aim of avoiding, to the extent possible, the scalability and privacy implications that arise from those platforms'
decisions to adopt a global broadcast model.
Whilst the privacy implications of a global consensus model are easy to understand, the scalability implications are
perhaps more subtle, yet serious. In a consensus system, it is critical that all processors of a transaction reach
precisely the same conclusion as to its effects. In situations where two transactions may act on the same data set,
it means that the two transactions must be processed in the same *order* by all nodes. If this were not the case then it
would be possible to devise situations where nodes processed transactions in different orders and reached different
conclusions as to the state of the system. It is for this reason that systems like Ethereum effectively run
single-threaded, meaning the speed of the system is limited by the single-threaded performance of the slowest
machine on the network.
In Corda, we assume the data being processed represents financial agreements between identifiable parties and that these
institutions will adopt the system only if a significant number of such agreements can be managed by the platform.
As such, the system has to be able to support parallelisation of execution to the greatest extent possible,
whilst ensuring correct transaction ordering when two transactions seek to act on the same piece of shared state.
To achieve this, we must minimise the number of parties who need to receive and process copies of any given
transaction and we must minimise the extent to which two transactions seek to mutate (or supersede) any given piece
of shared state.
A key design decision, therefore, is what should be the most atomic unit of shared data in the system. This decision
also has profound privacy implications: the more coarsely defined the shared data units, the larger the set of
actors who will likely have a stake in its accuracy and who must process and observe any update to it.
This becomes most obvious when we consider two models for representing cash balances and payments.
A simple account model for cash would define a data structure that maintained a balance at a particular bank for each
"account holder". Every holder of a balance would need a copy of this structure and would thus need to process and
validate every payment transaction, learning about everybody else's payments and balances in the process.
All payments across that set of accounts would have to be single-threaded across the platform, limiting maximum
throughput.
A more sophisticated example might create a data structure per account holder.
But, even here, I would leak my account balance to anybody to whom I ever made
a payment and I could only ever make one payment at a time, for the same reasons above.
A UTXO model would define a data structure that represented an *instance* of a claim against the bank. An account
holder could hold *many* such instances, the aggregate of which would reveal their balance at that institution. However,
the account holder now only needs to reveal to their payee those instances consumed in making a payment to that payee.
This also means the payer could make several payments in parallel. A downside is that the model is harder to understand.
However, we consider the privacy and scalability advantages to overwhelm the modest additional cognitive load this places
on those attempting to learn the system.
In what follows, further advantages and disadvantages of this design decision are explored.
Pros
----
The UTXO model has these advantages:
* Immutable ledger entries gives the usual advantages that a more functional approach brings: it's easy to do analysis
on a static snapshot of the data and reason about the contents.
* Because there are no accounts, it's very easy to apply transactions in parallel even for high traffic legal entities
assuming sufficiently granular entries.
* Transaction ordering becomes trivial: it is impossible to mis-order transactions due to the reliance on hash functions
to identify previous states. There is no need for sequence numbers or other things that are hard to provide in a
fully distributed system.
* Conflict resolution boils down to the double spending problem, which places extremely minimal demands on consensus
algorithms (as the variable you're trying to reach consensus on is a set of booleans).
Cons
----
It also comes with some pretty serious complexities that in practice must be abstracted from developers:
* Representing numeric amounts using immutable entries is unnatural. For instance, if you receive $1000 and wish
to send someone $100, you have to consume the $1000 output and then create two more: a $100 for the recipient and
$900 back to yourself as change. The fact that this happens can leak private information to an observer.
* Because users do need to think in terms of balances and statements, you have to layer this on top of the
underlying ledger: you can't just read someone's balance out of the system. Hence, the "wallet" / position manager.
Experience from those who have developed wallets for Bitcoin and other systems is that they can be complex pieces of code,
although the bulk of wallets' complexity in public systems is handling the lack of finality (and key management).
* Whilst transactions can be applied in parallel, it is much harder to create them in parallel due to the need to
strictly enforce a total ordering.
With respect to parallel creation, if the user is single threaded this is fine, but in a more complex situation
where you might want to be preparing multiple transactions in flight this can prove a limitation – in
the worst case where you have a single output that represents all your value, this forces you to serialise
the creation of every transaction. If transactions can be created and signed very fast that's not a concern.
If there's only a single user, that's not a concern.
Both cases are typically true in the Bitcoin world, so users don't suffer from this much. In the context of a
complex business with a large pool of shared funds, in which creation of transactions may be very slow due to the
need to get different humans to approve a tx using a signing device, this could quickly lead to frustrating
conflicts where someone approves a transaction and then discovers that it has become a double spend and
they must sign again. In the absolute worst case you could get a form of human livelock.
The tricky part about solving these problems is that the simplest way to express a payment request
("send me $1000 to public key X") inherently results in you receiving a single output, which then can
prove insufficiently granular to be convenient. In the Bitcoin space Mike Hearn and Gavin Andresen designed "BIP 70"
to solve this: it's a simple binary format for requesting a payment and specifying exactly how you'd like to get paid,
including things like the shape of the transaction. It may seem that it's an over complex approach: could you not
just immediately respend the big output back to yourself in order to split it? And yes, you could, until you hit
scenarios like "the machine requesting the payment doesn't have the keys needed to spend it",
which turn out to be very common. So it's really more effective for a recipient to be able to say to the
sender, "here's the kind of transaction I want you to send me". The :doc:`protocol framework <protocol-state-machines>`
may provide a vehicle to make such negotiations simpler.
A further challenge is privacy. Whilst our goal of not sending transactions to nodes that don't "need to know"
helps, to verify a transaction you still need to verify all its dependencies and that can result in you receiving
lots of transactions that involve random third parties. The problems start when you have received lots of separate
payments and been careful not to make them linkable to your identity, but then you need to combine them all in a
single transaction to make a payment.
Mike Hearn wrote an article about this problem and techniques to minimise it in
`this article <https://medium.com/@octskyward/merge-avoidance-7f95a386692f>`_ from 2013. This article
coined the term "merge avoidance", which has never been implemented in the Bitcoin space,
although not due to lack of practicality.
A piece of future work for the wallet implementation will be to implement automated "grooming" of the wallet
to "reshape" outputs to useful/standardised sizes, for example, and to send outputs of complex transactions
back to their issuers for reissuance to "sever" long privacy-breaching chains.
Finally, it should be noted that some of the issues described here are not really "cons" of
the UTXO model; they're just fundamental. If you used many different anonymous accounts to preserve some privacy
and then needed to spend the contents of them all simultaneously, you'd hit the same problem, so it's not
something that can be trivially fixed with data model changes.

102
docs/build/html/_sources/event-scheduling.txt vendored
View File

@ -1,102 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Event scheduling
================
This article explains our approach to modelling time based events in code. It explains how a contract
state can expose an upcoming event and what action to take if the scheduled time for that event is reached.
Introduction
------------
Many financial instruments have time sensitive components to them. For example, an Interest Rate Swap has a schedule
for when:
* Interest rate fixings should take place for floating legs, so that the interest rate used as the basis for payments
can be agreed.
* Any payments between the parties are expected to take place.
* Any payments between the parties become overdue.
Each of these is dependent on the current state of the financial instrument. What payments and interest rate fixings
have already happened should already be recorded in the state, for example. This means that the *next* time sensitive
event is thus a property of the current contract state. By next, we mean earliest in chronological terms, that is still
due. If a contract state is consumed in the UTXO model, then what *was* the next event becomes irrelevant and obsolete
and the next time sensitive event is determined by any successor contract state.
Knowing when the next time sensitive event is due to occur is useful, but typically some *activity* is expected to take
place when this event occurs. We already have a model for business processes in the form of :doc:`protocols <protocol-state-machines>`,
so in the platform we have introduced the concept of *scheduled activities* that can invoke protocol state machines
at a scheduled time. A contract state can optionally described the next scheduled activity for itself. If it omits
to do so, then nothing will be scheduled.
How to implement scheduled events
---------------------------------
There are two main steps to implementing scheduled events:
* Have your ``ContractState`` implementation also implement ``SchedulableState``. This requires a method named
``nextScheduledActivity`` to be implemented which returns an optional ``ScheduledActivity`` instance.
``ScheduledActivity`` captures what ``ProtocolLogic`` instance each node will run, to perform the activity, and when it
will run is described by a ``java.time.Instant``. Once your state implements this interface and is tracked by the
wallet, it can expect to be queried for the next activity when committed to the wallet.
* If nothing suitable exists, implement a ``ProtocolLogic`` to be executed by each node as the activity itself.
The important thing to remember is that in the current implementation, each node that is party to the transaction
will execute the same ``ProtocolLogic``, so it needs to establish roles in the business process based on the contract
state and the node it is running on. Each side will follow different but complementary paths through the business logic.
.. note:: The scheduler's clock always operates in the UTC time zone for uniformity, so any time zone logic must be
performed by the contract, using ``ZonedDateTime``.
In the short term, until we have automatic protocol session set up, you will also likely need to install a network
handler to help with obtaining a unqiue and secure random session. An example is described below.
The production and consumption of ``ContractStates`` is observed by the scheduler and the activities associated with
any consumed states are unscheduled. Any newly produced states are then queried via the ``nextScheduledActivity``
method and if they do not return ``null`` then that activity is scheduled based on the content of the
``ScheduledActivity`` object returned. Be aware that this *only* happens if the wallet considers the state
"relevant", for instance, because the owner of the node also owns that state. States that your node happens to
encounter but which aren't related to yourself will not have any activities scheduled.
An example
----------
Let's take an example of the interest rate swap fixings for our scheduled events. The first task is to implement the
``nextScheduledActivity`` method on the ``State``.
.. container:: codeset
.. sourcecode:: kotlin
override fun nextScheduledActivity(thisStateRef: StateRef,
protocolLogicRefFactory: ProtocolLogicRefFactory): ScheduledActivity? {
val nextFixingOf = nextFixingOf() ?: return null
val (instant, duration) = suggestInterestRateAnnouncementTimeWindow(index = nextFixingOf.name,
source = floatingLeg.indexSource,
date = nextFixingOf.forDay)
return ScheduledActivity(protocolLogicRefFactory.create(TwoPartyDealProtocol.FixingRoleDecider::class.java,
thisStateRef, duration), instant)
}
The first thing this does is establish if there are any remaining fixings. If there are none, then it returns ``null``
to indicate that there is no activity to schedule. Otherwise it calculates the ``Instant`` at which the interest rate
should become available and schedules an activity at that time to work out what roles each node will take in the fixing
business process and to take on those roles. That ``ProtocolLogic`` will be handed the ``StateRef`` for the interest
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:: 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
is responsible for starting a ``ProtocolLogic`` to perform one role in the fixing protocol with the ``sessionID`` sent
by the ``FixingRoleDecider`` on the other node which then launches the other role in the fixing protocol. Currently
the handler needs to be manually installed in the node.

61
docs/build/html/_sources/getting-set-up.txt vendored
View File

@ -1,61 +0,0 @@
Getting set up
==============
Ensure that you have access to R3 git repository.
https://bitbucket.org/R3-CEV/r3prototyping.git
If you cannot access the page please contact the R3 admin team.
Install the Oracle JDK 8u45 or higher. OpenJDK will probably also work, but it hasn't been tested.
Then install IntelliJ. The Community Edition is good enough:
https://www.jetbrains.com/idea/download/
Upgrade the Kotlin plugin to the latest version by clicking "Configure > Plugins" in the opening screen,
then clicking "Install JetBrains plugin", then searching for Kotlin, then hitting "Upgrade" and then "Restart".
You can confirm what is the latest version of Kotlin plugin on this page:
https://plugins.jetbrains.com/plugin/6954
Choose "Check out from version control" and use this git URL. Please remember to replace your_username with your
actual bitbucket user name.
https://your_username@bitbucket.org/R3-CEV/r3prototyping.git
After code is cloned open the project. Please ensure that Gradle project is imported.
You should have the "Unliked Gradle project?" pop-up window in the IntelliJ top right corner. Please click on "Import Gradle Project". Wait for it to think and download the dependencies. After that you might have another popup titled "Unindexed remote maven repositories found." This is general IntelliJ question and doesn't affect Corda, therefore you can decided to index them or not.
Next click on "green arrow" next to "All tests" pop-up on the top toolbar.
The code should build, the unit tests should show as all green.
You can catch up with the latest code by selecting "VCS -> Update Project" in the menu.
If IntelliJ complains about lack of an SDK
------------------------------------------
If on attempting to open the project (including importing Gradle project), IntelliJ refuses because SDK was not selected, do the following:
Configure -> Project Defaults -> Project Structure
on that tab:
Project Settings / Project
click on New… next to the red <No SDK> symbol, and select JDK. It should then pop up and show the latest JDK it has
found at something like
jdk1.8.0_xx…/Contents/Home
Also select Project language level: as 8. Click OK. Open should now work.
Doing it without IntelliJ
-------------------------
If you don't want to explore or modify the code in a local IDE, you can also just use the command line and a text editor:
* First run ``git clone https://your_username@bitbucket.org/R3-CEV/r3prototyping.git`` to download Corda source code. Please remember to replace your_username with your actual bitbucket user name.
* Next ensure that you are in r3repository ``cd r3repository``
* Then you can run ``./gradlew test`` to run the unit tests.
* Finally remeber to run ``git pull`` to upgrade the source code.

78
docs/build/html/_sources/index.txt vendored
View File

@ -1,78 +0,0 @@
Welcome to the Corda!
=====================
.. warning:: This build of the docs is from the *master branch*, not a milestone release. It may not reflect the
current state of the code.
This is the developer guide for Corda, a proposed architecture for distributed ledgers. Here are the sources
of documentation you may find useful, from highest level to lowest:
1. The `Introductory white paper`_ describes the motivating vision and background of the project. It is the kind
of document your boss should read. It describes why the project exists and briefly compares it to alternative
systems on the market.
2. This user guide. It describes *how* to use the system to write apps. It assumes you already have read the
relevant sections of the technology white paper and now wish to learn how to use it.
3. The `API docs`_.
.. _`Introductory white paper`: _static/corda-introductory-whitepaper.pdf
.. _`Technical white paper`: _static/corda-technical-whitepaper.pdf
.. _`API docs`: api/index.html
Read on to learn:
.. toctree::
:maxdepth: 2
:caption: Overview
inthebox
getting-set-up
data-model
transaction-data-types
merkle-trees
consensus
messaging
persistence
creating-a-cordapp
running-the-demos
node-administration
corda-configuration-files
.. toctree::
:maxdepth: 2
:caption: Tutorials
where-to-start
tutorial-contract
tutorial-contract-clauses
tutorial-test-dsl
tutorial-clientrpc-api
protocol-state-machines
oracles
tutorial-attachments
event-scheduling
.. toctree::
:maxdepth: 2
:caption: Contracts
contract-catalogue
contract-irs
initialmarginagreement
.. toctree::
:maxdepth: 2
:caption: Node API
clientrpc
.. toctree::
:maxdepth: 2
:caption: Appendix
secure-coding-guidelines
release-process
release-notes
network-simulator
node-explorer
codestyle
building-the-docs

73
docs/build/html/_sources/initialmarginagreement.txt vendored
View File

@ -1,73 +0,0 @@
Initial Margin Agreements
=========================
This app is a demonstration of how Corda can be used for the real world requirement of initial margin calculation and
agreement; featuring the integration of complex and industry proven third party libraries into Corda nodes.
SIMM Introduction
-----------------
SIMM is an acronym for "Standard Initial Margin Model". It is effectively the calculation of a "margin" that is paid
by one party to another when they agree a trade on certain types of transaction. This margin is
paid such that, in the event of one of the counterparties suffering a credit event
(a financial term and a polite way to say defaulting, not paying the debts that are due, or potentially even bankruptcy),
then the party that is owed any sum already has some of the amount that it should have been paid. This payment to the
receiving party is a preventative measure in order to reduce the risk of a potentially catastrophic default domino
effect that caused the `Great Financial Crisis <https://en.wikipedia.org/wiki/Financial_crisis_of_2007%E2%80%932008>`_,
as it means that they can be assured that if they need to pay another party, they will have a proportion of the funds
that they have been relying on.
To enact this, in September 2016, the ISDA committee - with full backing from various governing bodies -
`issued a ruling on what is known as the ISDA SIMM ™ model <http://www2.isda.org/news/isda-simm-deployed-today-new-industry-standard-for-calculating-initial-margin-widely-adopted-by-market-participants>`_,
a way of fairly and consistently calculating this margin. Any parties wishing to trade a financial product that is
covered under this ruling would, independently, use this model and calculate their margin payment requirement,
agree it with their trading counterparty and then pay (or receive, depending on the results of this calculation)
this amount. In the case of disagreement that is not resolved in a timely fashion, this payment would increase
and so therefore it is in the parties interest to reach agreement in a short as time frame as possible.
To be more accurate, the SIMM calculation is not performed on just one trade - it is calculated on an aggregate of
intermediary values (which in this model are sensitivities to risk factors) from a portfolio of trades; therefore
the input to a SIMM is actually this data, not the individual trades itself.
Also note that implementations of the SIMM are actually protected and subject to license restrictions by ISDA
(this is due to the model itself being protected). We were fortunate enough to technically partner with
`OpenGamma <http://www.opengamma.com>`_ who allowed us to demonstrate the SIMM process using their proprietary model.
In the source code released, we have replaced their analytics engine with very simple stub functions that allow
the process to run and can easily be swapped out in place for their real libraries.
Process steps
-------------
Preliminaries
- Ensure that there are a number of live trades with another party financial products that are covered under the
ISDA SIMM agreement (if none, then use the demo to enter some simple trades as described below).
Initial Margin Agreement Process
- Agree that one will be performing the margining calculation against a portfolio of trades with another party, and agree the trades in that portfolio. In practice, one node will start the protocol but it does not matter which node does.
- Individually (at the node level), identify the data (static, reference etc) one will need in order to be able to calculate the metrics on those trades
- Confirm with the other counterparty the dataset from the above set
- Calculate any intermediary steps and values needed for the margin calculation (ie sensitivities to risk factors)
- Agree on the results of these steps
- Calculate the initial margin
- Agree on the calculation of the above with the other party
- In practice, pay (or receive) this margin (omitted for the sake of complexity for this example)
Running the app
---------------
The demonstration can be run in two ways - via IntelliJ (which will allow you to add breakpoints, debug, etc), or via gradle and the command line.
Run with IntelliJ::
1. Open the `cordapp-samples` project with IntelliJ
2. Run the shared run configuration "SIMM Valuation Demo"
3. Browse to http://localhost:10005/web/simmvaluationdemo
Run via CLI::
1. Navigate to the `cordapp-samples` directory in your shell
2. Run the gradle target `deployNodes` (ie; ./gradlew deployNodes for Unix or gradlew.bat on Windows)
1. Unix: `cd simm-valuation-demo/build/nodes && ./runnodes`.
2. Windows: Open a command line window in each subdirectory of `simm-valuation-demo/build/nodes` and run `java -jar corda.jar`
4. Browse to http://localhost:10005/web/simmvaluationdemo

41
docs/build/html/_sources/inthebox.txt vendored
View File

@ -1,41 +0,0 @@
What's included?
================
The Corda prototype currently includes:
* A peer to peer network with message persistence and delivery retries.
* Key data structures for defining contracts and states.
* Smart contracts, which you can find in the :doc:`contract-catalogue`.
* Algorithms that work with them, such as serialising, hashing, signing, and verification of the signatures.
* API documentation and tutorials (what you're reading).
* A business process orchestration framework.
* Notary infrastructure for precise timestamping, and elimination of double spending without a blockchain.
* A simple REST API, and a web app demo that uses it to present a frontend for IRS trading.
Some things it does not currently include but should gain later are:
* Sandboxing, distribution or publication of smart contract code
* A user interface for administration
The prototype's goal is rapid exploration of ideas. Therefore in places it takes shortcuts that a production system
would not in order to boost productivity:
* It uses an object graph serialization framework instead of a well specified, vendor neutral protocol.
* There's currently no permissioning framework.
* Some privacy techniques aren't implemented yet.
* It uses an embedded SQL database and doesn't yet have connectivity support for mainstream SQL vendors (Oracle,
Postgres, MySQL, SQL Server etc).
Kotlin
------
Corda is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
and can be thought of as a simpler Scala, with much better Java interop. It is developed by and has commercial support
from JetBrains, the makers of the IntelliJ IDE and other popular developer tools.
As Kotlin is very new, without a doubt you have not encountered it before. Don't worry: it is designed as a better
Java for industrial use and as such, the syntax was carefully designed to be readable even to people who don't know
the language, after only a few minutes of introduction.
Due to the seamless Java interop the use of Kotlin to extend the platform is *not* required and the tutorial shows how
to write contracts in both Kotlin and Java. You can `read more about why Kotlin is a potentially strong successor to Java here <https://medium.com/@octskyward/why-kotlin-is-my-next-programming-language-c25c001e26e3>`_.

111
docs/build/html/_sources/merkle-trees.txt vendored
View File

@ -1,111 +0,0 @@
Transaction Tear-offs
======================
One of the basic data structures in our platform is a transaction. It can be passed around to be signed and verified,
also by third parties. The construction of transactions assumes that they form a whole entity with input and output states,
commands and attachments inside. However all sensitive data shouldn’t be revealed to other nodes that take part in
the creation of transaction on validation level (a good example of this situation is the Oracle which validates only
embedded commands). How to achive it in a way that convinces the other party the data they got for signing really did form
a part of the transaction?
We decided to use well known and described cryptographic scheme to provide proofs of inclusion and data integrity.
Merkle trees are widely used in peer-to-peer networks, blockchain systems and git.
You can read more on the concept `here <https://en.wikipedia.org/wiki/Merkle_tree>`_.
Merkle trees in Corda
----------------------
Transactions are split into leaves, each of them contains either input, output, command or attachment. Other fields like
timestamp or signers are not used in the calculation.
Next, the Merkle tree is built in the normal way by hashing the concatenation
of nodes’ hashes below the current one together. It’s visible on the example image below, where ``H`` denotes sha256 function,
"+" - concatenation.
.. image:: resources/merkleTree.png
The transaction has one input state, one output and three commands. If a tree is not a full binary tree, the rightmost nodes are
duplicated in hash calculation (dotted lines).
Finally, the hash of the root is the identifier of the transaction, it's also used for signing and verification of data integrity.
Every change in transaction on a leaf level will change its identifier.
Hiding data
-----------
Hiding data and providing the proof that it formed a part of a transaction is done by constructing Partial Merkle Trees
(or Merkle branches). A Merkle branch is a set of hashes, that given the leaves’ data, is used to calculate the root’s hash.
Then that hash is compared with the hash of a whole transaction and if they match it means that data we obtained belongs
to that particular transaction.
.. image:: resources/partialMerkle.png
In the example above, the red node is the one holding data for signing Oracle service. Blue nodes' hashes form the Partial Merkle
Tree, dotted ones are not included. Having the command that should be in a red node place and branch we are able to calculate
root of this tree and compare it with original transaction identifier - we have a proof that this command belongs to this transaction.
Example of usage
-----------------
Let’s focus on a code example. We want to construct a transaction with commands containing interest rate fix data as in:
:doc:`oracles`.
After construction of a partial transaction, with included ``Fix`` commands in it, we want to send it to the Oracle for checking
and signing. To do so we need to specify which parts of the transaction are going to be revealed. That can be done by constructing
filtering functions for inputs, outputs, attachments and commands separately. If a function is not provided by default none
of the elements from this group will be included in a Partial Merkle Tree.
.. container:: codeset
.. sourcecode:: kotlin
val partialTx = ...
val oracle: Party = ...
fun filterCommands(c: Command) = oracle.owningKey in c.signers && c.value is Fix
val filterFuns = FilterFuns(filterCommands = ::filterCommands)
Assuming that we already assembled partialTx with some commands and know the identity of Oracle service,
we pass filtering function over commands - ``filterCommands`` to ``FilterFuns``. It filters only
commands of type ``Fix`` as in IRSDemo example. Then we can construct ``FilteredTransaction``:
.. container:: codeset
.. sourcecode:: kotlin
val wtx: WireTransaction = partialTx.toWireTransaction()
val ftx = FilteredTransaction.buildMerkleTransaction(wtx, filterFuns)
In the Oracle example this step takes place in ``RatesFixProtocol``:
.. container:: codeset
.. sourcecode:: kotlin
val protocol = RatesFixProtocol(partialTx, filterFuns, oracle, fixOf, "0.675".bd, "0.1".bd)
``FilteredTransaction`` holds ``filteredLeaves`` (data that we wanted to reveal) and Merkle branch for them.
.. container:: codeset
.. sourcecode:: kotlin
// Getting included commands, inputs, outputs, attachments.
val cmds: List<Command> = ftx.filteredLeaves.commands
val ins: List<StateRef> = ftx.filteredLeaves.inputs
val outs: List<TransactionState<ContractState>> = ftx.filteredLeaves.outputs
val attchs: List<SecureHash> = ftx.filteredLeaves.attachments
If you want to verify obtained ``FilteredTransaction`` all you need is the root hash of the full transaction:
.. container:: codeset
.. sourcecode:: kotlin
if (!ftx.verify(merkleRoot)){
throw MerkleTreeException("Rate Fix Oracle: Couldn't verify partial Merkle tree.")
}
.. 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.

49
docs/build/html/_sources/messaging.txt vendored
View File

@ -1,49 +0,0 @@
Networking and messaging
========================
Corda uses AMQP/1.0 over TLS between nodes which is currently implemented using Apache Artemis, an embeddable message
queue broker. Building on established MQ protocols gives us features like persistence to disk, automatic delivery
retries with backoff and dead-letter routing, security, large message streaming and so on.
Artemis is hidden behind a thin interface that also has an in-memory only implementation suitable for use in
unit tests and visualisation tools.
.. note:: A future version of Corda will allow the MQ broker to be split out of the main node and run as a
separate server. We may also support non-Artemis implementations via JMS, allowing the broker to be swapped
out for alternative implementations.
There are multiple ways of interacting with the network. When writing an application you typically won't use the
messaging subsystem directly. Instead you will build on top of the :doc:`protocol framework <protocol-state-machines>`,
which adds a layer on top of raw messaging to manage multi-step protocols and let you think in terms of identities
rather than specific network endpoints.
Messaging types
---------------
Every ``Message`` object has an associated *topic* and may have a *session ID*. These are wrapped in a ``TopicSession``.
An implementation of ``MessagingService`` can be used to create messages and send them. You can get access to the
messaging service via the ``ServiceHub`` object that is provided to your app. Endpoints on the network are
identified at the lowest level using ``SingleMessageRecipient`` which may be e.g. an IP address, or in future
versions perhaps a routing path through the network.
Network Map Service
-------------------
Supporting the messaging layer is a network map service, which is responsible for tracking public nodes on the network.
Nodes have an internal component, the network map cache, which contains a copy of the network map (which is just a
document). When a node starts up its cache fetches a copy of the full network map, and requests to be notified of
changes. The node then registers itself with the network map service, and the service notifies subscribers that a new
node has joined the network. Nodes do not automatically deregister themselves, so (for example) nodes going offline
briefly for maintenance are retained in the network map, and messages for them will be queued, minimising disruption.
Nodes submit signed changes to the map service, which then forwards update notifications on to nodes which have
requested to be notified of changes.
The network map currently supports:
* Looking up nodes by service
* Looking up node for a party
* Suggesting a node providing a specific service, based on suitability for a contract and parties, for example suggesting
an appropriate interest rates oracle for a interest rate swap contract. Currently no recommendation logic is in place.
The code simply picks the first registered node that supports the required service.

41
docs/build/html/_sources/network-simulator.txt vendored
View File

@ -1,41 +0,0 @@
Network Simulator
=================
A network simulator is provided which shows traffic between nodes through the lifecycle of an interest rate swap
contract. It can optionally also show network setup, during which nodes register themselves with the network
map service and are notified of the changes to the map. The network simulator is run from the command line via Gradle:
**Windows**::
gradlew.bat network-simulator:run
**Other**::
./gradlew network-simulator:run
Interface
---------
.. image:: network-simulator.png
The network simulator can be run automatically, or stepped manually through each step of the interest rate swap. The
options on the simulator window are:
Simulate initialisation
If checked, the nodes registering with the network map is shown. Normally this setup step
is not shown, but may be of interest to understand the details of node discovery.
Run
Runs the network simulation in automatic mode, in which it progresses each step on a timed basis. Once running,
the simulation can be paused in order to manually progress it, or reset.
Next
Manually progress the simulation to the next step.
Reset
Reset the simulation (only available when paused).
Map/Circle
How the nodes are shown, by default nodes are rendered on a world map, but alternatively they can rendered
in a circle layout.
While the simulation runs, details of the steps currently being executed are shown in a sidebar on the left hand side
of the window.
.. TODO: Add documentation on how to use with different contracts for testing/debugging

105
docs/build/html/_sources/node-administration.txt vendored
View File

@ -1,105 +0,0 @@
Node administration
===================
When a node is running, it exposes an embedded database server, an embedded web server that lets you monitor it,
you can upload and download attachments, access a REST API and so on.
Database access
---------------
The node exposes its internal database over a socket which can be browsed using any tool that can use JDBC drivers.
The JDBC URL is printed during node startup to the log and will typically look like this:
``jdbc:h2:tcp://192.168.0.31:31339/node``
The username and password can be altered in the :doc:`corda-config-files` but default to username "sa" and a blank
password.
Any database browsing tool that supports JDBC can be used, but if you have IntelliJ Ultimate edition then there is
a tool integrated with your IDE. Just open the database window and add an H2 data source with the above details.
You will now be able to browse the tables and row data within them.
Monitoring your node
--------------------
Like most Java servers, the node exports various useful metrics and management operations via the industry-standard
`JMX infrastructure <https://en.wikipedia.org/wiki/Java_Management_Extensions>`_. JMX is a standard API
for registering so-called *MBeans* ... objects whose properties and methods are intended for server management. It does
not require any particular network protocol for export. So this data can be exported from the node in various ways:
some monitoring systems provide a "Java Agent", which is essentially a JVM plugin that finds all the MBeans and sends
them out to a statistics collector over the network. For those systems, follow the instructions provided by the vendor.
Sometimes though, you just want raw access to the data and operations itself. So nodes export them over HTTP on the
``/monitoring/json`` HTTP endpoint, using a program called `Jolokia <https://jolokia.org/>`_. Jolokia defines the JSON
and REST formats for accessing MBeans, and provides client libraries to work with that protocol as well.
Here are a few ways to build dashboards and extract monitoring data for a node:
* `JMX2Graphite <https://github.com/logzio/jmx2graphite>`_ is a tool that can be pointed to /monitoring/json and will
scrape the statistics found there, then insert them into the Graphite monitoring tool on a regular basis. It runs
in Docker and can be started with a single command.
* `JMXTrans <https://github.com/jmxtrans/jmxtrans>`_ is another tool for Graphite, this time, it's got its own agent
(JVM plugin) which reads a custom config file and exports only the named data. It's more configurable than
JMX2Graphite and doesn't require a separate process, as the JVM will write directly to Graphite.
* *Java Mission Control* is a desktop app that can connect to a target JVM that has the right command line flags set
(or always, if running locally). You can explore what data is available, create graphs of those metrics, and invoke
management operations like forcing a garbage collection.
* Cloud metrics services like New Relic also understand JMX, typically, by providing their own agent that uploads the
data to their service on a regular schedule.
Uploading and downloading attachments
-------------------------------------
Attachments are files that add context to and influence the behaviour of transactions. They are always identified by
hash and they are public, in that they propagate through the network to wherever they are needed.
All attachments are zip files. Thus to upload a file to the ledger you must first wrap it into a zip (or jar) file. Then
you can upload it by running this command from a UNIX terminal:
.. sourcecode:: shell
curl -F myfile=@path/to/my/file.zip http://localhost:31338/upload/attachment
The attachment will be identified by the SHA-256 hash of the contents, which you can get by doing:
.. sourcecode:: shell
shasum -a 256 file.zip
on a Mac or by using ``sha256sum`` on Linux. Alternatively, the hash will be returned to you when you upload the
attachment.
An attachment may be downloaded by fetching:
.. sourcecode:: shell
http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9
where DECD... is of course replaced with the hash identifier of your own attachment. Because attachments are always
containers, you can also fetch a specific file within the attachment by appending its path, like this:
.. sourcecode:: shell
http://localhost:31338/attachments/DECD098666B9657314870E192CED0C3519C2C9D395507A238338F8D003929DE9/path/within/zip.txt
Uploading interest rate fixes
-----------------------------
If you would like to operate an interest rate fixing service (oracle), you can upload fix data by uploading data in
a simple text format to the ``/upload/interest-rates`` path on the web server.
The file looks like this::
# Some pretend noddy rate fixes, for the interest rate oracles.
LIBOR 2016-03-16 1M = 0.678
LIBOR 2016-03-16 2M = 0.655
EURIBOR 2016-03-15 1M = 0.123
EURIBOR 2016-03-15 2M = 0.111
The columns are:
* Name of the fix
* Date of the fix
* The tenor / time to maturity in days
* The interest rate itself

70
docs/build/html/_sources/node-explorer.txt vendored
View File

@ -1,70 +0,0 @@
Node Explorer
=============
The node explorer provide views to the node's vault and transaction data using Corda's RPC framework.
The user can execute cash transaction commands to issue and move cash to other party on the network or exit cash using the user interface.
Running the UI
--------------
**Windows**::
gradlew.bat tools:explorer:run
**Other**::
./gradlew tools:explorer:run
Running Demo Nodes
------------------
**Windows**::
gradlew.bat tools:explorer:runDemoNodes
**Other**::
./gradlew tools:explorer:runDemoNodes
.. note:: 3 Corda nodes will be created on the following port on localhost by default.
* Notary -> 20002
* Alice -> 20004
* Bob -> 20006
Interface
---------
Login
User can login to any Corda node using the explorer, alternately, `gradlew explorer:runDemoNodes` can be used to start up demo nodes for testing.
Corda node address, username and password are required for login, the address is defaulted to localhost:0 if leave blank.
Username and password can be configured in node's configuration file; for demo nodes, it is defaulted to ``user1`` and ``test``.
.. note:: If you are connecting to the demo nodes, only Alice and Bob (20004, 20006) are accessible using user1 credential, you won't be able to connect to the notary.
.. image:: resources/explorer/login.png
:scale: 50 %
:align: center
Home
Home view shows the top level state of node and vault; currently, it shows your cash balance and the numbers of transaction executed.
The dashboard is intended to house widgets from different CordApp's and provide useful information to system admin at a glance.
.. image:: resources/explorer/dashboard.png
Cash
The cash view shows all currencies you currently own in a tree table format, it is grouped by issuer -> currency.
Individual cash transactions can be viewed by clicking on the table row. The user can also use the search field to narrow down the scope.
.. image:: resources/explorer/vault.png
Transactions
The transaction view contains all transactions handled by the node in a table view. It shows basic information on the table e.g. Transaction ID,
command type, USD equivalence value etc. User can expand the row by double clicking to view the inputs,
outputs and the signatures details for that transaction.
.. image:: resources/explorer/transactionView.png
New Transaction
This is where you can create new transaction; currently only the cash contract is supported.
The user can choose from three transaction types (issue, move and exit) and any party visible on the network.
The result of the transaction will be visible in the transaction screen when executed.
.. image:: resources/explorer/newTransaction.png

134
docs/build/html/_sources/oracles.txt vendored
View File

@ -1,134 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Writing oracle services
=======================
This article covers *oracles*: network services that link the ledger to the outside world by providing facts that
affect the validity of transactions.
The current prototype includes an example oracle that provides an interest rate fixing service. It is used by the
IRS trading demo app.
Introduction
------------
Oracles are a key concept in the block chain/decentralised ledger space. They can be essential for many kinds of
application, because we often wish to condition a transaction on some fact being true or false, but the ledger itself
has a design that is essentially functional: all transactions are *pure* and *immutable*. Phrased another way, a
smart contract cannot perform any input/output or depend on any state outside of the transaction itself. There is no
way to download a web page or interact with the user, in a smart contract. It must be this way because everyone must
be able to independently check a transaction and arrive at an identical conclusion for the ledger to maintan its
integrity: if a transaction could evaluate to "valid" on one computer and then "invalid" a few minutes later on a
different computer, the entire shared ledger concept wouldn't work.
But it is often essential that transactions do depend on data from the outside world, for example, verifying that an
interest rate swap is paying out correctly may require data on interest rates, verifying that a loan has reached
maturity requires knowledge about the current time, knowing which side of a bet receives the payment may require
arbitrary facts about the real world (e.g. the bankruptcy or solvency of a company or country) ... and so on.
We can solve this problem by introducing services that create digitally signed data structures which assert facts.
These structures can then be used as an input to a transaction and distributed with the transaction data itself. Because
the statements are themselves immutable and signed, it is impossible for an oracle to change its mind later and
invalidate transactions that were previously found to be valid. In contrast, consider what would happen if a contract
could do an HTTP request: it's possible that an answer would change after being downloaded, resulting in loss of
consensus (breaks).
The two basic approaches
------------------------
The architecture provides two ways of implementing oracles with different tradeoffs:
1. Using commands
2. Using attachments
When a fact is encoded in a command, it is embedded in the transaction itself. The oracle then acts as a co-signer to
the entire transaction. The oracle's signature is valid only for that transaction, and thus even if a fact (like a
stock price) does not change, every transaction that incorporates that fact must go back to the oracle for signing.
When a fact is encoded as an attachment, it is a separate object to the transaction and is referred to by hash.
Nodes download attachments from peers at the same time as they download transactions, unless of course the node has
already seen that attachment, in which case it won't fetch it again. Contracts have access to the contents of
attachments when they run.
.. note:: Currently attachments do not support digital signing, but this is a planned feature.
As you can see, both approaches share a few things: they both allow arbitrary binary data to be provided to transactions
(and thus contracts). The primary difference is whether the data is a freely reusable, standalone object or whether it's
integrated with a transaction.
Here's a quick way to decide which approach makes more sense for your data source:
* Is your data *continuously changing*, like a stock price, the current time, etc? If yes, use a command.
* Is your data *commercially valuable*, like a feed which you are not allowed to resell unless it's incorporated into
a business deal? If yes, use a command, so you can charge money for signing the same fact in each unique business
context.
* Is your data *very small*, like a single number? If yes, use a command.
* Is your data *large*, *static* and *commercially worthless*, for instance, a holiday calendar? If yes, use an
attachment.
* Is your data *intended for human consumption*, like a PDF of legal prose, or an Excel spreadsheet? If yes, use an
attachment.
Asserting continuously varying data
-----------------------------------
.. note:: A future version of the platform will include a complete tutorial on implementing this type of oracle.
Let's look at the interest rates oracle that can be found in the ``NodeInterestRates`` file. This is an example of
an oracle that uses a command because the current interest rate fix is a constantly changing fact.
The obvious way to implement such a service is like this:
1. The creator of the transaction that depends on the interest rate sends it to the oracle.
2. The oracle inserts a command with the rate and signs the transaction.
3. The oracle sends it back.
But this has a problem - it would mean that the oracle has to be the first entity to sign the transaction, which might impose
ordering constraints we don't want to deal with (being able to get all parties to sign in parallel is a very nice thing).
So the way we actually implement it is like this:
1. The creator of the transaction that depends on the interest rate asks for the current rate. They can abort at this point
if they want to.
2. They insert a command with that rate and the time it was obtained into the transaction.
3. They then send it to the oracle for signing, along with everyone else in parallel. The oracle checks that the command
has correct data for the asserted time, and signs if so.
This same technique can be adapted to other types of oracle.
The oracle consists of a core class that implements the query/sign operations (for easy unit testing), and then a separate
class that binds it to the network layer.
Here is an extract from the ``NodeService.Oracle`` class and supporting types:
.. sourcecode:: kotlin
/** A [FixOf] identifies the question side of a fix: what day, tenor and type of fix ("LIBOR", "EURIBOR" etc) */
data class FixOf(val name: String, val forDay: LocalDate, val ofTenor: Duration)
/** A [Fix] represents a named interest rate, on a given day, for a given duration. It can be embedded in a tx. */
data class Fix(val of: FixOf, val value: BigDecimal) : CommandData
class Oracle {
fun query(queries: List<FixOf>): List<Fix>
fun sign(wtx: WireTransaction): DigitalSignature.LegallyIdentifiable
}
Because the fix contains a timestamp (the ``forDay`` field), there can be an arbitrary delay between a fix being
requested via ``query`` and the signature being requested via ``sign``.
Pay-per-play oracles
--------------------
Because the signature covers the transaction, and transactions may end up being forwarded anywhere, the fact itself
is independently checkable. However, this approach can still be useful when the data itself costs money, because the act
of issuing the signature in the first place can be charged for (e.g. by requiring the submission of a fresh
``Cash.State`` that has been re-assigned to a key owned by the oracle service). Because the signature covers the
*transaction* and not only the *fact*, this allows for a kind of weak pseudo-DRM over data feeds. Whilst a smart
contract could in theory include a transaction parsing and signature checking library, writing a contract in this way
would be conclusive evidence of intent to disobey the rules of the service (*res ipsa loquitur*). In an environment
where parties are legally identifiable, usage of such a contract would by itself be sufficient to trigger some sort of
punishment.

89
docs/build/html/_sources/persistence.txt vendored
View File

@ -1,89 +0,0 @@
Persistence
===========
Corda offers developers the option to expose all or some part of a contract state to an *Object Relational Mapping* (ORM) tool
to be persisted in a RDBMS. The purpose of this is to assist *vault* development by effectively indexing
persisted contract states held in the vault for the purpose of running queries over them and to allow relational joins
between Corda data and private data local to the organisation owning a node.
The ORM mapping is specified using the `Java Persistence API <https://en.wikipedia.org/wiki/Java_Persistence_API>`_ (JPA)
as annotations and is converted to database table rows by the node automatically every time a state is recorded in the
node's local vault as part of a transaction.
.. note:: Presently the node includes an instance of the H2 database but any database that supports JDBC is a candidate and
the node will in the future support a range of database implementations via their JDBC drivers. Much of the node
internal state is also persisted there. You can access the internal H2 database via JDBC, please see the info
in ":doc:`node-administration`" for details.
Schemas
-------
Every ``ContractState`` can implement the ``QueryableState`` interface if it wishes to be inserted into the node's local
database and accessible using SQL.
.. literalinclude:: ../../core/src/main/kotlin/com/r3corda/core/schemas/PersistentTypes.kt
:language: kotlin
:start-after: DOCSTART QueryableState
:end-before: DOCEND QueryableState
The ``QueryableState`` interface requires the state to enumerate the different relational schemas it supports, for instance in
cases where the schema has evolved, with each one being represented by a ``MappedSchema`` object return by the
``supportedSchemas()`` method. Once a schema is selected it must generate that representation when requested via the
``generateMappedObject()`` method which is then passed to the ORM.
Nodes have an internal ``SchemaService`` which decides what to persist and what not by selecting the ``MappedSchema``
to use.
.. literalinclude:: ../../node/src/main/kotlin/com/r3corda/node/services/api/SchemaService.kt
:language: kotlin
:start-after: DOCSTART SchemaService
:end-before: DOCEND SchemaService
.. literalinclude:: ../../core/src/main/kotlin/com/r3corda/core/schemas/PersistentTypes.kt
:language: kotlin
:start-after: DOCSTART MappedSchema
:end-before: DOCEND MappedSchema
The ``SchemaService`` can be configured by a node administrator to select the schemas used by each app. In this way the
relational view of ledger states can evolve in a controlled fashion in lock-step with internal systems or other
integration points and not necessarily with every upgrade to the contract code.
It can select from the ``MappedSchema`` offered by a ``QueryableState``, automatically upgrade to a
later version of a schema or even provide a ``MappedSchema`` not originally offered by the ``QueryableState``.
It is expected that multiple different contract state implementations might provide mappings to some common schema.
For example an Interest Rate Swap contract and an Equity OTC Option contract might both provide a mapping to a common
Derivative schema. The schemas should typically not be part of the contract itself and should exist independently of it
to encourage re-use of a common set within a particular business area or Cordapp.
``MappedSchema`` offer a family name that is disambiguated using Java package style name-spacing derived from the class name
of a *schema family* class that is constant across versions, allowing the ``SchemaService`` to select a preferred version
of a schema.
The ``SchemaService`` is also responsible for the ``SchemaOptions`` that can be configured for a particular ``MappedSchema``
which allow the configuration of a database schema or table name prefixes to avoid any clash with other ``MappedSchema``.
.. note:: It is intended that there should be plugin support for the ``SchemaService`` to offer the version upgrading and
additional schemas as part of Cordapps, and that the active schemas be confgurable. However the present implementation
offers none of this and simply results in all versions of all schemas supported by a ``QueryableState`` being persisted.
This will change in due course. Similarly, it does not currently support configuring ``SchemaOptions`` but will do so in
the future.
Object Relational Mapping
-------------------------
The persisted representation of a ``QueryableState`` should be an instance of a ``PersistentState`` subclass, constructed
either by the state itself or a plugin to the ``SchemaService``. This allows the ORM layer to always associate a
``StateRef`` with a persisted representation of a ``ContractState`` and allows joining with the set of unconsumed states
in the vault.
The ``PersistentState`` subclass should be marked up as a JPA 2.1 *Entity* with a defined table name and having
properties (in Kotlin, getters/setters in Java) annotated to map to the appropriate columns and SQL types. Additional
entities can be included to model these properties where they are more complex, for example collections, so the mapping
does not have to be *flat*. The ``MappedSchema`` must provide a list of all of the JPA entity classes for that schema in order
to initialise the ORM layer.
Several examples of entities and mappings are provided in the codebase, including ``Cash.State`` and
``CommercialPaper.State``. For example, here's the first version of the cash schema.
.. literalinclude:: ../../finance/src/main/kotlin/com/r3corda/schemas/CashSchemaV1.kt
:language: kotlin

694
docs/build/html/_sources/protocol-state-machines.txt vendored
View File

@ -1,694 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Protocol state machines
=======================
This article explains our experimental approach to modelling financial protocols in code. It explains how the
platform's state machine framework is used, and takes you through the code for a simple 2-party asset trading protocol
which is included in the source.
Introduction
------------
Shared distributed ledgers are interesting because they allow many different, mutually distrusting parties to
share a single source of truth about the ownership of assets. Digitally signed transactions are used to update that
shared ledger, and transactions may alter many states simultaneously and atomically.
Blockchain systems such as Bitcoin support the idea of building up a finished, signed transaction by passing around
partially signed invalid transactions outside of the main network, and by doing this you can implement
*delivery versus payment* such that there is no chance of settlement failure, because the movement of cash and the
traded asset are performed atomically by the same transaction. To perform such a trade involves a multi-step protocol
in which messages are passed back and forth privately between parties, checked, signed and so on.
Despite how useful these protocols are, platforms such as Bitcoin and Ethereum do not assist the developer with the rather
tricky task of actually building them. That is unfortunate. There are many awkward problems in their implementation
that a good platform would take care of for you, problems like:
* Avoiding "callback hell" in which code that should ideally be sequential is turned into an unreadable mess due to the
desire to avoid using up a thread for every protocol instantiation.
* Surviving node shutdowns/restarts that may occur in the middle of the protocol without complicating things. This
implies that the state of the protocol must be persisted to disk.
* Error handling.
* Message routing.
* Serialisation.
* Catching type errors, in which the developer gets temporarily confused and expects to receive/send one type of message
when actually they need to receive/send another.
* Unit testing of the finished protocol.
Actor frameworks can solve some of the above but they are often tightly bound to a particular messaging layer, and
we would like to keep a clean separation. Additionally, they are typically not type safe, and don't make persistence or
writing sequential code much easier.
To put these problems in perspective, the *payment channel protocol* in the bitcoinj library, which allows bitcoins to
be temporarily moved off-chain and traded at high speed between two parties in private, consists of about 7000 lines of
Java and took over a month of full time work to develop. Most of that code is concerned with the details of persistence,
message passing, lifecycle management, error handling and callback management. Because the business logic is quite
spread out the code can be difficult to read and debug.
As small contract-specific trading protocols are a common occurence in finance, we provide a framework for the
construction of them that automatically handles many of the concerns outlined above.
Theory
------
A *continuation* is a suspended stack frame stored in a regular object that can be passed around, serialised,
unserialised and resumed from where it was suspended. This concept is sometimes referred to as "fibers". This may
sound abstract but don't worry, the examples below will make it clearer. The JVM does not natively support
continuations, so we implement them using a library called Quasar which works through behind-the-scenes
bytecode rewriting. You don't have to know how this works to benefit from it, however.
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 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
model (that represent facts about the world on the ledger), but rather indicate different stages in the progression
of a multi-stage protocol. Typically writing a state machine would require the use of a big switch statement and some
explicit variables to keep track of where you're up to. The use of continuations avoids this hassle.
A two party trading protocol
----------------------------
We would like to implement the "hello world" of shared transaction building protocols: a seller wishes to sell some
*asset* (e.g. some commercial paper) in return for *cash*. The buyer wishes to purchase the asset using his cash. They
want the trade to be atomic so neither side is exposed to the risk of settlement failure. We assume that the buyer
and seller have found each other and arranged the details on some exchange, or over the counter. The details of how
the trade is arranged isn't covered in this article.
Our protocol has two parties (B and S for buyer and seller) and will proceed as follows:
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 ``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 ``SignedTransaction`` back to B.
You can find the implementation of this protocol in the file ``finance/src/main/kotlin/com/r3corda/protocols/TwoPartyTradeProtocol.kt``.
Assuming no malicious termination, they both end the protocol being in posession of a valid, signed transaction that
represents an atomic asset swap.
Note that it's the *seller* who initiates contact with the buyer, not vice-versa as you might imagine.
We start by defining a wrapper that namespaces the protocol code, two functions to start either the buy or sell side
of the protocol, and two classes that will contain the protocol definition. We also pick what data will be used by
each side.
.. note:: The code samples in this tutorial are only available in Kotlin, but you can use any JVM language to
write them and the approach is the same.
.. container:: codeset
.. sourcecode:: kotlin
object TwoPartyTradeProtocol {
class UnacceptablePriceException(val givenPrice: Amount<Currency>) : Exception("Unacceptable price: $givenPrice")
class AssetMismatchException(val expectedTypeName: String, val typeName: String) : Exception() {
override fun toString() = "The submitted asset didn't match the expected type: $expectedTypeName vs $typeName"
}
// This object is serialised to the network and is the first protocol message the seller sends to the buyer.
data class SellerTradeInfo(
val assetForSale: StateAndRef<OwnableState>,
val price: Amount<Currency>,
val sellerOwnerKey: PublicKey
)
data class SignaturesFromSeller(val sellerSig: DigitalSignature.WithKey,
val notarySig: DigitalSignature.LegallyIdentifiable)
open class Seller(val otherSide: Party,
val notaryNode: NodeInfo,
val assetToSell: StateAndRef<OwnableState>,
val price: Amount<Currency>,
val myKeyPair: KeyPair,
override val progressTracker: ProgressTracker = Seller.tracker()) : ProtocolLogic<SignedTransaction>() {
@Suspendable
override fun call(): SignedTransaction {
TODO()
}
}
open class Buyer(val otherSide: Party,
val notary: Party,
val acceptablePrice: Amount<Currency>,
val typeToBuy: Class<out OwnableState>) : ProtocolLogic<SignedTransaction>() {
@Suspendable
override fun call(): SignedTransaction {
TODO()
}
}
}
This code defines 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.
Going through the data needed to become a seller, we have:
- ``otherSide: Party`` - the party with which you are trading.
- ``notaryNode: NodeInfo`` - the entry in the network map for the chosen notary. See ":doc:`consensus`" for more
information on notaries.
- ``assetToSell: StateAndRef<OwnableState>`` - a pointer to the ledger entry that represents the thing being sold.
- ``price: Amount<Currency>`` - the agreed on price that the asset is being sold for (without an issuer constraint).
- ``myKeyPair: KeyPair`` - the key pair that controls the asset being sold. It will be used to sign the transaction.
And for the buyer:
- ``acceptablePrice: Amount<Currency>`` - the price that was agreed upon out of band. If the seller specifies
a price less than or equal to this, then the trade will go ahead.
- ``typeToBuy: Class<out OwnableState>`` - the type of state that is being purchased. This is used to check that the
sell side of the protocol isn't trying to sell us the wrong thing, whether by accident or on purpose.
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`` 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 functions
---------------------
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
the underlying code to support this new feature. A protocol is suspended when calling either ``receive``, ``send`` or
``sendAndReceive`` which we will learn more about below. For now, just be aware that when one of these methods is
invoked, all methods on the stack must have been marked. If you forget, then in the unit test environment you will
get a useful error message telling you which methods you didn't mark. The fix is simple enough: just add the annotation
and try again.
.. note:: Java 9 is likely to remove this pre-marking requirement completely.
Starting your protocol
----------------------
The ``StateMachineManager`` is the class responsible for taking care of all running protocols in a node. It knows
how to register handlers with the messaging system (see ":doc:`messaging`") and iterate the right state machine
when messages arrive. It provides the send/receive/sendAndReceive calls that let the code request network
interaction and it will save/restore serialised versions of the fiber at the right times.
Protocols can be invoked in several ways. For instance, they can be triggered by scheduled events,
see ":doc:`event-scheduling`" to learn more about this. Or they can be triggered via the HTTP API. Or they can
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``).
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.
The process of starting a protocol returns a ``ListenableFuture`` that you can use to either block waiting for
the result, or register a callback that will be invoked when the result is ready.
In a two party protocol only one side is to be manually started using ``ServiceHub.invokeProtocolAsync``. The other side
has to be registered by its node to respond to the initiating protocol via ``ServiceHubInternal.registerProtocolInitiator``.
In our example it doesn't matter which protocol is the initiator and which is the initiated. For example, if we are to
take the seller as the initiator then we would register the buyer as such:
.. container:: codeset
.. sourcecode:: kotlin
val services: ServiceHubInternal = TODO()
services.registerProtocolInitiator(Seller::class) { otherParty ->
val notary = services.networkMapCache.notaryNodes[0]
val acceptablePrice = TODO()
val typeToBuy = TODO()
Buyer(otherParty, notary, acceptablePrice, typeToBuy)
}
This is telling the buyer node to fire up an instance of ``Buyer`` (the code in the lambda) when the initiating protocol
is a seller (``Seller::class``).
Implementing the seller
-----------------------
Let's implement the ``Seller.call`` method. This will be run when the protocol is invoked.
.. container:: codeset
.. sourcecode:: kotlin
@Suspendable
override fun call(): SignedTransaction {
val partialTX: SignedTransaction = receiveAndCheckProposedTransaction()
val ourSignature: DigitalSignature.WithKey = computeOurSignature(partialTX)
val allPartySignedTx = partialTX + ourSignature
val notarySignature = getNotarySignature(allPartySignedTx)
val result: SignedTransaction = sendSignatures(allPartySignedTx, ourSignature, notarySignature)
return result
}
Here we see the outline of the procedure. We receive a proposed trade transaction from the buyer and check that it's
valid. The buyer has already attached their signature before sending it. Then we calculate and attach our own signature so that the transaction is
now signed by both the buyer and the seller. We then send this request to a notary to assert with another signature that the
timestamp in the transaction (if any) is valid and there are no double spends, and send back both
our signature and the notaries signature. Note we should not send to the notary until all other required signatures have been appended
as the notary may validate the signatures as well as verifying for itself the transactional integrity.
Finally, we hand back to the code that invoked the protocol the finished transaction.
Let's fill out the ``receiveAndCheckProposedTransaction()`` method.
.. container:: codeset
.. sourcecode:: kotlin
@Suspendable
private fun receiveAndCheckProposedTransaction(): SignedTransaction {
// Make the first message we'll send to kick off the protocol.
val hello = SellerTradeInfo(assetToSell, price, myKeyPair.public)
val maybeSTX = sendAndReceive<SignedTransaction>(otherSide, hello)
maybeSTX.unwrap {
// Check that the tx proposed by the buyer is valid.
val missingSigs: Set<PublicKey> = it.verifySignatures(throwIfSignaturesAreMissing = false)
val expected = setOf(myKeyPair.public, notaryNode.identity.owningKey)
if (missingSigs != expected)
throw SignatureException("The set of missing signatures is not as expected: ${missingSigs.toStringsShort()} vs ${expected.toStringsShort()}")
val wtx: WireTransaction = it.tx
logger.trace { "Received partially signed transaction: ${it.id}" }
// Download and check all the things that this transaction depends on and verify it is contract-valid,
// even though it is missing signatures.
subProtocol(ResolveTransactionsProtocol(wtx, otherSide))
if (wtx.outputs.map { it.data }.sumCashBy(myKeyPair.public).withoutIssuer() != price)
throw IllegalArgumentException("Transaction is not sending us the right amount of cash")
return it
}
}
Let's break this down. We fill out the initial protocol message with the trade info, and then call ``sendAndReceive``.
This function takes a few arguments:
- The party on the other side.
- 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. If we get
back something else an exception is thrown.
Once ``sendAndReceive`` is called, the call method will be suspended into a continuation and saved to persistent
storage. If the node crashes or is restarted, the protocol will effectively continue as if nothing had happened. Your
code may remain blocked inside such a call for seconds, minutes, hours or even days in the case of a protocol that
needs human interaction!
.. note:: There are a couple of rules you need to bear in mind when writing a class that will be used as a continuation.
The first is that anything on the stack when the function is suspended will be stored into the heap and kept alive by
the garbage collector. So try to avoid keeping enormous data structures alive unless you really have to.
The second is that as well as being kept on the heap, objects reachable from the stack will be serialised. The state
of the function call may be resurrected much later! Kryo doesn't require objects be marked as serialisable, but even so,
doing things like creating threads from inside these calls would be a bad idea. They should only contain business
logic and only do I/O via the methods exposed by the protocol framework.
It's OK to keep references around to many large internal node services though: these will be serialised using a
special token that's recognised by the platform, and wired up to the right instance when the continuation is
loaded off disk again.
The buyer is supposed to send us a transaction with all the right inputs/outputs/commands in response to the opening
message, with their cash put into the transaction and their signature on it authorising the movement of the cash.
You get back a simple wrapper class, ``UntrustworthyData<SignedTransaction>``, 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.
Our "scrubbing" has three parts:
1. Check that the expected signatures are present and correct. At this point we expect our own signature to be missing,
because of course we didn't sign it yet, and also the signature of the notary because that must always come last.
2. We resolve the transaction, which we will cover below.
3. We verify that the transaction is paying us the demanded price.
Subprotocols
------------
Protocols can be composed via nesting. Invoking a sub-protocol looks similar to an ordinary function call:
.. container:: codeset
.. sourcecode:: kotlin
@Suspendable
private fun getNotarySignature(stx: SignedTransaction): DigitalSignature.LegallyIdentifiable {
progressTracker.currentStep = NOTARY
return subProtocol(NotaryProtocol.Client(stx))
}
In this code snippet we are using the ``NotaryProtocol.Client`` to request notarisation of the transaction.
We simply create the protocol object via its constructor, and then pass it to the ``subProtocol`` method which
returns the result of the protocol's execution directly. Behind the scenes all this is doing is wiring up progress
tracking (discussed more below) and then running the objects ``call`` method. Because this little helper method can
be on the stack when network IO takes place, we mark it as ``@Suspendable``.
Going back to the previous code snippet, we use a subprotocol called ``ResolveTransactionsProtocol``. This is
responsible for downloading and checking all the dependencies of a transaction, which in Corda are always retrievable
from the party that sent you a transaction that uses them. This protocol returns a list of ``LedgerTransaction``
objects, but we don't need them here so we just ignore the return value.
.. 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.
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's the rest of the code:
.. container:: codeset
.. sourcecode:: kotlin
open fun computeOurSignature(partialTX: SignedTransaction) = myKeyPair.signWithECDSA(partialTX.txBits)
@Suspendable
private fun sendSignatures(allPartySignedTX: SignedTransaction, ourSignature: DigitalSignature.WithKey,
notarySignature: DigitalSignature.LegallyIdentifiable): SignedTransaction {
val fullySigned = allPartySignedTX + notarySignature
logger.trace { "Built finished transaction, sending back to secondary!" }
send(otherSide, SignaturesFromSeller(ourSignature, notarySignature))
return fullySigned
}
It's all pretty straightforward from now on. Here ``txBits`` is the raw byte array representing the serialised
transaction, and we just use our private key to calculate a signature over it. As a reminder, in Corda signatures do
not cover other signatures: just the core of the transaction data.
In ``sendSignatures``, we take the two signatures we obtained and add them to the partial transaction we were sent.
There is 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.
You can also see that every protocol instance has a logger (using the SLF4J API) which you can use to log progress
messages.
.. warning:: This sample 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.
Implementing the buyer
----------------------
OK, let's do the same for the buyer side:
.. container:: codeset
.. sourcecode:: kotlin
@Suspendable
override fun call(): SignedTransaction {
val tradeRequest = receiveAndValidateTradeRequest()
val (ptx, cashSigningPubKeys) = assembleSharedTX(tradeRequest)
val stx = signWithOurKeys(cashSigningPubKeys, ptx)
val signatures = swapSignaturesWithSeller(stx)
logger.trace { "Got signatures from seller, verifying ... " }
val fullySigned = stx + signatures.sellerSig + signatures.notarySig
fullySigned.verifySignatures()
logger.trace { "Signatures received are valid. Trade complete! :-)" }
return fullySigned
}
@Suspendable
private fun receiveAndValidateTradeRequest(): SellerTradeInfo {
// Wait for a trade request to come in from the other side
val maybeTradeRequest = receive<SellerTradeInfo>(otherParty)
maybeTradeRequest.unwrap {
// What is the seller trying to sell us?
val asset = it.assetForSale.state.data
val assetTypeName = asset.javaClass.name
logger.trace { "Got trade request for a $assetTypeName: ${it.assetForSale}" }
if (it.price > acceptablePrice)
throw UnacceptablePriceException(it.price)
if (!typeToBuy.isInstance(asset))
throw AssetMismatchException(typeToBuy.name, assetTypeName)
// 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))
return it
}
}
@Suspendable
private fun swapSignaturesWithSeller(stx: SignedTransaction): SignaturesFromSeller {
progressTracker.currentStep = SWAPPING_SIGNATURES
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<SignaturesFromSeller>(otherSide, stx).unwrap { it }
}
private fun signWithOurKeys(cashSigningPubKeys: List<PublicKey>, 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))
}
return ptx.toSignedTransaction(checkSufficientSignatures = false)
}
private fun assembleSharedTX(tradeRequest: SellerTradeInfo): Pair<TransactionBuilder, List<PublicKey>> {
val ptx = TransactionType.General.Builder(notary)
// 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<Cash.State>()
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)
// 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.data.withNewOwner(freshKey.public)
ptx.addOutputState(state, tradeRequest.assetForSale.state.notary)
ptx.addCommand(command, tradeRequest.assetForSale.state.data.owner)
// And add a request for timestamping: it may be that none of the contracts need this! But it can't hurt
// to have one.
val currentTime = serviceHub.clock.instant()
ptx.setTime(currentTime, 30.seconds)
return Pair(ptx, cashSigningPubKeys)
}
This code is longer but no more complicated. 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().generateSpend``. See the contracts tutorial if this
part 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 network map.
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.
.. warning:: In the current version of the platform, exceptions thrown during protocol execution are not propagated
back to the sender. A thorough error handling and exceptions framework will be in a future version of the platform.
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 <http://reactivex.io/>`_ 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.
Unit testing
------------
A protocol can be a fairly complex thing that interacts with many services and other parties over the network. That
means unit testing one requires some infrastructure to provide lightweight mock implementations. The MockNetwork
provides this testing infrastructure layer; you can find this class in the node module
A good example to examine for learning how to unit test protocols is the ``ResolveTransactionsProtocol`` tests. This
protocol takes care of downloading and verifying transaction graphs, with all the needed dependencies. We start
with this basic skeleton:
.. container:: codeset
.. sourcecode:: kotlin
class ResolveTransactionsProtocolTest {
lateinit var net: MockNetwork
lateinit var a: MockNetwork.MockNode
lateinit var b: MockNetwork.MockNode
lateinit var notary: Party
@Before
fun setup() {
net = MockNetwork()
val nodes = net.createSomeNodes()
a = nodes.partyNodes[0]
b = nodes.partyNodes[1]
notary = nodes.notaryNode.info.identity
net.runNetwork()
}
@After
fun tearDown() {
net.stopNodes()
}
}
We create a mock network in our ``@Before`` setup method and create a couple of nodes. We also record the identity
of the notary in our test network, which will come in handy later. We also tidy up when we're done.
Next, we write a test case:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun resolveFromTwoHashes() {
val (stx1, stx2) = makeTransactions()
val p = ResolveTransactionsProtocol(setOf(stx2.id), a.info.identity)
val future = b.services.startProtocol("resolve", p)
net.runNetwork()
val results = future.get()
assertEquals(listOf(stx1.id, stx2.id), results.map { it.id })
assertEquals(stx1, b.storage.validatedTransactions.getTransaction(stx1.id))
assertEquals(stx2, b.storage.validatedTransactions.getTransaction(stx2.id))
}
We'll take a look at the ``makeTransactions`` function in a moment. For now, it's enough to know that it returns two
``SignedTransaction`` objects, the second of which spends the first. Both transactions are known by node A
but not node B.
The test logic is simple enough: we create the protocol, giving it node A's identity as the target to talk to.
Then we start it on node B and use the ``net.runNetwork()`` method to bounce messages around until things have
settled (i.e. there are no more messages waiting to be delivered). All this is done using an in memory message
routing implementation that is fast to initialise and use. Finally, we obtain the result of the protocol and do
some tests on it. We also check the contents of node B's database to see that the protocol had the intended effect
on the node's persistent state.
Here's what ``makeTransactions`` looks like:
.. container:: codeset
.. sourcecode:: kotlin
private fun makeTransactions(): Pair<SignedTransaction, SignedTransaction> {
// Make a chain of custody of dummy states and insert into node A.
val dummy1: SignedTransaction = DummyContract.generateInitial(MEGA_CORP.ref(1), 0, notary).let {
it.signWith(MEGA_CORP_KEY)
it.signWith(DUMMY_NOTARY_KEY)
it.toSignedTransaction(false)
}
val dummy2: SignedTransaction = DummyContract.move(dummy1.tx.outRef(0), MINI_CORP_PUBKEY).let {
it.signWith(MEGA_CORP_KEY)
it.signWith(DUMMY_NOTARY_KEY)
it.toSignedTransaction()
}
a.services.recordTransactions(dummy1, dummy2)
return Pair(dummy1, dummy2)
}
We're using the ``DummyContract``, a simple test smart contract which stores a single number in its states, along
with ownership and issuer information. You can issue such states, exit them and re-assign ownership (move them).
It doesn't do anything else. This code simply creates a transaction that issues a dummy state (the issuer is
``MEGA_CORP``, a pre-defined unit test identity), signs it with the test notary and MegaCorp keys and then
converts the builder to the final ``SignedTransaction``. It then does so again, but this time instead of issuing
it re-assigns ownership instead. The chain of two transactions is finally committed to node A by sending them
directly to the ``a.services.recordTransaction`` method (note that this method doesn't check the transactions are
valid).
And that's it: you can explore the documentation for the `MockNode API <api/com.r3corda.node.internal.testing/-mock-network/index.html>`_ here.
Versioning
----------
Fibers involve persisting object-serialised stack frames to disk. Although we may do some R&D into in-place upgrades
in future, for now the upgrade process for protocols is simple: you duplicate the code and rename it so it has a
new set of class names. Old versions of the protocol can then drain out of the system whilst new versions are
initiated. When enough time has passed that no old versions are still waiting for anything to happen, the previous
copy of the code can be deleted.
Whilst kind of ugly, this is a very simple approach that should suffice for now.
.. warning:: Protocols are not meant to live for months or years, and by implication they are not meant to implement entire deal
lifecycles. For instance, implementing the entire life cycle of an interest rate swap as a single protocol - whilst
technically possible - would not be a good idea. The platform provides a job scheduler tool that can invoke
protocols for this reason (see ":doc:`event-scheduling`")
Future features
---------------
The protocol framework is a key part of the platform and will be extended in major ways in future. Here are some of
the features we have planned:
* Identity based addressing
* Exposing progress trackers to local (inside the firewall) clients using message queues and/or WebSockets
* Exception propagation and management, with a "protocol hospital" tool to manually provide solutions to unavoidable
problems (e.g. the other side doesn't know the trade)
* Being able to interact with internal apps and tools via HTTP and similar
* Being able to interact with people, either via some sort of external ticketing system, or email, or a custom UI.
For example to implement human transaction authorisations.
* A standard library of protocols that can be easily sub-classed by local developers in order to integrate internal
reporting logic, or anything else that might be required as part of a communications lifecycle.

308
docs/build/html/_sources/release-notes.txt vendored
View File

@ -1,308 +0,0 @@
Release notes
=============
Here are brief summaries of what's changed between each snapshot release.
Milestone 5
-----------
* A simple RPC access control mechanism. Users, passwords and permissions can be defined in a configuration file.
This mechanism will be extended in future to support standard authentication systems like LDAP.
* New features in the explorer app and RPC API for working with cash:
* Cash can now be sent, issued and exited via RPC.
* Notes can now be associated with transactions.
* Hashes are visually represented using identicons.
* Lots of functional work on the explorer UI. You can try it out by running ``gradle tools:explorer:runDemoNodes`` to run
a local network of nodes that swap cash with each other, and then run ``gradle tools:explorer:run`` to start
the app.
* A new demo showing shared valuation of derivatives portfolios using the ISDA SIMM has been added. Note that this app
relies on a proprietary implementation of the ISDA SIMM business logic from OpenGamma. A stub library is provided
to ensure it compiles but if you want to use the app for real please contact us.
* Developer experience (we plan to do lots more here in milestone 6):
* Demos and samples have been split out of the main repository, and the initial developer experience continues to be
refined. All necessary JARs can now be installed to Maven Local by simply running ``gradle install``.
* It's now easier to define a set of nodes to run locally using the new "CordFormation" gradle plugin, which
defines a simple DSL for creating networks of nodes.
* The template CorDapp has been upgraded with more documentation and showing more features.
* Privacy: transactions are now structured as Merkle trees, and can have sections "torn off" - presented for
verification and signing without revealing the rest of the transaction.
* Lots of bug fixes, tweaks and polish starting the run up to the open source release.
API changes:
* Plugin service classes now take a ``PluginServiceHub`` rather than a ``ServiceHubInternal``.
* ``UniqueIdentifier`` equality has changed to only take into account the underlying UUID.
* The contracts module has been renamed to finance, to better reflect what it is for.
Milestone 4
-----------
New features in this release:
* Persistence:
* States can now be written into a relational database and queried using JDBC. The schemas are defined by the
smart contracts and schema versioning is supported. It is reasonable to write an app that stores data in a mix
of global ledger transactions and local database tables which are joined on demand, using join key slots that
are present in many state definitions. Read more about :doc:`persistence`.
* The embedded H2 SQL database is now exposed by default to any tool that can speak JDBC. The database URL is
printed during node startup and can be used to explore the database, which contains both node internal data
and tables generated from ledger states.
* Protocol checkpoints are now stored in the database as well. Message processing is now atomic with protocol
checkpointing and run under the same RDBMS transaction.
* MQ message deduplication is now handled at the app layer and performed under the RDMS transaction, so
ensuring messages are only replayed if the RDMS transaction rolled back.
* "The wallet" has been renamed to "the vault".
* Client RPC:
* New RPCs added to subscribe to snapshots and update streams state of the vault, currently executing protocols
and other important node information.
* New tutorial added that shows how to use the RPC API to draw live transaction graphs on screen.
* Protocol framework:
* Large simplifications to the API. Session management is now handled automatically. Messages are now routed
based on identities rather than node IP addresses.
* Decentralised consensus:
* A standalone one-node notary backed by a JDBC store has been added.
* A prototype RAFT based notary composed of multiple nodes is available on a branch.
* Data model:
* Compound keys have been added as preparation for merging a distributed RAFT based notary. Compound keys
are trees of public keys in which interior nodes can have validity thresholds attached, thus allowing
boolean formulas of keys to be created. This is similar to Bitcoin's multi-sig support and the data model
is the same as the InterLedger Crypto-Conditions spec, which should aid interop in future. Read more about
key trees in the ":doc:`transaction-data-types`" article.
* A new tutorial has been added showing how to use transaction attachments in more detail.
* Testnet
* Permissioning infrastructure phase one is built out. The node now has a notion of developer mode vs normal
mode. In developer mode it works like M3 and the SSL certificates used by nodes running on your local
machine all self-sign using a developer key included in the source tree. When developer mode is not active,
the node won't start until it has a signed certificate. Such a certificate can be obtained by simply running
an included command line utility which generates a CSR and submits it to a permissioning service, then waits
for the signed certificate to be returned. Note that currently there is no public Corda testnet, so we are
not currently running a permissioning service.
* Standalone app development:
* The Corda libraries that app developers need to link against can now be installed into your local Maven
repository, where they can then be used like any other JAR. See :doc:`creating-a-cordapp`.
* User interfaces:
* Infrastructure work on the node explorer is now complete: it is fully switched to using the MQ based RPC system.
* A library of additional reactive collections has been added. This API builds on top of Rx and the observable
collections API in Java 8 to give "live" data structures in which the state of the node and ledger can be
viewed as an ordinary Java ``List``, ``Map`` and ``Set``, but which also emit callbacks when these views
change, and which can have additional views derived in a functional manner (filtered, mapped, sorted, etc).
Finally, these views can then be bound directly into JavaFX UIs. This makes for a concise and functional
way of building application UIs that render data from the node, and the API is available for third party
app developers to use as well. We believe this will be highly productive and enjoyable for developers who
have the option of building JavaFX apps (vs web apps).
* The visual network simulator tool that was demoed back in April as part of the first Corda live demo has
been merged into the main repository.
* Documentation
* New secure coding guidelines. Corda tries to eliminate as many security mistakes as practical via the type
system and other mechanically checkable processes, but there are still things that one must be aware of.
* New attachments tutorial.
* New Client RPC tutorial.
* More tutorials on how to build a standalone CorDapp.
* Testing
* More integration testing support
* New micro-DSLs for expressing expected sequences of operations with more or less relaxed ordering constraints.
* QuickCheck generators to create streams of randomised transactions and other basic types. QuickCheck is a way
of writing unit tests that perform randomised fuzz testing of code, originally developed by the Haskell
community and now also available in Java.
API changes:
* The transaction types (Signed, Wire, LedgerTransaction) have moved to ``com.r3corda.core.transactions``. You can
update your code by just deleting the broken import lines and letting your IDE re-import them from the right
location.
* ``AbstractStateReplacementProtocol.verifyProposal`` has changed its prototype in a minor way.
* The ``UntrustworthyData<T>.validate`` method has been renamed to ``unwrap`` - the old name is now deprecated.
* The wallet, wallet service, etc. are now vault, vault service, etc. These better reflect the intent that they
are a generic secure data store, rather than something which holds cash.
* The protocol send/receive APIs have changed to no longer require a session id. Please check the current version
of the protocol framework tutorial for more details.
Milestone 3
-----------
* More work on preparing for the testnet:
* Corda is now a standalone app server that loads "CorDapps" into itself as plugins. Whilst the existing IRS
and trader demos still exist for now, these will soon be removed and there will only be a single Corda node
program. Note that the node is a single, standalone jar file that is easier to execute than the demos.
* Project Vega (shared SIMM modelling for derivative portfolios) has already been converted to be a CorDapp.
* Significant work done on making the node persist its wallet data to a SQL backend, with more on the way.
* Upgrades and refactorings of the core transaction types in preparation for the incoming sandboxing work.
* The Clauses API that seeks to make writing smart contracts easier has gone through another design iteration,
with the result that clauses are now cleaner and more composable.
* Improvements to the protocol API for finalising transactions (notarising, transmitting and storing).
* Lots of work done on an MQ based client API.
* Improvements to the developer site:
* The developer site has been re-read from start to finish and refreshed for M3 so there should be no obsolete
texts or references anywhere.
* The Corda non-technical white paper is now a part of the developer site and git repository. The LaTeX source is
also provided so if you spot any issues with it, you can send us patches.
* There is a new section on how to write CorDapps.
* Further R&D work by Sofus Mortensen in the experimental module on a new 'universal' contract language.
* SSL for the REST API and webapp server can now be configured.
Milestone 2
-----------
* Big improvements to the interest rate swap app:
* A new web app demonstrating the IRS contract has been added. This can be used as an example for how to interact with
the Corda API from the web.
* Simplifications to the way the demo is used from the command line.
* :doc:`Detailed documentation on how the contract works and can be used <contract-irs>` has been written.
* Better integration testing of the app.
* Smart contracts have been redesigned around reusable components, referred to as "clauses". The cash, commercial paper
and obligation contracts now share a common issue clause.
* New code in the experimental module (note that this module is a place for work-in-progress code which has not yet gone
through code review and which may, in general, not even function correctly):
* Thanks to the prolific Sofus Mortensen @ Nordea Bank, an experimental generic contract DSL that is based on the famous
2001 "Composing contracts" paper has been added. We thank Sofus for this great and promising research, which is so
relevant in the wake of TheDAO hack.
* The contract code from the recent trade finance demos is now in experimental. This code comes thanks to a
collaboration of the members; all credit to:
* Mustafa Ozturk @ Natixis
* David Nee @ US Bank
* Johannes Albertsen @ Dankse Bank
* Rui Hu @ Nordea
* Daniele Barreca @ Unicredit
* Sukrit Handa @ Scotiabank
* Giuseppe Cardone @ Banco Intesa
* Robert Santiago @ BBVA
* The usability of the command line demo programs has been improved.
* All example code and existing contracts have been ported to use the new Java/Kotlin unit testing domain-specific
languages (DSLs) which make it easy to construct chains of transactions and verify them together. This cleans up
and unifies the previous ad-hoc set of similar DSLs. A tutorial on how to use it has been added to the documentation.
We believe this largely completes our testing story for now around smart contracts. Feedback from bank developers
during the Trade Finance project has indicated that the next thing to tackle is docs and usability improvements in
the protocols API.
* Significant work done towards defining the "CorDapp" concept in code, with dynamic loading of API services and more to
come.
* Inter-node communication now uses SSL/TLS and AMQP/1.0, albeit without all nodes self-signing at the moment. A real
PKI for the p2p network will come later.
* Logging is now saved to files with log rotation provided by Log4J.
API changes:
* Some utility methods and extension functions that are specific to certain contract types have moved packages: just
delete the import lines that no longer work and let IntelliJ replace them with the correct package paths.
* The ``arg`` method in the test DSL is now called ``command`` to be consistent with the rest of the data model.
* The messaging APIs have changed somewhat to now use a new ``TopicSession`` object. These APIs will continue to change
in the upcoming releases.
* Clauses now have default values provided for ``ifMatched``, ``ifNotMatched`` and ``requiredCommands``.
New documentation:
* :doc:`contract-catalogue`
* :doc:`contract-irs`
* :doc:`tutorial-test-dsl`
Milestone 1
-----------
Highlights of this release:
* Event scheduling. States in the ledger can now request protocols to be invoked at particular times, for states
considered relevant by the wallet.
* Upgrades to the notary/consensus service support:
* There is now a way to change the notary controlling a state.
* You can pick between validating and non-validating notaries, these let you select your privacy/robustness tradeoff.
* A new obligation contract that supports bilateral and multilateral netting of obligations, default tracking and
more.
* Improvements to the financial type system, with core classes and contracts made more generic.
* Switch to a better digital signature algorithm: ed25519 instead of the previous JDK default of secp256r1.
* A new integration test suite.
* A new Java unit testing DSL for contracts, similar in spirit to the one already developed for Kotlin users (which
depended on Kotlin specific features).
* An experimental module, where developers who want to work with the latest Corda code can check in contracts/cordapp
code before it's been fully reviewed. Code in this module has compiler warnings suppressed but we will still make
sure it compiles across refactorings.
* Persistence improvements: transaction data is now stored to disk and automatic protocol resume is now implemented.
* Many smaller bug fixes, cleanups and improvements.
We have new documentation on:
* :doc:`event-scheduling`
* :doc:`transaction-data-types`
* :doc:`consensus`
Summary of API changes (not exhaustive):
* Notary/consensus service:
* ``NotaryService`` is now extensible.
* Every ``ContractState`` now has to specify a *participants* field, which is a list of parties that are able to
consume this state in a valid transaction. This is used for e.g. making sure all relevant parties obtain the updated
state when changing a notary.
* Introduced ``TransactionState``, which wraps ``ContractState``, and is used when defining a transaction output.
The notary field is moved from ``ContractState`` into ``TransactionState``.
* Every transaction now has a *type* field, which specifies custom build & validation rules for that transaction type.
Currently two types are supported: General (runs the default build and validation logic) and NotaryChange (
contract code is not run during validation, checks that the notary field is the only difference between the
inputs and outputs).
``TransactionBuilder()`` is now abstract, you should use ``TransactionType.General.Builder()`` for building transactions.
* The cash contract has moved from ``com.r3corda.contracts`` to ``com.r3corda.contracts.cash``
* ``Amount`` class is now generic, to support non-currency types such as physical assets. Where you previously had just
``Amount``, you should now use ``Amount<Currency>``.
* Refactored the Cash contract to have a new FungibleAsset superclass, to model all countable assets that can be merged
and split (currency, barrels of oil, etc.)
* Messaging:
* ``addMessageHandler`` now has a different signature as part of error handling changes.
* If you want to return nothing to a protocol, use ``Ack`` instead of ``Unit`` from now on.
* In the IRS contract, dateOffset is now an integer instead of an enum.
* In contracts, you now use ``tx.getInputs`` and ``tx.getOutputs`` instead of ``getInStates`` and ``getOutStates``. This is
just a renaming.
* A new ``NonEmptySet`` type has been added for cases where you wish to express that you have a collection of unique
objects which cannot be empty.
* Please use the global ``newSecureRandom()`` function rather than instantiating your own SecureRandom's from now on, as
the custom function forces the use of non-blocking random drivers on Linux.
Milestone 0
-----------
This is the first release, which includes:
* Some initial smart contracts: cash, commercial paper, interest rate swaps
* An interest rate oracle
* The first version of the protocol/orchestration framework
* Some initial support for pluggable consensus mechanisms
* Tutorials and documentation explaining how it works
* Much more ...

44
docs/build/html/_sources/release-process.txt vendored
View File

@ -1,44 +0,0 @@
Release process
===============
Corda is under heavy development. The current release process is therefore geared towards rapid iteration.
Each Corda development release is called a *milestone* and has its own branch in the git repository. Milestones are
temporarily stabilised snapshots of the Corda code which are suitable for developers to experiment with. They may
receive backported bugfixes but once announced a milestone will not have any API or backwards compatibility breaks.
Between milestones backwards compatibility is expected to break. Every new milestone comes with a short announcement
detailing:
* What major improvements have been made.
* How to forward port your code to the new milestone.
* What new documentation has become available.
* Important known issues.
Eventually, Corda will stabilise and release version 1. At that point backwards compatibility will be guaranteed
forever and the software will be considered production ready. Until then, expect it to be a building site and wear your
hard hat.
Our goal is to cut a new milestone roughly once a month. There are no fixed dates. If need be, a milestone may slip by
a few days to ensure the code is sufficiently usable. Usually the release will happen around the end of the month.
Steps to cut a release
======================
1. Pick a commit that is stable and do basic QA: run all the tests, run the demos.
2. Review the commits between this release and the last looking for new features, API changes, etc. Make sure the
summary in the current section of the :doc:`release-notes` is correct and update if not. Then move it into the right
section for this release. This is the right place to put any advice on how to port app code from the last release.
3. Additionally, if there are any new features or APIs that deserve a new section in the docsite and the author didn't
create one, bug them to do so a day or two before the release.
4. Regenerate the docsite if necessary and commit.
5. Create a branch with a name like `release-M0` where 0 is replaced by the number of the milestone.
6. Adjust the version in the root build.gradle file to take out the -SNAPSHOT and commit it on the branch.
7. Remove the "is master" warning from the docsite index page on this branch only.
8. Tag the branch with a tag like `release-M0.0`
9. Push the branch and the tag to git.
10. Write up a short announcement containing the summary of new features, changes, and API breaks. Send it to the r3dlg-awg mailing list.
11. On master, adjust the version number in the root build.gradle file upwards.
If there are serious bugs found in the release, backport the fix to the branch and then tag it with e.g. `release-M0.1`
Minor changes to the branch don't have to be announced unless it'd be critical to get all developers updated.

76
docs/build/html/_sources/running-the-demos.txt vendored
View File

@ -1,76 +0,0 @@
Running the demos
=================
The repository contains a small number of demo programs that run two-node networks, demonstrating functionality developed
so far. We have:
1. The trader demo, which shows a delivery-vs-payment atomic swap of commercial paper for cash. You can learn more about
how this works in :doc:`protocol-state-machines`.
2. The IRS demo, which shows two nodes establishing an interest rate swap between them and performing fixings with a
rates oracle, all driven via the HTTP API.
3. The IRS demo web interface - a web interface to the IRS demo.
4. The attachment demo, which demonstrates uploading attachments to nodes.
5. The SIMM valuation demo, a large demo which shows two nodes agreeing on a portfolio and valuing the initial margin
using the Standard Initial Margin Model.
.. note:: The demos currently must be run from IntelliJ, this will change before M6.
.. note:: If any demos don't work please jump on our mailing list and let us know.
Trader demo
-----------
1. Open the Corda project in IntelliJ and run the "Install" configuration
2. Open the Corda samples project in IntelliJ and run the "Trader Demo: Run Nodes" configuration
3. Run "Trader Demo: Run Buyer"
4. Run "Trader Demo: Run Seller"
In the "Trader Demo: Run Nodes" windows 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.
IRS demo
--------
1. Open the Corda project in IntelliJ and run the "Install" configuration
2. Open the Corda samples project in IntelliJ and run the "IRS Demo: Run Nodes" configuration
3. Run "IRS Demo: Run Upload Rates" to upload rates to the oracle.
4. Run "IRS Demo: Run Trade" to have nodes agree on a trade.
5. Run "IRS Demo: Run Date Change" to run the fixings.
In the "IRS Demo: Run Nodes" window you'll see a lot of activity when you run the trade and when you run the date change.
The date change rolls the clock forwards and causes the nodes to agree on the fixings over a period.
IRS web demo
------------
There is also an IRS web demo installed. To use this follow steps 1-3 in the IRS demo and then navigate to
http://localhost:10005/web/irsdemo and http://localhost:10005/web/irsdemo to see both node's view of the trades.
To use the demos click the "Create Deal" button, fill in the form, then click the "Submit" button. Now you will be
able to use the time controls at the top left of the home page to run the fixings. Click any individual trade in the
blotter to view it.
Attachment demo
---------------
1. Open the Corda project in IntelliJ and run the "Install" configuration
2. Open the Corda samples project in IntelliJ and run the "Attachment Demo: Run Nodes" configuration
3. Run "Attachment Demo: Run Recipient" - this waits for a trade to start
4. Run "Attachment Demo: Run Sender" - sends the attachment
In the "Attachment Demo: Run Nodes" window you should see some log lines scroll past, and within a few seconds the
message "File received - we're happy!" should be printed.
SIMM and Portfolio Demo
-----------------------
.. note:: Read more about this demo at :doc:`initialmarginagreement`.
To run the demo run:
1. Open the Corda project in IntelliJ and run the "Install" configuration
2. Open the Corda samples project in IntelliJ and run the "Simm Valuation Demo" configuration
Now open http://localhost:10005/web/simmvaluationdemo and http://localhost:10005/web/simmvaluationdemo to view the two nodes that this
will have started respectively. You can now use the demo by creating trades and agreeing the valuations.

47
docs/build/html/_sources/secure-coding-guidelines.txt vendored
View File

@ -1,47 +0,0 @@
Secure coding guidelines
========================
The platform does what it can to be secure by default and safe by design. Unfortunately the platform cannot
prevent every kind of security mistake. This document describes what to think about when writing applications
to block various kinds of attack. Whilst it may be tempting to just assume no reasonable counterparty would
attempt to subvert your trades using protocol level attacks, relying on trust for software security makes it
harder to scale up your operations later when you might want to add counterparties quickly and without
extensive vetting.
Protocols
---------
:doc:`protocol-state-machines` are how your app communicates with other parties on the network. Therefore they
are the typical entry point for malicious data into your app and must be treated with care.
The ``receive`` methods return data wrapped in the ``UntrustworthyData<T>`` marker type. This type doesn't add
any functionality, it's only there to remind you to properly validate everything that you get from the network.
Remember that the other side may *not* be running the code you provide to take part in the protocol: they are
allowed to do anything! Things to watch out for:
* A transaction that doesn't match a partial transaction built or proposed earlier in the protocol, for instance,
if you propose to trade a cash state worth $100 for an asset, and the transaction to sign comes back from the
other side, you must check that it points to the state you actually requested. Otherwise the attacker could
get you to sign a transaction that spends a much larger state to you, if they know the ID of one!
* A transaction that isn't of the right type. There are two transaction types: general and notary change. If you
are expecting one type but get the other you may find yourself signing a transaction that transfers your assets
to the control of a hostile notary.
* Unexpected changes in any part of the states in a transaction. If you have access to all the needed data, you
could re-run the builder logic and do a comparison of the resulting states to ensure that it's what you expected.
For instance if the data needed to construct the next state is available to both parties, the function to
calculate the transaction you want to mutually agree could be shared between both classes implementing both
sides of the protocol.
The theme should be clear: signing is a very sensitive operation, so you need to be sure you know what it is you
are about to sign, and that nothing has changed in the small print!
Contracts
---------
Contracts are arbitrary functions inside a JVM sandbox and therefore they have a lot of leeway to shoot themselves
in the foot. Things to watch out for:
* Changes in states that should not be allowed by the current state transition. You will want to check that no
fields are changing except the intended fields!
* Accidentally catching and discarding exceptions that might be thrown by validation logic.
* Calling into other contracts via virtual methods if you don't know what those other contracts are or might do.

204
docs/build/html/_sources/transaction-data-types.txt vendored
View File

@ -1,204 +0,0 @@
Data types
==========
Corda provides a large standard library of data types used in financial transactions and contract state objects.
These provide a common language for states and contracts.
Amount
------
The `Amount <api/com.r3corda.core.contracts/-amount/index.html>`_ class is used to represent an amount of some
fungible asset. It is a generic class which wraps around a type used to define the underlying product, called
the *token*. For instance it can be the standard JDK type ``Currency``, or an ``Issued`` instance, or this can be
a more complex type such as an obligation contract issuance definition (which in turn contains a token definition
for whatever the obligation is to be settled in).
.. note:: Fungible is used here to mean that instances of an asset is interchangeable for any other identical instance,
and that they can be split/merged. For example a £5 note can reasonably be exchanged for any other £5 note, and a
£10 note can be exchanged for two £5 notes, or vice-versa.
Here are some examples:
.. container:: codeset
.. sourcecode:: kotlin
// A quantity of some specific currency like pounds, euros, dollars etc.
Amount<Currency>
// A quantity of currency that is issued by a specific issuer, for instance central bank vs other bank dollars
Amount<Issued<Currency>>
// A quantity of obligations to deliver currency of any issuer.
Amount<Obligation.State<Currency>>
``Amount`` represents quantities as integers. For currencies the quantity represents pennies, cents or whatever
else the smallest integer amount for that currency is. You cannot use ``Amount`` to represent negative quantities
or fractional quantities: if you wish to do this then you must use a different type e.g. ``BigDecimal``. ``Amount``
defines methods to do addition and subtraction and these methods verify that the tokens on both sides of the operator
are equal (these are operator overloads in Kotlin and can be used as regular methods from Java). There are also
methods to do multiplication and division by integer amounts.
State
-----
A Corda contract is composed of three parts; the executable code, the legal prose, and the state objects that represent
the details of a specific deal or asset (see :doc:`data-model` for further detail). In relational database terms
a state is like a row in a database. A reference to a state in the ledger (whether it has been consumed or not)
is represented with a ``StateRef`` object. If the state ref has been looked up from storage, you will have a
``StateAndRef`` which is simply a ``StateRef`` plus the data.
The ``ContractState`` type is an interface that all states must implement. A ``TransactionState`` is a simple
container for a ``ContractState`` (the custom data used by a contract program) and additional platform-level state
information, such as the *notary* pointer (see :doc:`consensus`).
A number of interfaces then extend ``ContractState``, representing standardised functionality for common kinds
of state:
``OwnableState``
A state which has an owner (represented as a ``PublicKey``, discussed later). Exposes the owner and a function
for replacing the owner e.g. when an asset is sold.
``LinearState``
A state which links back to its previous state, creating a thread of states over time. A linear state is
useful when modelling an indivisible/non-fungible thing like a specific deal, or an asset that can't be
split (like a rare piece of art).
``DealState``
A LinearState representing an agreement between two or more parties. Intended to simplify implementing generic
protocols that manipulate many agreement types.
``FixableDealState``
A deal state, with further functions exposed to support fixing of interest rates.
NamedByHash and UniqueIdentifier
--------------------------------
Things which are identified by their hash, like transactions and attachments, should implement the ``NamedByHash``
interface which standardises how the ID is extracted. Note that a hash is *not* a globally unique identifier: it
is always a derivative summary of the contents of the underlying data. Sometimes this isn't what you want:
two deals that have exactly the same parameters and which are made simultaneously but which are logically different
can't be identified by hash because their contents would be identical. Instead you would use ``UniqueIdentifier``.
This is a combination of a (Java) ``UUID`` representing a globally unique 128 bit random number, and an arbitrary
string which can be paired with it. For instance the string may represent an existing "weak" (not guaranteed unique)
identifier for convenience purposes.
FungibleAssets and Cash
-----------------------
There is a common ``FungibleAsset`` superclass for contracts which model fungible assets, which also provides a standard
interface for its subclasses' state objects to implement. The clear use-case is ``Cash``, however ``FungibleAsset`` is
intended to be readily extensible to cover other assets, for example commodities could be modelled by using a subclass
whose state objects include further details (location of the commodity, origin, grade, etc.) as needed.
Transaction lifecycle types
---------------------------
The ``WireTransaction`` class contains the core of a transaction without signatures, and with references to attachments
in place of the attachments themselves (see also :doc:`data-model`). Once signed these are encapsulated in the
``SignedTransaction`` class. For processing a transaction (i.e. to verify it) it is first converted to a
``LedgerTransaction``, which involves verifying the signatures and associating them to the relevant command(s), and
resolving the attachment references to the attachments. Commands with valid signatures are encapsulated in the
``AuthenticatedObject`` type.
.. note:: A ``LedgerTransaction`` has not necessarily had its contracts be run, and thus could be contract-invalid
(but not signature-invalid). You can use the ``verify`` method as shown below to run the contracts.
When constructing a new transaction from scratch, you use ``TransactionBuilder``, which is a mutable transaction that
can be signed once modification of the internals is complete. It is typical for contract classes to expose helper
methods that can contribute to a ``TransactionBuilder``.
Here's an example of building a transaction that creates an issuance of bananas (note that bananas are not a real
contract type in the library):
.. container:: codeset
.. sourcecode:: kotlin
val notaryToUse: Party = ...
val txb = TransactionBuilder(notary = notaryToUse).withItems(BananaState(Amount(20, Bananas), fromCountry = "Elbonia"))
txb.signWith(myKey)
txb.setTime(Instant.now(), notaryToUse, 30.seconds)
// We must disable the check for sufficient signatures, because this transaction is not yet notarised.
val stx = txb.toSignedTransaction(checkSufficientSignatures = false)
// Alternatively, let's just check it verifies pretending it was fully signed. To do this, we get
// a WireTransaction, which is what the SignedTransaction wraps. Thus by verifying that directly we
// skip signature checking.
txb.toWireTransaction().toLedgerTransaction(services).verify()
In a unit test, you would typically use a freshly created ``MockServices`` object, or more realistically, you would
write your tests using the :doc:`domain specific language for writing tests <tutorial-test-dsl>`.
Party and PublicKey
-------------------
Entities using the network are called *parties*. Parties can sign structures using keys, and a party may have many
keys under their control.
Parties may sometimes be identified pseudonomously, for example, in a transaction sent to your node as part of a
chain of custody it is important you can convince yourself of the transaction's validity, but equally important that
you don't learn anything about who was involved in that transaction. In these cases a public key may be present
without any identifying information about who owns it.
Identities of parties involved in signing a transaction can be represented simply by a ``PublicKey``, or by further
information (such as name) using the ``Party`` class. An ``AuthenticatedObject`` represents an object (like a command)
that has been signed by a set of parties.
.. note:: These types are provisional and will change significantly in future as the identity framework becomes more
fleshed out.
Multi-signature support
-----------------------
Corda supports scenarios where more than one key or party is required to authorise a state object transition, for example:
"Either the CEO or 3 out of 5 of his assistants need to provide signatures".
Key Trees
^^^^^^^^^
This is achieved by public key composition, using a tree data structure ``PublicKeyTree``. A ``PublicKeyTree`` stores the
cryptographic public key primitives in its leaves and the composition logic in the intermediary nodes. Every intermediary
node specifies a *threshold* of how many child signatures it requires.
An illustration of an *"either Alice and Bob, or Charlie"* public key tree:
.. image:: resources/public-key-tree.png
:width: 300px
To allow further flexibility, each child node can have an associated custom *weight* (the default is 1). The *threshold*
then specifies the minimum total weight of all children required. Our previous example can also be expressed as:
.. image:: resources/public-key-tree-2.png
:width: 300px
Verification
^^^^^^^^^^^^
Signature verification is performed in two stages:
1. Given a list of signatures, each signature is verified against the expected content.
2. The public keys corresponding to the signatures are matched against the leaves of the public key tree in question,
and the total combined weight of all children is calculated for every intermediary node. If all thresholds are satisfied,
the public key tree requirement is considered to be met.
Date support
------------
There are a number of supporting interfaces and classes for use by contract which deal with dates (especially in the
context of deadlines). As contract negotiation typically deals with deadlines in terms such as "overnight", "T+3",
etc., it's desirable to allow conversion of these terms to their equivalent deadline. ``Tenor`` models the interval
before a deadline, such as 3 days, etc., while ``DateRollConvention`` describes how deadlines are modified to take
into account bank holidays or other events that modify normal working days.
Calculating the rollover of a deadline based on working days requires information on the bank holidays involved
(and where a contract's parties are in different countries, for example, this can involve multiple separate sets of
bank holidays). The ``BusinessCalendar`` class models these calendars of business holidays; currently it loads these
from files on disk, but in future this is likely to involve reference data oracles in order to ensure consensus on the
dates used.
Cryptography & maths support
----------------------------
The ``SecureHash`` class represents a secure hash of unknown algorithm. We currently define only a single subclass,
``SecureHash.SHA256``. There are utility methods to create them, parse them and so on.
We also provide some mathematical utilities, in particular a set of interpolators and classes for working with
splines. These can be found in the `maths package <api/com.r3corda.core.math/index.html>`_.

99
docs/build/html/_sources/tutorial-attachments.txt vendored
View File

@ -1,99 +0,0 @@
.. highlight:: kotlin
.. raw:: html
Using attachments
=================
Attachments are (typically large) Zip/Jar files referenced within a transaction, but not included in the transaction
itself. These files can be requested from the originating node as needed, although in many cases will be cached within
nodes already. Examples include:
* Contract executable code
* Metadata about a transaction, such as PDF version of an invoice being settled
* Shared information to be permanently recorded on the ledger
To add attachments the file must first be added to the node's storage service using ``StorageService.importAttachment()``,
which returns a unique ID that can be added using ``TransactionBuilder.addAttachment()``. Attachments can also be
uploaded and downloaded via HTTP, to enable integration with external systems. For instructions on HTTP upload/download
please see ":doc:`node-administration`".
Normally attachments on transactions are fetched automatically via the ``ResolveTransactionsProtocol`` when verifying
received transactions. Attachments are needed in order to validate a transaction (they include, for example, the
contract code), so must be fetched before the validation process can run. ``ResolveTransactionsProtocol`` calls
``FetchTransactionsProtocol`` to perform the actual retrieval.
It is encouraged that where possible attachments are reusable data, so that nodes can meaningfully cache them.
Attachments demo
----------------
There is a worked example of attachments, which relays a simple document from one node to another. The "two party
trade protocol" also includes an attachment, however it is a significantly more complex demo, and less well suited
for a tutorial.
The demo code is in the file "src/main/kotlin/com/r3corda/demos/attachment/AttachmentDemo.kt", with the core logic
contained within the two functions ``runRecipient()`` and ``runSender()``. We'll look at the recipient function first;
this subscribes to notifications of new validated transactions, and if it receives a transaction containing attachments,
loads the first attachment from storage, and checks it matches the expected attachment ID. ``ResolveTransactionsProtocol``
has already fetched all attachments from the remote node, and as such the attachments are available from the node's
storage service. Once the attachment is verified, the node shuts itself down.
.. sourcecode:: kotlin
private fun runRecipient(node: Node) {
val serviceHub = node.services
// Normally we would receive the transaction from a more specific protocol, but in this case we let [FinalityProtocol]
// handle receiving it for us.
serviceHub.storageService.validatedTransactions.updates.subscribe { event ->
// When the transaction is received, it's passed through [ResolveTransactionsProtocol], which first fetches any
// attachments for us, then verifies the transaction. As such, by the time it hits the validated transaction store,
// we have a copy of the attachment.
val tx = event.tx
if (tx.attachments.isNotEmpty()) {
val attachment = serviceHub.storageService.attachments.openAttachment(tx.attachments.first())
assertEquals(PROSPECTUS_HASH, attachment?.id)
println("File received - we're happy!\n\nFinal transaction is:\n\n${Emoji.renderIfSupported(event.tx)}")
thread {
node.stop()
}
}
}
}
The sender correspondingly builds a transaction with the attachment, then calls ``FinalityProtocol`` to complete the
transaction and send it to the recipient node:
.. sourcecode:: kotlin
private fun runSender(node: Node, otherSide: Party) {
val serviceHub = node.services
// Make sure we have the file in storage
if (serviceHub.storageService.attachments.openAttachment(PROSPECTUS_HASH) == null) {
com.r3corda.demos.Role::class.java.getResourceAsStream("bank-of-london-cp.jar").use {
val id = node.storage.attachments.importAttachment(it)
assertEquals(PROSPECTUS_HASH, id)
}
}
// Create a trivial transaction that just passes across the attachment - in normal cases there would be
// inputs, outputs and commands that refer to this attachment.
val ptx = TransactionType.General.Builder(notary = null)
ptx.addAttachment(serviceHub.storageService.attachments.openAttachment(PROSPECTUS_HASH)!!.id)
// Despite not having any states, we have to have at least one signature on the transaction
ptx.signWith(ALICE_KEY)
// Send the transaction to the other recipient
val tx = ptx.toSignedTransaction()
serviceHub.startProtocol(LOG_SENDER, FinalityProtocol(tx, emptySet(), setOf(otherSide))).success {
thread {
Thread.sleep(1000L) // Give the other side time to request the attachment
node.stop()
}
}.failure {
println("Failed to relay message ")
}
}

83
docs/build/html/_sources/tutorial-clientrpc-api.txt vendored
View File

@ -1,83 +0,0 @@
.. _graphstream: http://graphstream-project.org/
Client RPC API
==============
In this tutorial we will build a simple command line utility that connects to a node and dumps the transaction graph to
the standard output. We will then put some simple visualisation on top. For an explanation on how the RPC works see
:doc:`clientrpc`.
We start off by connecting to the node itself. For the purposes of the tutorial we will run the Trader demo on some
local port and connect to the Buyer side. We will pass in the address as a command line argument. To connect to the node
we also need to access the certificates of the node, we will access the node's ``certificates`` directory directly.
.. literalinclude:: example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt
:language: kotlin
:start-after: START 1
:end-before: END 1
Now we can connect to the node itself using a valid RPC login. By default the user `user1` is available with password `test`.
.. literalinclude:: example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt
:language: kotlin
:start-after: START 2
:end-before: END 2
``proxy`` now exposes the full RPC interface of the node:
.. literalinclude:: ../../node/src/main/kotlin/com/r3corda/node/services/messaging/CordaRPCOps.kt
:language: kotlin
:start-after: interface CordaRPCOps
:end-before: }
The one we need in order to dump the transaction graph is ``verifiedTransactions``. The type signature tells us that the
RPC will return a list of transactions and an Observable stream. This is a general pattern, we query some data and the
node will return the current snapshot and future updates done to it.
.. literalinclude:: example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt
:language: kotlin
:start-after: START 3
:end-before: END 3
The graph will be defined by nodes and edges between them. Each node represents a transaction and edges represent
output-input relations. For now let's just print ``NODE <txhash>`` for the former and ``EDGE <txhash> <txhash>`` for the
latter.
.. literalinclude:: example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt
:language: kotlin
:start-after: START 4
:end-before: END 4
Now we can start the trader demo as per described in :doc:`running-the-demos`::
# Build the demo
./gradlew installDist
# Start the buyer
./build/install/r3prototyping/bin/trader-demo --role=BUYER
In another terminal we can connect to it with our client::
# Connect to localhost:31337
./docs/source/example-code/build/install/docs/source/example-code/bin/client-rpc-tutorial localhost:31337 Print
We should see some ``NODE``-s printed. This is because the buyer self-issues some cash for the demo.
Unless we ran the seller before we shouldn't see any ``EDGE``-s because the cash hasn't been spent yet.
In another terminal we can now start the seller::
# Start sellers in a loop
for i in {0..9} ; do ./build/install/r3prototyping/bin/trader-demo --role=SELLER ; done
We should start seeing new ``NODE``-s and ``EDGE``-s appearing.
Now let's try to visualise the transaction graph. We will use a graph drawing library called graphstream_
.. literalinclude:: example-code/src/main/kotlin/com/r3corda/docs/ClientRpcTutorial.kt
:language: kotlin
:start-after: START 5
:end-before: END 5
If we run the client with ``Visualise`` we should see a simple graph being drawn as new transactions are being created
by the seller runs.
That's it! We saw how to connect to the node and stream data from it.

194
docs/build/html/_sources/tutorial-contract-clauses.txt vendored
View File

@ -1,194 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Writing a contract using clauses
================================
This tutorial will take you through restructuring the commercial paper contract to use clauses. You should have
already completed ":doc:`tutorial-contract`".
Clauses are essentially micro-contracts which contain independent verification logic, and can be logically composed
together to form a contract. Clauses are designed to enable re-use of common logic, for example issuing state objects
is generally the same for all fungible contracts, so a common issuance clause can be inherited for each contract's
issue clause. This cuts down on scope for error, and improves consistency of behaviour. By splitting verification logic
into smaller chunks, they can also be readily tested in isolation.
Clauses can be composed of subclauses, for example the ``AllClause`` or ``AnyClause`` clauses take list of clauses
that they delegate to. Clauses can also change the scope of states and commands being verified, for example grouping
together fungible state objects and running a clause against each distinct group.
The commercial paper contract has a ``Group`` outermost clause, which contains the ``Issue``, ``Move`` and ``Redeem``
clauses. The result is a contract that looks something like this:
1. Group input and output states together, and then apply the following clauses on each group:
a. If an ``Issue`` command is present, run appropriate tests and end processing this group.
b. If a ``Move`` command is present, run appropriate tests and end processing this group.
c. If a ``Redeem`` command is present, run appropriate tests and end processing this group.
Commercial paper class
----------------------
To use the clause verification logic, the contract needs to call the ``verifyClause`` function, passing in the
transaction, a clause to verify, and a collection of commands the clauses are expected to handle all of. This list of
commands is important because ``verifyClause`` checks that none of the commands are left unprocessed at the end, and
raises an error if they are. The top level clause would normally be a composite clause (such as ``AnyComposition``,
``AllComposition``, etc.) which contains further clauses. The following examples are trimmed to the modified class
definition and added elements, for brevity:
.. container:: codeset
.. sourcecode:: kotlin
class CommercialPaper : Contract {
override val legalContractReference: SecureHash = SecureHash.sha256("https://en.wikipedia.org/wiki/Commercial_paper")
override fun verify(tx: TransactionForContract) = verifyClause(tx, Clauses.Group(), tx.commands.select<Commands>())
.. sourcecode:: java
public class CommercialPaper implements Contract {
@Override
public SecureHash getLegalContractReference() {
return SecureHash.Companion.sha256("https://en.wikipedia.org/wiki/Commercial_paper");
}
@Override
public void verify(@NotNull TransactionForContract tx) throws IllegalArgumentException {
ClauseVerifier.verifyClause(tx, new Clauses.Group(), extractCommands(tx));
}
Clauses
-------
We'll tackle the inner clauses that contain the bulk of the verification logic, first, and the clause which handles
grouping of input/output states later. The clauses must extend the ``Clause`` abstract class, which defines
the ``verify`` function, and the ``requiredCommands`` property used to determine the conditions under which a clause
is triggered. Composite clauses should extend the ``CompositeClause`` abstract class, which extends ``Clause`` to
add support for wrapping around multiple clauses.
The ``verify`` function defined in the ``Clause`` interface is similar to the conventional ``Contract`` verification
function, although it adds new parameters and returns the set of commands which it has processed. Normally this returned
set is identical to the ``requiredCommands`` used to trigger the clause, however in some cases the clause may process
further optional commands which it needs to report that it has handled.
The ``Move`` clause for the commercial paper contract is relatively simple, so we will start there:
.. container:: codeset
.. sourcecode:: kotlin
class Move: Clause<State, Commands, Issued<Terms>>() {
override val requiredCommands: Set<Class<out CommandData>>
get() = setOf(Commands.Move::class.java)
override fun verify(tx: TransactionForContract,
inputs: List<State>,
outputs: List<State>,
commands: List<AuthenticatedObject<Commands>>,
groupingKey: Issued<Terms>?): Set<Commands> {
val command = commands.requireSingleCommand<Commands.Move>()
val input = inputs.single()
requireThat {
"the transaction is signed by the owner of the CP" by (input.owner in command.signers)
"the state is propagated" by (outputs.size == 1)
// Don't need to check anything else, as if outputs.size == 1 then the output is equal to
// the input ignoring the owner field due to the grouping.
}
return setOf(command.value)
}
}
.. sourcecode:: java
class Move extends Clause<State, Commands, State> {
@NotNull
@Override
public Set<Class<? extends CommandData>> getRequiredCommands() {
return Collections.singleton(Commands.Move.class);
}
@NotNull
@Override
public Set<Commands> verify(@NotNull TransactionForContract tx,
@NotNull List<? extends State> inputs,
@NotNull List<? extends State> outputs,
@NotNull List<? extends AuthenticatedObject<? extends Commands>> commands,
@NotNull State groupingKey) {
AuthenticatedObject<Commands.Move> cmd = requireSingleCommand(tx.getCommands(), Commands.Move.class);
// There should be only a single input due to aggregation above
State input = single(inputs);
if (!cmd.getSigners().contains(input.getOwner()))
throw new IllegalStateException("Failed requirement: the transaction is signed by the owner of the CP");
// Check the output CP state is the same as the input state, ignoring the owner field.
if (outputs.size() != 1) {
throw new IllegalStateException("the state is propagated");
}
// Don't need to check anything else, as if outputs.size == 1 then the output is equal to
// the input ignoring the owner field due to the grouping.
return Collections.singleton(cmd.getValue());
}
}
Group Clause
------------
We need to wrap the move clause (as well as the issue and redeem clauses - see the relevant contract code for their
full specifications) in an outer clause that understands how to group contract states and objects. For this we extend
the standard ``GroupClauseVerifier`` and specify how to group input/output states, as well as the top-level to run on
each group. As with the top level clause on a contract, this is normally a composite clause that delegates to subclauses.
.. container:: codeset
.. sourcecode:: kotlin
class Group : GroupClauseVerifier<State, Commands, Issued<Terms>>(
AnyComposition(
Redeem(),
Move(),
Issue())) {
override fun groupStates(tx: TransactionForContract): List<TransactionForContract.InOutGroup<State, Issued<Terms>>>
= tx.groupStates<State, Issued<Terms>> { it.token }
}
.. sourcecode:: java
class Group extends GroupClauseVerifier<State, Commands, State> {
public Group() {
super(new AnyComposition<>(
new Clauses.Redeem(),
new Clauses.Move(),
new Clauses.Issue()
));
}
@NotNull
@Override
public List<InOutGroup<State, State>> groupStates(@NotNull TransactionForContract tx) {
return tx.groupStates(State.class, State::withoutOwner);
}
}
For the ``CommercialPaper`` contract, this is the top level clause for the contract, and is passed directly into
``verifyClause`` (see the example code at the top of this tutorial).
Summary
-------
In summary the top level contract ``CommercialPaper`` specifies a single grouping clause of type
``CommercialPaper.Clauses.Group`` which in turn specifies ``GroupClause`` implementations for each type of command
(``Redeem``, ``Move`` and ``Issue``). This reflects the flow of verification: In order to verify a ``CommercialPaper``
we first group states, check which commands are specified, and run command-specific verification logic accordingly.
Debugging
---------
Debugging clauses which have been composed together can be complicated due to the difficulty in knowing which clauses
have been matched, whether specific clauses failed to match or passed verification, etc. There is "trace" level
logging code in the clause verifier which evaluates which clauses will be matched and logs them, before actually
performing the validation. To enable this, ensure trace level logging is enabled on the ``Clause`` interface.

803
docs/build/html/_sources/tutorial-contract.txt vendored
View File

@ -1,803 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Writing a contract
==================
This tutorial will take you through how the commercial paper contract works. This uses a simple contract structure of
everything being in one contract class, while most actual contracts in Corda are broken into clauses (which we'll
discuss in the next tutorial). Clauses help reduce tedious boilerplate, but it's worth understanding how a
contract is built without them before starting.
You can see the full Kotlin version of this contract in the code as ``CommercialPaperLegacy``. The code in this
tutorial is available in both Kotlin and Java. You can quickly switch between them to get a feeling for how
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
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.
Starting the commercial paper class
-----------------------------------
A smart contract is a class that implements the ``Contract`` interface. This can be either implemented directly, or
by subclassing an abstract contract such as ``OnLedgerAsset``.
.. container:: codeset
.. sourcecode:: kotlin
class CommercialPaper : Contract {
override val legalContractReference: SecureHash = SecureHash.sha256("https://en.wikipedia.org/wiki/Commercial_paper");
override fun verify(tx: TransactionForVerification) {
TODO()
}
}
.. sourcecode:: java
public class CommercialPaper implements Contract {
@Override
public SecureHash getLegalContractReference() {
return SecureHash.Companion.sha256("https://en.wikipedia.org/wiki/Commercial_paper");
}
@Override
public void verify(TransactionForVerification tx) {
throw new UnsupportedOperationException();
}
}
Every contract must have at least a ``getLegalContractReference()`` and a ``verify()`` method. In Kotlin we express
a getter without a setter as an immutable property (val). The *legal contract reference* is supposed to be a hash
of a document that describes the legal contract and may take precedence over the code, in case of a dispute.
.. note:: The way legal contract prose is bound to a smart contract implementation will change in future.
The verify method returns nothing. This is intentional: the function either completes correctly, or throws an exception,
in which case the transaction is rejected.
So far, so simple. Now we need to define the commercial paper *state*, which represents the fact of ownership of a
piece of issued paper.
States
------
A state is a class that stores data that is checked by the contract.
.. container:: codeset
.. sourcecode:: kotlin
data class State(
val issuance: PartyAndReference,
override val owner: PublicKey,
val faceValue: Amount<Issued<Currency>>,
val maturityDate: Instant
) : OwnableState {
override val contract = CommercialPaper()
override val participants = listOf(owner)
fun withoutOwner() = copy(owner = NullPublicKey)
override fun withNewOwner(newOwner: PublicKey) = Pair(Commands.Move(), copy(owner = newOwner))
}
.. sourcecode:: java
public static class State implements OwnableState {
private PartyAndReference issuance;
private PublicKey owner;
private Amount<Issued<Currency>> faceValue;
private Instant maturityDate;
public State() {
} // For serialization
public State(PartyAndReference issuance, PublicKey owner, Amount<Issued<Currency>> faceValue,
Instant maturityDate) {
this.issuance = issuance;
this.owner = owner;
this.faceValue = faceValue;
this.maturityDate = maturityDate;
}
public State copy() {
return new State(this.issuance, this.owner, this.faceValue, this.maturityDate);
}
@NotNull
@Override
public Pair<CommandData, OwnableState> withNewOwner(@NotNull PublicKey newOwner) {
return new Pair<>(new Commands.Move(), new State(this.issuance, newOwner, this.faceValue, this.maturityDate));
}
public PartyAndReference getIssuance() {
return issuance;
}
public PublicKey getOwner() {
return owner;
}
public Amount<Issued<Currency>> getFaceValue() {
return faceValue;
}
public Instant getMaturityDate() {
return maturityDate;
}
@NotNull
@Override
public Contract getContract() {
return new JavaCommercialPaper();
}
@Override
public boolean equals(Object o) {
if (this == o) return true;
if (o == null || getClass() != o.getClass()) return false;
State state = (State) o;
if (issuance != null ? !issuance.equals(state.issuance) : state.issuance != null) return false;
if (owner != null ? !owner.equals(state.owner) : state.owner != null) return false;
if (faceValue != null ? !faceValue.equals(state.faceValue) : state.faceValue != null) return false;
return !(maturityDate != null ? !maturityDate.equals(state.maturityDate) : state.maturityDate != null);
}
@Override
public int hashCode() {
int result = issuance != null ? issuance.hashCode() : 0;
result = 31 * result + (owner != null ? owner.hashCode() : 0);
result = 31 * result + (faceValue != null ? faceValue.hashCode() : 0);
result = 31 * result + (maturityDate != null ? maturityDate.hashCode() : 0);
return result;
}
@NotNull
@Override
public List<PublicKey> getParticipants() {
return ImmutableList.of(this.owner);
}
}
We define a class that implements the ``ContractState`` interface.
The ``ContractState`` interface requires us to provide a ``getContract`` method that returns an instance of the
contract class itself. In future, this will change to support dynamic loading of contracts with versioning
and signing constraints, but for now this is how it's written.
We have four fields in our state:
* ``issuance``, a reference to a specific piece of commercial paper issued by some party.
* ``owner``, the public key of the current owner. This is the same concept as seen in Bitcoin: the public key has no
attached identity and is expected to be one-time-use for privacy reasons. However, unlike in Bitcoin, we model
ownership at the level of individual states rather than as a platform-level concept as we envisage many
(possibly most) contracts on the platform will not represent "owner/issuer" relationships, but "party/party"
relationships such as a derivative contract.
* ``faceValue``, an ``Amount<Issued<Currency>>``, which wraps an integer number of pennies and a currency that is
specific to some issuer (e.g. a regular bank, a central bank, etc). You can read more about this very common
type in :doc:`transaction-data-types`.
* ``maturityDate``, an `Instant <https://docs.oracle.com/javase/8/docs/api/java/time/Instant.html>`_, which is a type
from the Java 8 standard time library. It defines a point on the timeline.
States are immutable, and thus the class is defined as immutable as well. The ``data`` modifier in the Kotlin version
causes the compiler to generate the equals/hashCode/toString methods automatically, along with a copy method that can
be used to create variants of the original object. Data classes are similar to case classes in Scala, if you are
familiar with that language. The ``withoutOwner`` method uses the auto-generated copy method to return a version of
the state with the owner public key blanked out: this will prove useful later.
The Java code compiles to almost identical bytecode as the Kotlin version, but as you can see, is much more verbose.
Commands
--------
The logic for a contract may vary depending on what stage of a lifecycle it is automating. So it can be useful to
pass additional data into the contract code that isn't represented by the states which exist permanently in the ledger.
For this purpose we have commands. Often they don't need to contain any data at all, they just need to exist. A command
is a piece of data associated with some *signatures*. By the time the contract runs the signatures have already been
checked, so from the contract code's perspective, a command is simply a data structure with a list of attached
public keys. Each key had a signature proving that the corresponding private key was used to sign. Because of this
approach contracts never actually interact or work with digital signatures directly.
Let's define a few commands now:
.. container:: codeset
.. sourcecode:: kotlin
interface Commands : CommandData {
class Move : TypeOnlyCommandData(), Commands
class Redeem : TypeOnlyCommandData(), Commands
class Issue : TypeOnlyCommandData(), Commands
}
.. sourcecode:: java
public static class Commands implements core.contract.Command {
public static class Move extends Commands {
@Override
public boolean equals(Object obj) {
return obj instanceof Move;
}
}
public static class Redeem extends Commands {
@Override
public boolean equals(Object obj) {
return obj instanceof Redeem;
}
}
public static class Issue extends Commands {
@Override
public boolean equals(Object obj) {
return obj instanceof Issue;
}
}
}
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
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.
The verify function
-------------------
The heart of a smart contract is the code that verifies a set of state transitions (a *transaction*). The function is
simple: it's given a class representing the transaction, and if the function returns then the transaction is considered
acceptable. If it throws an exception, the transaction is rejected.
Each transaction can have multiple input and output states of different types. The set of contracts to run is decided
by taking the code references inside each state. Each contract is run only once. As an example, a contract that includes
2 cash states and 1 commercial paper state as input, and has as output 1 cash state and 1 commercial paper state, will
run two contracts one time each: Cash and CommercialPaper.
.. container:: codeset
.. sourcecode:: kotlin
override fun verify(tx: TransactionForContract) {
// Group by everything except owner: any modification to the CP at all is considered changing it fundamentally.
val groups = tx.groupStates(State::withoutOwner)
// There are two possible things that can be done with this CP. The first is trading it. The second is redeeming
// it for cash on or after the maturity date.
val command = tx.commands.requireSingleCommand<CommercialPaper.Commands>()
.. sourcecode:: java
@Override
public void verify(TransactionForContract tx) {
List<InOutGroup<State, State>> groups = tx.groupStates(State.class, State::withoutOwner);
AuthenticatedObject<Command> cmd = requireSingleCommand(tx.getCommands(), Commands.class);
We start by using the ``groupStates`` method, which takes a type and a function. State grouping is a way of ensuring
your contract can handle multiple unrelated states of the same type in the same transaction, which is needed for
splitting/merging of assets, atomic swaps and so on. More on this next.
The second line does what the code suggests: it searches for a command object that inherits from the
``CommercialPaper.Commands`` supertype, and either returns it, or throws an exception if there's zero or more than one
such command.
Using state groups
------------------
The simplest way to write a smart contract would be to say that each transaction can have a single input state and a
single output state of the kind govered by that contract. This would be easy for the developer, but would prevent many
important use cases.
The next easiest way to write a contract would be to iterate over each input state and expect it to have an output
state. Now you can build a single transaction that, for instance, moves two different cash states in different currencies
simultaneously. But it gets complicated when you want to issue or exit one state at the same time as moving another.
Things get harder still once you want to split and merge states. We say states are *fungible* if they are
treated identically to each other by the recipient, despite the fact that they aren't quite identical. Dollar bills are
fungible because even though one may be worn/a bit dirty and another may be crisp and new, they are still both worth
exactly $1. Likewise, ten $1 bills are almost exactly equivalent to one $10 bill. On the other hand, $10 and £10 are not
fungible: if you tried to pay for something that cost £20 with $10+£10 notes your trade would not be accepted.
To make all this easier the contract API provides a notion of groups. A group is a set of input states and output states
that should be checked for validity together.
Consider the following simplified currency trade transaction:
* **Input**: $12,000 owned by Alice (A)
* **Input**: $3,000 owned by Alice (A)
* **Input**: £10,000 owned by Bob (B)
* **Output**: £10,000 owned by Alice (B)
* **Output**: $15,000 owned by Bob (A)
In this transaction Alice and Bob are trading $15,000 for £10,000. Alice has her money in the form of two different
inputs e.g. because she received the dollars in two payments. The input and output amounts do balance correctly, but
the cash smart contract must consider the pounds and the dollars separately because they are not fungible: they cannot
be merged together. So we have two groups: A and B.
The ``TransactionForContract.groupStates`` method handles this logic for us: firstly, it selects only states of the
given type (as the transaction may include other types of state, such as states representing bond ownership, or a
multi-sig state) and then it takes a function that maps a state to a grouping key. All states that share the same key are
grouped together. In the case of the cash example above, the grouping key would be the currency.
In this kind of contract we don't want CP to be fungible: merging and splitting is (in our example) not allowed.
So we just use a copy of the state minus the owner field as the grouping key.
Here are some code examples:
.. container:: codeset
.. sourcecode:: kotlin
// Type of groups is List<InOutGroup<State, Pair<PartyReference, Currency>>>
val groups = tx.groupStates() { it: Cash.State -> Pair(it.deposit, it.amount.currency) }
for ((inputs, outputs, key) in groups) {
// Either inputs or outputs could be empty.
val (deposit, currency) = key
...
}
.. sourcecode:: java
List<InOutGroup<State, Pair<PartyReference, Currency>>> groups = tx.groupStates(Cash.State.class, s -> Pair(s.deposit, s.amount.currency))
for (InOutGroup<State, Pair<PartyReference, Currency>> group : groups) {
List<State> inputs = group.getInputs();
List<State> outputs = group.getOutputs();
Pair<PartyReference, Currency> key = group.getKey();
...
}
The ``groupStates`` call uses the provided function to calculate a "grouping key". All states that have the same
grouping key are placed in the same group. A grouping key can be anything that implements equals/hashCode, but it's
always an aggregate of the fields that shouldn't change between input and output. In the above example we picked the
fields we wanted and packed them into a ``Pair``. It returns a list of ``InOutGroup``, which is just a holder for the
inputs, outputs and the key that was used to define the group. In the Kotlin version we unpack these using destructuring
to get convenient access to the inputs, the outputs, the deposit data and the currency. The Java version is more
verbose, but equivalent.
The rules can then be applied to the inputs and outputs as if it were a single transaction. A group may have zero
inputs or zero outputs: this can occur when issuing assets onto the ledger, or removing them.
In this example, we do it differently and use the state class itself as the aggregator. We just
blank out fields that are allowed to change, making the grouping key be "everything that isn't that":
.. container:: codeset
.. sourcecode:: kotlin
val groups = tx.groupStates() { it: State -> it.withoutOwner() }
.. sourcecode:: java
List<InOutGroup<State, State>> groups = tx.groupStates(State.class, State::withoutOwner);
For large states with many fields that must remain constant and only one or two that are really mutable, it's often
easier to do things this way than to specifically name each field that must stay the same. The ``withoutOwner`` function
here simply returns a copy of the object but with the ``owner`` field set to ``NullPublicKey``, which is just a public key
of all zeros. It's invalid and useless, but that's OK, because all we're doing is preventing the field from mattering
in equals and hashCode.
Checking the requirements
-------------------------
After extracting the command and the groups, we then iterate over each group and verify it meets the required business
logic.
.. container:: codeset
.. sourcecode:: kotlin
val timestamp: Timestamp? = tx.timestamp
for ((inputs, outputs, key) in groups) {
when (command.value) {
is Commands.Move -> {
val input = inputs.single()
requireThat {
"the transaction is signed by the owner of the CP" by (input.owner in command.signers)
"the state is propagated" by (group.outputs.size == 1)
// Don't need to check anything else, as if outputs.size == 1 then the output is equal to
// the input ignoring the owner field due to the grouping.
}
}
is Commands.Redeem -> {
// Redemption of the paper requires movement of on-ledger cash.
val input = inputs.single()
val received = tx.outputs.sumCashBy(input.owner)
val time = timestamp?.after ?: throw IllegalArgumentException("Redemptions must be timestamped")
requireThat {
"the paper must have matured" by (time >= input.maturityDate)
"the received amount equals the face value" by (received == input.faceValue)
"the paper must be destroyed" by outputs.isEmpty()
"the transaction is signed by the owner of the CP" by (input.owner in command.signers)
}
}
is Commands.Issue -> {
val output = outputs.single()
val time = timestamp?.before ?: throw IllegalArgumentException("Issuances must be timestamped")
requireThat {
// Don't allow people to issue commercial paper under other entities identities.
"output states are issued by a command signer" by (output.issuance.party.owningKey in command.signers)
"output values sum to more than the inputs" by (output.faceValue.quantity > 0)
"the maturity date is not in the past" by (time < output.maturityDate)
// Don't allow an existing CP state to be replaced by this issuance.
"can't reissue an existing state" by inputs.isEmpty()
}
}
else -> throw IllegalArgumentException("Unrecognised command")
}
}
.. sourcecode:: java
Timestamp time = tx.getTimestamp(); // Can be null/missing.
for (InOutGroup<State> group : groups) {
List<State> inputs = group.getInputs();
List<State> outputs = group.getOutputs();
// For now do not allow multiple pieces of CP to trade in a single transaction. Study this more!
State input = single(filterIsInstance(inputs, State.class));
checkState(cmd.getSigners().contains(input.getOwner()), "the transaction is signed by the owner of the CP");
if (cmd.getValue() instanceof JavaCommercialPaper.Commands.Move) {
checkState(outputs.size() == 1, "the state is propagated");
// Don't need to check anything else, as if outputs.size == 1 then the output is equal to
// the input ignoring the owner field due to the grouping.
} else if (cmd.getValue() instanceof JavaCommercialPaper.Commands.Redeem) {
checkNotNull(timem "must be timestamped");
Instant t = time.getBefore();
Amount<Issued<Currency>> received = CashKt.sumCashBy(tx.getOutputs(), input.getOwner());
checkState(received.equals(input.getFaceValue()), "received amount equals the face value");
checkState(t.isBefore(input.getMaturityDate(), "the paper must have matured");
checkState(outputs.isEmpty(), "the paper must be destroyed");
} else if (cmd.getValue() instanceof JavaCommercialPaper.Commands.Issue) {
// .. etc .. (see Kotlin for full definition)
}
}
This loop is the core logic of the contract.
The first line simply gets the timestamp out of the transaction. Timestamping of transactions is optional, so a time
may be missing here. We check for it being null later.
.. note:: In future timestamping may be mandatory for all transactions.
.. warning:: In the Kotlin version as long as we write a comparison with the transaction time first the compiler will
verify we didn't forget to check if it's missing. Unfortunately due to the need for smooth Java interop, this
check won't happen if we write e.g. ``someDate > time``, it has to be ``time < someDate``. So it's good practice to
always write the transaction timestamp first.
The first line (first three lines in Java) impose a requirement that there be a single piece of commercial paper in
this group. We do not allow multiple units of CP to be split or merged even if they are owned by the same owner. The
``single()`` method is a static *extension method* defined by the Kotlin standard library: given a list, it throws an
exception if the list size is not 1, otherwise it returns the single item in that list. In Java, this appears as a
regular static method of the type familiar from many FooUtils type singleton classes and we have statically imported it
here. In Kotlin, it appears as a method that can be called on any JDK list. The syntax is slightly different but
behind the scenes, the code compiles to the same bytecodes.
Next, we check that the transaction was signed by the public key that's marked as the current owner of the commercial
paper. Because the platform has already verified all the digital signatures before the contract begins execution,
all we have to do is verify that the owner's public key was one of the keys that signed the transaction. The Java code
is straightforward: we are simply using the ``Preconditions.checkState`` method from Guava. The Kotlin version looks a little odd: we have a *requireThat* construct that looks like it's
built into the language. In fact *requireThat* is an ordinary function provided by the platform's contract API. Kotlin
supports the creation of *domain specific languages* through the intersection of several features of the language, and
we use it here to support the natural listing of requirements. To see what it compiles down to, look at the Java version.
Each ``"string" by (expression)`` statement inside a ``requireThat`` turns into an assertion that the given expression is
true, with an ``IllegalStateException`` being thrown that contains the string if not. It's just another way to write out a regular
assertion, but with the English-language requirement being put front and center.
Next, we take one of two paths, depending on what the type of the command object is.
If the command is a ``Move`` command, then we simply verify that the output state is actually present: a move is not
allowed to delete the CP from the ledger. The grouping logic already ensured that the details are identical and haven't
been changed, save for the public key of the owner.
If the command is a ``Redeem`` command, then the requirements are more complex:
1. We want to see that the face value of the CP is being moved as a cash claim against some party, that is, the
issuer of the CP is really paying back the face value.
2. The transaction must be happening after the maturity date.
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 function. Again, this is an extension function,
so in Kotlin code it appears as if it was a method on the ``List<Cash.State>`` 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
that given public key, or throws an exception if there were no such states *or* if there were different currencies
represented in the outputs! So we can see that this contract imposes a limitation on the structure of a redemption
transaction: you are not allowed to move currencies in the same transaction that the CP does not involve. This
limitation could be addressed with better APIs, if it were to be a real limitation.
Finally, we support an ``Issue`` command, to create new instances of commercial paper on the ledger. It likewise
enforces various invariants upon the issuance.
This contract is simple and does not implement all the business logic a real commercial paper lifecycle
management program would. For instance, there is no logic requiring a signature from the issuer for redemption:
it is assumed that any transfer of money that takes place at the same time as redemption is good enough. Perhaps
that is something that should be tightened. Likewise, there is no logic handling what happens if the issuer has gone
bankrupt, if there is a dispute, and so on.
As the prototype evolves, these requirements will be explored and this tutorial updated to reflect improvements in the
contracts API.
How to test your contract
-------------------------
Of course, it is essential to unit test your new nugget of business logic to ensure that it behaves as you expect.
As contract code is just a regular Java function you could write out the logic entirely by hand in the usual
manner. But this would be inconvenient, and then you'd get bored of writing tests and that would be bad: you
might be tempted to skip a few.
To make contract testing more convenient Corda provides a language-like API for both Kotlin and Java that lets
you easily construct chains of transactions and verify that they either pass validation, or fail with a particular
error message.
Testing contracts with this domain specific language is covered in the separate tutorial, :doc:`tutorial-test-dsl`.
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 *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).
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 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.
For our commercial paper contract however, the things that can be done with it are quite simple. Let's start with
a method to wrap up the issuance process:
.. container:: codeset
.. sourcecode:: kotlin
fun generateIssue(issuance: PartyAndReference, faceValue: Amount<Issued<Currency>>, maturityDate: Instant,
notary: Party): TransactionBuilder {
val state = State(issuance, issuance.party.owningKey, faceValue, maturityDate)
return TransactionBuilder(notary = notary).withItems(state, Command(Commands.Issue(), issuance.party.owningKey))
}
We take a reference that points to the issuing party (i.e. the caller) and which can contain any internal
bookkeeping/reference numbers that we may require. The reference field is an ideal place to put (for example) a
join key. Then the face value of the paper, and the maturity date. It returns a ``TransactionBuilder``.
A ``TransactionBuilder`` is one of the few mutable classes the platform provides. It allows you to add inputs,
outputs and commands to it and is designed to be passed around, potentially between multiple contracts.
.. 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,
an issuer should issue the CP (starting out owned by themselves), and then sell it in a separate transaction.
The function we define creates a ``CommercialPaper.State`` object that mostly just uses the arguments we were given,
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 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
any ``StateAndRef`` (input), ``ContractState`` (output) or ``Command`` objects and it'll build up the transaction
for you.
There's one final thing to be aware of: we ask the caller to select a *notary* that controls this state and
prevents it from being double spent. You can learn more about this topic in the :doc:`consensus` article.
.. note:: For now, don't worry about how to pick a notary. More infrastructure will come later to automate this
decision for you.
What about moving the paper, i.e. reassigning ownership to someone else?
.. container:: codeset
.. sourcecode:: kotlin
fun generateMove(tx: TransactionBuilder, paper: StateAndRef<State>, newOwner: PublicKey) {
tx.addInputState(paper)
tx.addOutputState(paper.state.data.withOwner(newOwner))
tx.addCommand(Command(Commands.Move(), paper.state.data.owner))
}
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
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<CommercialPaper.State>`` object. This is exactly what it sounds like:
a small object that has a (copy of) a state object, and also the (txhash, index) that indicates the location of this
state on the ledger.
We add the existing paper state as an input, the same paper state with the owner field adjusted as an output,
and finally a move command that has the old owner's public key: this is what forces the current owner's signature
to be present on the transaction, and is what's checked by the contract.
Finally, we can do redemption.
.. container:: codeset
.. sourcecode:: kotlin
@Throws(InsufficientBalanceException::class)
fun generateRedeem(tx: TransactionBuilder, paper: StateAndRef<State>, wallet: Wallet) {
// Add the cash movement using the states in our wallet.
Cash().generateSpend(tx, paper.state.data.faceValue.withoutIssuer(), paper.state.data.owner, wallet.statesOfType<Cash.State>())
tx.addInputState(paper)
tx.addCommand(Command(Commands.Redeem(), paper.state.data.owner))
}
Here we can see an example of composing contracts together. When an owner wishes to redeem the commercial paper, the
issuer (i.e. the caller) must gather cash from its wallet and send the face value to the owner of the paper.
.. 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 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. 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`` 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
any issuer, thus we must strip it here. This represents a design mismatch that we will resolve in future
versions with a more complete way to express issuer constraints.
A ``TransactionBuilder`` is not by itself ready to be used anywhere, so first, we must convert it to something that
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 ``SignedTransaction`` object.
You can see how transactions flow through the different stages of construction by examining the commercial paper
unit tests.
How multi-party transactions are constructed and transmitted
------------------------------------------------------------
OK, so now we know how to define the rules of the ledger, and we know how to construct transactions that satisfy
those rules ... and if all we were doing was maintaining our own data that might be enough. But we aren't: Corda
is about keeping many different parties all in sync with each other.
In a classical blockchain system all data is transmitted to everyone and if you want to do something fancy, like
a multi-party transaction, you're on your own. In Corda data is transmitted only to parties that need it and
multi-party transactions are a way of life, so we provide lots of support for managing them.
You can learn how transactions are moved between peers and taken through the build-sign-notarise-broadcast
process in a separate tutorial, :doc:`protocol-state-machines`.
Non-asset-oriented smart contracts
----------------------------------
Although this tutorial covers how to implement an owned asset, there is no requirement that states and code contracts
*must* be concerned with ownership of an asset. It is better to think of states as representing useful facts about the
world, and (code) contracts as imposing logical relations on how facts combine to produce new facts. Alternatively
you can imagine that states are like rows in a relational database and contracts are like stored procedures and
relational constraints.
When writing a contract that handles deal-like entities rather than asset-like entities, you may wish to refer
to ":doc:`contract-irs`" and the accompanying source code. Whilst all the concepts are the same, deals are
typically not splittable or mergeable and thus you don't have to worry much about grouping of states.
Making things happen at a particular time
-----------------------------------------
It would be nice if you could program your node to automatically redeem your commercial paper as soon as it matures.
Corda provides a way for states to advertise scheduled events that should occur in future. Whilst this information
is by default ignored, if the corresponding *Cordapp* is installed and active in your node, and if the state is
considered relevant by your wallet (e.g. because you own it), then the node can automatically begin the process
of creating a transaction and taking it through the life cycle. You can learn more about this in the article
":doc:`event-scheduling`".
Encumbrances
------------
All contract states may be *encumbered* by up to one other state, which we call an **encumbrance**.
The encumbrance state, if present, forces additional controls over the encumbered state, since the encumbrance state contract
will also be verified during the execution of the transaction. For example, a contract state could be encumbered
with a time-lock contract state; the state is then only processable in a transaction that verifies that the time
specified in the encumbrance time-lock has passed.
The encumbered state refers to its encumbrance by index, and the referred encumbrance state
is an output state in a particular position on the same transaction that created the encumbered state. Note that an
encumbered state that is being consumed must have its encumbrance consumed in the same transaction, otherwise the
transaction is not valid.
The encumbrance reference is optional in the ``ContractState`` interface:
.. container:: codeset
.. sourcecode:: kotlin
val encumbrance: Int? get() = null
.. sourcecode:: java
@Nullable
@Override
public Integer getEncumbrance() {
return null;
}
The time-lock contract mentioned above can be implemented very simply:
.. container:: codeset
.. sourcecode:: kotlin
class TestTimeLock : Contract {
...
override fun verify(tx: TransactionForContract) {
val time = tx.timestamp.before ?: throw IllegalStateException(...)
...
requireThat {
"the time specified in the time-lock has passed" by
(time >= tx.inputs.filterIsInstance<TestTimeLock.State>().single().validFrom)
}
}
...
}
We can then set up an encumbered state:
.. container:: codeset
.. sourcecode:: kotlin
val encumberedState = Cash.State(amount = 1000.DOLLARS `issued by` defaultIssuer, owner = DUMMY_PUBKEY_1, encumbrance = 1)
val fourPmTimelock = TestTimeLock.State(Instant.parse("2015-04-17T16:00:00.00Z"))
When we construct a transaction that generates the encumbered state, we must place the encumbrance in the corresponding output
position of that transaction. And when we subsequently consume that encumbered state, the same encumbrance state must be
available somewhere within the input set of states.
In future, we will consider the concept of a *covenant*. This is where the encumbrance travels alongside each iteration of
the encumbered state. For example, a cash state may be encumbered with a *domicile* encumbrance, which checks the domicile of
the identity of the owner that the cash state is being moved to, in order to uphold sanction screening regulations, and prevent
cash being paid to parties domiciled in e.g. North Korea. In this case, the encumbrance should be permanently attached to
the all future cash states stemming from this one.
We will also consider marking states that are capable of being encumbrances as such. This will prevent states being used
as encumbrances inadvertently. For example, the time-lock above would be usable as an encumbrance, but it makes no sense to
be able to encumber a cash state with another one.
Clauses
-------
It is typical for slightly different contracts to have lots of common logic that can be shared. For example, the
concept of being issued, being exited and being upgraded are all usually required in any contract. Corda calls these
frequently needed chunks of logic "clauses", and they can simplify development considerably.
Clauses and how to use them are addressed in the next tutorial, ":doc:`tutorial-contract-clauses`".

560
docs/build/html/_sources/tutorial-test-dsl.txt vendored
View File

@ -1,560 +0,0 @@
.. highlight:: kotlin
.. role:: kotlin(code)
:language: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Writing a contract test
=======================
This tutorial will take you through the steps required to write a contract test using Kotlin and/or Java.
The testing DSL allows one to define a piece of the ledger with transactions referring to each other, and ways of
verifying their correctness.
Testing single transactions
---------------------------
We start with the empty ledger:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun emptyLedger() {
ledger {
}
}
.. sourcecode:: java
import static com.r3corda.core.testing.JavaTestHelpers.*;
import static com.r3corda.core.contracts.JavaTestHelpers.*;
@Test
public void emptyLedger() {
ledger(l -> {
return Unit.INSTANCE; // We need to return this explicitly
});
}
The DSL keyword ``ledger`` takes a closure that can build up several transactions and may verify their overall
correctness. A ledger is effectively a fresh world with no pre-existing transactions or services within it.
Let's add a Cash transaction:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCashDoesntCompile() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` DUMMY_CASH_ISSUER,
owner = DUMMY_PUBKEY_1
)
ledger {
transaction {
input(inState)
}
}
}
.. sourcecode:: java
@Test
public void simpleCashDoesntCompile() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getDUMMY_CASH_ISSUER()),
getDUMMY_PUBKEY_1()
);
ledger(l -> {
l.transaction(tx -> {
tx.input(inState);
});
return Unit.INSTANCE;
});
}
We can add a transaction to the ledger using the ``transaction`` primitive. The transaction in turn may be defined by
specifying ``input``-s, ``output``-s, ``command``-s and ``attachment``-s.
The above ``input`` call is a bit special: Transactions don't actually contain input states, just references
to output states of other transactions. Under the hood the above ``input`` call creates a dummy transaction in the
ledger (that won't be verified) which outputs the specified state, and references that from this transaction.
The above code however doesn't compile:
.. container:: codeset
.. sourcecode:: kotlin
Error:(26, 21) Kotlin: Type mismatch: inferred type is Unit but EnforceVerifyOrFail was expected
.. sourcecode:: java
Error:(26, 31) java: incompatible types: bad return type in lambda expression missing return value
This is deliberate: The DSL forces us to specify either ``this.verifies()`` or ``this `fails with` "some text"`` on the
last line of ``transaction``:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCash() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = DUMMY_PUBKEY_1
)
ledger {
transaction {
input(inState)
this.verifies()
}
}
}
.. sourcecode:: java
@Test
public void simpleCash() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getDUMMY_PUBKEY_1()
);
ledger(l -> {
l.transaction(tx -> {
tx.input(inState);
return tx.verifies();
});
return Unit.INSTANCE;
});
}
The code finally compiles. When run, it produces the following error::
com.r3corda.core.contracts.TransactionVerificationException$ContractRejection: java.lang.IllegalArgumentException: Failed requirement: for deposit [01] at issuer Snake Oil Issuer the amounts balance
.. note:: The reference here to the 'Snake Oil Issuer' is because we are using the pre-canned ``DUMMY_CASH_ISSUER``
identity as the issuer of our cash.
The transaction verification failed, because the sum of inputs does not equal the sum of outputs. We can specify that
this is intended behaviour by changing ``this.verifies()`` to ``this `fails with` "the amounts balance"``:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCashFailsWith() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = DUMMY_PUBKEY_1
)
ledger {
transaction {
input(inState)
this `fails with` "the amounts balance"
}
}
}
.. sourcecode:: java
@Test
public void simpleCashFailsWith() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getDUMMY_PUBKEY_1()
);
ledger(l -> {
l.transaction(tx -> {
tx.input(inState);
return tx.failsWith("the amounts balance");
});
return Unit.INSTANCE;
});
}
We can continue to build the transaction until it ``verifies``:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCashSuccess() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = DUMMY_PUBKEY_1
)
ledger {
transaction {
input(inState)
this `fails with` "the amounts balance"
output(inState.copy(owner = DUMMY_PUBKEY_2))
command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
this.verifies()
}
}
}
.. sourcecode:: java
@Test
public void simpleCashSuccess() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getDUMMY_PUBKEY_1()
);
ledger(l -> {
l.transaction(tx -> {
tx.input(inState);
tx.failsWith("the amounts balance");
tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));
tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
return tx.verifies();
});
return Unit.INSTANCE;
});
}
``output`` specifies that we want the input state to be transferred to ``DUMMY_PUBKEY_2`` and ``command`` adds the
``Move`` command itself, signed by the current owner of the input state, ``DUMMY_PUBKEY_1``.
We constructed a complete signed cash transaction from ``DUMMY_PUBKEY_1`` to ``DUMMY_PUBKEY_2`` and verified it. Note
how we left in the ``fails with`` line - this is fine, the failure will be tested on the partially constructed
transaction.
What should we do if we wanted to test what happens when the wrong party signs the transaction? If we simply add a
``command`` it will ruin the transaction for good... Enter ``tweak``:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCashTweakSuccess() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = DUMMY_PUBKEY_1
)
ledger {
transaction {
input(inState)
this `fails with` "the amounts balance"
output(inState.copy(owner = DUMMY_PUBKEY_2))
tweak {
command(DUMMY_PUBKEY_2) { Cash.Commands.Move() }
this `fails with` "the owning keys are the same as the signing keys"
}
command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
this.verifies()
}
}
}
.. sourcecode:: java
@Test
public void simpleCashTweakSuccess() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getDUMMY_PUBKEY_1()
);
ledger(l -> {
l.transaction(tx -> {
tx.input(inState);
tx.failsWith("the amounts balance");
tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));
tx.tweak(tw -> {
tw.command(getDUMMY_PUBKEY_2(), new Cash.Commands.Move());
return tw.failsWith("the owning keys are the same as the signing keys");
});
tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
return tx.verifies();
});
return Unit.INSTANCE;
});
}
``tweak`` creates a local copy of the transaction. This allows the local "ruining" of the transaction allowing testing
of different error conditions.
We now have a neat little test that tests a single transaction. This is already useful, and in fact testing of a single
transaction in this way is very common. There is even a shorthand toplevel ``transaction`` primitive that creates a
ledger with a single transaction:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun simpleCashTweakSuccessTopLevelTransaction() {
val inState = Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = DUMMY_PUBKEY_1
)
transaction {
input(inState)
this `fails with` "the amounts balance"
output(inState.copy(owner = DUMMY_PUBKEY_2))
tweak {
command(DUMMY_PUBKEY_2) { Cash.Commands.Move() }
this `fails with` "the owning keys are the same as the signing keys"
}
command(DUMMY_PUBKEY_1) { Cash.Commands.Move() }
this.verifies()
}
}
.. sourcecode:: java
@Test
public void simpleCashTweakSuccessTopLevelTransaction() {
Cash.State inState = new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getDUMMY_PUBKEY_1()
);
transaction(tx -> {
tx.input(inState);
tx.failsWith("the amounts balance");
tx.output(inState.copy(inState.getAmount(), getDUMMY_PUBKEY_2()));
tx.tweak(tw -> {
tw.command(getDUMMY_PUBKEY_2(), new Cash.Commands.Move());
return tw.failsWith("the owning keys are the same as the signing keys");
});
tx.command(getDUMMY_PUBKEY_1(), new Cash.Commands.Move());
return tx.verifies();
});
}
Chaining transactions
---------------------
Now that we know how to define a single transaction, let's look at how to define a chain of them:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun chainCash() {
ledger {
unverifiedTransaction {
output("MEGA_CORP cash") {
Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = MEGA_CORP_PUBKEY
)
}
}
transaction {
input("MEGA_CORP cash")
output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
this.verifies()
}
}
}
.. sourcecode:: java
@Test
public void chainCash() {
ledger(l -> {
l.unverifiedTransaction(tx -> {
tx.output("MEGA_CORP cash",
new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getMEGA_CORP_PUBKEY()
)
);
return Unit.INSTANCE;
});
l.transaction(tx -> {
tx.input("MEGA_CORP cash");
Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
return tx.verifies();
});
return Unit.INSTANCE;
});
}
In this example we declare that ``MEGA_CORP`` has a thousand dollars but we don't care where from, for this we can use
``unverifiedTransaction``. Note how we don't need to specify ``this.verifies()``.
The ``output`` cash was labelled with ``"MEGA_CORP cash"``, we can subsequently referred to this other transactions, e.g.
by ``input("MEGA_CORP cash")`` or ``"MEGA_CORP cash".output<Cash.State>()``.
What happens if we reuse the output cash twice?
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun chainCashDoubleSpend() {
ledger {
unverifiedTransaction {
output("MEGA_CORP cash") {
Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = MEGA_CORP_PUBKEY
)
}
}
transaction {
input("MEGA_CORP cash")
output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
this.verifies()
}
transaction {
input("MEGA_CORP cash")
// We send it to another pubkey so that the transaction is not identical to the previous one
output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_2))
command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
this.verifies()
}
}
}
.. sourcecode:: java
@Test
public void chainCashDoubleSpend() {
ledger(l -> {
l.unverifiedTransaction(tx -> {
tx.output("MEGA_CORP cash",
new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getMEGA_CORP_PUBKEY()
)
);
return Unit.INSTANCE;
});
l.transaction(tx -> {
tx.input("MEGA_CORP cash");
Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
return tx.verifies();
});
l.transaction(tx -> {
tx.input("MEGA_CORP cash");
Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
// We send it to another pubkey so that the transaction is not identical to the previous one
tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_2()));
tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
return tx.verifies();
});
return Unit.INSTANCE;
});
}
The transactions ``verifies()`` individually, however the state was spent twice!
We can also verify the complete ledger by calling ``verifies``/``fails`` on the ledger level. We can also use
``tweak`` to create a local copy of the whole ledger:
.. container:: codeset
.. sourcecode:: kotlin
@Test
fun chainCashDoubleSpendFailsWith() {
ledger {
unverifiedTransaction {
output("MEGA_CORP cash") {
Cash.State(
amount = 1000.DOLLARS `issued by` MEGA_CORP.ref(1, 1),
owner = MEGA_CORP_PUBKEY
)
}
}
transaction {
input("MEGA_CORP cash")
output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
this.verifies()
}
tweak {
transaction {
input("MEGA_CORP cash")
// We send it to another pubkey so that the transaction is not identical to the previous one
output("MEGA_CORP cash".output<Cash.State>().copy(owner = DUMMY_PUBKEY_1))
command(MEGA_CORP_PUBKEY) { Cash.Commands.Move() }
this.verifies()
}
this.fails()
}
this.verifies()
}
}
.. sourcecode:: java
@Test
public void chainCashDoubleSpendFailsWith() {
ledger(l -> {
l.unverifiedTransaction(tx -> {
tx.output("MEGA_CORP cash",
new Cash.State(
issuedBy(DOLLARS(1000), getMEGA_CORP().ref((byte)1, (byte)1)),
getMEGA_CORP_PUBKEY()
)
);
return Unit.INSTANCE;
});
l.transaction(tx -> {
tx.input("MEGA_CORP cash");
Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_1()));
tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
return tx.verifies();
});
l.tweak(lw -> {
lw.transaction(tx -> {
tx.input("MEGA_CORP cash");
Cash.State inputCash = l.retrieveOutput(Cash.State.class, "MEGA_CORP cash");
// We send it to another pubkey so that the transaction is not identical to the previous one
tx.output(inputCash.copy(inputCash.getAmount(), getDUMMY_PUBKEY_2()));
tx.command(getMEGA_CORP_PUBKEY(), new Cash.Commands.Move());
return tx.verifies();
});
lw.fails();
return Unit.INSTANCE;
});
l.verifies();
return Unit.INSTANCE;
});
}

69
docs/build/html/_sources/where-to-start.txt vendored
View File

@ -1,69 +0,0 @@
.. highlight:: kotlin
.. raw:: html
<script type="text/javascript" src="_static/jquery.js"></script>
<script type="text/javascript" src="_static/codesets.js"></script>
Where to start
==============
So you want to start experimenting with Corda. Where do you begin? Although Corda is still very early and missing
large chunks of important functionality, this article will hopefully put you on the right place.
An experiment with Corda is started by picking a *scenario* and then turning it into a *demo*. It is important to
understand that at this stage in its life, Corda does not have a single unified server that loads everything
dynamically. Instead, Corda provides an object oriented API which is then used by a *driver* program, with one driver
per scenario. You can see the existing demo apps in action by :doc:`running-the-demos`.
In future this design will change and there will be a single server that does everything. But for now, there isn't.
A scenario contains:
* A set of participating nodes and their roles.
* Some business process you wish to automate (typically simplified from the real thing).
* The smart contracts and protocols that will automate that process.
It may also specify a REST/JSON API, but this is optional.
Here's are two example scenarios included in the box:
1. Bank A wishes to buy some commercial paper in return for cash. Bank B wants to issue and sell some CP to Bank A.
This is probably the simplest scenario in Corda that still does something interesting. It's like the buttered
bread of finance.
2. Bank A and Bank B want to enter into an interest rate swap and evolve it through its lifecycle.
The process of implementing a scenario looks like this:
1. First of all, design your states and transaction types. Read about the :doc:`data-model` if you aren't sure what that
involves.
2. Now, create a new file in the finance/src/main directory. You can either any JVM language but we only provide examples
in Java and Kotlin. The file should define your state classes and your contract class, which will define the
allowable state transitions. You can learn how these are constructed by reading the ":doc:`tutorial-contract`" tutorial.
3. It isn't enough to just define static data and logic that controls what's allowed. You must also orchestrate the
business process. This is the job of the protocol framework. You can learn how to author these by reading
":doc:`protocol-state-machines`".
4. Once you have created your states, transactions and protocols, you need a way to demonstrate them (outside of the
unit tests, of course). This topic is covered below.
The trader demo
---------------
Until Corda has a unified server that can dynamically load every aspect of an application (i.e. software implementing a scenario),
we have to do a bit of copy/paste wiring ourselves.
The trader demo is a good place to start understanding this, which can be found in src/main/kotlin/demos/TraderDemo.kt
The idea of a driver program is that it starts a node in one of several roles, according to a command line flag. The
driver may step through some pre-programmed scenario automatically or it may register an API to be exported via HTTP.
You would then have to drive the node externally for your demo.
The best way to create your own scenario is not to write a driver from scratch but to copy the existing trader or IRS
demo drivers and then customise them, as much of the code would end up being shared (like for command line parsing).
Things you will want to adjust:
1. The name of the grouping directory each node role will create its private directory under.
2. The demo protocols that just wrap the real business process in some kind of fake trading logic.
The IRS driver program registers REST APIs, but as this is seriously in flux right now and the APIs will change a lot,
we do not recommend you try this as part of your initial explorations unless you are feeling adventurous.