diff --git a/docs/source/key-concepts.rst b/docs/source/key-concepts.rst new file mode 100644 index 0000000000..af73341214 --- /dev/null +++ b/docs/source/key-concepts.rst @@ -0,0 +1,188 @@ +Key Concepts +============ + +States +------ + What is a state? +A State Object represents an agreement between two or more parties, governed by machine-readable Contract Code. +This code references, and is intended to implement, portions of human-readable Legal Prose. +A state object is a digital document which records the existence, content and current state of an agreement between +two or more parties. It is intended to be shared only with those who have a legitimate reason to see it. +The ledger is defined as a set of immutable state objects. +An objective of Corda is to ensure that all parties to the agreement remain in consensus as to this state as it evolves. + +The following diagram illustrates a State object: + +.. image:: whitepaper/images/partiesto.png + + What can we represent in a state? + +Contracts +--------- + What's a contract? +Corda enforces business logic through smart contract code, which is constructed as a pure function that either accepts +or rejects a transaction, and which can be composed from simpler, reusable functions. The functions interpret transactions +as taking states as inputs and producing output states through the application of (smart contract) commands, and accept + the transaction if the proposed actions are valid. + + What does a contract contain? + Relationship to states + + Verify() +A contract is pure function; contracts do not have storage or the ability to interact with anything. +Given the same transaction, a contract’s “verify” function always yields exactly the same result. + + Clauses + + Contracts sandbox / Deterministic JVM? +Contracts define part of the business logic of the ledger, and they are mobile: nodes will download and run contracts +inside a sandbox without any review in some deployments, although we envisage the use of signed code for Corda deployments in the regulated sphere. +Corda uses an augmented JVM custom sandbox that is radically more restrictive than the ordinary JVM sandbox, and it enforces +not only security requirements but also deterministic execution. + + + +Ledger construct model +---------------------- +The Corda model focused on states of agreements is in contrast to systems where the data over which participants much +reach consensus is the state of an entire ledger or the state of an entire virtual machine. + +Corda provides three main tools to achieve global distributed consensus: +• Smart contract logic to ensure state transitions are valid according to the pre-agreed rules. +• Uniqueness and timestamping services to order transactions temporally and eliminate conflicts. +• An orchestration framework which simplifies the process of writing com- plex multi-step protocols between multiple different parties. + + Why we chose the UTXO model +There are two competing computational models used in distributed ledger technology: the virtual computer model (as used +by Ethereum) and the UTXO model (as popularised by Bitcoin). In this model the database is a set of immutable rows keyed +by (hash:output index). Transactions define outputs that append new rows and inputs which consume existing rows. + +Corda follows the UTXO (unspent transaction output set) model: +• Immutable states are consumed and created by transactions +• Transactions have multiple inputs and outputs +• A contract is pure function; contracts do not have storage or the ability to interact with anything. +Given the same transaction, a contract’s “verify” function always yields exactly the same result. +with additional features: +• Corda states can include arbitrary typed data. +• Transactions invoke not only input contracts but also the contracts of the outputs. +• Corda uses the term “contract” to refer to a bundle of business logic that may handle various different tasks, +beyond transaction verification. +• Corda contracts are Turing-complete and can be written in any ordinary programming language that targets the JVM. +• Corda allows arbitrarily-precise time-bounds to be specified in transactions (which must be attested to by a trusted timestamper) +• Corda's primary consensus implementations use block-free conflict resolution algorithms. +• Corda does not order transactions using a block chain and by implication does not use miners or proof-of-work. Instead +each state points to a notary, which is a service that guarantees it will sign a transaction only if all the input states are un-consumed. + + + +Transactions +------------ + What is a transaction in Corda? +Transactions transition state objects through a lifecycle. +Transaction are used to update the ledger by consuming existing state objects and producing new state objects. +A transaction update is accepted according to the following two aspects of consensus: +1. Transaction validity: parties can reach certainty that a proposed update transaction defining output states is valid +by checking that the associated contract code runs successfully and has all the required signatures; and that any +transactions to which this transaction refers are also valid. +2. Transaction uniqueness: parties can reach certainty that the transaction in question is the unique consumer of all its +input states. That is: there exists no other transaction, over which we have previously reached consensus (validity and uniqueness), that consumes any of the same states. + +The following diagram illustrates a simple Issuance Transaction: + +.. image:: whitepaper/images/cash.png + + + + Elements of a transaction + + When is a transaction valid? / invalid? +Parties can agree on transaction validity by independently running the same contract code and validation logic. +Consensus over transaction validity is performed only by parties to the transaction in question. Therefore, data is only +shared with those parties which are required to see it. Other platforms generally reach consensus at the ledger level. +Thus, any given actor in a Corda system sees only a subset of the overall data managed by the system as a whole. + + Transaction Tear-Off + +Data sharing model +------------------ +The Shared Ledger Vision is based on a progression from a world where parties to shared facts record and manage their own +records, with associated discrepancies and duplications (“Bilateral - Reconciliation”) or one where parties delegate control + and responsibility over critical processing to centralised utilities (“Third Party / Market Infrastructure”), to one where + they collaborate to maintain a shared record, assured to be consistent between them, consuming the services of existing + and new service providers and market infrastructure providers on an open and competitive basis. + +This transitional model is illustrated in the following diagram: + +.. image:: whitepaper/images/shared-logic.png + + +Consensus / Notaries +-------------------- +Consensus over transaction validity is performed only by parties to the transaction in question. Therefore, data is only + shared with those parties which are required to see it. Other platforms generally reach consensus at the ledger level. + Thus, any given actor in a Corda system sees only a subset of the overall data managed by the system as a whole. + We say a piece of data is “on- ledger” if at least two actors on the system are in consensus as to its existence and + details and we allow arbitrary combinations of actors to participate in the consensus process for any given piece of data. + Data held by only one actor is “off-ledger”. + +Corda has “pluggable” uniqueness services. This is to improve privacy, scalability, legal-system compatibility and +algorithmic agility. A single service may be composed of many mutually untrusting nodes coordinating via a byzantine +fault tolerant algorithm, or could be very simple, like a single machine. In some cases, like when evolving a state +requires the signatures of all relevant parties, there may be no need for a uniqueness service at all. + +It is important to note that these uniqueness services are required only to attest as to whether the states consumed by +a given transaction have previously been consumed; they are not required to attest as to the validity of the transaction +itself, which is a matter for the parties to the transaction. This means that the uniqueness services are not required to +(and, in the general case, will not) see the full contents of any transactions, significantly improving privacy and scalability +of the system compared with alternative distributed ledger and blockchain designs. + + + +Flows +----- +Flows enable complex multi-party business interactions without a central controller. +in Corda all communication takes the form of small multi-party sub-protocols called flows. +The flow framework presents a programming model that looks to the developer as if they have the ability to run millions +of long lived threads which can survive node restarts, and even node upgrades. APIs are provided to send and receive +object graphs to and from other identities on the network, embed sub-flows, and report progress to observers. +The flow framework provide the following: +* **Just-in-time** state machine compiler. Code that is written in a blocking manner typically cannot be stopped and transparently +restarted later. The first time a flow’s call method is invoked a bytecode-to-bytecode transformation occurs that +rewrites the classes into a form that implements a resumable state machine. These state machines are sometimes called fibers +or coroutines, and the transformation engine Corda uses (Quasar) is capable of rewriting code arbitrarily deep in the stack on the fly. +* Transparent checkpointing. +* Identity to IP address mapping. +* A library of subflows +* Progress reporting +* Flow hospital + +Section 4 of the Corda Technical WhitePaper provides a comprehensive description of the above features. + +The following diagram illustrates a sample Multi-party Business Flow: + +.. image:: resources/flow-diagram.png + +Oracles +------- +Oracles represent gateways to proprietary (or other) business logic executors (e.g., Central Counterparties or valuation agents) +that can be verified on-ledger by participants. + +Attachments +----------- + +Vault +----- + +CorDapp +------- +Corda is a platform for the writing of “CorDapps”: applications that extend the global database with new capabilities. +Such apps define new data types, new inter-node protocol flows and the “smart contracts” that determine allowed changes. + +The combination of state objects (data), Contract Code (allowable opera- tions), Transaction Protocols (business logic +choreography), any necessary APIs, Vault plugins, and UI components can be thought of a Shared Ledger application, +or Corda Distributed Application (“CorDapp”). This is the core set of components a contract developer on the platform +should expect to build. + +Please see our published White Papers for in depth explanations of these concepts: +":doc:`https://docs.corda.net/_static/corda-introductory-whitepaper.pdf` +":doc:`https://docs.corda.net/_static/corda-technical-whitepaper.pdf` diff --git a/docs/source/resources/flow-diagram.png b/docs/source/resources/flow-diagram.png new file mode 100644 index 0000000000..a9e6c27c1e Binary files /dev/null and b/docs/source/resources/flow-diagram.png differ