Reflects recent docs PR on V2.

* Removes old network diagram. Consolidates two sections on node naming. Moves contract constraints to API section.

* Minor corrections to the V2 cheatsheet.

* Makes it clearer how to build a JAR. Removes ambiguous deployNodes content.

docs/source/api-contract-constraints.rst

@@ -1,15 +1,15 @@
-Contract Constraints
-====================
+API: Contract Constraints
+=========================
 
 A basic understanding of contract key concepts, which can be found :doc:`here </key-concepts-contracts>`,
 is required reading for this page.
 
 Transaction states specify a constraint over the contract that will be used to verify it.  For a transaction to be
-valid, the verify() function associated with each state must run successfully. However, for this to be secure, it is
-not sufficient to specify the verify() function by name as there may exist multiple different implementations with the
-same method signature and enclosing class. Contract constraints solve this problem by allowing a contract developer to
-constrain which verify() functions out of the universe of implementations can be used.
-(ie the universe is everything that matches the signature and contract constraints restricts this universe to a subset.)
+valid, the ``verify`` function associated with each state must run successfully. However, for this to be secure, it is
+not sufficient to specify the ``verify`` function by name as there may exist multiple different implementations with
+the same method signature and enclosing class. Contract constraints solve this problem by allowing a contract developer
+to constrain which ``verify`` functions out of the universe of implementations can be used (i.e. the universe is
+everything that matches the signature and contract constraints restricts this universe to a subset).
 
 A typical constraint is the hash of the CorDapp JAR that contains the contract and states but will in future releases
 include constraints that require specific signers of the JAR, or both the signer and the hash. Constraints can be
@@ -20,12 +20,13 @@ constructs a ``TransactionState`` without specifying the constraint parameter a
 (``AutomaticHashConstraint``) is used. This default will be automatically resolved to a specific
 ``HashAttachmentConstraint`` that contains the hash of the attachment which contains the contract of that
 ``TransactionState``. This automatic resolution occurs when a ``TransactionBuilder`` is converted to a
-``WireTransaction``. This reduces the boilerplate involved in finding a specific hash constraint when building a transaction.
+``WireTransaction``. This reduces the boilerplate involved in finding a specific hash constraint when building a
+transaction.
 
 It is possible to specify the constraint explicitly with any other class that implements the ``AttachmentConstraint``
 interface. To specify a hash manually the ``HashAttachmentConstraint`` can be used and to not provide any constraint
 the ``AlwaysAcceptAttachmentConstraint`` can be used - though this is intended for testing only. An example below
-shows how to construct a ``TransactionState`` with an explicitly specified hash constraint from within a flow;
+shows how to construct a ``TransactionState`` with an explicitly specified hash constraint from within a flow:
 
 .. sourcecode:: java
 
@@ -42,12 +43,11 @@ shows how to construct a ``TransactionState`` with an explicitly specified hash
      LedgerTransaction ltx = wtx.toLedgerTransaction(serviceHub)
      ltx.verify() // Verifies both the attachment constraints and contracts
 
-
 This mechanism exists both for integrity and security reasons. It is important not to verify against the wrong contract,
 which could happen if the wrong version of the contract is attached. More importantly when resolving transaction chains
 there will, in a future release, be attachments loaded from the network into the attachment sandbox that are used
-to verify the transaction chain. Ensuring the attachment used is the correct one ensures that the verification will
-not be tamperable by providing a fake contract.
+to verify the transaction chain. Ensuring the attachment used is the correct one ensures that the verification is
+tamper-proof by providing a fake contract.
 
 CorDapps as attachments
 -----------------------
@@ -55,10 +55,10 @@ CorDapps as attachments
 CorDapp JARs (:doc:`cordapp-overview`) that are installed to the node and contain classes implementing the ``Contract``
 interface are automatically loaded into the ``AttachmentStorage`` of a node at startup.
 
-After CorDapps are loaded into the attachment store the node creates a link between contract classes and the
-attachment that they were loaded from. This makes it possible to find the attachment for any given contract.
-This is how the automatic resolution of attachments is done by the ``TransactionBuilder`` and how, when verifying
-the constraints and contracts, attachments are associated with their respective contracts.
+After CorDapps are loaded into the attachment store the node creates a link between contract classes and the attachment
+that they were loaded from. This makes it possible to find the attachment for any given contract. This is how the
+automatic resolution of attachments is done by the ``TransactionBuilder`` and how, when verifying the constraints and
+contracts, attachments are associated with their respective contracts.
 
 Implementations
 ---------------
@@ -95,9 +95,15 @@ to specify JAR URLs in the case that the CorDapp(s) involved in testing already
 MockNetwork/MockNode
 ********************
 
+<<<<<<< HEAD:docs/source/key-concepts-contract-constraints.rst
 The most simple way to ensure that a vanilla instance of a MockNode generates the correct CorDapps is to make a call
 to ``setCordappPackages`` before the MockNetwork/Node are created and then ``unsetCordappPackages`` after the test
 has finished. These calls will cause the ``AbstractNode`` to use the named packages as sources for CorDapps. All files
+=======
+The simplest way to ensure that a vanilla instance of a MockNode generates the correct CorDapps is to use the
+``cordappPackages`` constructor parameter (Kotlin) or the ``setCordappPackages`` method on ``MockNetworkParameters`` (Java)
+when creating the MockNetwork. This will cause the ``AbstractNode`` to use the named packages as sources for CorDapps. All files
+>>>>>>> 6c02c91ec... Removes old network diagram. Consolidates two sections on node naming. Moves contract constraints to API section.:docs/source/api-contract-constraints.rst
 within those packages will be zipped into a JAR and added to the attachment store and loaded as CorDapps by the
 ``CordappLoader``. An example of this usage would be:
 

docs/source/cheat-sheet.rst

@@ -4,6 +4,6 @@ Cheat sheet
 A "cheat sheet" summarizing the key Corda types. A PDF version is downloadable `here`_.
 
 .. image:: resources/cheatsheet.jpg
-:width: 700px
+    :width: 700px
 
 .. _`here`: _static/corda-cheat-sheet.pdf

docs/source/corda-api.rst

@@ -0,0 +1,105 @@
+Corda API
+=========
+
+The following are the core APIs that are used in the development of CorDapps:
+
+.. toctree::
+   :maxdepth: 1
+
+   api-states
+   api-persistence
+   api-contracts
+   api-contract-constraints
+   api-vault-query
+   api-transactions
+   api-flows
+   api-identity
+   api-service-hub
+   api-rpc
+   api-core-types
+
+Before reading this page, you should be familiar with the :doc:`key concepts of Corda <key-concepts>`.
+
+Internal APIs and stability guarantees
+--------------------------------------
+
+.. warning:: For Corda 1.0 we do not currently provide a stable wire protocol or support for database upgrades.
+   Additionally, the JSON format produced by the client-jackson module may change in future.
+   Therefore, you should not expect to be able to migrate persisted data from 1.0 to future versions.
+
+   Additionally, it may be necessary to recompile applications against future versions of the API until we begin offering
+   ABI stability as well. We plan to do this soon after the release of Corda 1.0.
+
+   Finally, please note that the 1.0 release has not yet been security audited. You should not run it in situations
+   where security is required.
+
+Corda artifacts can be required from Java 9 Jigsaw modules.
+From within a ``module-info.java``, you can reference one of the modules e.g., ``requires net.corda.core;``.
+
+.. warning:: while Corda artifacts can be required from ``module-info.java`` files, they are still not proper Jigsaw modules,
+   because they rely on the automatic module mechanism and declare no module descriptors themselves. We plan to integrate Jigsaw more thoroughly in the future.
+
+Corda stable modules
+--------------------
+
+The following modules have a stable API we commit not to break in following releases, unless an incompatible change is required for security reasons:
+
+* **Core (net.corda.core)**: core Corda libraries such as crypto functions, types for Corda's building blocks: states, contracts, transactions, attachments, etc. and some interfaces for nodes and protocols
+* **Client RPC (net.corda.client.rpc)**: client RPC
+* **Client Jackson (net.corda.client.jackson)**: JSON support for client applications
+
+Corda incubating modules
+------------------------
+
+The following modules don't yet have a completely stable API, but we will do our best to minimise disruption to
+developers using them until we are able to graduate them into the public API:
+
+* **net.corda.node.driver**: test utilities to run nodes programmatically
+* **net.corda.confidential.identities**: experimental support for confidential identities on the ledger
+* **net.corda.node.test.utils**: generic test utilities
+* **net.corda.finance**: a range of elementary contracts (and associated schemas) and protocols, such as abstract fungible assets, cash, obligation and commercial paper
+* **net.corda.client.jfx**: support for Java FX UI
+* **net.corda.client.mock**: client mock utilities
+* **Cordformation**: Gradle integration plugins
+
+Corda unstable modules
+----------------------
+
+The following modules are available but we do not commit to their stability or continuation in any sense:
+
+* **net.corda.buildSrc**: necessary gradle plugins to build Corda
+* **net.corda.node**: core code of the Corda node (eg: node driver, node services, messaging, persistence)
+* **net.corda.node.api**: data structures shared between the node and the client module, e.g. types sent via RPC
+* **net.corda.samples.network.visualiser**: a network visualiser that uses a simulation to visualise the interaction and messages between nodes on the Corda network
+* **net.corda.samples.demos.attachment**: demonstrates sending a transaction with an attachment from one to node to another, and the receiving node accessing the attachment
+* **net.corda.samples.demos.bankofcorda**: simulates the role of an asset issuing authority (eg. central bank for cash)
+* **net.corda.samples.demos.irs**: demonstrates an Interest Rate Swap agreement between two banks
+* **net.corda.samples.demos.notary**: a simple demonstration of a node getting multiple transactions notarised by a distributed (Raft or BFT SMaRt) notary
+* **net.corda.samples.demos.simmvaluation**: A demo of SIMM valuation and agreement on a distributed ledger
+* **net.corda.samples.demos.trader**: demonstrates four nodes, a notary, an issuer of cash (Bank of Corda), and two parties trading with each other, exchanging cash for a commercial paper
+* **net.corda.node.smoke.test.utils**: test utilities for smoke testing
+* **net.corda.node.test.common**: common test functionality
+* **net.corda.tools.demobench**: a GUI tool that allows to run Corda nodes locally for demonstrations
+* **net.corda.tools.explorer**: a GUI front-end for Corda
+* **net.corda.tools.graphs**: utilities to infer project dependencies
+* **net.corda.tools.loadtest**: Corda load tests
+* **net.corda.verifier**: allows out-of-node transaction verification, allowing verification to scale horizontally
+* **net.corda.webserver**: is a servlet container for CorDapps that export HTTP endpoints. This server is an RPC client of the node
+* **net.corda.sandbox-creator**: sandbox utilities
+* **net.corda.quasar.hook**: agent to hook into Quasar and provide types exclusion lists
+
+.. warning:: Code inside any package in the ``net.corda`` namespace which contains ``.internal`` or in ``net.corda.node`` for internal use only.
+   Future releases will reject any CorDapps that use types from these packages.
+
+.. warning:: The web server module will be removed in future. You should call Corda nodes through RPC from your web server of choice e.g., Spring Boot, Vertx, Undertow.
+
+The ``@DoNotImplement`` annotation
+----------------------------------
+
+Certain interfaces and abstract classes within the Corda API have been annotated
+as ``@DoNotImplement``. While we undertake not to remove or modify any of these classes' existing
+functionality, the annotation is a warning that we may need to extend them in future versions of Corda.
+Cordapp developers should therefore just use these classes "as is", and *not* attempt to extend or implement any of them themselves.
+
+This annotation is inherited by subclasses and subinterfaces.
+

docs/source/cordapp-build-systems.rst

@@ -115,27 +115,29 @@ is already correctly configured and this is for reference only;
 
 Creating the CorDapp JAR
 ------------------------
-The gradle ``jar`` task included in the CorDapp template build file will automatically build your CorDapp JAR correctly
-as long as your dependencies are set correctly.
+Once your dependencies are set correctly, you can build your CorDapp JAR using the gradle ``jar`` task:
+
+* Unix/Mac OSX: ``./gradlew jar``
+
+* Windows: ``gradlew.bat jar``
+
+The CorDapp JAR will be output to the ``build/libs`` folder.
 
 .. warning:: The hash of the generated CorDapp JAR is not deterministic, as it depends on variables such as the
    timestamp at creation. Nodes running the same CorDapp must therefore ensure they are using the exact same CorDapp
-   jar, and not different versions of the JAR created from identical sources.
+   JAR, and not different versions of the JAR created from identical sources.
 
 The filename of the JAR must include a unique identifier to deduplicate it from other releases of the same CorDapp.
 This is typically done by appending the version string to the CorDapp's name. This unique identifier should not change
 once the JAR has been deployed on a node. If it does, make sure no one is relying on ``FlowContext.appName`` in their
 flows (see :doc:`versioning`).
 
-Installing the CorDapp jar
+Installing the CorDapp JAR
 --------------------------
 
 .. note:: Before installing a CorDapp, you must create one or more nodes to install it on. For instructions, please see
    :doc:`generating-a-node`.
 
-At runtime, nodes will load any plugins present in their ``plugins`` folder. Therefore in order to install a CorDapp on
+At runtime, nodes will load any CorDapps present in their ``plugins`` folder. Therefore in order to install a CorDapp on
 a node, the CorDapp JAR must be added to the ``<node_dir>/plugins/`` folder, where ``node_dir`` is the folder in which
 the node's JAR and configuration files are stored.
-
-The ``deployNodes`` gradle task, if correctly configured, will automatically place your CorDapp JAR as well as any
-dependent CorDapp JARs specified into the ``plugins`` folder automatically.

docs/source/generating-a-node.rst

@@ -23,7 +23,22 @@ into the ``plugins`` folder.
 
 Node naming
 -----------
-A node's name must be a valid X.500 name that obeys the following additional constraints:
+A node's name must be a valid X.500 distinguished name. In order to be compatible with other implementations
+(particularly TLS implementations), we constrain the allowed X.500 attribute types to a subset of the minimum supported
+set for X.509 certificates (specified in RFC 3280), plus the locality attribute:
+
+* Organization (O)
+* State (ST)
+* Locality (L)
+* Country (C)
+* Organizational-unit (OU)
+* Common name (CN) (only used for service identities)
+
+The name must also obey the following constraints:
+
+* The organisation, locality and country attributes are present
+
+    * The state, organisational-unit and common name attributes are optional
 
 * The fields of the name have the following maximum character lengths:
 
@@ -33,21 +48,22 @@ A node's name must be a valid X.500 name that obeys the following additional con
     * Locality: 64
     * State: 64
 
-* The country code is a valid ISO 3166-1 two letter code in upper-case
-
-* The organisation, locality and country attributes are present
+* The country attribute is a valid ISO 3166-1 two letter code in upper-case
 
 * The organisation field of the name obeys the following constraints:
 
+    * Upper-case first letter
     * Has at least two letters
     * No leading or trailing whitespace
     * No double-spacing
-    * Upper-case first letter
     * Does not contain the words "node" or "server"
-    * Does not include the characters ',' or '=' or '$' or '"' or '\'' or '\\'
+    * Does not include the following characters: ``,`` , ``=`` , ``$`` , ``"`` , ``'`` , ``\``
     * Is in NFKC normalization form
     * Only the latin, common and inherited unicode scripts are supported
 
+        * This is to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and
+          character confusability attacks
+
 The Cordform task
 -----------------
 Corda provides a gradle plugin called ``Cordform`` that allows you to automatically generate and configure a set of

docs/source/key-concepts-ecosystem.rst

@@ -41,14 +41,4 @@ Nodes can provide several types of services:
 * One or more pluggable **notary services**. Notaries guarantee the uniqueness, and possibility the validity, of ledger
   updates. Each notary service may be run on a single node, or across a cluster of nodes.
 * Zero or more **oracle services**. An oracle is a well-known service that signs transactions if they state a fact and
-  that fact is considered to be true.
-
-These components are illustrated in the following diagram:
-
-.. image:: resources/cordaNetwork.png
-   :scale: 25%
-   :align: center
-
-In this diagram, Corda infrastructure services are those upon which all participants depend, such as the network map
-and notary services. Corda services may be deployed by participants, third parties or a central network operator
-(such as R3). The diagram is not intended to imply that only a centralised model is supported.
+  that fact is considered to be true.

docs/source/key-concepts-identity.rst

@@ -34,24 +34,6 @@ only shared with those who need to see them, and planned use of Intel SGX, it is
 privacy breaches. Confidential identities are used to ensure that even if a third party gets access to an unencrypted
 transaction, they cannot identify the participants without additional information.
 
-Name
-----
-
-Identity names are X.500 distinguished names with Corda-specific constraints applied. In order to be compatible with
-other implementations (particularly TLS implementations), we constrain the allowed X.500 attribute types to a subset of
-the minimum supported set for X.509 certificates (specified in RFC 3280), plus the locality attribute:
-
-* organization (O)
-* state (ST)
-* locality (L)
-* country (C)
-* organizational-unit (OU)
-* common name (CN) - used only for service identities
-
-The organisation, locality and country attributes are required, while state, organisational-unit and common name are
-optional. Attributes cannot be be present more than once in the name. The "country" code is strictly restricted to valid
-ISO 3166-1 two letter codes.
-
 Certificates
 ------------
 
@@ -73,6 +55,4 @@ business sensitive details of transactions). In some cases nodes may also use pr
 to the main network map service, for operational reasons. Identities registered with such network maps must be
 considered well known, and it is never appropriate to store confidential identities in a central directory without
 controls applied at the record level to ensure only those who require access to an identity can retrieve its
-certificate.
-
-.. TODO: Revisit once design & use cases of private maps is further fleshed out
+certificate.

docs/source/key-concepts.rst

@@ -16,7 +16,6 @@ This section should be read in order:
    key-concepts-identity
    key-concepts-states
    key-concepts-contracts
-   key-concepts-contract-constraints
    key-concepts-transactions
    key-concepts-flows
    key-concepts-consensus