Skip to content

README-STELLAR-ONLY.md

Latest commit

 

History

History
418 lines (307 loc) · 10.7 KB

README-STELLAR-ONLY.md

File metadata and controls

418 lines (307 loc) · 10.7 KB
Raw

Stellar Sealed-Bid Auction System

A pure Stellar blockchain sealed-bid auction platform with Soroban smart contracts, featuring private-input encryption and real-time updates.

🌟 Pure Stellar Architecture

This project is exclusively built on Stellar with no other blockchain dependencies:

🔗 Smart Contracts (Stellar/Soroban Only)

  • Location: contracts/src/lib.rs
  • Language: Rust
  • Platform: Stellar Soroban
  • Features:
    • Commit-reveal bidding scheme
    • On-chain auction management
    • Secure bid encryption
    • Automatic winner determination

🖥️ Backend (Node.js + Stellar SDK)

  • Location: server.js
  • Integration: Stellar SDK only
  • Features:
    • Stellar RPC integration
    • Real-time updates via Socket.io
    • API endpoints for auction management
    • Stellar wallet services

🌐 Frontend (HTML/JavaScript + Stellar)

  • Location: public/
  • Integration: Stellar SDK only
  • Features:
    • Stellar wallet integration
    • Modern responsive UI
    • Real-time auction updates
    • Bid commitment and revelation

🚀 Quick Start (Stellar Only)

Prerequisites

  1. Install Rust (for Stellar smart contracts):

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh

  2. Install Soroban CLI (Stellar smart contract toolkit):

    cargo install --locked soroban-cli

  3. Install Node.js (v18+):

    # Download from https://nodejs.org/

Setup Steps

  1. Clone and Install:

    git clone https://github.com/akordavid373/sealed-auction-platform.git
cd sealed-bid-auction
npm install

  2. Build Stellar Smart Contract:

    npm run build-contract

  3. Configure Stellar Environment:

    cp .env.example .env
# Edit .env with your Stellar keys

  4. Deploy to Stellar Network:

    npm run deploy-contract

  5. Start Application:

    npm start

  6. Open Browser: http://localhost:3000

🔐 Stellar Smart Contract Features

Core Functions (Stellar Only)

// Create new auction on Stellar
create_auction(title, description, starting_bid, duration)

// Commit sealed bid to Stellar
commit_bid(auction_id, commitment, bid_amount)

// Reveal bid amount on Stellar
reveal_bid(bid_id, bid_amount, secret)

// End auction on Stellar and determine winner
end_auction(auction_id)

// Cancel auction on Stellar (creator only)
cancel_auction(auction_id)

Stellar Security Features

  • Commit-Reveal Scheme: Prevents front-running attacks
  • On-Chain Storage: All auction data immutable on Stellar
  • Cryptographic Security: SHA256 commitment hashes
  • Access Control: Only creators can cancel auctions
  • Stellar Network Security: Built-in network consensus

💫 Stellar Integration

Stellar Wallet Connection

// Connect with Stellar secret key
const wallet = new StellarWallet();
await wallet.connectWithSecret('your_stellar_secret_key');

// Or create new Stellar wallet
const newWallet = wallet.createWallet();
console.log(newWallet.publicKey, newWallet.secretKey);

Stellar Transaction Flow

  1. Create Auction: Call Stellar smart contract
  2. Commit Bid: Submit encrypted commitment to Stellar
  3. Reveal Bid: Submit actual bid amount and secret to Stellar
  4. End Auction: Automatically determine highest bidder on Stellar
  5. Withdraw: Winner receives funds automatically on Stellar

Stellar Network Support

  • Stellar Testnet: Free development and testing
  • Stellar Mainnet: Production deployment
  • Future: Custom Stellar networks support

🛠️ Stellar Development Commands

Stellar Smart Contract Development

# Build Stellar contract
npm run build-contract

# Test Stellar contract
npm run test-contract

# Deploy to Stellar testnet
npm run deploy-contract

Backend Development (Stellar)

# Start development server with Stellar integration
npm run dev

# Run tests with Stellar integration
npm test

# Start with auto-reload
nodemon server.js

Frontend Development (Stellar)

Frontend is served from the backend with Stellar wallet integration.

📊 Stellar API Endpoints

Stellar Integration Only

// GET /api/stellar/contract-info
// Returns Stellar contract address and network info

// POST /api/stellar/create-auction
// Creates auction on Stellar blockchain

// POST /api/stellar/commit-bid
// Commits bid to Stellar blockchain

// POST /api/stellar/reveal-bid
// Reveals bid on Stellar blockchain

// GET /api/stellar/auctions
// Lists all Stellar blockchain auctions

Stellar Real-time Events

// Socket.io events for Stellar
socket.on('stellarAuctionCreated', (auction) => { /* ... */ });
socket.on('stellarBidCommitted', (data) => { /* ... */ });
socket.on('stellarBidRevealed', (data) => { /* ... */ });
socket.on('stellarAuctionEnded', (auction) => { /* ... */ });

🔧 Stellar Configuration

Environment Variables (Stellar Only)

# Stellar Configuration
STELLAR_NETWORK=testnet
SECRET_KEY=your_stellar_secret_key_here
PUBLIC_KEY=your_stellar_public_key_here
CONTRACT_ID=deployed_stellar_contract_id

# Stellar RPC URLs
TESTNET_RPC_URL=https://soroban-testnet.stellar.org
MAINNET_RPC_URL=https://mainnet.stellar.org

# Application
PORT=3000
NODE_ENV=development

Stellar Contract Deployment

# Deploy to Stellar testnet
npm run deploy-contract -- --network testnet

# Deploy to Stellar mainnet
npm run deploy-contract -- --network mainnet

🧪 Stellar Testing

Stellar Smart Contract Tests

cd contracts
cargo test

Integration Tests (Stellar)

npm test

Manual Stellar Testing

  1. Connect Stellar wallet with testnet account
  2. Create auction with test parameters on Stellar
  3. Place bids using commit-reveal on Stellar
  4. Verify auction end and winner selection on Stellar

🌍 Stellar Deployment Options

Local Development (Stellar)

npm run dev
# Runs on http://localhost:3000 with Stellar integration

Cloud Deployment (Stellar)

Heroku (Stellar)

heroku create stellar-auction
git push heroku main
heroku config:set STELLAR_NETWORK=testnet

Railway (Stellar)

railway login
railway init
railway up

Docker (Stellar)

docker build -t stellar-auction .
docker run -p 3000:3000 stellar-auction

🔒 Stellar Security Considerations

Stellar Smart Contract Security

  • Audit: Stellar contract should be professionally audited
  • Testing: Comprehensive Stellar test coverage required
  • Upgradability: Consider Stellar proxy patterns for updates

Stellar Key Management

  • Secret Keys: Never expose Stellar private keys in frontend
  • Environment: Use secure environment variables for Stellar keys
  • Backup: Secure Stellar key backup procedures

Stellar Network Security

  • HTTPS: Required for production Stellar deployment
  • Rate Limiting: API protection implemented
  • Input Validation: All Stellar inputs validated

📱 Mobile Compatibility (Stellar)

The Stellar application is fully responsive and works on:

  • Desktop browsers (Chrome, Firefox, Safari)
  • Mobile browsers (iOS Safari, Chrome Mobile)
  • Tablets (iPad, Android tablets)

🔄 Stellar Transaction Flow Diagram

User → Frontend → Backend → Stellar Network
  ↓        ↓        ↓         ↓
Create   Form     API    Stellar Smart Contract
Auction  Submit   Call   create_auction()
  ↓        ↓        ↓         ↓
Commit   Hash     API    Stellar Smart Contract
Bid     Submit   Call   commit_bid()
  ↓        ↓        ↓         ↓
Reveal   Amount   API    Stellar Smart Contract
Bid     Submit   Call   reveal_bid()
  ↓        ↓        ↓         ↓
End      Timer    API    Stellar Smart Contract
Auction  Check    Call   end_auction()

🌟 Why Stellar Only?

Advantages of Pure Stellar Architecture

  1. Low Transaction Costs: Stellar transactions are nearly free
  2. Fast Settlement: 3-5 second confirmation times
  3. Built-in Decentralized Exchange: Native asset trading
  4. Multi-Currency Support: Native support for various tokens
  5. Energy Efficient: Environmentally friendly consensus
  6. Simple Integration: Clean, focused architecture

No Ethereum Dependencies

  • ✅ No Solidity: Pure Rust smart contracts
  • ✅ No Web3.js: Only Stellar SDK
  • ✅ No Gas Fees: Stellar's minimal fees
  • ✅ No Hardhat: Soroban CLI only
  • ✅ No Ethereum Networks: Only Stellar testnet/mainnet

🤝 Contributing to Stellar Project

  1. Fork the repository
  2. Create feature branch for Stellar improvements
  3. Make changes to Stellar components
  4. Add Stellar-specific tests
  5. Submit pull request

📞 Stellar Support

🎉 What's Next for Stellar?

Planned Stellar Features

  • Stellar Asset Integration: Support for various Stellar tokens
  • Stellar Path Payments: Multi-currency auctions
  • Stellar AMM Integration: Decentralized exchange features
  • Stellar Multisig: Enhanced security
  • Stellar Anchor Integration: Fiat on-ramps

Technical Stellar Improvements

  • Stellar Fee Optimization: Reduce transaction costs
  • Stellar Scalability: Handle high-volume auctions
  • Stellar UI/UX: Enhanced user experience
  • Stellar Testing: Expanded test coverage

Built with ❤️ exclusively for the Stellar ecosystem

🌟 Repository: https://github.com/akordavid373/sealed-auction-platform

🚀 Live Demo: (Coming soon)

📧 Contact: [Your contact information]

📁 Pure Stellar Project Structure

stellar-sealed-bid-auction/
├── 🔗 contracts/
│   ├── src/lib.rs              # Stellar smart contract (Rust)
│   ├── Cargo.toml              # Rust dependencies
│   └── StellarSealedBidAuction.ts # TypeScript SDK
├── 🖥️ server.js                # Node.js + Stellar backend
├── 🌐 public/
│   ├── index.html              # Stellar frontend
│   ├── stellar-wallet.js       # Stellar wallet integration
│   └── app.js                  # Frontend logic
├── 📜 scripts/deploy-stellar.js # Stellar deployment script
├── ⚙️ .env.example             # Stellar environment template
├── 📖 README-STELLAR-ONLY.md   # Stellar documentation
└── 📦 package.json             # Stellar dependencies

Note: This is a Stellar-only implementation with no Ethereum or other blockchain dependencies.