StarkLotto

StarkLotto is a decentralized lottery game built on Starknet and Stellar, offering secure and transparent on-chain draws. It uses Cairo smart contracts on Starknet and Rust/Soroban smart contracts on Stellar, with a single unified Next.js frontend that supports both chains.

▶️ Watch the Hackathon Video

🌐 Testnet Version: 👉 https://starklotto-eta.vercel.app/

🏗️ Monorepo Structure

starklotto/
├── packages/
│   ├── snfoundry/          # Cairo smart contracts (Starknet)
│   ├── soroban/            # Rust/Soroban smart contracts (Stellar)
│   └── nextjs/             # Unified Next.js frontend (both chains)

🚀 Features

Dual-chain lottery — play on Starknet or Stellar from the same interface.
Cairo contracts on Starknet: Lottery, ERC20 token (STRKP), Vault, NFT tickets, Randomness.
Soroban contracts on Stellar: Lottery, StellarPlay token (STLP), Vault — commit-reveal randomness.
Chain-agnostic frontend — a ChainAdapter abstraction layer decouples UI from chain-specific logic.
Wallet support — Argent / Braavos (Starknet), Freighter / Albedo (Stellar).
NFT tickets — each Starknet ticket is minted as an ERC721.
Progressive prize tiers — 1 match: 1% · 2: 4% · 3: 10% · 4: 15% · 5 (Jackpot): 70%.
PWA-ready frontend with i18n (i18next) and TailwindCSS + DaisyUI.

📜 Prerequisites

Starknet stack

Tool	Version
Starknet-devnet	v0.4.0
Scarb	v2.11.4
Snforge	v0.41.0
Cairo	v2.11.4
RPC	v0.8.0

Stellar stack

Tool	Version
Rust	stable (1.78+)
stellar-cli	v0.22+
wasm32 target	`rustup target add wasm32-unknown-unknown`

General

Tool	Version
Node.js	LTS (compatible with Next.js 15)
Yarn	v3.2.3

🔧 Installation

1️⃣ Clone the repository

git clone https://github.com/FutureMindsTeam/starklotto.git
cd starklotto

Note: To contribute, branch off Dev before making changes:
git checkout -b feature/your-feature Dev

2️⃣ Install JS dependencies

yarn install

3️⃣ Configure environment variables

# Starknet (packages/snfoundry/)
cp packages/snfoundry/.env.example packages/snfoundry/.env

# Stellar (packages/soroban/)
cp packages/soroban/.env.example packages/soroban/.env

# Frontend (packages/nextjs/)
cp packages/nextjs/.env.example packages/nextjs/.env.local

Key variables for the frontend:

# Starknet
NEXT_PUBLIC_DEVNET_PROVIDER_URL=http://127.0.0.1:5050
NEXT_PUBLIC_SEPOLIA_PROVIDER_URL=

# Stellar
NEXT_PUBLIC_STELLAR_NETWORK=testnet
NEXT_PUBLIC_STELLAR_HORIZON_URL=https://horizon-testnet.stellar.org
NEXT_PUBLIC_STELLAR_SOROBAN_RPC_URL=https://soroban-testnet.stellar.org
NEXT_PUBLIC_STELLAR_LOTTERY_CONTRACT=
NEXT_PUBLIC_STELLAR_TOKEN_CONTRACT=
NEXT_PUBLIC_STELLAR_VAULT_CONTRACT=

⚡ Starknet — Local Development

Start the local network

yarn chain

Deploy contracts

yarn deploy          # Deploy (clears previous)
yarn deploy:no-reset # Deploy (keeps previous)

Start the frontend

yarn start

Open http://localhost:3000.

Compile contracts only

yarn compile

Run Cairo tests

yarn test

🌟 Stellar — Development

Install Rust target (one-time)

rustup target add wasm32-unknown-unknown

Build Soroban contracts

yarn stellar:build

Run Soroban tests

yarn stellar:test

Format Soroban code

yarn stellar:fmt

Deploy to Stellar Testnet

# 1. Set up your Stellar account in stellar-cli
stellar keys generate default --network testnet

# 2. Fund the account (testnet only)
stellar keys fund default --network testnet

# 3. Deploy contracts
yarn stellar:deploy:testnet

After deploying, copy the contract IDs into packages/nextjs/.env.local:

NEXT_PUBLIC_STELLAR_LOTTERY_CONTRACT=C...
NEXT_PUBLIC_STELLAR_TOKEN_CONTRACT=C...
NEXT_PUBLIC_STELLAR_VAULT_CONTRACT=C...

Deploy to Stellar Mainnet

yarn stellar:deploy:mainnet

🏛️ Architecture Overview

Smart Contracts

Starknet (`packages/snfoundry/contracts/src/`)

Contract	Description
`Lottery.cairo`	Draw management, ticket purchase, prize distribution
`StarkPlayERC20.cairo`	Platform token (STRKP) with mint/burn/prize roles
`StarkPlayVault.cairo`	STRK ↔ STRKP conversion with fee management
`LottoTicketNFT.cairo`	ERC721 NFT per ticket
`MockRandomness.cairo`	Randomness oracle integration

Stellar (`packages/soroban/contracts/`)

Contract	Description
`lottery/`	Draw management with commit-reveal randomness
`token/`	StellarPlay token (STLP), SEP-0041 compatible
`vault/`	XLM ↔ STLP conversion with fee management

Frontend (`packages/nextjs/`)

The frontend uses a chain-adapter pattern to remain agnostic of the underlying blockchain:

Page / Component
      ↓
useLotteryBuyTickets (unified hook)
      ↓  parallel pattern
useBuyTickets        useStellarBuyTickets
(Starknet hooks)     (Stellar hooks)
      ↓
  ChainAdapter interface
      ↓
Starknet contracts   Stellar Soroban contracts

Key directories:

Path	Description
`services/chain-adapter/`	`ChainAdapter` interface, Starknet and Stellar adapters
`hooks/scaffold-stark/`	Starknet-specific hooks
`hooks/scaffold-stellar/`	Stellar-specific hooks
`hooks/useLottery*.ts`	Unified hooks (chain-agnostic)
`hooks/useChainAdapter.ts`	Assembles the write adapter for the active chain
`context/ChainContext.tsx`	Global chain selector (Starknet / Stellar)
`services/web3/stellar/`	Stellar wallet connectors and Soroban RPC helpers
`contracts/deployedContracts.ts`	Auto-generated Starknet contract addresses
`contracts/stellarContracts.ts`	Stellar contract IDs (from env vars)

📝 Contributions

Fork the repository.
Create a branch off Dev:

git checkout -b feature/new-feature Dev

Make your changes and commit:

git commit -m "feat: description of change"

Push and open a Pull Request targeting Dev.

🤝 Contact

🛠️ Command Reference

This repo uses Yarn as package manager.

General

Command	Description
`yarn install`	Install all JS dependencies
`yarn start`	Start the Next.js dev server
`yarn format`	Format all code (Cairo + TypeScript)
`yarn format:check`	Check formatting without writing changes
`yarn next:lint`	Run Next.js linter
`yarn next:check-types`	TypeScript type check
`yarn prepare`	Install Husky git hooks

Starknet — Smart Contracts

Command	Description
`yarn compile`	Compile Cairo contracts with Scarb
`yarn test`	Run Snforge test suite
`yarn chain`	Start local Starknet devnet
`yarn deploy`	Deploy contracts (clears previous)
`yarn deploy:no-reset`	Deploy contracts (keeps previous)
`yarn verify`	Verify contracts with Walnut

Stellar — Smart Contracts

Command	Description
`yarn stellar:build`	Compile Soroban contracts to WASM
`yarn stellar:test`	Run Soroban unit tests
`yarn stellar:fmt`	Format Rust code
`yarn stellar:fmt:check`	Check Rust formatting without writing
`yarn stellar:deploy:testnet`	Deploy contracts to Stellar Testnet
`yarn stellar:deploy:mainnet`	Deploy contracts to Stellar Mainnet

Frontend

Command	Description
`yarn start`	Start development server on localhost:3000
`yarn test:nextjs`	Run Vitest test suite
`yarn vercel`	Deploy to Vercel
`yarn vercel:yolo`	Force deploy to Vercel (ignoring errors)

Name		Name	Last commit message	Last commit date
Latest commit History 282 Commits
.github		.github
.husky		.husky
.yarn		.yarn
docs/ADMIN		docs/ADMIN
docu		docu
packages		packages
starklotto_debug		starklotto_debug
.devcontainer.json		.devcontainer.json
.gitignore		.gitignore
.tool-versions		.tool-versions
.yarnrc.yml		.yarnrc.yml
CLAUDE.md		CLAUDE.md
CONTRIBUTING.md		CONTRIBUTING.md
IMPLEMENTATION_CHECKLIST_456.md		IMPLEMENTATION_CHECKLIST_456.md
LICENSE		LICENSE
README.md		README.md
package.json		package.json
test_balance_validation.md		test_balance_validation.md
yarn.lock		yarn.lock

Folders and files

Latest commit

History

Repository files navigation

StarkLotto

🏗️ Monorepo Structure

🚀 Features

📜 Prerequisites

Starknet stack

Stellar stack

General

🔧 Installation

1️⃣ Clone the repository

2️⃣ Install JS dependencies

3️⃣ Configure environment variables

⚡ Starknet — Local Development

Start the local network

Deploy contracts

Start the frontend

Compile contracts only

Run Cairo tests

🌟 Stellar — Development

Install Rust target (one-time)

Build Soroban contracts

Run Soroban tests

Format Soroban code

Deploy to Stellar Testnet

Deploy to Stellar Mainnet

🏛️ Architecture Overview

Smart Contracts

Starknet (packages/snfoundry/contracts/src/)

Stellar (packages/soroban/contracts/)

Frontend (packages/nextjs/)

📝 Contributions

🤝 Contact

🛠️ Command Reference

General

Starknet — Smart Contracts

Stellar — Smart Contracts

Frontend

About

Resources

License

Contributing

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Uh oh!

Contributors

Uh oh!

Languages

Starknet (`packages/snfoundry/contracts/src/`)

Stellar (`packages/soroban/contracts/`)

Frontend (`packages/nextjs/`)

Packages