RChain consensus specification


PoS Consensus - Proof Of Stake  - A family of blockchain consensus protocols.  https://en.wikipedia.org/wiki/Proof-of-stake

GHOST Protocol - 'Greedy Heaviest Observed SubTree'.  https://github.com/ethereum/wiki/wiki/White-Paper#modified-ghost-implementation


Talk about Proof of work, investment, mining and nonces.  

In order to participate in the protocol as a validator, a bond must be provided.  This bond replaces the financial penalties associated with cheating in the traditional Proof of Work consensus model employed by Bitcoin.  It also replaces the infrastructure investment, in that since work is not needed to propose a block, large amounts of compute are similarly no longer required.


Bonded Validator: 

A client that has provided a bond in the form of tokens.  Initially (Mercury timeframe) the only staking token that will be supported is the Rev token.  In the future, additional tokens may be supported in specific namespaces/regions or shards.

Unbonded Validator:

A client that was previously a bonded validator that has requested to leave the validator set and is waiting to reclaim their stake.  During this time, the client can no longer propose blocks or be paid fees.  They can, however, be slashed if previous block proposals include slashable offenses, and cryptographic evidence is provided to that effect by another validator or watcher.


The Consensus protocol has to do the following:

  • Create an economic incentive for validators to join the network and participate in the protocol.
  • Create an economic incentive to finalize user transactions.
  • Create an economic cost to validators engaging in bad behavior.
    • This behavior is identifiable by other validators in the network.
  • Validators can join and leave the network at will without damaging the network.
  • The validators can be anonymous with the exception of their public key.
  • Account for connectivity issues, validators will not receive 100% of messages or transactions.
  • The protocol is resistant to the following attacks:
    • Army of ants attack
    • Byzantine Generals problem
    • Whales (Centralization, where the network is controlled by a few actors)

The Consensus protocol should also support the following:

  • Not waste electricity (Not be a Proof of Work protocol)
  • Be significantly faster than PoW
  • Run on simpler hardware (personal computers) given fast, reliable network connectivity (depends on software footprint of the node itself)

The Proof of Stake Contract

Proof-of-stake in RChain will be handled by the PoS "blessed" contract within the RChain state. Since all validators must know about each other, this contract will live in the top level namespace (see Powerset shards - sharding solution is still TBD).  The root namespace will store the validator set and their bonds and derive the individual validator weights from that information. 

This contract will perform the following functions:

  • Bonding (adding new validators)
  • Unbonding (removing validators)
  • Slashing

Additionally, each shard will have a local version of the PoS blessed contract which performs the following functions:

  • Rewards distribution (paying validators transaction fees for the work they do)
    • Rewards will only be paid in Rev in the Mercury time frame.
  • Implements the rate at which new blocks are proposed (Block Gas limit), which is included as part of the block?
  • Transaction gas limit - the minimum gas limit in order to accept a transaction for processing.
  • Medha Parlikar (Unlicensed): Determine if we will support a block gas limit, which will operate as a 'default' in the event that a validator doesn't want to explicitly propose blocks.

Bonding Process

A prospective validator will make a bonding request via the bonding API call to a validator in a shard requesting to join the validator group.  The bonding request has to contain the following parameters:

  • The validator id
  • The address or purse containing the bond
  • The address or purse where rewards will be paid.

When the bonding request is approved the following happens:

  • The node will receive the necessary blocks required to start validating.
  • A response is sent to the client making the request that the bonding request was approved.

If the bonding request is not approved:

  • A message to that effect is returned to the client with a reason for the rejection.

Reasons for rejecting a bonding request:

  • Insufficient/empty bond (results in immediate rejection of request)
  • Bad cryptographic evidence (results in deduction of tokens from purse)
  • Duplicate validator id
  • Medha Parlikar (Unlicensed): region is full - will we have maximums on validator counts?  - No, we will let economics handle that piece.  Validators will go where the money is.


Unbonding is triggered when the PoS contract is invoked (again in the normal way) with the signature of an existing validator along with a return channel. On the return channel, an unforgeable name is sent, which the now ex-validator can listen on. After the post-unbonding stake holding time has elapsed, a purse containing the ex-validaor's stake is sent on that name, thus allowing the validator to recover their bond. The unbonding is successful so long as it does not exceed the unbonding rate specified for the region.

  • The the post-unbonding wait time can be set by the region, but the protocol should define a minimum, to prevent a shard from reducing security by allowing validators to unbond too quickly. 
  • The maximum unbonding rate (N validators per 100 blocks) can be set within the region. 
  • The validator remains on the list of validators until the post-unbonding period has elapsed.
  • When an unbonding request comes into the contract, rewards are paid out to the bonded validators.  The validator that is unbonding has their rewards added to their bond purse only.  This is to prevent cheating in the event transaction fees exceed the bond amount forfeited.
  • Medha Parlikar (Unlicensed): If validator limits for a given shard do not exist, then the queue becomes a moot point.  The decision on validator limits has not been made yet.

Unbonding Wait Period

During this time the validator is not active.  The validator cannot propose blocks, nor receive rewards.  The stake is held by the PoS contract, and the validator can be slashed by other validators.  The other validators are not aware that the validator has requested to unbond.  The unbonding request is held by the PoS contract in the shard.   Note that no rewards are distributed at this time, only the exact original stake (minus any slashed amount) is returned. Unpaid rewards can be withdrawn from the shard's local PoS contract after unbonding has occurred (see below). 

The purpose of this wait time is to prevent a variant of the "long range attack" (reference Details of Proof-of-Stake in RChain )

  • Medha Parlikar (Unlicensed): Finalize the unbonding wait period If we are going to be pruning the blockchain, then a long range attack is easier, not harder for a validator to execute.  
  • Medha Parlikar (Unlicensed): If we are pruning / gc'ing the blockchain, is there a need to hold on to the entire blockchain, so that long range attacks can be identified and validators slashed?  Can this be part of the role of a watcher?


Slashing is triggered when the PoS contract is invoked with the following arguments:

  • ID of the offender (a validator)
  • Signature of the accuser (a validator or watcher)
  • Offence descriptor
  • Cryptographic evidence of the offence
  • A purse return channel

Only validators can slash and the slashed bond is distributed equally among all remaining validators. If the evidence is invalid then the block that includes the invalid slashing transaction is considered invalid, eventually leading to the accusers bond to be deducted instead. If a validator's stake drops to 0 then they are automatically unbonded. The following are slashable offences:

  • Breach of SLA (as defined by the specific region; the evidence to prove performance failure is also region specific)
  • Not following the rules
    • Producing an invalid block: evidence = signed message from offender sending that block
    • Equivocation (as defined in CBC Casper protocols): evidence = pair of signed messages from offender which cannot be causally ordered by justifications

Notification of Slash

A validator that has been slashed will be notified that he has been slashed, what the offence was (SLA, equivocation, invalid block).

  • Medha Parlikar (Unlicensed): With sharding, determine where slashing takes place.  Where will slashing events be recorded on the blockchain.
    • Michael Birch (Unlicensed): Based on Shards in RChain, validator bond amounts are stored in the parent shard.  Slashing events will be recorded in the parent shard as well as the shard where the offence took place.
  • Medha Parlikar (Unlicensed): Determine how much gossip is needed in the network about a slashed validator.  Should the entire network be informed, if so, what will the validators do with that information.

Slashing amounts

Slashing API

Authored by Former user (Deleted)

This details the slashing API for the proof of stake contract. Each bullet will become an API endpoint where the arguments will be the blocks that are asked of. If the same block can be slashed for multiple reasons, use the ordering of the following list to determine precedence.

  • For invalid blocks that are missing any required fields. Note a block must contain at least a sender and a valid signature from that sender in order to be considered a block. This is 1 block.
  • For blocks that have parents that don't lead back to a block in the blockDAG, show the justification chains up until at least X blocks including the block in question. Note that this should only be done after catching up to around the latest block. It is at least X blocks instead of exactly X because you want to make sure that other validators can reproduce seeing X blocks that don't lead back to something in the blockDAG. This can be any amount greater than X+1 blocks.
  • For blocks that have hashes that aren't the same as the computed hashes. This includes the block hash, the parents hash list, the post state hash, the new code hash, and the transaction receipt logs hash. This is 1 block.
  • For blocks with an invalid block number, show the parent block and the block in question. This is 2 blocks.
  • For blocks with an invalid sequence number, show the creator justification block and the block in question. This is 2 blocks.
  • For blocks that don't have bonded validators field reflecting the bonded validators in the proof of stake contract (including validating that the bonded stake is above a certain minimum threshold), show that invalid block. This is 1 block.
  • For blocks that don't have a parent that matches the derived parent based on the estimator, show all the justification blocks and the block in question. This is one more than the number of validators.
  • For blocks that contain invalid transactions/deployments (including invalid slashing transactions that are valid from the Rholang interpreter's standpoint), show that invalid block. This is 1 block.
  • For block(s) in the chain that have the same (user, millisecond timestamp) transaction, show the invalid block(s) that contain those transactions. This is at least 2 blocks.
  • For blocks that contain justifications that lead to invalid blocks but don't slash their creator, show the justification chain that leads to that invalid block including the invalid block itself. This is at least 2 blocks.
  • For blocks that contain justifications that lead to knowledge of a equivocation but don't slash the equivocator, show the justification chain(s) that lead to three blocks that are enough to minimally prove the equivocation. This is at least 4 blocks.
  • For equivocations, show the base equivocation block and the two that have sequence numbers that follow. This is 3 blocks.


A basic ejection criteria that addresses the 'lazy' validator or 'underperforming' validator is required, in order to ensure the security of the network.  At some random interval, one of the validators in the set proposes an invalid block.  Which validator needs to also be randomized.  The invalid block is a challenge to one of the other validators in the set.  Which validator is challenged is also randomized.  The validator presenting the challenge also holds an associated 'coupon' that can be redeemed against a slash. The coupon is only good for the slashing event associated with that particular challenge block.  There are one of 3 possible outcomes from the challenge:

  • The validator responds correctly - with a slash. 
  • The validator responds incorrectly -  they accept the block & add a justification.  
    • Medha Parlikar (Unlicensed): If a validator accepts an invalid block they should be slashed for being a lazy validator and just accepting blocks.
  • The validator does not respond
    • In this event, the validator may have failed to receive the block, or is underperforming.
      • Medha Parlikar (Unlicensed): Determine how we will quantify that the validator is underperforming.  this may require 'N' successive failures
      • In this event, the validator will not be slashed, but be ejected.  There is a question regarding transaction fees.  Validators that are ejected for non-performance should not receive fees.

The kinds of invalid blocks need to be determined.  The invalidity of the block must be subtle, and should only present itself when the validator attempts to update its state (run the contents of the block).  What is injected into the block has to be something that can be created programmatically, that is more expensive to detect outside of validating the block.

Rewards Distribution

Rewards distribution is handled by a local PoS contract. Fees will accrue within the PoS contract or a purse controlled by the PoS contract.  At a random interval, the PoS contract will divide the fees by the number of validators in the shard and distributes the fees to the validator set. 

Rewards will accrue until the validator withdraws their rewards. 

The validator can withdraw their rewards from the local PoS contract by calling the contract with the following information:

  • Private key signature associated with the public validator key
  • A purse return channel
  • Medha Parlikar (Unlicensed): Validators will have to provide a purse or address for their rewards.   The bonding request will need to include this location as well.

Reference: RChain Validator Economics


The blessed Rev mint contract can only exist in a single namespace.  If the mint exists at the root namespace, it will exist in the same namespace where all the staking, sharding and validator information for the network is stored.  Can the Rev mint contract mint Rev and distribute the Rev to PoS contracts in shards for distribution as validator rewards?  Rev' Tokens in the shards would be considered as 'backed by Rev' much in the same way as a currency is backed by gold.  

Reference: RChain Validator Economics

The rate at which this Rev is minted by the blessed Rev Contract:Reference: RChain Validator Economics

How PoS contracts in a shard distribute Rev rewards (separate from transaction fees) :Reference: Shards in RChain

GHOST Protocol

There are 2 stages to the protocol: Scoring and Traversal


The validator weight is tied to the validator's bond amount.  The validator weight is assigned by the PoS contract running in the root shard, and is determined by the validators' bond in relation to the total bond staked in the network.  These validator weights will change as validators bond and unbond from the network.

When a validator places a bet on a block, the validator's weight is added to the block' score. 


Justifications are the validator's reasons why a block is included or not included as part of the fork-choice-rule.  In essence a validator says 'I'm betting on this proposed block because it has the most weight' or 'I'm NOT betting on this proposed block because this other block has more weight'.  Justifications are part of the block data, and this is how a block makes its way to finalization.  

Scoring in action:  

To see multiple blocks and the progression of scoring, reference the Consensus presentation here: https://docs.google.com/presentation/d/1znz01SF1ljriPzbMoFV0J127ryPglUYLFyhvsb-ftQk/edit#slide=id.g36e6995ef0_2_28

Transaction confirmation

Current day practice with bitcoin and other PoW coins is to wait for 6 blocks to be added to the chain after the transaction has been proposed within a block.  This means that the transaction confirmation time is actually 6X the block creation time.  This isn't acceptable as a go forward plan for the RChain blockchain.  There needs to be some mechanism that can provide fault tolerance information and finalization information for a given block.  Furthermore,  if blocks are being created at different rates in different shards, it makes it hard for industries to obtain a sense for how long transaction finalization will take.  Exchanges and users will need to know transaction confirmation status, how confident they can be in a transaction's 'finality' and some estimation of transaction confirmation times.

  • There is a mechanism that emits the blocks that are considered 'finalized' by the protocol.
  • There is a mechanism that emits the clique or a way to calculate the clique for each block, so that interested parties can observe the level of fault tolerance (risk of reversal) for the block.

The system will race to quiescence.