Discord Tipping Bot with Stellar

A Discord bot that enables users to tip each other using Stellar (XLM) cryptocurrency, powered by a Soroban smart contract.

Try the Interactive Demo

See it in action immediately:

./run-demo.sh

Or manually:

cd cli
cargo run --release

The CLI demo features:

• Beautiful ASCII art interface
• Interactive walkthrough tutorial
• Full tipping simulation
• Statistics and transaction history
• No setup required - runs instantly!

Perfect for presentations, testing, and learning how the system works!

Features

• Seamless Tipping: Tip other Discord users with XLM instantly
• Smart Contract: Secure on-chain tipping via Soroban smart contract
• Wallet Management: Generate or import Stellar wallets
• Balance Tracking: Check your balance and transaction history
• Deposit/Withdraw: Easily move funds in and out
• Statistics: View your tipping stats

Project Structure

.
├── contracts/
│   ├── tipping/           # Soroban smart contract for tips
│   │   ├── src/
│   │   │   ├── lib.rs     # Contract logic
│   │   │   └── test.rs    # Contract tests
│   │   └── Cargo.toml
│   └── hello-world/       # Example contract
├── cli/                   # Interactive CLI demo
│   ├── src/
│   │   ├── main.rs        # CLI entry point
│   │   ├── demo.rs        # Demo logic
│   │   └── wallet.rs      # Wallet models
│   └── Cargo.toml
├── bot/                   # Discord bot application
│   ├── src/
│   │   ├── main.rs        # Bot entry point
│   │   ├── commands.rs    # Discord slash commands
│   │   ├── stellar.rs     # Stellar integration
│   │   ├── database.rs    # User data management
│   │   ├── config.rs      # Configuration
│   │   └── error.rs       # Error handling
│   └── Cargo.toml
├── Cargo.toml             # Workspace configuration
├── run-demo.sh            # Quick demo launcher
└── README.md

Getting Started

Prerequisites

• Rust (1.70+)
• Stellar CLI
• Discord Bot Token (Create one here)
• SQLite

Installation

1. Clone the repository

   git clone <your-repo-url>
   cd discord-tip-bot

2. Build the smart contract

   cd contracts/tipping
   stellar contract build

3. Deploy the contract to testnet

   stellar contract deploy \
     --wasm target/wasm32-unknown-unknown/release/tipping.wasm \
     --network testnet

   Save the contract ID that's returned!

4. Initialize the contract

   stellar contract invoke \
     --id <CONTRACT_ID> \
     --network testnet \
     -- initialize \
     --admin <YOUR_STELLAR_ADDRESS> \
     --token <NATIVE_TOKEN_ID>

5. Configure the bot

   cd ../../bot
   cp ../.env.example .env
   # Edit .env with your configuration

6. Build and run the bot

   cargo build --release
   cargo run --release

Configuration

Create a .env file in the root directory:

DISCORD_TOKEN=your_discord_bot_token
DATABASE_URL=sqlite:bot.db
STELLAR_NETWORK=testnet
STELLAR_CONTRACT_ID=your_deployed_contract_id
STELLAR_ADMIN_SECRET=your_stellar_secret_key
MIN_TIP_AMOUNT=1000000
MAX_TIP_AMOUNT=10000000000

Discord Commands

Command	Description
/register [address]	Register your Stellar wallet (generates new if no address provided)
/balance	Check your current tip balance
/tip @user <amount> [message]	Send a tip to another user
/deposit	Get instructions to deposit XLM
/withdraw <amount>	Withdraw XLM to your Stellar wallet
/stats	View your tipping statistics
/help	Show help information

Example Usage

1. Register with the bot

   /register
   

   The bot will generate a new Stellar wallet and DM you the keys.

2. Deposit XLM

   /deposit
   

   Follow the instructions to fund your account.

3. Tip someone

   /tip @friend 5 Thanks for the help!
   

   This sends 5 XLM to @friend with a message.

4. Check your balance

   /balance
   

5. View statistics

   /stats
   

Testing the Smart Contract

cd contracts/tipping
cargo test

Development

Running locally for development

# Terminal 1: Watch and rebuild the bot
cd bot
cargo watch -x run

# Terminal 2: Watch and test the contract
cd contracts/tipping
cargo watch -x test

Building for production

# Build optimized contract
cd contracts/tipping
stellar contract optimize --wasm target/wasm32-unknown-unknown/release/tipping.wasm

# Build optimized bot
cd ../../bot
cargo build --release

Security Considerations

• Never commit your .env file - it contains sensitive keys
• Secure storage: In production, use a proper key management solution
• Rate limiting: Consider adding rate limits for tipping
• Audit: Have the smart contract audited before mainnet deployment
• User keys: Implement secure key storage for user wallets

Network Support

• Testnet: For development and testing (default)
• Mainnet: For production use (set STELLAR_NETWORK=mainnet)

Resources

• Stellar Documentation
• Soroban Smart Contracts
• Serenity (Discord Bot Framework)
• Stellar Laboratory