mirror of
https://github.com/corda/corda.git
synced 2024-12-24 07:06:44 +00:00
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.
This commit is contained in:
parent
70d99409f1
commit
6d7f06131d
Binary file not shown.
@ -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:
|
||||
|
105
docs/source/corda-api.rst
Normal file
105
docs/source/corda-api.rst
Normal file
@ -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.
|
||||
|
@ -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.
|
@ -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
|
||||
|
@ -42,13 +42,3 @@ Nodes can provide several types of services:
|
||||
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.
|
@ -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
|
||||
------------
|
||||
|
||||
@ -74,5 +56,3 @@ to the main network map service, for operational reasons. Identities registered
|
||||
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
|
@ -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
|
||||
|
Binary file not shown.
Before Width: | Height: | Size: 668 KiB After Width: | Height: | Size: 670 KiB |
Binary file not shown.
Before Width: | Height: | Size: 100 KiB |
Loading…
Reference in New Issue
Block a user