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

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,7 +95,7 @@ to specify JAR URLs in the case that the CorDapp(s) involved in testing already
 MockNetwork/MockNode
 ********************
 
-The most simple way to ensure that a vanilla instance of a MockNode generates the correct CorDapps is to use the
+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
 within those packages will be zipped into a JAR and added to the attachment store and loaded as CorDapps by the

docs/source/corda-api.rst

@@ -9,6 +9,7 @@ The following are the core APIs that are used in the development of CorDapps:
    api-states
    api-persistence
    api-contracts
+   api-contract-constraints
    api-vault-query
    api-transactions
    api-flows

docs/source/generating-a-node.rst

@@ -23,7 +23,22 @@ into the ``cordapps`` 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,33 +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.
-
-All of these attributes have the following set of constraints applied for security reasons:
-
- - No blacklisted words (currently "node" and "server").
- - Restrict names to Latin scripts for now to avoid right-to-left issues, debugging issues when we can't pronounce names over the phone, and character confusability attacks.
- - No commas or equals signs.
- - No dollars or quote marks.
-
-Additionally the "organisation" attribute must consist of at least three letters and starting with a capital letter,
-and "country code" is strictly restricted to valid ISO 3166-1 two letter codes.
-
 Certificates
 ------------
 
@@ -82,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