NOTE: This document is DEPRECATED. A new version will be published at some point.

1 Motivation
2 Outstanding issues
3 Architecture
- 3.1 Components
  - 3.1.1 Common data structures
    - 3.1.1.1 KonsensusConfig
    - 3.1.1.2 ValidatorConfig
  - 3.1.2 K-of-N consensus
    - 3.1.2.1 KonsensusFactory
    - 3.1.2.2 KonsensusProxy
    - 3.1.2.3 KoNsensus
    - 3.1.2.4 KonsensusUpdater
  - 3.1.3 Child-validator management
    - 3.1.3.1 ValidatorManager
    - 3.1.3.2 StakeAdder
    - 3.1.3.3 Validator
  - 3.1.4 Depository
  - 3.1.5 The Mint
  - 3.1.6 Wallets
- 3.2 Shard tree setup
  - 3.2.1 Sprout
    - 3.2.1.1 K-of-N Konsensus setup
    - 3.2.1.2 Mint & Depository setup
    - 3.2.1.3 Stake placement
  - 3.2.2 Removing a stakeholder
  - 3.2.3 Adding a stakeholder
  - 3.2.4 Child-shard absorption
  - 3.2.5 Mount
  - 3.2.6 Umount
- 3.3 Atomic cross-shard value transfer
  - 3.3.1 Parent-to-child transfer
  - 3.3.2 Child-to-parent transfer
4 Useful links

Motivation

The purpose of the protocol is to transfer value between independent shards.

The shards could be either RChain networks or any other network that implements the protocol.

Each client trusts his own shard and it's ancestors all the way up to the root shard. Clients living in two different shards will not both trust the other party's shard.

For this reasons, when two parties are transferring value between two arbitrary shards, they should meet at the least common ancestor, where the value exchange between the two parties becomes a normal blockchain transaction.

The cross-shard value transfer protocol provides a way for each of the clients to move value from their own wallets to a parent shard or back.

Outstanding issues

how to do weighted multi-signature
notification on block finalization (check with @Michael Birch (Unlicensed) & @Former user (Deleted))
Should we have a shard DAG in a future version?
how to roll-back cross-shard transfers when something goes wrong during the transfer?
how to mount an existing shard?
How to unmount a shard without destroying it?
Why not register all the wallets in a public WalletRegistry?
Do we sign the "approved" contracts used for REV?
How to avoid the situation when the validators move their stakes out of the child shard while still holding their validator status?
How does interaction with PoS contract happens at bonding/unbonding
how to update K in order to keep the K/N ratio the same as validators bond/unbond. Should we keep the ratio in the config and re-compute K each time?

Architecture

The shards are organised in a tree structure.

The dependencies are from child shards to parent shards.

The validators of the child chard act as clients of the parent shard.

The parent shard validators are not involved in the child shards.

Components

Common data structures

KonsensusConfig

genesis_hash
validators : [ ValidatorConfig ]
k : Int

ValidatorConfig

ip_address
public_key
expected_bond : Int

K-of-N consensus

KonsensusFactory

Creates the Konsensus contract. This extra layer is needed because the create call has to be confirmed by all the validators.

KonsensusFactory API

KonsensusFactory API
create	KonsensusConfig→ KonsensusFactory	Instantiates the K-of-N contract given the public keys of the validators and a given K value
createKonsensus	Signature → Konsensus	Creates the consensus after all the signatures are accumulated. The expected signature is the name of Konsensus process, signed with the caller's private key. The call returns only when all the required signatures are accumulated.

KonsensusProxy

This is used to control messages sent to a name. The notation KonsensusProxy[X] used further means that, after a message with K signatures is received the call will be forwarded to X.

The KonsensusProxy is instantiated by Konsensus:makeProxy. The K used is the one which Konsensus was created with, See KonsensusFactory:create

KonsensusProxy

KonsensusProxy
send	Message → Signature → Unit	Accumulates K signatures on a message. After all the K messages are received the message is forwarded to the underlying address. The expected signature is the message signed with the callers' private key.

KoNsensus

A smart contract running in the parent shard which supervises the consensus in the child shard by running a K-of-N algorithm.

This mechanism is required because the parent shard validators don't want to be aware of any child shards.

Processes that require k-of-n consensus are wrapped in a KonsensusProxy by calling makeProxy

Konsensus API

Konsensus API
getConfig	Unit → KonsensusConfig	returns the configuration of the Konsensus contract
getUpdater	Unit → KonsensusProxy[KonsensusUpdater]	Creates an updater for this Konsensus instance, wrapped in a KonsensusProxy that requires signatures equal to the number of public-keys
makeProxy	Name → KonsensusProxy[_]	Creates a proxy on top of an existing name

(deprecated) Cross-shard transfers