Merged in mike-m1-docs-refresh (pull request #196)

Refresh docs for M1 release.

docs/source/inthebox.rst

@@ -1,46 +1,46 @@
 What's included?
 ================
 
-The current prototype consists of a small amount of code that defines:
+The Corda prototype currently includes:
 
-* Key data structures.
+* A peer to peer network with message persistence and delivery retries.
+* Key data structures for defining contracts and states.
+* Smart contracts:
+    * Cash
+    * Cash obligations
+    * Interest rate swaps
+    * Commercial paper (implemented in both Java and Kotlin for comparison)
 * Algorithms that work with them, such as serialising, hashing, signing, and verification of the signatures.
-* Two smart contracts that implement a notion of a cash claim and basic commercial paper (implemented twice, in two
-  different programming languages). These are simplified versions of the real things.
-* Unit tests that check the algorithms do what is expected, and which verify the behaviour of the smart contracts.
-* API documentation and tutorials (what you're reading)
-* A simple standalone node that uses an embedded message queue broker as its P2P messaging layer.
-* A trading demo that runs the node in either a listening/buying mode, or a connecting/selling mode, and swaps some
-  fake commercial paper assets for some self-issued IOU cash, using a generic *protocol framework*.
-* It also includes two oracles: one for precise timestamping and another for interest rate swaps.
+* 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.
 
 Some things it does not currently include but should gain later are:
 
 * Sandboxing, distribution or publication of smart contract code
-* A peer to peer network
 * Database persistence
-* An API for integrating external software
 * A user interface for administration
 * Many other things
 
-You can browse `the JIRA bug tracker <https://r3-cev.atlassian.net/>`_.
-
 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.
-* It uses secp256r1, an obsolete elliptic curve.
 * It uses the default, out of the box Apache Artemis MQ protocol instead of AMQP/1.0 (although switching should be easy)
+* There is no inter-node SSL or other encryption yet.
 
 Contracts
 ---------
 
 The primary goal of this prototype is to implement various kinds of contracts and verify that useful business logic
 can be expressed with the data model, developing and refining an API along the way. To that end there are currently
-two contracts in the repository:
+four contracts in the repository:
 
 1. Cash
 2. Commercial paper
+3. Nettable obligations
+4. Interest rate swaps
 
 ``Cash`` implements the idea of a claim on some quantity of deposits at some institutional party, denominated in some currency,
 identified by some *deposit reference*. A deposit reference is an opaque byte array which is usable by
@@ -57,12 +57,14 @@ contract is implemented twice, once in Java and once in a language called Kotlin
 ``InterestRateSwap`` implements a vanilla OTC same currency bilateral fixed / floating leg swap. For further details,
 see :doc:`irs`
 
+``Obligation`` implements a bilaterally or multi-laterally nettable, fungible obligation that can default.
+
 Each contract comes with unit tests.
 
 Kotlin
 ------
 
-The prototype is written in a language called `Kotlin <https://kotlinlang.org/>`_. Kotlin is a language that targets the JVM
+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.
 
@@ -72,10 +74,3 @@ 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>`_.
-
-Kotlin programs use the regular Java standard library and ordinary Java frameworks. Frameworks used at this time are:
-
-* JUnit for unit testing
-* Kryo for serialisation (this is not intended to be permanent)
-* Gradle for the build
-* Guava for a few utility functions

docs/source/release-notes.rst

@@ -6,27 +6,72 @@ Here are brief summaries of what's changed between each snapshot release.
 Unreleased
 ----------
 
-Here are changes in git master that haven't yet made it to a snapshot release:
+There are currently no unreleased changes.
 
-* Made the ``NotaryService`` extensible, we now have both validating and non-validating notaries.
-* Added a protocol for changing the notary for a state.
-* Every ``ContractState`` now has to specify a *participants* field, which is a list of parties that are able to
+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.
+    * 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:
+    * 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.
 
-  - **General**. Runs the default build and validation logic.
-  - **NotaryChange**. Contract code is not run during validation, checks that the notary field is the only difference
-    between the inputs and outputs.
-
-* 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 assets, or currency with additional information).
+* 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.)
-* Switched to the ed25519 elliptic curve from secp256r1. Note that this introduces a new external lib dependency.
+* 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
 -----------

docs/source/running-the-demos.rst

@@ -73,9 +73,7 @@ And in the second run:
 
     ./build/install/r3prototyping/bin/irsdemo --role=NodeB
 
-The node in the first terminal will complain that it didn't know about nodeB, so restart it. It'll then find the
-location and identity keys of nodeA and be happy. NodeB also doubles up as the interest rates oracle and you should
-see some rates data get loaded.
+NodeB also doubles up as the interest rates oracle and you should see some rates data get loaded.
 
 Now in the third terminal run: