Removed Key Concept docs.

docs/source/key-concepts.rst

@@ -1,188 +0,0 @@
-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.
-
-    <diags>
-
-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.
-
-    <diags>
-
-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
-
-    <diags>
-
-    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`