Prepared by Marius Georgescu

• RAFFLEIZE C-A-R-D-A-N-A - (Commit-And-Reveal-Decentralized-Application-for-Native-Assets)
  • 🚀 Quick Start
    • Prerequisites
    • 1. Clone and Setup
    • 2. Configure Atlas
    • 3. Configure Operation Key
    • 3. Deploy validators
    • 3. Build and Run
    • 4. Access API
  • Overview
    • Key Benefits
    • Features
  • Architecture
  • Documentation
  • API Documentation
    • Key Endpoints
  • Development
    • Project Structure
    • PureScript Code Generation
    • Development Tools
    • Key Files
    • Testing
  • Contributing
    • Code Quality
  • License
  • Support
  • Acknowledgments

• Unix-like operating system (Linux, macOS, or WSL2)
• Git installed
• Nix package manager
• Direnv

This project uses the The Developer Experience Shell to build a fully-functioning and reproducible Cardano development shell for Haskell quickly and across multiple operating systems (and architectures).

git clone https://github.com/mariusgeorgescu/raffleize.git
cd raffleize

• After installing and configuring nix and direnv, clone the repo and type:

 direnv allow

• The test suite for operations (transactions) can be run with the following command:

cabal test 

Create atlas_config.json with your Maestro token:

{
  "coreProvider": {
    "maestroToken": "YOUR_TOKEN_HERE",
    "turboSubmit": true
  },
  "networkId": "preview"
}

Create operation.prv with your private key mnemonic (24 words). Make sure you have enough funds available for covering the validators deployment. For testnet, you can get funds from the Cardano Testnet Faucet.

• This service requires validators to be deployed and to be used as reference UTxOs in the transactions. The validators can be deployed from the TUI.

cabal run tui

• After deployment a file named raffleize_validators_config.json which contains the validators reference UTxO and the admin key.

# Load environment
direnv allow

# Build project
cabal run build

# Start server
cabal run server

# Or use Admin TUI
cabal run  tui

• API Documentation: http://localhost:8082/swagger-ui
• Default credentials: cardano / lovelace

For detailed installation instructions, see 🚀 Quick Start.

RAFFLEIZE C-A-R-D-A-N-A is a decentralized application (DApp) for digital assets raffles based on a commit and reveal scheme (CRS) as a source of randomness for electing winners. Built on the Cardano blockchain, it provides a secure, transparent, and trustless platform for conducting raffles.

• Decentralized Trust: Eliminates reliance on central authorities through transparent, verifiable winner selection
• Digital Asset Monetization: Enables asset owners to monetize their holdings through raffles
• Enhanced Liquidity: Tokenized raffle ownership and tickets for increased marketability
• Privacy Preservation: Anonymous participation fostering secure transactions
• Inclusive Participation: No identity verification required for participation

• Smart Contract Integration: Plutus-based smart contracts for secure raffle logic
• REST API: Full-featured API with Swagger documentation
• Terminal User Interface: Interactive TUI for direct interaction
• WebSocket Support: Real-time updates and notifications
• Comprehensive Testing: Unit and property-based test suite
• PureScript Bridge: Automated code generation for frontend integration
• Docker Support: Production-ready containerization

The project follows a modular architecture with three main components:

1. Smart Contracts (src/RaffleizeDApp/OnChain/)

   • Raffleize Validator - Main raffle logic
   • Ticket Validator - Ticket management
   • Minting Policy - NFT minting

2. Transaction Building (src/RaffleizeDApp/TxBuilding/)

   • Transaction construction and validation
   • Blockchain interactions
   • Context management

3. User Interfaces (src/RaffleizeDApp/Server/, src/RaffleizeDApp/TUI/)

   • REST API server
   • Terminal user interface
   • WebSocket support

• Functional Specification - Detailed functional requirements and specifications
• Diagrams - Architecture and flow diagrams
• Changelog - Version history and changes

The REST API provides endpoints for:

• Transaction Building: Construct and submit Cardano transactions
• Data Lookups: Query raffles, tickets, and user information
• Real-time Updates: WebSocket support for live updates
• API Documentation - Complete API reference

• POST /build-tx - Build transactions
• POST /submit-tx - Submit transactions
• GET /raffles - Get all raffles
• GET /raffle/{raffleId} - Get specific raffle
• POST /user-raffles - Get user's raffles
• POST /user-tickets - Get user's tickets

For complete API documentation, visit the Swagger UI when the server is running.

src/RaffleizeDApp/
├── OnChain/          # Smart contract code
├── TxBuilding/       # Transaction building
├── Server/           # REST API server
├── TUI/              # Terminal user interface
├── CodeGen/          # PureScript code generation
├── Tests/            # Test suite
└── CustomTypes/      # Type definitions

just psgen

just repl      # GHC REPL
just test      # Run tests
just gc        # Clean Nix store
just link-hls  # Link Haskell Language Server

• raffleize.cabal - Package configuration
• atlas_config.json - Atlas Cardano SDK configuration
• raffleize_validators_config.json - Validator addresses
• *.plutus - Compiled smart contracts

cabal run test  # Run all tests

1. Follow the installation instructions
2. Set up development environment:

   just allow
   just link-hls  # For VS Code users

3. Start development:

   just repl      # For Haskell development
   just server    # For API development
   just tui       # For UI development

• Follow Haskell best practices
• Ensure comprehensive test coverage
• Document all public APIs
• Prioritize type safety and correctness

This project is licensed under the GPL-3.0 License - see the LICENSE file for details.

For questions and support:

• Create an issue on GitHub
• Check the Functional Specification for detailed information
• Review the API documentation at the Swagger UI

Thanks to the Cardano community for support. This project is part of F10-developer-ecosystem-the-evolution - Project Catalyst Idea #105248