PAO DocsCommunity DocsInfrastructure DocsPeerplays.com

Requirements Specification

The Peerplays Decentralized Exchange (DEX) platform design requirements specification.

1. Introduction

This requirements specification (RS) describes the high-level requirements for the initial release of the Peerplays Decentralized Exchange platform (DEX). This document is intended to be used by the members of the project team who will implement and verify the correct functioning of the system. Unless otherwise noted, all requirements specified here are committed for the initial release.

1.1. Purpose

The purpose of this RS is to cover the high-level outline and resulting requirements of the DEX. Lower level requirements documents for each component will be created.

1.2. Document Conventions

For the purpose of traceability, the following codes will be used in this RS:

Code

Meaning

OE-#

Operating Environment Requirement

CO-#

Constraint

DE-#

Dependency

IL-#

Interface Layer Requirement

CL-#

Chain Layer Requirement

AC-#

Application Component Requirement

EC-#

Exchange Component Requirement

WC-#

Wallet Component Requirement

The keyword shall indicates a requirement statement.

1.3. Project Scope

The DEX will permit Peerplays users to:

  • exchange Peerplays assets

  • view, auction, buy, and sell NFTs

  • use the following wallet functions

    • create an account

    • send / receive Peerplays assets

    • deposit / withdraw sidechain assets (BTC, ETH, etc.)

    • use GPOS vesting

    • governance voting (witnesses, SONs, advisors)

    • create CATs

    • view blockchain status

Peerplays assets in the context of this RS are any on-chain asset. This includes native Peerplays assets like the PPY coin, Peerplays NFTs, and CATs. This also includes assets that have originated off-chain that have been transferred onto the Peerplays chain through the services of Peerplays SONs. These external (sidechain) assets include Peerplays versions of BTC, HIVE, or ETH and even Peerplays versions of NFTs living on the Ethereum chain. The external assets are backed by their counterparts, locked in a Peerplays controlled account on their native chains.

2. Overall Description

2.1. Product Perspective

The design for the DEX seamlessly integrates application, asset exchange, and wallet functions into a singular app. The DEX will act as the main wallet for Peerplays users. It will give users the ability to use the exchange without needing another app. Basic NFT related functions will be included. The DEX is composed of three components: The application, The exchange, and the wallet.

FIG 1. Peerplays DEX Application High-Level Overview (Page Map)

The structure of the DEX will be based on two layers, the interface (UI) layer, and the chain layer. The interface layer consists of the UI/UX design elements and interfaces with the chain layer to perform actions on behalf of the user. The chain layer consists of the blockchain and API. It provides business logic, object models, and storage.

FIG 2. Peerplays DEX Two Layer Structure

2.2. User Classes and Characteristics

User class

Description

User

A user is an entity that accesses the DEX . A user with a Peerplays account has the intention of using the DEX to manage their account and Peerplays assets. A user without a Peerplays account has the intention of using the DEX to create a new account. A user (with or without an account) may also be interested in accessing the DEX to view information on the status of the blockchain, markets, etc.

2.3. Operating Environment

OE-1: The DEX shall operate correctly with the following web browsers (and platforms):

Browser

Platforms

Google Chrome

Ubuntu GNU Linux, Windows 10, Android, macOS, iOS

Firefox

Ubuntu GNU Linux, Windows 10, Android, macOS, iOS

Brave

Ubuntu GNU Linux, Windows 10, Android, macOS, iOS

Safari

macOS, iOS

OE-2: The DEX shall operate correctly at the minimum resolution of 1334-by-750-pixel resolution at 326 ppi onward (iPhone SE resolution).

OE-3: The DEX shall permit user access by desktop computer, Android, iOS, and Windows smartphones and tablets.

OE-4: In later versions of the DEX , the DEX shall operate as both a hosted version and a stand-alone app (i.e. Electron App).

2.4. Design and Implementation Constraints

CO-1: All HTML code shall conform to the HTML 5.0 standard.

CO-2: Design elements shall maintain a standard look and feel by using Tailwind CSS and Tailwind UI components.

CO-3: The DEX UI shall be built with a responsive UI design.

2.5. Assumptions and Dependencies

DE-1: The operation of the DEX depends on the Peerplays chain being operational.

DE-2: Successful transfers of assets on to and off of the Peerplays chain depends on having an operational sidechain for any given asset.

3. System Features

3.1. App Design

3.1.1. Interface Layer

Description

The interface layer of the DEX consists of the overall application's graphical design framework. This framework ties together the UIs of the application, exchange, and wallet components into one cohesive UX design. In this way the interface layer can be described as both the individual UI elements and the wrapper that binds them into what a user would experience as a single app.

The interface layer is responsible for information display, receiving and validating user input, managing input and output from the chain layer, and app navigation.

The interface layer interfaces with the chain layer. Users never interact directly with the chain layer. In a traditional web app, the interface layer would be like the client-side code.

FIG 3. Peerplays DEX Interface Layer

Requirements

The requirements below are for the overall DEX UI which contains the application, wallet, and exchange specific UIs. See the sections relating to each specific component for requirements for their part of the interface layer.

IL-1: The interface layer shall integrate component specific UIs to provide a consistent graphical design across all components.

IL-2: The interface layer shall provide navigation for all integrated components. Navigation must provide access to the following pages:

  • HOME PAGE

  • WALLET

    • Wallet Dashboard

    • Voting

    • Vesting

    • Network Info

    • NFT Manager

    • CAT Manager

  • EXCHANGE

    • Exchange Dashboard

    • Exchange

    • Asset Explorer

    • NFT Listings

  • SETTINGS

    • App Settings

IL-3: The interface layer shall be built with a responsive UI design.

IL-4: The interface layer shall allow user input in relevant form fields to perform the functions of the related component.

IL-5: The interface layer shall perform input field validation and inform the user of acceptable form inputs.

IL-6: The interface layer shall provide the user with help/hint text to explain available options and input fields.

IL-7: If an error occurs, the interface layer shall display meaningful error information to the user and provide them with actions they can take to attempt to resolve the error whenever possible.

3.1.2. Chain Layer

Description

The chain layer of the DEX consists of the blockchain API, on-chain objects, and transaction storage. The API provides business logic required to take user input, transform that input as necessary, and perform actions on the blockchain. The chain layer also supplies the interface layer with information from the chain. The purpose of the chain layer is to split away the business logic and data storage from the graphical design.

In a traditional web app, the chain layer would be like the server-side code and data storage.

FIG 4. Peerplays DEX Chain Layer

Requirements

The requirements below are for the overall DEX functions which contains the application, wallet, and exchange specific functions. See the sections relating to each specific component for requirements for their part of the chain layer.

CL-1: The chain layer shall interface with the interface layer via the blockchain API.

CL-2: The chain layer shall contain the objects and functions required by the exchange and wallet components.

3.2. Components

3.2.1. Application Component

Description

The application component is the basic foundation for the DEX. It provides the following functions:

  • the DEX home page

  • navigation

  • account creation

  • authentication

    • login/logout

    • user session management

  • notifications

  • help docs

  • application settings

    • wallet settings

    • exchange settings

Lower level requirements specification documents will contain functional specifications for the above features.

3.2.1.1. Application Component UI

Requirements

AC-1: The application component UI shall provide navigation to the following pages (or page fragments) which contain features as listed below:

  • Site Header (page fragment)

    • app navigation

  • Site Body (page fragment, container for app pages)

  • Site Footer (page fragment)

  • Home Page

    • marketing content

  • Application Settings Page

    • wallet backup

    • view private keys

    • wallet settings

    • exchange settings

  • Login Page (stand-alone page, no header/footer)

  • Create Account Page (stand-alone page, no header/footer)

    • account creation

3.2.2. Exchange Component

Description

The exchange facilitates the exchange of assets. It is important to Peerplays communities and blockchain governance because it allows the flow of PPY and CATs to accounts across the chain. The exchange is also necessary for rewards generation as the transaction fees are distributed to those who stake into the LPs.

The exchange component handles all decentralized exchange related functions. This includes:

  • trading pairs / markets

  • the order book

  • user order management

  • market trade history

  • searching and viewing asset information

  • exchanging Peerplays assets using various order types

    • market orders

    • limit orders

      • good-til-canceled

      • good-til-time

      • fill-or-kill

      • immediate-or-cancel

      • maker-or-cancel

    • stop-limit orders

  • quick send

  • quick trade

  • NFT auction / sale listings

  • trade slippage protection

  • Peerplays Automatic Market Maker (AMM)

  • viewing and managing price charts

Lower level requirements specification documents will contain functional specifications for the above features.

3.2.2.1. Exchange Component UI

Requirements

EC-1: The exchange component UI shall provide navigation to the following pages which contain features as listed below:

  • Exchange Dashboard

    • quick send

    • quick trade

    • user activity feed

    • user assets list

  • Exchange Page

    • order books

    • buy / sell controls

    • user order history

    • user open orders

    • user asset balances display

    • market trade history

    • trading pairs / markets

    • price charts

    • price / volume statistics

  • Asset Explorer

    • advanced asset search

    • asset info (single asset information page)

  • NFT Listings

    • NFT auction / sales listings

3.2.2.2. Automated Market Maker (AMM)

Description

The AMM will utilize an algorithm which allows exchange and order book mechanics based on Uniswap-like technology. The AMM executes trades using the supply available within the liquidity pools.

A PPY based Uniswap-like algorithm will be necessary for the exchange to function. This will allow an exchange-like experience but also guarantees liquidity. This also makes PPY the basis of all trades and compliments Peerplays asset staking mechanisms.

Something like a hybrid between Uniswap and a traditional exchange order book, the AMM algorithm allows speculative trading of any trading pair. The prices are set on supply and demand principles. The diagram below illustrates the key differences between traditional trading, Uniswap, and the AMM algorithm.

FIG 5. Peerplays DEX Automated Market Maker

In a traditional exchange, an order book is filled with the orders of buyers and sellers in a given market. Orders are filled when buyers are willing to pay what the sellers are asking for, or sellers are willing to take what buyers are bidding. Liquidity in this case is entirely dependent on the supply provided by the buyers and sellers.

In a Uniswap system, there are no order books. Instead, people stake assets into liquidity pools to earn rewards based on generated transaction fees. Buyers and sellers simply swap their assets at a price that preserves the liquidity within the underlying liquidity pools. Essentially, the greater the gap in supply between two assets, the higher the price will be for that trading pair. This creates an incentive to balance the supply in the liquidity pools.

Peerplays AMM combines the two systems to make an exchange system supported by staked liquidity pools. Order books are populated from the liquidity pools based on the difference between the available supplies of the assets in a given pair. Like in Uniswap, the higher the supply gap, the higher the price. The order book then takes orders from buyers and sellers with their limit prices. In this way, the pair of liquidity pools of the trading pair act as large market making buyers and sellers who are always willing to trade. As long as there are people willing to stake their assets to the liquidity pools, there will always be available liquidity for the exchange.

Requirements

EC-2: The AMM shall manage its own limit orders for each market (trading pair) based on LP supply comparison.

EC-3: The AMM shall execute transactions on the chain in accordance with its operating algorithms.

EC-4: The AMM shall adjust all its positions based on changes in available supply in the LPs to preserve liquidity.

3.2.2.3. Exchange Liquidity Pools (LPs)

Description

The liquidity pools are special Peerplays controlled accounts that store staked assets for use in exchange trading. Users can stake assets to LPs to claim rewards based on exchange fees related to those assets.

Requirements

EC-5: The LPs shall store a supply of assets from stakeholders.

EC-6: The LPs shall allow assets to be staked and un-staked.

3.2.2.4. Trade Slippage Protection

Description

Slippage refers to the difference between the expected price of a trade and the price at which the trade is executed. Slippage can occur at any time but is most prevalent during periods of higher volatility when market orders are used. It can also occur when a large order is executed but there isn't enough volume at the chosen price to maintain the current bid/ask spread. To protect users from slippage on large market orders, the DEX should provide slippage protection.

Requirements

EC-7 The exchange shall implement trade slippage protection where market orders that move the price in excess of 10% will stop executing and return a partial fill. For example: a market buy submitted when the last trade price is $4,000 will only fill at price levels below $4,400.

3.2.3. Wallet Component

Description

The wallet is the main component with which users interact with the Peerplays chain. The wallet is the window to their account and asset information. It's also the foundation of account functions like logging in/out, sending/staking assets, governance, and viewing the status of the blockchain.

The wallet module handles all user account related functions. This includes:

  • creating new accounts

  • viewing and managing a user's account information

  • viewing a user's asset balances

  • sending and receiving assets

  • voting functions

  • vesting (staking) functions

  • creating, viewing, and managing a user's NFTs

  • searching and viewing other user's NFTs

  • creating, viewing, and managing a user's CATs

  • searching and viewing other user's CATs

  • viewing the blockchain status information

  • searching and viewing other user's public information

  • viewing help documentation for user account functions

  • user session management

Lower level requirements specification documents will contain functional specifications for the above features.

3.2.3.1. Wallet Component UI

Requirements

WC-1: The Wallet module view layer shall provide the following pages which contain features as listed below:

  • Wallet Dashboard

    • user assets list

    • user NFTs list

    • user activity feed

    • rewards information

    • quick voting

    • quick vesting

    • asset send / receive

    • balance claims

  • Voting Page

    • vote for witnesses

    • vote for sons

    • vote for advisors

  • Vesting Page

    • power up asset

    • power down asset

  • Network Info

    • blockchain status information

    • Peerplays account search

    • fee schedule

  • NFT Manager

    • user NFTs list

    • NFT templates

    • create NFT

    • NFT Explorer

      • advanced NFT search

      • NFT Info (single NFT page)

  • CAT Manager

    • user CATs list

    • CAT templates

    • create CAT

    • CAT distribution

    • CAT governance

    • CAT Explorer

      • advanced CAT search

      • CAT Info (single CAT page)

4. Appendix A: Glossary

Term

Meaning

Notes / References

RS

Requirement Specification

-

DEX

Decentralized Exchange

-

NFT(s)

Non-Fungible Token(s)

-

GPOS

Gamified Proof of Stake

-

CAT(s)

Community Asset Token(s)

-

UI

User Interface

-

UX

User Experience

-

AMM

Automated Market Maker

-

LP(s)

Liquidity Pool(s)

-

5. Appendix B: References

Tailwind CSS

PreviousNEX-FS11 WhaleVault IntegrationNextFunctional Specs

Last updated