LemonJet Sui Contracts

LemonJet is a Sui-based game of chance where players stake SUI (or any supported coin type) against configurable payout coefficients. The Move contracts in this repository keep the full game loop on-chain: player registration, vault liquidity management, game execution, referral rewards, and points-based loyalty incentives.

Project Snapshot

• Language: Move
• Target Network: Sui Devnet/Testnet/Mainnet
• Key Features:
  • Deterministic and auditable play flow driven by Sui randomness.
  • Vault share system with fees, admin dividends, and referral rewards.
  • Player registry that supports optional referrer names.
  • Points program that mints an on-chain loyalty token and tracks campaign volume.

Getting Started

Prerequisites

Install the Sui CLI toolchain (includes Move compiler and simulator). Follow the official setup guide:

curl -fsSL https://install.sui.io | sh
sui client active-address            # verify installation

Ensure your environment is configured for the target network (Devnet/Testnet/Mainnet) by running sui client switch --env <ENV>.

Build & Test

From the repository root:

sui move build                       # type checking and bytecode generation
sui move test                        # run Move unit tests

The tests include coverage for referral reward bookkeeping in the points module.

Deploying

1. Publish the package on the desired network:

   sui client publish --gas-budget <BUDGET>

2. Record the published package ID. You will need it to invoke entry functions.
3. Run initial setup (see the flow below) using sui client call.

💡 These contracts are generic over the staked coin type T. When deploying to mainnet, publish an instance per supported asset or wrap the vault in a front-end router.

Core Modules

Module	Purpose
admin	Mints an AdminCap that authorises vault/points configuration.
player	Maintains player objects, optional referrers, and name registry.
lemonjet	Implements the game loop, fee logic, and outcome events.
vault	Manages liquidity, share minting/burning, admin dividends, and payouts.
points	Sets up the loyalty program, tracks play volume, and mints POINTS tokens.

The relevant source files live under sources/. Move.toml defines package metadata and dependencies.

Typical Workflow

1. Admin initialisation

   • Call admin::init to create the AdminCap.
   • With the cap, invoke vault::create<T> to deploy a vault for the chosen coin type.
   • With the cap, run points::setup<T> to configure loyalty caps and cadence.

2. Player onboarding

   • Share objects player::PlayerRegistry and player::NameRegistry by calling player::init once after publish.
   • Players register via player::create (optionally referencing an existing player address) or player::create_by_name.

3. Game play

   • Players fund the vault using vault::deposit<T> to mint vault shares.
   • A front end requests randomness and calls lemonjet::play_and_earn_points_(...) with the desired coefficient.
   • The function records stake volume, awards referral shares, deducts house fees, and emits an Outcome event.

4. Rewards and exits

   • Players redeem liquidity with vault::redeem<T> (exit fees fund rewards).
   • Referral accounts claim accumulated vault shares through vault::claim*.
   • Volume rewards are collected with points::claim_ref_volume followed by points::claim to mint POINTS tokens.
   • Admins harvest dividends with vault::admin_claim* and rotate points cycles using points::next_cycle.

Configuration Highlights

• House edge in lemonjet::HOUSE_EDGE defaults to 1%.
• Coefficient bounds are enforced between 1.01x and 50x (coef is expressed in basis points with two decimals).
• Vault limits: vault::max_payout caps single-win exposure using the stored liquidity and a golden-ratio heuristic.
• Referral rewards: 30% of the house fee is allocated to the referrer; 20% mints admin shares; remaining fees stay in the vault.
• Points cycle: Controlled by points::Config (point capacity and interval). Completed cycles snapshot volumes into RateRegistry.

Repository Structure

.
├── Move.toml            # Package manifest and dependency declarations
├── Move.lock            # Locked dependency versions
├── README.md            # Project documentation (this file)
├── build/               # Build artifacts (generated by Sui CLI)
└── sources/             # Move modules

Development Tips

• Use sui client call --function ... --module ... for manual testing against a local sandbox or testnet.
• Enable verbose test output with sui move test --verbose 2 when debugging complex scenarios.
• When adding new modules, register them in Move.toml and ensure entry functions validate versioning like existing modules.

Disclaimer

These contracts are unaudited and are provided for research and experimentation only. Deploy to production at your own risk.