O Google Cloud é o ponto de partida porque é de lá que sai a credencial que permite o motor escrever na planilha automaticamente. Sem ela, toda execução do GitHub Actions vai travar no primeiro acesso ao Sheets.

Como criar o projeto

Acesse console.cloud.google.com, clique no seletor de projetos no topo e depois em "Novo projeto". Dê um nome descritivo (ex: tron-staking-engine) e clique em Criar. Aguarde alguns segundos até o projeto ser provisionado.

Quais APIs ativar?

Com o projeto selecionado, vá em APIs e serviços → Biblioteca. Você precisa ativar exatamente duas:

Pesquise cada uma pelo nome e clique em Ativar. Sem as duas ativas simultaneamente, o motor retorna erro 403.

Criar a Service Account (conta de serviço)

Vá em APIs e serviços → Credenciais → + Criar credenciais → Conta de serviço. Preencha:

• Nome: tron-staking-bot (ou qualquer nome descritivo)
• Papel/Role: selecione Editor
• Clique em Concluído

Após criar, clique no e-mail gerado da conta de serviço (formato: nome@projeto.iam.gserviceaccount.com). Vá na aba Chaves → Adicionar chave → Criar nova chave → JSON → Criar. Um arquivo .json será baixado. Esse é o arquivo mais sensível de todo o setup — guarde-o fora do repositório Git.

Como alimentar esse dado no GitHub

Abra o arquivo .json em um editor de texto (Bloco de Notas, VS Code, qualquer um). Selecione todo o conteúdo (Ctrl+A), copie (Ctrl+C). No GitHub, vá em Settings → Secrets and variables → Actions → New repository secret, nomeie como GDRIVE_CREDENTIALS e cole o JSON completo no valor.

A planilha funciona como o "banco de dados" do motor — registra histórico de votos, estados da máquina e o dashboard de performance. O ponto crítico aqui é o compartilhamento: a Service Account precisa ter permissão de Editor antes do motor rodar.

Criando a planilha

Acesse sheets.google.com e crie uma planilha em branco. Dentro dela, crie 4 abas com os nomes exatos abaixo (o motor busca por nome):

DASHBOARD    → Visão geral: saldo, APR atual, último ciclo
VOTE_LOG     → Histórico de todas as trocas e reinvestimentos
SR_SCORES    → Ranking de SRs com score calculado pelo motor
STATE_LOCKS  → Memória de estado da Máquina de Estados (não edite manualmente)

Compartilhar com o e-mail da Service Account

Aqui está o detalhe que trava mais gente: você precisa compartilhar a planilha com o e-mail da Service Account, não com a sua conta Google pessoal. Esse e-mail está disponível em Google Cloud → Credenciais → Contas de serviço.

1. Na planilha, clique em "Compartilhar" (canto superior direito)
2. Cole o e-mail da Service Account (ex: tron-staking-bot@seu-projeto.iam.gserviceaccount.com)
3. Defina como "Editor"
4. Desmarque "Notificar pessoas" e confirme

Como obter o ID da planilha

A URL da planilha tem o formato abaixo. O ID é a sequência de caracteres entre /d/ e /edit:

https://docs.google.com/spreadsheets/d/SEU_ID_AQUI/edit#gid=0
                                       ▲──────────▲
                                       Copie isso

Esse valor vai para o Secret ID_PLANILHA_GOOGLE no GitHub.

O motor consulta a rede TRON por dois caminhos diferentes, com funções complementares. Aqui no @CanalQb, testamos as duas integrações e cada uma tem um papel específico que não pode ser substituído pela outra.

TronScan — Dados de mercado e votos

Site: tronscan.org — é o explorador oficial da rede TRON. O motor usa a API do TronScan para:

• Listar os Super Representantes do Top 27
• Coletar dados de APR, produtividade e ranking de cada SR
• Consultar recompensas pendentes (rewardNum) como referência secundária

Para obter a API Key do TronScan, acesse tronscan.org/#/setting/api, faça login e gere uma chave. Essa chave aumenta o rate limit e evita bloqueios por excesso de requisições. O motor funciona sem ela, mas pode ser limitado em ciclos intensos.

TronGrid — Transações on-chain

Site: trongrid.io — é o provedor de infraestrutura oficial da TRON Foundation. O motor usa a API do TronGrid para:

• Construir e broadcast de transações reais (Claim, Stake, Vote)
• Consultar saldo e recursos da carteira (Energy, Bandwidth, allowance)
• Assinar e enviar transações on-chain com a chave privada

Para a API Key do TronGrid, acesse trongrid.io/dashboard, crie uma conta e gere uma chave. As chaves de ambos os serviços são opcionais mas altamente recomendadas — sem elas, o motor usa endpoints públicos com rate limit bem mais restritivo.

O Telegram é onde você vai receber os alertas em tempo real. E o melhor? Funciona de graça. Mas tem um porém: o bot só envia mensagem para destinos que ele conhece. E ele só "conhece" você depois do /start.

Criando o bot com o BotFather

1. Abra o Telegram e pesquise por @BotFather (conta oficial, tem selo azul)
2. Envie o comando /newbot
3. Escolha um nome amigável para exibição (ex: Tron Staking Monitor)
4. Escolha um username único que termine em bot (ex: tron_staking_monitor_bot)
5. O BotFather responderá com o Token de Acesso no formato: 1234567890:AAExxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Por que o /start é obrigatório?

Por uma regra de privacidade do Telegram: bots não podem iniciar conversas com usuários arbitrários. O usuário precisa dar o primeiro passo. Sem o /start, qualquer mensagem enviada pelo motor retorna o erro 400 - chat not found, mesmo com token e Chat ID corretos.

Para ativar: pesquise seu bot pelo username criado (ex: @tron_staking_monitor_bot), abra a conversa e clique em "Iniciar" ou envie /start. Pronto — o bot agora pode te enviar mensagens.

Como obter o Chat ID numérico (mensagens diretas)

Para DMs (mensagem direta para você), o Telegram exige o Chat ID numérico, não o @username. Usernames são aceitos apenas para canais e grupos públicos.

1. No Telegram, pesquise por @userinfobot
2. Envie qualquer mensagem para ele
3. Ele responderá com seu Id: (um número como 683972422)
4. Esse número vai para o Secret TELEGRAM_CHAT_ID

Enviando para um grupo ou canal

Se você preferir receber os alertas em um canal privado (o que facilita manter histórico organizado), o processo é diferente:

1. Crie um canal ou grupo privado no Telegram
2. Adicione seu bot como Administrador com permissão de "Postar mensagens"
3. Envie qualquer mensagem no canal/grupo
4. Acesse no navegador: https://api.telegram.org/botSEU_TOKEN/getUpdates
5. No JSON retornado, localize: "chat": {"id": -1001234567890}
6. Esse número negativo é o ID do canal — use-o no Secret TELEGRAM_CHAT_ID

Esse é o ponto que mais confunde quem está começando. A tron_deploy_key é uma chave SSH dedicada para o repositório — ela permite que o motor faça git push automaticamente, sem precisar da sua senha do GitHub.

Pense assim: é como uma crachá de acesso exclusivo para o robô entrar no repositório e postar atualizações. Se esse crachá for comprometido, você revoga e emite um novo — sem afetar sua conta GitHub principal.

Como gerar o par de chaves do zero

Execute no terminal do seu computador (Linux, macOS ou WSL no Windows):

# Gera o par de chaves SSH sem passphrase (necessário para automação)
ssh-keygen -t ed25519 -f tron_deploy_key -C "tron-staking-deploy" -N ""

# Dois arquivos serão criados:
# tron_deploy_key      → chave PRIVADA (fica no GitHub Secret)
# tron_deploy_key.pub  → chave PÚBLICA (fica no GitHub como Deploy Key)

Onde cada arquivo vai

Proteger as chaves localmente

Após configurar no GitHub, nunca suba esses arquivos para o repositório. Certifique-se que o .gitignore contém:

tron_deploy_key
tron_deploy_key.pub
*.pem
*.json
.env

Os Secrets são a cofre do projeto. Tudo que é sensível fica aqui — nunca no código. Para acessar: seu repositório → Settings → Secrets and variables → Actions → New repository secret.

O projeto tem 4 workflows distintos no GitHub Actions. Cada um tem um propósito específico e só executa quando você quer (exceto o principal, que é agendado).

Workflow principal — motor completo

O arquivo main.yml configura dois gatilhos simultâneos:

on:
  schedule:
    - cron: "0 */6 * * *"   # Executa automaticamente a cada 6 horas
  workflow_dispatch:          # Executa manualmente quando você quiser

O cron: "0 */6 * * *" significa: toda vez que o minuto for 0 e a hora for divisível por 6 (00h, 06h, 12h, 18h UTC). Para disparar manualmente, vá em Actions → TRON Staking Engine → Run workflow.

Workflows de teste (execução manual)

Os três workflows de teste só rodam quando você clica em "Run workflow" — nunca automaticamente. E todos têm a opção de escolher entre DRY-RUN e execução real antes de rodar:

O motor não é apenas automação — é automação com defesas em camadas. Aqui estão os mecanismos que evitam perda de TRX e comportamento inesperado:

Proteção de Energy e Bandwidth

Antes de qualquer transação, o motor executa has_enough_resources(). Se Energy ou Bandwidth estiverem abaixo do mínimo para a operação específica, o ciclo é pulado por completo — nenhuma ação, nenhum TRX gasto em taxa. O motor tenta novamente 6 horas depois.

Máquina de Estados com cooldowns

O motor usa a aba STATE_LOCKS da planilha para lembrar o que já foi feito. Cada fase tem cooldown próprio — Claim, Stake e Vote nunca executam no mesmo ciclo. Isso evita gasto duplo de recursos e garante que o motor siga exatamente a sequência correta de 24h entre cada operação.

Anti-Churn com BadCount

Para evitar trocas desnecessárias de SR (o que gastaria Energy e poderia reduzir ganhos), o motor só substitui um SR quando ele apresenta performance abaixo do limiar por 4 ciclos consecutivos. Uma queda pontual é ignorada — apenas queda persistente aciona a troca.

Buffer de 49 TRX

O motor nunca usa mais do que o excedente — sempre mantém 49 TRX disponíveis para cobrir eventuais taxas manuais ou situações inesperadas de rede. O cálculo é simples: surplus = int(saldo) - 49. Se der zero ou negativo, nenhum stake é feito.

Delta mínimo de score (+3 pontos)

Uma troca de SR só acontece se o novo SR for pelo menos 3 pontos melhor no score composto. Isso evita que o motor fique rotacionando SRs por diferenças insignificantes que não representam ganho real de APR.

Limpeza automática de logs

Cada workflow inclui um step final que deleta execuções antigas do GitHub Actions — mantém o histórico limpo e dentro dos limites de armazenamento do GitHub.