diff --git a/README.md b/README.md index 0c5e92a..770d3cf 100644 --- a/README.md +++ b/README.md @@ -1,64 +1,59 @@ -# Casper Lottery -This repository contains the front-end implementation of a decentralized application (DApp) demonstrating a simple lottery system using CSPR.suite series of products. - -Built with CSPR.click, Odra, and the CSPR.cloud, this DApp showcases how Casper blockchain technology can be utilized for transparent and fair random selection processes. - -Detailed spec: [here](./docs/specs.md) - -### Setup -#### CSPR.click -Create a new project using CSPR.click react template: -``` -npx create-react-app my-new-casper-app --template @make-software/csprclick-react -``` - -Go to the newly created project directory, install dependencies and run the app. - -In this case it will be "my-new-casper-app" -``` -cd my-new-casper-app -npm install -npm start -``` -This command will start the development server. You can view the app by navigating to http://localhost:3000 in your web browser. - -More details [here](https://docs.cspr.click/) - -[CRA link](https://www.npmjs.com/package/@make-software/cra-template-csprclick-react) - -### Build -To build the project for production, use: -``` -npm run build -``` -This command will create a build folder with optimized production-ready files. - -### Usage -To initialize and use the CSPR.click feature in the frontend application, follow these steps: -1. ####Import the hook: -In the React component file where you want to use the CSPR.click feature, import the hook from the library: -``` -import { useClickRef } from '@make-software/csprclick-ui'; -``` -2. ####Initialize the hook: -``` -const clickRef = useClickRef(); -``` -3. ####Use methods to handle sign in/sign out events -``` -clickRef.on('csprclick:signed_in', async (event) => await doSomethingWithAccount(event.account)); -``` -4. ####Add the CSPR.click header -To add the CSPR.click header to your application import the ClickUI component. - -``` -import { ClickUI } from '@make-software/csprclick-ui'; -``` -Customize the behavior of the hook by passing options as parameters. For example, you can use advanced functions such as adding a list of languages, a dark theme, and a list of currencies by passing parameters to props. -``` - -``` +# Lottery Demo dApp + +This is an example of a decentralized application (or dApp) built on the [Casper Network](https://casper.network), a layer 1 proof-of-stake (PoS) blockchain. Lottery game logic implemented on-chain aims to demonstrate the value of blockchain, which is the increased trust to the outcome since nobody can manipulate the results. + +To participate in the lottery, you need to buy a ticket using the Casper Network native token. After collecting a fee, the application puts the proceeds into the prize pool, which is used to reward the players. When somebody wins the jackpot, a new game round starts, making the game indefinite. + +You can try it by playing the lottery deployed to [Casper Testnet](https://testnet.cspr.live/) at https://lottery-demo.casper.network. Please use the [Faucet](https://testnet.cspr.live/tools/faucet) to obtain the test tokens. + +![Lottery Application](docs/images/lottery-application.png) + +## Toolset + +This application was created to onboard software engineers to the Casper blockchain and the Web3 architecture in general. Unlike traditional Web2 applications, in Web3, users may interact with blockchain directly. It changes the traditional paradigm of how information flows between users and the application and forces the application to observe the network activity and react correspondingly. + +To ease the integration, this example was developed with the help of higher-level abstractions that address those specific challenges of Web3 development and elevate the developer experience. + +![Casper Development Ecosystem](docs/images/development-ecosystem.png) + +- [CSPR.click](https://docs.cspr.click) is a Web3 authentication layer that covers the end-user interaction with the blockchain. It provides integration with all the wallets in the Casper Ecosystem and greets users with a well-known Single-Sign-On like experience +- [Odra](https://odra.dev/docs/) is a smart contract framework written in Rust that abstracts the chain-specific details behind a familiar OOP interface +- [CSPR.cloud](https://docs.cspr.cloud) is a middleware layer for the Casper Network. It observes and indexes the network activity and provides access to it via a scalable REST API and real-time WebSocket subscriptions + +Register a free [CSPR.build](https://console.cspr.build/) account to generate CSPR.click and CSPR.cloud keys. + +## Architecture + +Lottery Demo is a Web that consists of four primary components interacting with each other: + +- [Smart Contract](smart-contract) runs on the Casper Network and implements the lottery logic +- [Event Listener](server/src/event-handler.ts) listens to the contract on-chain activity and aggregates it to the database for faster access via the API +- [API](server/src/api.ts) reads aggregated on-chain data and serves it to the Web Client. It also acts as a proxy to the CSPR.cloud APIs to make it possible for the Web Client to access CSPR.cloud without exposing the access key +- [Web Client](client) allows users to play the lottery by directly calling the smart contract and displaying information about past plays. It fetches the lottery data from the API and general blockchain data (e.g. account balance) from CSPR.cloud via the CSPR.cloud proxy endpoints exposed by the API + +![Architecture](docs/images/architecture.png) + +Each component's code resides in a corresponding separate directory of this mono-repository. [Event Listener](server/src/event-handler.ts) and [API](server/src/api.ts) are both parts of the [server](server) infrastructure. + +## Setup + +To configure you local environment perform the following steps: + +1. Register a free [CSPR.build](https://console.cspr.build) account. Create CSPR.click and CSPR.cloud keys. +2. Build and deploy the smart contract to [Casper Testnet](https://testnet.cspr.live) as described [here](smart-contract/README.md). You can skip this step and use the existing [Testnet smart contract](https://testnet.cspr.live/contract-package/8efc85466cf4054f47eb009b683b611fa63cccd14f074bf78f1e9404dc52a347) package hash `8efc85466cf4054f47eb009b683b611fa63cccd14f074bf78f1e9404dc52a347`. +2. Update Web Client configuration as described [here](client/README.md#setup) +3. Update Server configuration as described [here](server/README.md#setup) + +## Build + +TODO + +## Run + +TODO + +## About Casper + +[Casper](https://casper.network) is a layer 1 proof-of-stake (PoS) blockchain that prioritizes security and decentralization. Casper was built with developer needs in mind and supports features such as upgradable smart contracts or multi-signature transactions on the protocol level. Casper smart contracts are run in a WASM virtual machine, creating the possibility of using a wider variety of languages for smart contract development. + +Join [Casper Developers](https://t.me/CSPRDevelopers) Telegram channel to connect with other developers. \ No newline at end of file diff --git a/client/README.md b/client/README.md index b1e3004..1c1dc13 100644 --- a/client/README.md +++ b/client/README.md @@ -1,14 +1,35 @@ -# csprclick-react template +# Lottery Demo dApp Client -## Install +Casper Lottery Client is a React application bootstrapped from [CSPR.click React template](https://www.npmjs.com/package/@make-software/cra-template-csprclick-react). To read more about CSPR.click, please check [the documentation](https://docs.cspr.click). -Congrats! You have successfully created a new React project with CSPR.click! +## Setup -Please type +Before building фтв running the Web Client, please update the configuration. Start with copying the config template: ```bash cp public/config.js.local public/config.js +``` + +Next, update the following configuration values: +1. Change `lottery_app_contract_package_hash` if you deployed your own contract. If you want to use the [demo application](https://lottery-demo.casper.network) contract, keep the default value. +2. Change `cspr_click_app_id` to your CSPR.click App ID from [CSPR.build Console](https://console.cspr.build) + +The rest of the values should remain the same for the local development, unless you made corresponding changes in other places. + +## Build + +To build the project for production, use: +``` +npm run build +``` + +This command will create a build folder with optimized production-ready files. + +## Run + +To run the application, use: + +```bash npm start ``` -to start developing. diff --git a/client/public/config.js.local b/client/public/config.js.local index 7777daf..71c3587 100644 --- a/client/public/config.js.local +++ b/client/public/config.js.local @@ -2,7 +2,7 @@ const config = { lottery_app_contract_package_hash: '8efc85466cf4054f47eb009b683b611fa63cccd14f074bf78f1e9404dc52a347', lottery_play_payment_amount: '1000000', lottery_api_url: 'https://cspr-lottery-demo-api.dev.make.services', - lottery_api_ws_url: 'wss://cspr-lottery-demo-api.dev.make.services/deploys', + lottery_api_ws_url: 'wss://cspr-lottery-demo-api.dev.make.services', cspr_click_app_name: 'Lottery Demo', cspr_click_app_id: 'cspr-lottery-demo', cspr_live_url: 'https://testnet.cspr.live', diff --git a/docs/assets/Fig-1.png b/docs/assets/Fig-1.png deleted file mode 100755 index 261869d..0000000 Binary files a/docs/assets/Fig-1.png and /dev/null differ diff --git a/docs/assets/Fig-2.png b/docs/assets/Fig-2.png deleted file mode 100755 index 0678a10..0000000 Binary files a/docs/assets/Fig-2.png and /dev/null differ diff --git a/docs/assets/Fig-4.png b/docs/assets/Fig-4.png deleted file mode 100755 index 9d3b6bb..0000000 Binary files a/docs/assets/Fig-4.png and /dev/null differ diff --git a/docs/images/architecture.png b/docs/images/architecture.png new file mode 100644 index 0000000..2812f27 Binary files /dev/null and b/docs/images/architecture.png differ diff --git a/docs/assets/Fig-3.png b/docs/images/development-ecosystem.png similarity index 100% rename from docs/assets/Fig-3.png rename to docs/images/development-ecosystem.png diff --git a/docs/images/lottery-application.png b/docs/images/lottery-application.png new file mode 100644 index 0000000..fb6c772 Binary files /dev/null and b/docs/images/lottery-application.png differ diff --git a/docs/links.md b/docs/links.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/spec-v1.md b/docs/spec-v1.md deleted file mode 100644 index 3db74c5..0000000 --- a/docs/spec-v1.md +++ /dev/null @@ -1,40 +0,0 @@ -**1. System Overview:** - -* **Smart Contract:** Acts as an escrow account, holding the funds. -* **Web App:** User interface. -* **Relayer Server:** Third-party service facilitating communication between the web app and the smart contract. -* **Relayer Contract:** Third-party smart contract bridging the gap between the relayer server and the main DApp contract. - -**2. Smart Contract Functionality:** - -* **State Variables:** - * `admin`: Address of the contract administrator. - * `relayer`: Address of the realyer smart contract. - * `paused`: Boolean flag indicating if the contract is paused. - * `distribution_amount`: Fixed amount users can receive. - * `distributed_to_addr`: Mapping to track addresses that have already received funds - * `distributed_to_acc`: Mapping to track GitHub accounts that have already received funds -* **Functions:** - * `init(admin: Address, realyer: Address, distribution_amount: U512)`: Initializes the contract. - * `distribute(user_addr: Address, github_acc: String)`: Distributes funds to a user if eligible. - * `pause()`: Pauses the contract, preventing distributions. - * `unpause()`: Resumes the contract, allowing distributions. - -**3. Web App Functionality:** - -* **Login:** Allows users to connect their crypto wallet. -* **Input:** Users provide their GitHub username. -* **GitHub API Call:** Web app verifies the existence of the provided GitHub account using the official API. -* **Deployment Request:** Web app generates a transaction object containing: - * User address. - * Verified GitHub username. - * The escorw smart contract address. -* **Relayer Server Interaction:** Web app sends the transaction object to the relayer server. - -**4. Relayer Server and Contract Interaction:** - -* **Relayer Server:** - * Receives the transaction object from the web app. - * Forwards the transaction object to the relayer contract. -* **Relayer Contract:** - * Calls the `distribute` function of the main DApp contract, providing user address and verified GitHub username. \ No newline at end of file diff --git a/docs/specs.md b/docs/specs.md deleted file mode 100644 index 55ab07d..0000000 --- a/docs/specs.md +++ /dev/null @@ -1,112 +0,0 @@ -# PWB Example dApp - -Created: March 15, 2024 - -## Casper example dApp - -### Background - -Despite being around for 15 years, blockchain is still considered a new technology, and here, “new” really means “unknown.” Businesses and the developer community still misunderstand blockchain. While it’s easy to build the narrative for the product value of blockchain, which is trust in the information coming from it, onboarding developers requires more effort. - -Considering that one of the favorite learning methods for developers nowadays is learning by example, we want to develop an example of a functioning dApp, that covers all the aspects of the blockchain integration, and not only the smart contract part. We want this example to teach developers the main concepts instead of relying on white-label templates (e.g. NFT galleries or meme coins). - -The example should highlight the shift in the information flow that happens in Web3 applications compared to “traditional” Web2 ones, where the end-users, by design, don’t have access and control over their data. In Web2, the application controls the data storage, and thus the data: - -![Figure 1](assets/Fig-1.png) - -The blockchain challenges the status quo of this approach and introduces a new way of managing the data that gives control to the users: - -![Figure 2.png](assets/Fig-2.png) - -Instead of relying on the application as the middle-man, the users interact with the blockchain directly, resulting in a three-piece architecture: - -1. Client application that provides an interface to interact with the blockchain and reads the data from the blockchain directly or from the server-side API -2. Smart contracts, which are on-chain logic that processes user requests in a trustful and predictable way -3. Server-side that observes the on-chain activity and reacts to it accordingly by triggering the related pipelines, aggregating the data for the end-users, etc. The server side typically consists of the on-chain activity handler application and the API - -Casper Ecosystem contains tools that simplify blockchain integration on all of those layers to the point where developers with little to no prior Web3 experience can relatively quickly onboard into the space, and we want to leverage those instruments in the Example dApp: - -![Figure 3.png](assets/Fig-3.png) - -1. [CSPR.click](http://CSPR.click) is a Web3 authentication layer that provides: - 1. Integration with all wallets in the Casper Ecosystem - 2. Access to all fiat on-ramps in the Casper Ecosystem - 3. And most importantly, familiarity to everybody with a Single-Sign-On approach that ensures a seamless user onboarding experience -2. Odra is a smart contract framework written in Rust that abstracts the chain-specific details behind a familiar OOP-like interface -3. [CSPR.cloud](http://CSPR.cloud) is a middleware layer that observes on-chain activity and provides: - 1. Access to indexed and normalized blockchain data via REST API - 2. Realtime WebSocket streams that provide a granular subscription to the data required by the dApp - 3. Access to the Casper Node RPC API - -With Odra, CSPR.click, and [CSPR.cloud](http://CSPR.cloud), we can prepare an example dApp that teaches developers this new Web3 architecture without overwhelming them with the lower-level details that would delay their onboarding into the blockchain. - -### Application - -The application should be simple and easy to understand while highlighting the value of blockchain. For example, a To-do application, which is a common example for front-end frameworks, will not work here. Implementing a To-do application on a blockchain will not increase its value. A lottery, on the other hand, will benefit from blockchain as it increases trust in the fairness of the process. Taking into account that everybody is familiar with the concept and requires no additional introduction, we’ll use it for our example. - -The application will allow users to play the lottery by buying a ticket that gives them a chance to instantly win the jackpot, a small consolation prize, or win nothing. With each unsuccessful play, the jackpot increases by the ticket price minus the lottery fee. The blockchain will make the lottery process transparent and immune to manipulations. - -The application should be Web-based and work on both desktop and mobile. - -The “Home” page will be divided into two sections: - -1. Play section -Will be managing the users’ play experience -2. Plays section -Will be displaying the plays in the current jackpot round - -The “Play” section will have four states: - -1. Onboarding state -Will be inviting users to connect a Casper wallet -2. Play state -Will be inviting users with connected accounts to play -3. Waiting state -Will be displaying a loading indicator for users waiting for the results of their play -4. Result state -Will be notifying users about the results of their play - -To demonstrate a typical use case of indexing the on-chain data on the application side, we’ll add two more pages: - -1. Jackpots page -Will be accessible from the top navigation menu and will display information about past jackpots -2. Plays page -Will be accessible from: - 1. “My plays” top navigation menu and will display plays made by the currently connected account - 2. “Jackpots” page and will display plays for the selected jackpot - -Considering that we may want to deploy this application under a public URL, we should add the “About” page explaining the application's demo purposes with links to Odra, CSPR.click, CSPR.cloud, and Casper Network documentation pages. - -Each play payment will contribute to three “buckets”: - -1. Current jackpot amount -2. Next jackpot starting amount -3. Application fee - -This logic will be handled by the smart contract, which will also allow you to configure the ratios and provide a possibility to transfer the application fees outside of the contract. - -### Technical details - -The client application should be React-based and bootstrapped from the [CSPR.click React template](https://www.npmjs.com/package/@make-software/cra-template-csprclick-react): - -![Figure 4](assets/Fig-4.png) - -We should reuse as much of the existing UI elements provided in the template application as possible. The top navigation menu should be limited only to featured “CSPR Products”, custom “About” and “Jackpots” links, and the standard “Account” menu. The language, currency, network, and theme selectors should be omitted. - -The jackpot and plays data will be aggregated by the Event Handler application from the contract-level events to be served to the Client application via the API. To keep the application simpler, we’ll denormalize jackpots and plays into one entity containing the following properties: - -- `round_id` -- `play_id` -- `player_account_hash` -- `prize_amount` -- `is_jackpot` - -This way, the application state management will be simpler. - -## Tickets - -All tickets are maintained in the Github project for this repo at https://github.com/casper-ecosystem/pbw-2024-workshop/issues - -Tickets not yet entered into the Github system are kept in the tickets subfolder. Master list is [here](./tickets/tickets-all.md) - - diff --git a/docs/tickets/client/tickets-client.md b/docs/tickets/client/tickets-client.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/tickets/repository/tickets-repository.md b/docs/tickets/repository/tickets-repository.md deleted file mode 100644 index 10ae51c..0000000 --- a/docs/tickets/repository/tickets-repository.md +++ /dev/null @@ -1,11 +0,0 @@ -### As Event Handler, I should have the dev environment - -### As API, I should have the dev environment - -### As Example dApp, I should have the dev environment - -### As Event Handler, I should have the production environment - -### As API, I should have the production environment - -### As Example dApp, I should have the production environment \ No newline at end of file diff --git a/docs/tickets/server/tickets-server.md b/docs/tickets/server/tickets-server.md deleted file mode 100644 index e69de29..0000000 diff --git a/docs/tickets/smart-contract/tickets-sc.md b/docs/tickets/smart-contract/tickets-sc.md deleted file mode 100644 index e69de29..0000000 diff --git a/server/README.md b/server/README.md index e69de29..c1f75d0 100644 --- a/server/README.md +++ b/server/README.md @@ -0,0 +1 @@ +# Lottery Demo dApp Server \ No newline at end of file diff --git a/smart-contract/README.md b/smart-contract/README.md index 4185887..ebb378c 100644 --- a/smart-contract/README.md +++ b/smart-contract/README.md @@ -1,5 +1,4 @@ - -# Lottery Smart Contract - Demo +# Lottery Demo dApp Smart Contract This smart contract allows users to participate in a demo lottery on the Casper blockchain. Users can purchase tickets and have a chance to win the prize pool, which is accumulated from ticket purchases or a consolation prize. @@ -37,21 +36,6 @@ These functionalities can only be called by the contract owner (designated durin 4. **Note:** Whether the user is a winner is immediately determined based on a pseudo-random number generation mechanism (for demo purposes only). This mechanism is not suitable for production use. 5. Winners receive their prizes automatically (jackpot or consolation prize) based on the outcome. -## Deployment Addresses - -**- Testnet:** - - - contract hash: `hash-40777e199af2ae4756c2a148c24e79885dc062fe4428adf23212dd04fd73187b` - -**- Mainnet (if applicable):** - - - contract hash: coming soon. - -## Security Considerations - -- This smart contract is a demo application not ready for production use. It uses a naive pseudo-random number generation mechanism. A secure random number generation mechanism is crucial for real-world lottery applications. - - ## Usage It's recommended to install `cargo-odra` first. You can find it here: [https://github.com/odradev/odra](https://github.com/odradev/odra)