1.Set up your machine for CorDapp development #

Quickstart

  • Set up your machine for Dapp development
  • Run the Example Dapp
  • Download sample Dapps
Last updated on 31st Jan 2019

2.The network #

The network

Summary

  • A Keto network is made up of nodes running Keto and KetoDapps
  • The network is permissioned, with access controlled by a doorman
  • Communication between nodes is point-to-point, instead of relying on global broadcasts
Last updated on 29th Jan 2019

2.1.network structure #

2.1.1.The Network Structure Overview #

Network structure

A Keto network is an authenticated peer-to-peer network of nodes, where each node is a JVM run-time environment hosting Keto services and executing applications known as D-Apps.

All communication between nodes is direct, with TLS-encrypted messages sent over AMQP/1.0. This means that data is shared only on a need-to-know basis; in Keto, there are no global broadcasts.

Each network has a network map service that publishes the IP addresses through which every node on the network can be reached, along with the identity certificates of those nodes and the services they provide.

Last updated on 5th Feb 2019

2.1.2.Network Services Overview #

Network services

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.
Last updated on 5th Feb 2019

2.2.The ledger Overview #

The ledger

Summary

  • The ledger is subjective from each peer’s perspective
  • Two peers are always guaranteed to see the exact same version of any on-ledger facts they share

Overview

In Keto, there is no single central store of data. Instead, each node maintains a separate database of known facts. As a result, each peer only sees a subset of facts on the ledger, and no peer is aware of the ledger in its entirety.

For example, imagine a network with five nodes, where each coloured circle represents a shared fact:

_images/ledger-venn.png

We can see that although Carl, Demi and Ed are aware of shared fact 3, Alice and Bob are not.

Equally importantly, Corda guarantees that whenever one of these facts is shared by multiple nodes on the network, it evolves in lockstep in the database of every node that is aware of it:

_images/ledger-table.png

For example, Alice and Bob will both see the exact same version of shared facts 1 and 7.

Last updated on 5th Feb 2019

2.3.Certificates #

Identity

Summary

  • Identities in Keto can represent legal identities or service identities
  • Identities are attested to by X.509 certificate signed by the Doorman or a well known identity
  • Well known identities are published in the network map
  • Confidential identities are only shared on a need to know basis

Identities in Keto can represent:

  • Legal identity of an organisation
  • Service identity of a network service

Legal identities are used for parties in a transaction, such as the owner of a cash state. Service identities are used for those providing transaction-related services, such as notary, or oracle. Service identities are distinct to legal identities so that distributed services can exist on nodes owned by different organisations. Such distributed service identities are based on CompositeKeys, which describe the valid sets of signers for a signature from the service. See API: Core types for more technical detail on composite keys.

Identities are either well known or confidential, depending on whether their X.509 certificate (and corresponding certificate path to a trusted root certificate) is published:

  • Well known identities are the generally identifiable public key of a legal entity or service, which makes them ill-suited to transactions where confidentiality of participants is required. This certificate is published in the network map service for anyone to access.
  • Confidential identities are only published to those who are involved in transactions with the identity. The public key may be exposed to third parties (for example to the notary service), but distribution of the name and X.509 certificate is limited.

Although there are several elements to the Keto transaction privacy model, including ensuring that transactions are only shared with those who need to see them, and planned use of Intel SGX, it is important to provide defense in depth against 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.

Certificates

Nodes must be able to verify the identity of the owner of a public key, which is achieved using X.509 certificates. When first run a node generates a key pair and submits a certificate signing request to the network Doorman service (see Network permissioning). The Doorman service applies appropriate identity checks then issues a certificate to the node, which is used as the node certificate authority (CA). From this initial CA certificate the node automatically creates and signs two further certificates, a TLS certificate and a signing certificate for the node’s well known identity. Finally the node builds a node info record containing its address and well known identity, and registers it with the network map service.

From the signing certificate the organisation can create both well known and confidential identities. Use-cases for well known identities include clusters of nodes representing a single identity for redundancy purposes, or creating identities for organisational units.

It is up to organisations to decide which identities they wish to publish in the network map service, making them well known, and which they wish to keep as confidential identities for privacy reasons (typically to avoid exposing business sensitive details of transactions). In some cases nodes may also use private network map services in addition 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.

Last updated on 31st Jan 2019

2.4.States Overview #

Overview

state is an immutable object representing a fact known by one or more Corda nodes at a specific point in time. States can contain arbitrary data, allowing them to represent facts of any kind (e.g. stocks, bonds, loans, KYC data, identity information…).

For example, the following state represents an IOU – an agreement that Alice owes Bob an amount X:

_images/state.png

Specifically, this state represents an IOU of £10 from Alice to Bob.

As well as any information about the fact itself, the state also contains a reference to the contract that governs the evolution of the state over time. We discuss contracts in Contracts.

State sequences

As states are immutable, they cannot be modified directly to reflect a change in the state of the world.

Instead, the lifecycle of a shared fact over time is represented by a state sequence. When a state needs to be updated, we create a new version of the state representing the new state of the world, and mark the existing state as historic.

This sequence of state replacements gives us a full view of the evolution of the shared fact over time. We can picture this situation as follows:

_images/state-sequence.png

The vault

Each node on the network maintains a vault – a database where it tracks all the current and historic states that it is aware of, and which it considers to be relevant to itself:

_images/vault-simple.png

We can think of the ledger from each node’s point of view as the set of all the current (i.e. non-historic) states that it is aware of.

Last updated on 5th Feb 2019

2.5.Contracts Overview #

 

Last updated on 5th Feb 2019

2.6.Transactions Overview #

Transactions

Summary

  • Transactions are proposals to update the ledger
  • A transaction proposal will only be committed if:
    • It doesn’t contain double-spends
    • It is contractually valid
    • It is signed by the required parties

Transaction verification

Recall that a transaction is only valid if it is digitally signed by all required signers. However, even if a transaction gathers all the required signatures, it is only valid if it is also contractually valid.

Contract validity is defined as follows:

  • Each state points to a contract
  • contract takes a transaction as input, and states whether the transaction is considered valid based on the contract’s rules
  • A transaction is only valid if the contract of every input state and every output state considers it to be valid

We can picture this situation as follows:

_images/tx-validation.png

The contract code can be written in any JVM language, and has access to the full capabilities of the language, including:

  • Checking the number of inputs, outputs, commands, timestamps, and/or attachments
  • Checking the contents of any of these components
  • Looping constructs, variable assignment, function calls, helper methods, etc.
  • Grouping similar states to validate them as a group (e.g. imposing a rule on the combined value of all the cash states)

A transaction that is not contractually valid is not a valid proposal to update the ledger, and thus can never be committed to the ledger. In this way, contracts impose rules on the evolution of states over time that are independent of the willingness of the required signers to sign a given transaction.

The contract sandbox

Transaction verification must be deterministic – a contract should either always accept or always reject a given transaction. For example, transaction validity cannot depend on the time at which validation is conducted, or the amount of information the peer running the contract holds. This is a necessary condition to ensure that all peers on the network reach consensus regarding the validity of a given ledger update.

To achieve this, contracts evaluate transactions in a deterministic sandbox. The sandbox has a whitelist that prevents the contract from importing libraries that could be a source of non-determinism. This includes libraries that provide the current time, random number generators, libraries that provide filesystem access or networking libraries, for example. Ultimately, the only information available to the contract when verifying the transaction is the information included in the transaction itself.

Contract limitations

Since a contract has no access to information from the outside world, it can only check the transaction for internal validity. It cannot check, for example, that the transaction is in accordance with what was originally agreed with the counterparties.

Peers should therefore check the contents of a transaction before signing it, even if the transaction is contractually valid, to see whether they agree with the proposed ledger update. A peer is under no obligation to sign a transaction just because it is contractually valid. For example, they may be unwilling to take on a loan that is too large, or may disagree on the amount of cash offered for an asset.

Last updated on 5th Feb 2019

2.7.Actions Overview #

Flows

Summary

  • Flows automate the process of agreeing ledger updates
  • Communication between nodes only occurs in the context of these flows, and is point-to-point
  • Built-in flows are provided to automate common tasks
 
Last updated on 5th Feb 2019

2.7.1.1 #

Motivation

Corda networks use point-to-point messaging instead of a global broadcast. This means that coordinating a ledger update requires network participants to specify exactly what information needs to be sent, to which counterparties, and in what order.

Here is a visualisation of the process of agreeing a simple ledger update between Alice and Bob:

_images/flow.gif

The flow framework

Rather than having to specify these steps manually, Corda automates the process using flows. A flow is a sequence of steps that tells a node how to achieve a specific ledger update, such as issuing an asset or settling a trade.

Here is the sequence of flow steps involved in the simple ledger update above:

_images/flow-sequence.png

Running flows

Once a given business process has been encapsulated in a flow and installed on the node as part of a CorDapp, the node’s owner can instruct the node to kick off this business process at any time using an RPC call. The flow abstracts all the networking, I/O and concurrency issues away from the node owner.

All activity on the node occurs in the context of these flows. Unlike contracts, flows do not execute in a sandbox, meaning that nodes can perform actions such as networking, I/O and use sources of randomness within the execution of a flow.

Inter-node communication

Nodes communicate by passing messages between flows. Each node has zero or more flow classes that are registered to respond to messages from a single other flow.

Suppose Alice is a node on the network and wishes to agree a ledger update with Bob, another network node. To communicate with Bob, Alice must:

  • Start a flow that Bob is registered to respond to
  • Send Bob a message within the context of that flow
  • Bob will start its registered counterparty flow

Now that a connection is established, Alice and Bob can communicate to agree a ledger update by passing a series of messages back and forth, as prescribed by the flow steps.

Subflows

Flows can be composed by starting a flow as a subprocess in the context of another flow. The flow that is started as a subprocess is known as a subflow. The parent flow will wait until the subflow returns.

The flow library

Corda provides a library of flows to handle common tasks, meaning that developers do not have to redefine the logic behind common processes such as:

  • Notarising and recording a transaction
  • Gathering signatures from counterparty nodes
  • Verifying a chain of transactions

Further information on the available built-in flows can be found in Flow library.

Concurrency

The flow framework allows nodes to have many flows active at once. These flows may last days, across node restarts and even upgrades.

This is achieved by serializing flows to disk whenever they enter a blocking state (e.g. when they’re waiting on I/O or a networking call). Instead of waiting for the flow to become unblocked, the node immediately starts work on any other scheduled flows, only returning to the original flow at a later date.

Last updated on 31st Jan 2019

2.7.2.Actions Framework Overview #

The flow framework

Rather than having to specify these steps manually, Corda automates the process using flows. A flow is a sequence of steps that tells a node how to achieve a specific ledger update, such as issuing an asset or settling a trade.

Here is the sequence of flow steps involved in the simple ledger update above:

_images/flow-sequence.png

 
Last updated on 5th Feb 2019

2.7.3.Building Actions Overview #

Running flows

Once a given business process has been encapsulated in a flow and installed on the node as part of a CorDapp, the node’s owner can instruct the node to kick off this business process at any time using an RPC call. The flow abstracts all the networking, I/O and concurrency issues away from the node owner.

All activity on the node occurs in the context of these flows. Unlike contracts, flows do not execute in a sandbox, meaning that nodes can perform actions such as networking, I/O and use sources of randomness within the execution of a flow.

Last updated on 5th Feb 2019

2.7.4.Inter-node communications Overview #

Inter-node communication

Nodes communicate by passing messages between flows. Each node has zero or more flow classes that are registered to respond to messages from a single other flow.

Suppose Alice is a node on the network and wishes to agree a ledger update with Bob, another network node. To communicate with Bob, Alice must:

  • Start a flow that Bob is registered to respond to
  • Send Bob a message within the context of that flow
  • Bob will start its registered counterparty flow

Now that a connection is established, Alice and Bob can communicate to agree a ledger update by passing a series of messages back and forth, as prescribed by the flow steps.

Subflows

Flows can be composed by starting a flow as a subprocess in the context of another flow. The flow that is started as a subprocess is known as a subflow. The parent flow will wait until the subflow returns.

The flow library

Corda provides a library of flows to handle common tasks, meaning that developers do not have to redefine the logic behind common processes such as:

  • Notarising and recording a transaction
  • Gathering signatures from counterparty nodes
  • Verifying a chain of transactions

Further information on the available built-in flows can be found in Flow library.

Concurrency

The flow framework allows nodes to have many flows active at once. These flows may last days, across node restarts and even upgrades.

This is achieved by serialising flows to disk whenever they enter a blocking state (e.g. when they’re waiting on I/O or a networking call). Instead of waiting for the flow to become unblocked, the node immediately starts work on any other scheduled flows, only returning to the original flow at a later date.

Last updated on 5th Feb 2019

2.8.Consensus Overview #

Consensus

Summary

  • To be committed, transactions must achieve both validity and uniqueness consensus
  • Validity consensus requires contractual validity of the transaction and all its dependencies
  • Uniqueness consensus prevents double-spends
 
Last updated on 5th Feb 2019

2.8.1.Two types of consensus Overview #

Determining whether a proposed transaction is a valid ledger update involves reaching two types of consensus:

  • Validity consensus – this is checked by each required signer before they sign the transaction
  • Uniqueness consensus – this is only checked by a notary service

Validity consensus

Validity consensus is the process of checking that the following conditions hold both for the proposed transaction, and for every transaction in the transaction chain that generated the inputs to the proposed transaction:

  • The transaction is accepted by the contracts of every input and output state
  • The transaction has all the required signatures

It is not enough to verify the proposed transaction itself. We must also verify every transaction in the chain of transactions that led up to the creation of the inputs to the proposed transaction.

This is known as walking the chain. Suppose, for example, that a party on the network proposes a transaction transferring us a treasury bond. We can only be sure that the bond transfer is valid if:

  • The treasury bond was issued by the central bank in a valid issuance transaction
  • Every subsequent transaction in which the bond changed hands was also valid

The only way to be sure of both conditions is to walk the transaction’s chain. We can visualize this process as follows:

_images/validation-consensus.png

When verifying a proposed transaction, a given party may not have every transaction in the transaction chain that they need to verify. In this case, they can request the missing transactions from the transaction proposer(s). The transaction proposer(s) will always have the full transaction chain, since they would have requested it when verifying the transaction that created the proposed transaction’s input states.

Uniqueness consensus

Imagine that Bob holds a valid central-bank-issued cash state of $1,000,000. Bob can now create two transaction proposals:

  • A transaction transferring the $1,000,000 to Charlie in exchange for £800,000
  • A transaction transferring the $1,000,000 to Dan in exchange for €900,000

This is a problem because, although both transactions will achieve validity consensus, Bob has managed to “double-spend” his USD to get double the amount of GBP and EUR. We can visualize this as follows:

_images/uniqueness-consensus.png

To prevent this, a valid transaction proposal must also achieve uniqueness consensus. Uniqueness consensus is the requirement that none of the inputs to a proposed transaction have already been consumed in another transaction.

If one or more of the inputs have already been consumed in another transaction, this is known as a double spend, and the transaction proposal is considered invalid.

 

Last updated on 5th Feb 2019

2.9.Overview #

Nodes

Summary

  • A node is JVM run-time with a unique network identity running the Keto software

  • The node has two interfaces with the outside world:

    • A network layer, for interacting with other nodes
    • RPC, for interacting with the node’s owner
  • The node’s functionality is extended by installing Keto D-Apps in the plugin registry

 
Last updated on 31st Jan 2019

2.9.1.Node architecture Overview #

Node architecture

A Corda node is a JVM run-time environment with a unique identity on the network that hosts Corda services and CorDapps.

We can visualize the node’s internal architecture as follows:

_images/node-architecture.png

The core elements of the architecture are:

  • A persistence layer for storing data
  • A network interface for interacting with other nodes
  • An RPC interface for interacting with the node’s owner
  • A service hub for allowing the node’s flows to call upon the node’s other services
  • A cordapp interface and provider for extending the node by installing CorDapps
Last updated on 5th Feb 2019

2.9.2.Persistence layer, Network interface, RPC, The service hub Overview #

Persistence layer

The persistence layer has two parts:

  • The vault, where the node stores any relevant current and historic states
  • The storage service, where it stores transactions, attachments and flow checkpoints

The node’s owner can query the node’s storage using the RPC interface (see below).

Network interface

All communication with other nodes on the network is handled by the node itself, as part of running a flow. The node’s owner does not interact with other network nodes directly.

RPC interface

The node’s owner interacts with the node via remote procedure calls (RPC). The key RPC operations the node exposes are documented in API: RPC operations.

The service hub

Internally, the node has access to a rich set of services that are used during flow execution to coordinate ledger updates. The key services provided are:

  • Information on other nodes on the network and the services they offer
  • Access to the contents of the vault and the storage service
  • Access to, and generation of, the node’s public-private keypairs
  • Information about the node itself
  • The current time, as tracked by the node

The CorDapp provider

The CorDapp provider is where new CorDapps are installed to extend the behavior of the node.

The node also has several CorDapps installed by default to handle common tasks such as:

  • Retrieving transactions and attachments from counterparties
  • Upgrading contracts
  • Broadcasting agreed ledger updates for recording by counterparties

Draining mode

In order to operate a clean shutdown of a node, it is important than no flows are in-flight, meaning no checkpoints should be persisted. The node is able to be put in a Flows Draining Mode, during which:

  • Commands requiring to start new flows through RPC will be rejected.
  • Scheduled flows due will be ignored.
  • Initial P2P session messages will not be processed, meaning peers will not be able to initiate new flows involving the node.
  • All other activities will proceed as usual, ensuring that the number of in-flight flows will strictly diminish.

As their number – which can be monitored through RPC – reaches zero, it is safe to shut the node down. This property is durable, meaning that restarting the node will not reset it to its default value and that a RPC command is required.

Last updated on 5th Feb 2019

3.How to - Overview #

bla bla bla

Last updated on 6th Feb 2019

3.1.Hallo World D-Apps Overview #

3.2.Hallo World Token Overview #

3.3.How to - Side-chain Overview #

3.4.How to - Private Side-chain Overview #

4.API's Overview #

5.SDK's Overview #

5.1.Typescript Overview #

Typescript SDK

Last updated on 23rd Feb 2019

5.2.Java Overview #

5.3.Javascript Overview #

5.4.C/C++ Overview #

skjflsdkfldskjfdsf

Close Menu
×
×

Cart