Peerplays Technical Summary
Peerplays is a decentralized, global crypto platform, built on the most advanced blockchain technology available today. Peerplays brings a new paradigm of fairness, speed, transparency, and security to the global economy.
Peerplays’ decentralization is based on the Delegated Proof of Stake (DPoS) consensus model, meaning that blocks are produced by a group of "Witness" nodes which are elected by stake-weighted token holder voting.
In addition to the Witnesses and the Advisors, a group of blockchain accounts, likewise elected by token holder voting, which vote to specify configurable blockchain parameters, and vote to include or reject proposed new features and other modifications to the consensus protocol.
Peerplays is a smart contracting platform specifically targeted at humanizing crypto economies.
Peerplays is not a Turing complete smart contracting platform, meaning that Peerplays does not support arbitrary, user-defined smart contracts; rather, it provides a well-defined set of officially maintained, built-in contracts. This is in contrast to Turing complete smart contracting platforms like EOS or Ethereum, which provide few to no official contracts, but allow users to define and share contracts without any formally defined quality or correctness verification.
This document is intended to give new Peerplays developers an introduction to the Peerplays architecture and software. Readers are expected to be familiar with C++ software development in general, but not with Peerplays specifically.
This document will walk readers through the code repository structure and how to build the software; describe the individual libraries and executables and their purposes; and examine how the smart contracts work and discuss how to create or modify Peerplays smart contracts.
Graphene is the underlying technology behind the Peerplays blockchain. It's an open-source blockchain technology, mainly written in C++. The Graphene source is available in numerous variations, as it has been forked and adapted many times.
There is no other known blockchain like Graphene that can even try to compete in the processing such a high number of transactions this blockchain already can.
Graphene-based coins can do something Bitcoin was never capable of, and will never be. And that is being a real-time value exchange system that will get mass adoption, with great apps built upon it.
A few of the advantages of Graphene are:
- Can push over 10,000 transactions per second (TPS), versus Bitcoin, currently at around 7 transactions per second - this could mean Bitcoin payments hanging for 3-4 days!
- Best-in-class block production and transaction finality at three seconds compared to Bitcoin at 10 minutes.
- Supports payments with zero commission. Users can transfer coins from one account to another absolutely free of charge.
- Uses the Delegated Proof of Stake (DPOS) algorithm instead of Proof of work (POW).
- The possibility of working with several tokens in one system at once.
The key Graphene resources can be found here and are a very good starting point for anyone wanting to understand the Peerplays blockchain.
Peerplays is based on the Delegated Proof of Stake (DPOS) consensus mechanism, where the number of Witnesses are selected, via continuous voting by the PPY token holders, to produce blocks.
Note: The number of block producing (active) Witnesses has to be an odd number.
Only these Witnesses produce the blocks in their respective time slots until the next maintenance interval. After the maintenance interval, the algorithm chooses the next set of Witnesses based on the voting results. Furthermore:
- Only token holders can participate in the voting process.
- Token holders can vote multiple times, for multiple Witnesses.
Apart from Witnesses, the token holders also elect Advisors who have the privilege of proposing changes to the network parameters. These changes range from something as simple as transaction fees – to the number of elected Witnesses.
Under DPOS the administrative authority rests in the hands of the users, just like a democracy. But unlike Witnesses, the Advisors are not compensated for retaining their positions.
Building on the success of the DPOS consensus mechanism, Peerplays introduced a unique enhancement called Gamified Proof of Stake (GPOS).
The original intent of Peerplays was to operate as a Decentralized Autonomous Cooperative (DAC) where DPOS enabled the voting collective of core token holders to determine who would act as Advisors, Witness, and Proposals within Peerplays. However, the challenges of voter turnout continued to plague Peerplays like other DPOS based blockchains.
GPOS made a protocol change such that PPY token holders now receive a 'participation reward' based on their voting performance and how many PPY they have vested or 'staked'.
This is a significant change from the original DPOS protocol where token holders were rewarded with their share of a 'rake', taken from a percentage of the blockchain fees, and then distributed to token holders relative to their token holdings, regardless of any voting participation.
The importance of voter participation of the PPY token holders is paramount to the security of the blockchain. The introduction of GPOS ensures that token holders will take an active interest in the operation and governance of Peerplays.
The official Peerplays repository can be found at:
This repository uses git submodules, so be sure to fetch the submodules when cloning. This can be done by passing the
--recursiveflag when cloning:
$ git clone https://github.com/peerplays-network/peerplays --recursive
The most significant subdirectories in the repository are
tests. The Peerplays implementation is almost entirely defined within various libraries, which are located in the
programssubdirectory contains small wrappers around these libraries, exposing their functionality as executable binaries.
testssubdirectory contains various tests to verify that essential blockchain features and functionality are working, and to detect regressions should they occur during development.
We'll now look at each of the three subdirectories in greater detail.
Peerplays is implemented in several
librarieswithin the libraries sub directory of the repository. A high level description of each of the libraries is as follows:
applicationclass, which implements the heart of a Peerplays node
chaincontains the bulk of the blockchain implementation, including all Peerplays specific functionality
dbcontains the database functionality, implementing the in-memory database as well as the persistence layer
egenesisis a small library which embeds the genesis block data into the binary
fcis a library implementing many utility functionalities, including serialization, RPC, concurrency, etc.
netcontains the peer-to-peer networking layer of Peerplays
pluginscontains several plugin libraries which can be utilized within a Peerplays node
utilitiescontains code and data necessary to Peerplays’ implementation, but not critical to the core functionality
walletcontains the reference command-line wallet implementation
Of these libraries, the bulk of development activity occurs within the
chainlibrary, and sometimes
fc. The other libraries remain reasonably stable, seeing comparatively small updates and modifications.
Peerplays contains several programs, but only two of these are relevant to modern Peerplays development:
cli_wallet.In addition, the code within these folders exists just to expose library functionality in an executable, and is rarely updated.
witness_nodeprogram is the only maintained Peerplays node executable. The name
witness_nodeis something of a misnomer, as this executable is really just a full node, but it can provide witness (i.e., block producer) functionality by loading the
Tip: If you wish to sync with the Peerplays blockchain network and maintain a database of the current chain state, this is the program to do it with.
cli_walletprogram implements a command-line wallet for Peerplays. It requires a network connection to a running
witness_nodeto provide chain state information to it. This program provides a basic UI for all Peerplays functionality.
Peerplays uses the Boost testing framework for its tests. Most of the Peerplays tests use the
database_fixture, defined in
tests/common/database_fixture.hpp, as the basis of the tests. This file also defines many macros and functions to reduce the boilerplate of test writing.
The bulk of the tests are written in the
tests/testsfolder, and are run by the
chain_testbinary. All tests of core functionality should be included in this directory and binary.
This section provides a high-level overview of the architecture of smart contracts in Peerplays, how they work, and how they are created.
At its essence, a Peerplays smart contract is comprised of three main types of object:
The Peerplays protocol defines a set of actions a user can take within the blockchain ecosystem, called
operations. All interactions with the blockchain take place through
operations, and in a sense, they are the blockchain’s API.
evaluator, which implements that operation’s functionality within the Peerplays software implementation. Thus an
operationis like a function prototype, whereas an
evaluatoris the function definition.
Finally, all data persistently stored by the blockchain is contained within database
objectdefines a group of fields, analogous to columns of a relational database table.
operations charge a fee to execute, and each must specify an account to pay the fee. This account’s ID must be returned by the
fee_payer()method on the
operationmust also provide a stateless consistency check which examines the
operation’s fields and throws an exception if anything is invalid.
operations must provide a
calculate_fee()method which examines the
operationand calculates the fee to execute it. This method may not reference blockchain state, however, each
fee_parameters_typestruct containing settings for the fee calculation defined at runtime, and an instance of this struct is passed to the
operations automatically require the authorization of their fee paying account, but an
operationmay additionally specify other accounts which must authorize their execution by defining the
Note: If a transaction contains an
operationwhich requires a given account’s authorization, signatures sufficient to satisfy that account’s authority must be provided on the transaction.
evaluatorwhich implements that
operation’s modifications to the blockchain database. Each
evaluatormost provide two methods:
The evaluate step examines the
operationwith read-only access to the database, and verifies that the
operationcan be applied successfully. The apply step then modifies the database.
evaluatormust also define a type alias,
evaluator::operation_type, which aliases the specific
operationimplemented by that evaluator.
The Peerplays software implementation utilizes a custom, in-memory relational-style database to track the blockchain state as new blocks and transactions are applied, containing
operations which modify the database.
This database is implemented in the
libraries/dbfolder, and it provides persistence to disk as well as undo functionality allowing the rewinding of changes, such as when a partially-applied transaction fails to execute, or blocks are popped due to a chain reorganization (i.e. when switching forks).
The Peerplays database tracks various
objecttypes, each of which defines the columns of a table. The rows of this table represent the individual object instances in the database. Along with each
objecttype is an index type, which, in relational database terms, defines the primary and secondary keys, which can be used to look up object instances.
The primary key is always an
object_idtype, a unique numerical ID for each object instance known to the blockchain. All
idfield from their base class which contains this ID. This field is set by the database automatically and does not need to be modified manually.
Peerplays smart contracts are defined as a set of
operations which are analogous to API calls provided by the contract.
operations are implemented by
evaluators, which provide code to verify that the operation can execute successfully, and then to perform the requisite modifications to database
objects specify an index, which defines keys which can be used to look up an object instance within the database.
Since Peerplays is a Graphene based blockchain it supports the Graphene API at its core.
For more information on the Graphene API go to:
To make access to the API easier for developers there are two Python libraries that can be used.
This is a communications library which allows interface with the Peerplays blockchain directly and without the need for a cli_wallet. It provides a wallet interface and can construct any kind of transactions and properly sign them for broadcast.
The repository can be found here:
The purpose of
pypeerplaysis to simplify development of products and services that use the Peerplays blockchain. It comes with:
- It’s own (bip32-encrypted) wallet
- RPC interface for the Blockchain backend
- JSON-based blockchain objects (accounts, blocks, events, etc)
- A simple to use yet powerful API
- Transaction construction and signing
- Push notification API
- and more
The repository can be found here:
The APIs are separated into two categories:
- the Blockchain API which is used to query blockchain data (account, assets, trading history, etc.)
- the CLI Wallet API which has your private keys loaded and is required when interacting with the blockchain with new transactions.
The set of available calls depends on whether you connect to a full node (
witness_node) or the wallet (
cli_wallet). Both support RPC-JSON. The full node also supports the websocket protocol with notifications.
Which blockchain network you connect to depends on the configuration of the full node and the wallet.
Tip: If you run a full node, we recommend you connect your wallet to your local full node even though it could be connected to any other public full node as well.
The blockchain API (as provided by the
witness_nodeapplication) can be used to obtain any kind of data stored in the blockchain. Besides data stores in the blockchain itself (blocks, transactions, etc. ..), higher level objects (such as accounts, balances, etc. …) can be retrieved through the full node’s database.
It is not required to run a local full node if you want to query a particular blockchain or database, but you can also query any existing public node for information.
Important: The blockchain API doesn't know about private keys, and cannot sign transactions for you. All it does is validate and broadcast transactions to the P2P network.
The cli-wallet api, as provided by the
cli_walletbinary, allows you to create and sign transactions and broadcast them.