#web3 #soroban #gaming #nft #stellar #payment

soroban-snooker

A smart contract showcasing web3 gaming with Soroban on Stellar

3 releases

0.1.4 Feb 28, 2024
0.1.3 Feb 7, 2024
0.1.2 Dec 19, 2023

#20 in #stellar

Download history 9/week @ 2024-09-19 18/week @ 2024-09-26 23/week @ 2024-10-03

58 downloads per month

Custom license

475KB
1.5K SLoC

JavaScript 1K SLoC // 0.1% comments Rust 287 SLoC // 0.1% comments

MIT License Twitter

Build Status Current Crates.io Version


Logo

Soroban Snooker

A smart contract showcasing web3 gaming with Soroban on Stellar
Play Game Demo · Developer Video Guide

About Soroban Snooker

Soroban Snooker is a smart contract, running on the Rust-based smart contracts platform Soroban, and deployed on the Stellar blockchain. This project, accompanied by a simple game client, aims to demonstrate various use cases and functionalities of web3 gaming on Soroban, including:

  • How to implement In-App Purchases to receive payments from players.
  • How to issue rewards to players such as achievement NFTs, as part of the gameplay experience.
  • How to implement decentralized gameplay validation, including pool physics and time-based checks.
  • How to utilize auth and set up admin functions for management of game assets and withdrawals.
  • How to employ different Soroban storage types to manage game data efficiently, including temporary, persistent, and instance storage.
  • How to leverage custom types for client-contract communication.
  • How to integrate the Freighter Stellar wallet to the game client.
  • How to implement a local/guest mode for players without a wallet.

Built With

Soroban smart contracts

Rust Javascript

The Soroban smart contract is written in Rust, setup instructions are provided below.

The game client, on the other hand, is written in plain Javascript and does not require any external framework. To get started, simply open the client/game.js file and get hacking. Please be aware that the game loop operates with a fixed frame rate, enhancing interoperability with pool physics validation in the smart contract. However, it is feasible to decouple the frame rate for smoother rendering, but implementing this is left as an exercise for the reader.

Getting Started

To begin with the project, follow these steps to set up your environment:

Prerequisites

Ensure you have the following installed:

By following the above steps and setting up the required prerequisites, you will have your environment ready for working with the project.

Install, Build, Deploy and Run

  1. Cloning the Repository:

    git clone https://github.com/FredericRezeau/soroban-snooker.git
    
  2. Running Tests:

    cargo test -- --nocapture
    
  3. Building the Contract:

    cargo build --target wasm32-unknown-unknown --release
    
  4. Deploying to Testnet:

    Configure the Testnet network:

    soroban config network add --rpc-url https://soroban-testnet.stellar.org:443 --network-passphrase 'Test SDF Network ; September 2015' TESTNET
    

    Configure an identity for the admin:

    soroban config identity add --secret-key ADMIN
    

    Deploy the contract and save the output value (your contract ID) using:

    soroban contract deploy --wasm target/wasm32-unknown-unknown/release/soroban_snooker.wasm --source ADMIN --network TESTNET
    
  5. Initializing the contract:

    Follow the guide at the URL below for detailed instructions on how to wrap Stellar tokens for payments and reward assets issued on Stellar: https://soroban.stellar.org/docs/advanced-tutorials/tokens#compatibility-with-stellar-assets

    If you wish to initialize the contract using the native token, execute the following command:

     soroban contract invoke --network TESTNET --source ADMIN --id YOUR_CONTRACT_ID -- initialize --payment_token CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC --admin ADMIN --payment_amount 10 --reward_token CDLZFC3SYJYDZT7K67VZ75HPJVIEUVNIXF47ZG2FB2RMQQVU2HHGCYSC --reward_amount 10
    
  6. Editing the contract ID:

    Open client/game.js and edit the following line with your contract id.

    const contractId = "CA7VJIGYO6OU5U5BQ77B6YAQDEQQ6E5U5OMVIG5XLHZKCHZLQA3N4Q7N";
    
  7. Optional, for Non-Freighter Users:

    If you are not using Freighter, open client/game.js and edit the following line with your test account secret seed.

    // Enter a valid secret seed if you need testing without Freighter.
    const testSecret = "S---ECRET";
    

Using the Smart Contract

To interact with the smart contract for testing or just playing, you have two main options:

  1. Using the Game Client:

    • Launch the client/index.html file. To bypass browser limitations, consider serving the client/index.html file through HTTP/S.
    • If you're using Freighter, ensure that you are on testnet.
  2. Using the Soroban CLI:

    • To open a game session and get a pool table, execute the following command:
     soroban contract invoke --network TESTNET --source PLAYER --id YOUR_CONTRACT_ID -- insertcoin --player PLAYER
    
    • To withdraw payments, use the following command:
     soroban contract invoke --network TESTNET --source ADMIN --id YOUR_CONTRACT_ID -- withdraw --account YOUR_STELLAR_ADDRESS --amount 10
    

Contributing

Contributions are what make the open source community such an amazing place to learn, inspire, and create. Any contributions you make are greatly appreciated.

If you have a suggestion that would make this better, please fork the repo and create a pull request. You can also simply open an issue with the tag "enhancement". Don't forget to give the project a star! Thanks again!

  1. Fork the Project
  2. Create your Feature Branch (git checkout -b feature/AmazingFeature)
  3. Commit your Changes (git commit -m 'Add some AmazingFeature')
  4. Push to the Branch (git push origin feature/AmazingFeature)
  5. Open a Pull Request

License

Distributed under the MIT License. See LICENSE for more information.

Contact

Fred Kyung-jin Rezeau - @FredericRezeau

Litemint Marketplace: https://litemint.com

Check out our tradable card game on Stellar: https://litemint.io

Join our discord server: https://litemint.gg

Dependencies

~11–16MB
~326K SLoC