• Stars
    star
    105
  • Rank 328,130 (Top 7 %)
  • Language
    JavaScript
  • License
    Other
  • Created almost 6 years ago
  • Updated over 2 years ago

Reviews

There are no reviews yet. Be the first to send feedback to the community and the maintainers!

Repository Details

Smart contracts for POSDAO (Proof of Stake Decentralized Autonomous Organization consensus), a DPOS consensus implemented in Solidity and running within EVM with swappable BFT consensus

POSDAO Smart Contracts

Implementation of the POSDAO consensus algorithm in Solidity.

About

POSDAO is a Proof-of-Stake (POS) algorithm implemented as a decentralized autonomous organization (DAO). It is designed to provide a decentralized, fair, and energy efficient consensus for public chains. The algorithm works as a set of smart contracts written in Solidity. POSDAO is implemented with a general purpose BFT consensus protocol such as AuthorityRound (AuRa) with a leader and probabilistic finality, or Honeybadger BFT (HBBFT), leaderless and with instant finality. It incentivizes actors to behave in the best interests of a network.

The algorithm provides a Sybil control mechanism for reporting malicious validators and adjusting their stake, distributing a block reward, and managing a set of validators. The authors implement the POSDAO for a sidechain based on Ethereum 1.0 protocol.

POSDAO Repositories and Resources

Smart Contract Summaries

Note: The following descriptions are for AuRa contracts only. HBBFT contract implementations are not started yet and are not listed nor described here. All contracts are located in the contracts directory.

  • BlockRewardAuRa: generates and distributes rewards according to the logic and formulas described in the white paper. Main features include:

    • distributes the entrance/exit fees from the erc-to-erc, native-to-erc, and/or erc-to-native bridges among validators pools;
    • mints native coins needed for the erc-to-native bridge;
    • makes a snapshot of the validators stakes at the beginning of each staking epoch. That snapshot is used by the StakingAuRa.claimReward function to transfer rewards to validators and their delegators.
  • Certifier: allows validators to use a zero gas price for their service transactions (see OpenEthereum Wiki for more info). The following functions are considered service transactions:

    • ValidatorSetAuRa.emitInitiateChange
    • ValidatorSetAuRa.reportMalicious
    • RandomAura.commitHash
    • RandomAura.revealNumber
  • Governance: lets any validator to create a ballot for some validator removal. This can be helpful when some validator doesn't work for a long time or delays blocks. Validators can vote to remove a bad validator from the validator set.

  • InitializerAuRa: used once on network startup and then destroyed. This contract is needed for initializing upgradable contracts since an upgradable contract can't have the constructor. The bytecode of this contract is written by the scripts/make_spec.js into spec.json along with other contracts when initializing on genesis block.

  • RandomAuRa: generates and stores random numbers in a RANDAO manner (and controls when they are revealed by AuRa validators). Random numbers are used to form a new validator set at the beginning of each staking epoch by the ValidatorSet contract. Key functions include:

    • commitHash and revealNumber. Can only be called by the validator's node when generating and revealing their secret number (see RANDAO to understand principle). Each validator node must call these functions once per collection round. This creates a random seed which is used by ValidatorSetAuRa contract. See the white paper for more details;

    • onFinishCollectRound. This function is automatically called by the BlockRewardAuRa contract at the end of each collection round. It controls the reveal phase for validator nodes and punishes validators when they donโ€™t reveal (see the white paper for more details on the banning protocol);

    • currentSeed. This public getter is used by the ValidatorSetAuRa contract at the latest block of each staking epoch to get the accumulated random seed for randomly choosing new validators among active pools. It can also be used by anyone who wants to use the network's random seed. Note, that its value is only updated when revealNumber function is called: that's expected to be occurred at least once per collection round which length in blocks can be retrieved with the collectRoundLength public getter. Since the revealing validator always knows the next random number before sending, your DApp should restrict any business logic actions (that depends on random) during reveals phase.

      An example of how the seed could be retrieved by an external smart contract.
      pragma solidity 0.5.11;
      
      
      interface IPOSDAORandom {
          function collectRoundLength() external view returns(uint256);
          function currentSeed() external view returns(uint256);
      }
      
      contract Example {
          IPOSDAORandom private _posdaoRandomContract; // address of RandomAuRa contract
          uint256 private _seed;
          uint256 private _seedLastBlock;
          uint256 private _updateInterval;
      
          constructor(IPOSDAORandom _randomContract) public {
              require(_randomContract != IPOSDAORandom(0));
              _posdaoRandomContract = _randomContract;
              _seed = _randomContract.currentSeed();
              _seedLastBlock = block.number;
              _updateInterval = _randomContract.collectRoundLength();
              require(_updateInterval != 0);
          }
      
          function useSeed() public {
              if (_wasSeedUpdated()) {
                  // using updated _seed ...
              } else {
                  // using _seed ...
              }
          }
      
          function _wasSeedUpdated() private returns(bool) {
              if (block.number - _seedLastBlock <= _updateInterval) {
                  return false;
              }
      
              _updateInterval = _posdaoRandomContract.collectRoundLength();
      
              uint256 remoteSeed = _posdaoRandomContract.currentSeed();
              if (remoteSeed != _seed) {
                  _seed = remoteSeed;
                  _seedLastBlock = block.number;
                  return true;
              }
              return false;
          }
      }
  • Registry: stores human-readable keys associated with addresses, like DNS information. This contract is needed primarily to store the address of the Certifier contract (see OpenEthereum Wiki for details).

  • StakingAuRa: contains staking logic including:

    • creating, storing, and removing pools by candidates and validators;
    • staking tokens by participants (delegators, candidates, or validators) into the pools;
    • storing participantsโ€™ stakes;
    • withdrawing tokens and rewards by participants from the pools;
    • moving tokens between pools by participant.
  • TokenMinter: used when we need to have an ability to mint POSDAO tokens not only by the bridge, but also by the BlockRewardAuRa contract if the staking token contract doesn't support a mintReward function. Particularly, it is used for the PermittableToken contract: https://blockscout.com/poa/xdai/address/0xf8D1677c8a0c961938bf2f9aDc3F3CFDA759A9d9/contracts. The PermittableToken contract is a reduced version of the full ERC677BridgeTokenRewardable contract.

  • TxPermission: along with the Certifier contract, controls the use of zero gas price by validators in service transactions, protecting the network against "transaction spamming" by malicious validators. The protection logic is declared in the allowedTxTypes function.

  • TxPriority: manages and stores the transactions priority list used by Ethereum client. See NethermindEth/nethermind#2300 for description.

  • ValidatorSetAuRa: stores the current validator set and contains the logic for choosing new validators at the beginning of each staking epoch. The logic uses a random seed generated and stored by the RandomAuRa contract. Also, ValidatorSetAuRa is responsible for discovering and removing malicious validators. This contract is based on reporting ValidatorSet described in OpenEthereum Wiki.

For a detailed description of each function of the contracts, see their source code.

Usage

Install Dependencies

$ npm install

Testing

Note: Test development for unit testing and integration testing is in progress.

Integration test setup is available here: https://github.com/poanetwork/posdao-test-setup

To run unit tests:

$ npm run test 

Flatten

Flattened contracts can be used to verify the contract code in a block explorer like BlockScout or Etherscan. See https://docs.blockscout.com/for-users/smart-contract-interaction/verifying-a-smart-contract for Blockscout verification instructions.

To prepare flattened version of the contracts:

$ npm run flat

Once flattened, the contracts are available in the flat directory.

Security Audit

Contributing

See the CONTRIBUTING document for contribution, testing and pull request protocol.

License

Licensed under either of:

at your option.

More Repositories

1

token-wizard

(Discontinued) TokenWizard is an DApp to create and manage crowdsale and token contracts using a simple UI
JavaScript
384
star
2

hbbft

An implementation of the paper "Honey Badger of BFT Protocols" in Rust. This is a modular library of consensus.
Rust
356
star
3

solidity-flattener

Utility to combine Solidity project to a flat file
JavaScript
326
star
4

threshold_crypto

A pairing-based threshold cryptosystem for collaborative decryption and signatures used in HoneybadgerBFT implementation
Rust
185
star
5

vdf

An implementation of Verifiable Delay Functions in Rust
Rust
170
star
6

wiki

POA Library: wiki, how-to, FAQ. Includes instructions how to set-up a new network, to run a full node, connect wallets,
81
star
7

poa-network-consensus-contracts

Main repository for POADAO consensus. Includes contracts for Initial Ceremony, Governance, Management of Validators
JavaScript
67
star
8

ex_abi

The Ethereum ABI Interface
Elixir
60
star
9

poa-faucet

POA Network faucet
SCSS
57
star
10

proofofphone

KYC oracle to link your phone number and Ethereum wallet in Oracles network
JavaScript
48
star
11

blockscout-terraform

An automation framework for spinning up cloud infrastructure to run BlockScout
HCL
46
star
12

poa-chain-spec

Spec files, bootnodes, governance contracts addresses for POA Network instances: Core (live), Sokol (test), xDai
33
star
13

poa-dapps-voting

POA Network Governance Dapp
JavaScript
26
star
14

deployment-playbooks

Ansible playbooks for deployment POA Network nodes on EC2 or any Linux (Ubuntu 16.04) hosting. Includes master of ceremony, validator, bootnode, explorer, netstat roles
Shell
25
star
15

poa-popa

DApp for proof of physical address (PoPA) attestation for validators of POA Network
JavaScript
24
star
16

hydrabadger

A simple, experimental, peer-to-peer network node using the hbbft consensus algorithm which can be run as a standalone client or used as a library
Rust
22
star
17

poa-dapps-validators

DApp for a list of validators with metadata for POA Network (Core/Sokol). Validators can update metadata using DApp.
JavaScript
13
star
18

chain-explorer

Blockchain explorer
JavaScript
13
star
19

poa-netstats-agent

Netstat agent for EVM based networks
Elixir
11
star
20

poa-devops

POA Network DevOps scripts
Shell
11
star
21

website

website and documentation home of poanetwork.com
11
star
22

parity-bridge-research

Reasarch of https://github.com/paritytech/parity-bridge/
Solidity
9
star
23

poa-test-setup

Deployment of POA network in one click and e2e tests of Ceremony/Governance DApps
JavaScript
9
star
24

deployment-terraform

Ansible and Terraform deployment automation of POA clones
JavaScript
9
star
25

poa-dapps-keys-generation

POA Network keys generation Dapp
JavaScript
9
star
26

hex_fmt

Formatting and shortening byte slices as hexadecimal strings
Rust
8
star
27

poa-ballot-stats

Read POA voting records and rank voters by how many ballots they missed.
Rust
7
star
28

deployment-azure

Azure Templates for deploying POA Network to on Azure Cloud
7
star
29

cross-chain-deploy

JavaScript
6
star
30

eth-netstats

Netstats dashboard
JavaScript
6
star
31

howey-test-wizard

Howey test for blockchain tokens and crypto assets
JavaScript
5
star
32

hydrabadger-android

Mobile messenger based on hbbft consensus
JavaScript
4
star
33

poa-netstats-warehouse

Storage and data-processing companion for the poa-netstats-agent
Elixir
4
star
34

poamania-contracts

Smart contracts for POA Mania
JavaScript
4
star
35

poa-poba

DApp for proof of bank account (PoBA) attestation
JavaScript
3
star
36

poa-scripts-moc

Scripts for Master of Ceremony (MoC) to generate initial keys, distribute tokens, and misc.
JavaScript
3
star
37

eth-net-props

Get properties of EVM compatible networks
JavaScript
3
star
38

RFC

Technical write-ups that describe modifications to the Protocol, DApps, or any significant topic.
3
star
39

tokensale-right

Treasury and token contracts (right side of the bridge)
2
star
40

poa-scripts-validator

Script for validator
JavaScript
2
star
41

auto-updater-setup

How to setup parity auto-updater
2
star
42

ethgasstation-gasPrice-estimate

Python
2
star
43

poa-network-monitor

Scripts for POA network monitoring
JavaScript
2
star
44

poa-governance-notifications

A CLI tool for monitoring a blockchain for POA Network governance ballots.
Rust
2
star
45

e2e-test-token-wizard

A tool for end-to-end test the Token wizard. Based Selenium Webdriver.
JavaScript
2
star
46

e2e-blockscout

End to end tests for BlockScout https://github.com/poanetwork/blockscout
JavaScript
1
star
47

validator-node-dockerized

How to launch validator node with Docker Compose
Shell
1
star
48

poa-contract-metadata

A mapping of POA contract addresses to broadly accepted icons for those addresses.
JavaScript
1
star
49

poamania-subgraph

TypeScript
1
star
50

eth-net-intelligence-api

Netstats service
JavaScript
1
star
51

wallet

MyEtherWallet with POA Network support
JavaScript
1
star