Easy Win Lottery - Documentação

Visão Geral

Easy Win Lottery é um aplicativo descentralizado (Dapp) completo desenvolvido para a blockchain Alephium, utilizando a linguagem de programação RALPH para o contrato inteligente e React/TypeScript para o front-end. O sistema implementa uma loteria com regras específicas, permitindo aos usuários comprar bilhetes, participar de sorteios semanais e ganhar prêmios.

Estrutura do Projeto

easy-win-lottery/
├── contracts/
│   └── EasyWinLottery.ral       # Contrato inteligente em RALPH
├── scripts/
│   ├── alephium.config.ts       # Configuração para diferentes ambientes
│   └── deploy.ts                # Script de implantação do contrato
├── src/
│   ├── components/
│   │   ├── BettingForm.tsx      # Formulário para apostas
│   │   ├── CountdownTimer.tsx   # Contador regressivo para o próximo sorteio
│   │   └── LastDrawResults.tsx  # Exibição dos resultados do último sorteio
│   ├── lib/
│   │   └── web3.ts              # Integração com a Web3 da Alephium
│   ├── pages/
│   │   └── index.tsx            # Página principal do aplicativo
│   └── styles/                  # Arquivos CSS para estilização
├── tests/
│   └── lottery.test.ts          # Testes automatizados
└── README.md                    # Documentação principal

Componentes Principais

1. Contrato Inteligente (EasyWinLottery.ral)

O contrato implementa a lógica da loteria com as seguintes funcionalidades:

• Regras do Jogo: 25 números disponíveis, cada bilhete permite escolher entre 15 e 20 números, e em cada sorteio 15 números são sorteados aleatoriamente.
• Frequência de Sorteio: Todo domingo às 00:00 GMT.
• Modos de Aposta: Aposta Simples, Escolha Rápida e Perseverança.
• Preços dos Bilhetes: Variam de 3 ALPH (15 números) até 46.512 ALPH (20 números).
• Distribuição de Prêmios: 80% do total arrecadado vai para prêmios, com diferentes percentuais para cada categoria de acertos.

2. Scripts de Implantação

• alephium.config.ts: Configuração para diferentes ambientes (devnet, testnet, mainnet).
• deploy.ts: Script para implantação do contrato, incluindo cálculo do próximo domingo à meia-noite GMT.

3. Integração Web3 (web3.ts)

Biblioteca para interação com o contrato inteligente, incluindo:

• Inicialização do provedor de nós e carteira
• Funções para compra de bilhetes, reivindicação de prêmios e consulta de informações
• Utilitários para conversão de dados e cálculos

4. Front-end (React/TypeScript)

• Página Principal: Exibe informações do sorteio atual, contador regressivo e resultados do último sorteio.
• Formulário de Apostas: Permite aos usuários escolher números, selecionar modo de aposta e comprar bilhetes.
• Componentes Auxiliares: Contador regressivo e exibição de resultados.

5. Testes Automatizados

Testes para validar as principais funcionalidades do contrato:

• Compra de bilhetes
• Processo de sorteio
• Consulta de informações

Guia de Uso

Pré-requisitos

• Node.js v16 ou superior
• npm ou yarn
• Acesso a um nó Alephium (local para desenvolvimento ou remoto para produção)
• Carteira Alephium com fundos suficientes

Configuração do Ambiente

1. Clone o repositório:

   git clone <repositório>
   cd easy-win-lottery
   

2. Instale as dependências:

   npm install
   

3. Configure as variáveis de ambiente: Crie um arquivo .env na raiz do projeto com as seguintes variáveis:

   PRIVATE_KEY_DEVNET=<sua-chave-privada-para-devnet>
   PRIVATE_KEY_TESTNET=<sua-chave-privada-para-testnet>
   PRIVATE_KEY_MAINNET=<sua-chave-privada-para-mainnet>
   

Implantação do Contrato

1. Para implantar no ambiente de desenvolvimento:

   npm run deploy:devnet
   

2. Para implantar no testnet:

   npm run deploy:testnet
   

3. Para implantar no mainnet:

   npm run deploy:mainnet
   

Execução do Front-end

1. Inicie o servidor de desenvolvimento:

   npm run dev
   

2. Acesse o aplicativo em http://localhost:3000

Execução dos Testes

npm run test

Considerações Técnicas

Geração de Aleatoriedade

O contrato utiliza uma combinação de hash do bloco, timestamp e um seed fornecido pelo admin para gerar números aleatórios para o sorteio. Esta abordagem híbrida oferece um bom equilíbrio entre aleatoriedade e segurança.

Temporização dos Sorteios

O sistema calcula o timestamp do próximo domingo à meia-noite GMT e permite que o admin execute o sorteio após esse momento. Isso garante que os sorteios ocorram regularmente, mesmo que não seja exatamente no momento programado.

Gestão de Fundos

O contrato implementa um sistema de alocação de fundos que separa o pool principal de prêmios e uma reserva para prêmios fixos, garantindo que haja sempre fundos suficientes para pagar os prêmios de menor valor.

Otimização de Armazenamento

Para economizar espaço e reduzir custos de transação, o contrato utiliza ByteVec para armazenar arrays de números, em vez de estruturas mais complexas.

Limitações e Melhorias Futuras

1. Interface Administrativa: Desenvolver uma interface específica para o admin gerenciar sorteios e monitorar o sistema.

2. Histórico de Sorteios: Implementar uma página para visualizar o histórico completo de sorteios anteriores.

3. Notificações: Adicionar um sistema de notificações para alertar os usuários sobre sorteios e prêmios.

4. Integração com Oráculos: Utilizar oráculos externos para melhorar a geração de aleatoriedade.

5. Otimização de Gas: Refinar o código do contrato para reduzir ainda mais os custos de transação.

Segurança

O contrato implementa várias medidas de segurança:

• Verificação rigorosa de chamador para funções administrativas
• Validação de entradas para prevenir manipulação
• Verificação de saldo suficiente antes de transferências
• Proteção contra reentrância

Suporte e Contribuições

Para suporte ou contribuições, entre em contato com a equipe de desenvolvimento ou abra uma issue no repositório do projeto.

---

© 2025 Easy Win Lottery - Desenvolvido para a blockchain Alephium