PIP: 0006
Title: Sweeps
Authors: Jonathan Baha'i
Status: Draft
Type: Protocol
Created: 2019-07-08
Discussion: PIP-6-SWEEPS channel at https://discord.gg/Y9PZjzv
Sweeps represents a series of functions within the Peerplays blockchain which can be utilized to run a sweepstakes type lotto. The reasons for using sweepstakes is to avoid the possibility of dealing with fixing odds where a ‘house’ often is given greater odds than the players. In a sweepstakes type operation, the resolution to each draw must conclude with the objectives of the parameters of the draw to select winners.
The selection process is done in a decentralized fashion that doesn’t allow for anyone to have preliminary knowledge of which ticket will be drawn.
Each Sweeps ticket is represented by an asset within the Peerplays blockchain. This asset has the ability to be transferred to other account holders, giving the player the ability to send tickets as gifts to others, or for an organizer to potentially arrange for a presale through authorized vendors. Once the draw has reached resolution, the asset class is destroyed leaving only the historical record of the asset within the Peerplays blockchain. This ensures there isn’t a build up of ‘junk assets’ taking up storage within the blockchain and reducing its performance over time.
Sweepstakes and lottery operations are well known games of chance around the world. They have been used for thousands of years in various ways by dynasties, governments, churches, companies, and other types of organizations. The games can take different formats and provide different odds in winning. Often times a large portion goes to winners while a portion of the total amount collected also went to the organizer of the game.
Because of the immense popularity these types of games have garnered over the years many governments have used it as a means of collecting additional tax revenue from their citizens. Charitable organizations likewise have utilized these as means for getting additional funds for their cause. However, the incumbent organizations are failing to address the concerns of accountability, transparency, and security that the newer generations are demanding from age old institutions. The pressure is beginning to show on their dwindling revenues.
By utilizing the Peerplays blockchain, these age old organizations as well as smaller ones can add accountability, transparency, and most importantly, provable fairness to a sweepstakes lotto which will ensure that all participants will be protected through the power of the Peerplays blockchain Sweeps smart contracts.
Have a decentralized sweepstakes lotto functions enables developers to create numerous types of games which utilize the Peerplays blockchain. By having these functions available in the Peerplays blockchain people who participate in these draws can be assured that they are always carried out fairly, and the payouts are done in accordance with the rules set out in the blockchain operations instead of the operators. This will also enable greater transparency which will improve reporting and auditing of the draws which reduce the cost of fraud investigations and regulatory review should they be necessary in a particular instance.
Essentially, Sweeps is simply a way to collect data from the user and pass it as parameters to a Javascript Library (PeerplaysJS-lib), which takes the input, performs some sanity checking, and reformats it into a transaction (TRX) that the witness will understand. A second library (PeerplaysJS-WS) is used to connect to the specified API and initiate a remote procedure call (RPC), passing the data as a parameter. The backend/node/witness then performs backend validation on the content of the transaction, and if valid, writes it to the block and communicates this change via P2P. Each level in the chain uses a promise/callback to pass the result of this operation back to the user. The BlockChain API URL is used to connect to the witness tasked with creating the new block in the chain - only one witness can create a block for any given 3 second interval, and this process is randomized (as opposed to sequential) to avoid possible attacks. Once they have created and signed their block (containing the new transactions), they distribute it to their peers.
At the surface level, there is a hosted dApp. This is written in any web capable language (example: JS and React), can run on any server (for example, it could easily run on Node, Apache, Nginx, etc), and could easily be built in a variety of ways. The important thing here is that it must have the peerplaysjs-lib library available to it, and it must be running in an environment that supports websockets in order to connect to a Node/Witness. This is the user interface. Each dApp is expected to be configured with correct websocket URLs (for Peerplays API, etc). Any interaction the user performs is sent via RPC (see PeerplaysJS-Lib and WS), and returned via callbacks and promises.
The PeerplaysJS library handles all communications between the applications front end and the blockchain itself, and is written in JS. Most interactions take the form of formatted JSON that is sent via the transaction helper and the PeerplaysJs-Ws library over websockets. As mentioned, peerplaysjs-ws is a dependency. It may be helpful to think of this as packaging a message for transfer before sending it to PeerplaysJS-WS for the actual transmission.
The PeerplaysJS-WS library provides websocket communication with the backend Peerplays API, making it possible for us to write transactions to the blockchain, query for details, create accounts and so on. Messages that are formatted within the PeerplaysJS library (with their data originating from the dApp) use this to communicate with a node/witness for information.
The Peerplays repository is the Node/Witness/BackEnd. It provides an API for both P2P connections and connections from a website. This is mostly seemingly unaltered Graphene with some specific items added for things like lottery end dates. It uses FC (a library that supports multi threading/asynchronous run applications) to provide it's API Services.
-
User fills out form and submits
-
Form data is passed to src/actions/lotteryactions.js (including the following parameters)
Lottery: The specific draw id the user is taking part in.
Buyer: The buyers account number as an id (the 1.2. is assumed, hence only the last number is passed).
Tickets_To_Buy: How many tickets the user is looking to purchase.
Amount: The total cost of the transaction and it's source. In this case, the amount is assumed to be PPY (which as the core asset is always assigned id 1.3.0), aka asset id 0, and the amount is specified as a whole number (example: 2.00000 is expressed as a low of 200000 and a high of 0. 0.00001 would be expressed as a low of 1 and a high of 0). The function of 'high' is unknown at the moment, but presumably it is used for sums larger than 1 variable could contain in C++.)
Extensions: Unknown at this time, always null
-
The LotteryRepository (src/repositories/LotteryRepository.js) is called with these parameters and the keys needed to complete it.
-
The LotteryRepository initializes a TransactionBuilder (peerplaysjs-lib/lib/chain/src/TransactionBuilder.js) with the appropriate fees and details, then invokes the TransactionBuilders 'broadcast' method.
-
The broadcast method checks to ensure that the transaction is valid (has all required signatures and data) before invoking the ApisInstance from the PeerPlaysJS-WS library, also passing it a callback function to return the result to the user when complete.
-
lib/src/ApisInstance.js creates a remote procedure call (RPC) via websocket, invoking the 'broadcast_transaction_with_callback' on the witness.
-
The PeerPlays application receives the connection and handles it with network_broadcast_api::broadcast_transaction_with_callback (within libs/app/api.cpp). Here the transaction is validated server side, the callbacks are loaded into an array, the transaction is pushed to the database, which is then rebroadcast using the P2P networking.
-
The callbacks then return in sequence the result of the users transaction, whether it was successful or not.
Further discussions and review on this topic can be had on the Peerplays Discord server in the Improvement Proposals Category in the PIP-6-SWEEPS channel at https://discord.gg/Y9PZjzv
This document is placed in the public domain