Manual do Usuário

Sobre o Smart Agro Cost

O Smart Agro Cost é uma plataforma que cruza dados do Censo Agropecuário IBGE com custos de transação em blockchain para simular a viabilidade de adoção de contratos inteligentes no agronegócio brasileiro.

Público-alvo: Pesquisadores, estudantes, produtores rurais, empresas de tecnologia agro e tomadores de decisão interessados em rastreabilidade agropecuária.

Ferramentas Disponíveis

Clique em qualquer ferramenta abaixo para navegar diretamente para a explicação detalhada.

1. Indicadores IBGE

Funcionalidade: Ferramenta de visualização e análise dos dados do Censo Agropecuário do IBGE.

🎯 O que esta ferramenta faz?

• Exibe gráficos de valor de vendas por produto
• Mostra distribuição de estabelecimentos por produto
• Permite comparar diferentes classificações (Agricultura, Pecuária, etc.)
• Visualização combinada (valor de vendas vs estabelecimentos)

⚙️ Como usar:

1. Selecione a região desejada (Brasil, Sul, RS ou Alegrete)
2. Escolha a classificação e subclassificação (opcional)
3. Defina se é estabelecimento familiar ou não
4. Marque INC 02/2018 se quiser apenas produtos obrigatórios à rastreabilidade (apenas agricultura)
5. Use Top N para limitar a quantidade de produtos exibidos
6. Clique em "Atualizar Dashboard"

📊 O que significam os gráficos?

• Gráfico de barras/linhas: Mostra a concentração de vendas por produto
• Cores diferentes: Valor de vendas (azul) vs Estabelecimentos (verde)

2. Implementação Rápida (Modo Automático)

Funcionalidade: Ferramenta para deploy automático de contratos inteligentes com execução sequencial.

🎯 Quando usar?

• Contratos simples que não exigem argumentos complexos
• Testes iniciais para entender o fluxo de execução
• Quando você quer uma estimativa rápida de custos

⚙️ Como usar:

1. Escolha o contrato que deseja testar
2. Clique em "Analisar Contrato"
3. Acompanhe a execução sequencial de todas as funções do contrato

📝 O que acontece nos bastidores?

• O sistema cria argumentos fictícios para as funções
• Executa cada função em sequência
• Registra o custo de gas de cada transação
• Apresenta o custo total em BRL

🔧 Exemplo prático - Teste com um contrato real:

1. Baixe o contrato de exemplo: contrato.sol (contrato com funções de exemplo)
   Clique no link acima e copie o conteúdo ou faça download do arquivo contrato.sol
2. Carregue na ferramenta: Clique para selecionar o arquivo baixado
3. Visualize o custo das funções:
   • setNome(string) - Altera o nome do produto
   • setPreco(uint256) - Altera o preço do produto

3. Implementação Controlada (Modo Iterativo)

Funcionalidade: Ferramenta para execução manual de funções de contratos inteligentes com controle total sobre argumentos e parâmetros.

🎯 Quando usar?

• Contratos complexos com funções interdependentes
• Quando você precisa testar argumentos específicos (endereços, valores, strings)
• Para simular fluxos reais de negócio com dados reais
• Quando quer controlar quantas vezes cada função será executada

⚙️ Como usar - Passo a passo:

1. Carregar o contrato: Selecione o arquivo .sol do contrato Smart Contract
2. Definir a cotação: Selecione o período para cálculo dos custos:
   • Última Cotação: Preço mais recente registrado
   • Média Últimas 24h: Preço médio das últimas 24 horas
   • Média Última Semana: Preço médio dos últimos 7 dias
   • Média Último Mês: Preço médio dos últimos 30 dias
   • Média Histórica: Preço médio de todo o período disponível
3. Clicar em Carregar ABI do Contrato:
4. Verificar status: Confira se o contrato já está "Deployado" ou "Não Deployado"
5. Escolher o contrato: Na lista "Contratos Disponíveis", selecione o contrato desejado (um arquivo pode ter múltiplos contratos)
6. Preencher argumentos: Para cada função, informe os argumentos necessários:
   • Use o botão "Auto-preenchimento" para gerar valores automáticos
   • Ou digite manualmente os valores desejados
7. Definir execuções: No campo ao lado do botão "Executar", defina quantas vezes a função será repetida (ex: 1, 10, 1000)
8. Executar: Clique em "Executar Função" para iniciar a transação
9. Acompanhar: Observe os resultados no painel de logs à direita

📊 Entendendo os resultados no painel de logs:

• ✅ Função executada: Nome da função que foi chamada
• ⛽ Gas estimado: Quantidade de gas prevista para uma execução
• 🔥 Gas real usado: Gas efetivamente consumido no total da transação
• 🌍 Custos por rede: Detalhamento do custo em:
  • Token nativo: ETH, BNB, MATIC, etc.
  • USD: Valor em dólares americanos
  • BRL: Valor em reais brasileiros
  • Gas price: Preço unitário do gas no momento da execução (na criptomoeda correspondente)

🛠️ Funcionalidades especiais:

• Pré-preencher todas as funções: Botão no cabeçalho da seção de funções que preenche automaticamente TODOS os argumentos de TODAS as funções
• Auto-preenchimento individual: Cada função tem seu próprio botão "Auto-preenchimento" para gerar valores compatíveis com o tipo do argumento
• Execução repetida: Simule execuções em massa (ex: 10.000 propriedades rurais) ajustando o número de repetições
• Limpar/Copiar logs: Botões no painel direito para gerenciar o histórico de execuções

🔧 Exemplo prático - Teste com um contrato real:

1. Baixe o contrato de exemplo: multi.sol (contrato com funções de exemplo)
   Clique no link acima e copie o conteúdo ou faça download do arquivo multi.sol
Este contrato contém duas classes:
• TestAddresses - Funções para gerenciar owner e admin
• Produto3 - Funções para gerenciar nome e preço de produtos
2. Carregue na ferramenta: Use o botão "Selecione arquivo .sol" e escolha o arquivo baixado
3. Selecione um contrato: Escolha Produto3 ou TestAddresses na lista suspensa
4. Teste as funções:
   • setNome(string) - Altere o nome do produto
   • setPreco(uint256) - Altere o preço do produto
   • transferOwnership(address) - Transfere a propriedade do contrato
5. Simule adoção em larga escala: Defina "execuções = 1000" para ver o custo total de 1.000 transações

4. Simulação de Adoção

Funcionalidade: Ferramenta principal que cruza custos de transação blockchain com dados do Censo Agropecuário IBGE para estimar viabilidade de adoção em larga escala.

🎯 Cenários de uso:

• Políticas públicas: Estimar custo de implementar rastreabilidade obrigatória
• Cooperativas: Avaliar viabilidade de adotar blockchain para toda a base
• Pesquisa acadêmica: Comparar custos entre diferentes culturas e regiões
• Empresas de tecnologia: Identificar produtos com maior potencial de adoção

⚙️ Como usar - Passo a passo completo:

📁 BLOCO 1: Dados de Origem (Censo Agropecuário)

1. Região: Selecione Brasil (total), Sul, Rio Grande do Sul ou Alegrete (município)
2. Classificação/Subclassificação: Filtre por Agricultura, Pecuária, etc.
3. Base de Cálculo: Escolha entre:
   • 📊 Por Nº de Estabelecimentos: Cada propriedade rural = 1 unidade rastreável
   • 📦 Por Produção (Quantidade): Cada unidade de medida (tonelada, cabeça, saca) = 1 unidade rastreável

🔗 BLOCO 2: Configuração do Contrato

1. Contrato: Selecione o contrato inteligente deployado
2. Rede Blockchain: Escolha entre Ethereum, BNB Chain, Polygon ou Avalanche
3. Tipo de Produtor: Marque "👨‍🌾 Somente Agricultura Familiar" se desejar
4. Regulamentação: Marque "📜 Somente Obrigatório INC 02/2018" para produtos com rastreabilidade obrigatória (somente agricultura)

⚙️ BLOCO 3: Parâmetros da Simulação

1. Período de Custo: Defina qual base de preços usar:
   • ⚡ Última Execução: Preço mais recente registrado
   • 📅 Média das últimas 24h: Preço médio do dia
   • 📆 Média da última semana: Preço médio semanal
   • 📆 Média do último mês: Preço médio mensal
   • 🕰️ Média histórica (all-time): Preço médio de todo período
   • 🎯 Período personalizado: Selecione datas específicas (aparecem campos adicionais)
2. Ordenar por: Escolha como classificar os resultados:
   • 💰 Total Estimado (BRL): Produtos com maior custo blockchain
   • 💵 Valor Vendido (BRL): Produtos com maior faturamento
   • 🏠 Nº de Estabelecimentos: Produtos com mais propriedades
3. Top N Produtos: Limite a quantidade exibida (ex: 10 = só os 10 maiores)

🔧 BLOCO 4: Funções do Contrato para Simular

1. Selecione as funções que deseja executar (checkboxes)
2. Para cada função, defina quantas execuções repetidas (ex: 1 = uma transação, 1000 = mil transações)
3. Use "✅ Selecionar todas" ou "❌ Desmarcar todas" para agilizar

📊 Executar e analisar resultados:

1. Clique em "Gerar Simulação"
2. Aguarde o processamento (2-10 segundos)
3. Analise os cards de estatísticas no topo
4. Explore o gráfico e a tabela detalhada
5. Use "Exportar CSV" ou "Imprimir" para salvar resultados

📊 Entendendo os resultados:

📈 Cards de estatísticas:

• Total Estimado: Soma do custo blockchain para todos os produtos da região
• Produtos Analisados: Quantos produtos diferentes estão nos resultados
• Custo Médio por Rastreio: Custo para cada estabelecimento ou produção
• Cenário Simulado: Nome do contrato utilizado
• Gás por Contrato: Total de gas consumido (por estabelecimento ou produção)

📋 Tabela detalhada:

• Produto: Nome da cultura/atividade agropecuária
• Custo Unitário de Rastreabilidade (BRL): Custo de UMA execução das funções selecionadas
• Estabelecimentos/Produção: Quantidade usada no cálculo (conforme base selecionada)
• Valor Vendido (BRL): Faturamento total do produto na região (fonte IBGE)
• Total Estimado (BRL): Custo blockchain multiplicado pela quantidade (ex: 2.000 propriedades × R$ 0,50)
• % Custo/Valor: Indicador de viabilidade

💡 Dicas específicas para esta ferramenta:

• Comece com "Brasil" e "Última Execução": Visão geral rápida antes de detalhar
• Compare redes diferentes: Execute a mesma simulação trocando apenas a rede blockchain
• Use "Top N = 10 ou 20": Gráficos ficam mais legíveis
• Teste "Familiar = Sim": Agricultura familiar pode ter diferentes perfis de produção
• Período personalizado: Útil para comparar custos antes/depois de eventos de mercado
• Exporte CSV: Ideal para análises adicionais em Excel/Planilhas

🔧 Exemplo prático - Rastreabilidade da produção de soja no RS:

1. Região: Rio Grande do Sul
2. Classificação: Agricultura → Lavouras temporárias
3. Base de Cálculo: Por Produção (toneladas)
4. Contrato: token_manager_1155.sol
5. Rede: Avalanche (mais barata) ou Ethereum (mais cara)
6. Funções: deploy[1], mintRootBatch[1], addStatus[5], splitBatch[5]
7. Período: Média última semana
8. Executar → Analisar % Custo/Valor da soja

5. Histórico de Custos

Funcionalidade: Ferramenta para comparar custos de transação entre diferentes redes blockchain ao longo do tempo, com dados reais de gas price e cotações.

🎯 Para que serve?

• Comparar redes: Ethereum vs BNB Chain vs Polygon vs Avalanche (e outras redes suportadas)
• Visualizar tendências: Identifique padrões de custo ao longo do tempo (horários mais baratos, dias da semana, etc.)
• Tomada de decisão: Escolha a rede mais adequada para seu caso de uso baseado em dados históricos reais
• Planejamento financeiro: Estime custos futuros baseado em médias históricas

⚙️ Como usar - Passo a passo:

🌐 1. Seleção de Redes Blockchain

• Marque os checkboxes das redes que deseja comparar
• Todas as redes ficam selecionadas por padrão ao carregar a página
• As cores das redes são geradas automaticamente para fácil identificação no gráfico
• Auto-atualização: Ao marcar/desmarcar uma rede, os dados recarregam automaticamente após 500ms

📅 2. Período de Análise

• 24 Horas: Dados das últimas 24 horas
• 7 Dias: Dados da última semana
• 30 Dias: Dados do último mês
• Todo Período: Todo o histórico disponível no banco de dados
• Personalizado: Selecione datas específicas (aparecem campos adicionais)
  • Após selecionar as datas, aguarde 500ms que os dados carregam automaticamente
  • Período considerado das 00:00 às 23:59:59 UTC

⛽ 3. Configuração de Gas

• Unidades de Gas por Transação: Defina quantas unidades de gas sua transação consome
• Valor padrão: 21.000 unidades (transferência simples em Ethereum)
• Exemplos:
  • Transferência simples: ~21.000 gas
  • Contrato complexo: 100.000 - 500.000 gas
  • Rastreabilidade de produto: ~150.000 - 300.000 gas
• Auto-atualização: Ao alterar o valor, os dados recarregam automaticamente após 800ms

🚀 4. Carregamento Automático

• Ao abrir a página, os dados carregam automaticamente com as configurações padrão
• Não é necessário clicar em "Atualizar Análise" manualmente (botão disponível como fallback)
• Todas as alterações nos filtros recarregam os dados automaticamente

📊 Entendendo os resultados:

📈 Gráfico de Evolução de Custos:

• Tipo de gráfico: Linha (padrão) ou Barras (use o botão "Alternar Gráfico")
• Cada cor: Representa uma rede blockchain diferente
• Eixo X: Data/Hora no formato UTC (Dia/Mês Hora:Minuto)
• Eixo Y: Custo da transação em BRL (já multiplicado pelas unidades de gas)
• Tooltip: Passe o mouse sobre qualquer ponto para ver:
  • Data e hora exata (UTC)
  • Custo exato da transação
• Zoom: Use Scroll do mouse para ampliar períodos específicos
• Download: Clique em "Baixar" para salvar o gráfico como imagem PNG

📊 Cards de Estatísticas Comparativas:

• Custo Médio: Preço médio da transação no período selecionado
• Mínimo: Menor custo registrado no período (identifica melhores momentos)
• Máximo: Maior custo registrado no período
• Último: Custo da transação mais recente registrada
• Cada rede tem seu próprio card com sua cor característica

📋 Tabela de Dados Históricos:

• Clique em "Mostrar Tabela" para visualizar os dados brutos
• Exibe os 50 registros mais recentes em ordem decrescente (mais novos primeiro)
• Colunas:
  • Rede: Blockchain utilizada
  • Data/Hora: Timestamp exato em UTC
  • Custo (BRL): Já multiplicado pelas unidades de gas definidas
  • Gas Units: Quantidade configurada
  • Gas Price (Gwei): Preço do gas no momento da coleta
• Exportar Dados: Botão no cabeçalho para baixar todos os dados em CSV

🔧 Exemplo prático - Escolhendo a melhor rede para rastreabilidade:

1. Deixe todas as redes selecionadas (Ethereum, BNB Chain, Polygon, Avalanche)
2. Defina Gas Units = 150.000 (estimativa para registrar um produto na blockchain)
3. Selecione período 7 Dias para ver a variação recente
4. Compare os cards de estatísticas:
   • Qual rede tem o MENOR custo médio?
   • Qual rede tem a MENOR variação (mínimo vs máximo)?
5. Use Zoom no gráfico para ver horários mais baratos
6. Exporte os dados em CSV para análise aprofundada em Excel
7. Desmarque Ethereum para melhor visualizar as demais

🛠️ Funcionalidades avançadas:

• Modo Claro/Escuro: Botão de lua/sol no cabeçalho para alternar o tema
• Auto-refresh completo: Todos os filtros (redes, período, gas units) atualizam automaticamente
• Dados em tempo real: Novas coletas de gas price são inseridas no banco a cada 15 minutos
• Suporte a múltiplas redes: Além das padrão, novas redes aparecem automaticamente ao serem adicionadas

Guia Rápido - Primeiros Passos

O Smart Agro Cost oferece 5 ferramentas diferentes. O fluxo básico de uso é:

• 1 Escolha a ferramenta desejada na página inicial (consulte cada seção deste manual para detalhes)
• 2 Configure os filtros específicos da ferramenta (região, redes, contratos, funções)
• 3 Execute a análise (botão "Gerar Simulação", "Atualizar Dashboard" ou "Executar Função")
• 4 Exporte resultados (CSV, PNG) para seus relatórios, se desejar

Entendendo os Resultados

Cada ferramenta apresenta resultados específicos. Abaixo os conceitos comuns:

📊 Simulação de Adoção / Indicadores IBGE:

• Total Estimado (BRL): Custo total de rastreabilidade para todos os estabelecimentos/produtos da região
• Custo Médio por Rastreio: Custo médio de uma execução de função na rede blockchain escolhida
• % Custo/Valor: Percentual do custo blockchain em relação ao valor de venda do produto

⛽ Histórico de Custos:

• Gráfico linha/barra: Evolução do custo por rede ao longo do tempo
• Cards de estatísticas: Média, mínimo, máximo e último valor por rede
• Tabela: Dados brutos com timestamp, gas price e custo em BRL

🔧 Implementação (Rápida/Controlada):

• Logs de execução: Status, gas usado, custo e retorno de cada função
• Custos por rede: Detalhamento em token nativo, USD e BRL

🎨 Indicadores de viabilidade (Simulação de Adoção):

Dicas e Boas Práticas

• Comece pelo Brasil / Todo Período: Tenha uma visão geral antes de detalhar
• Teste redes diferentes: Compare Ethereum vs Polygon vs BNB Chain - os custos variam muito!
• Use o filtro Top N: Para gráficos mais legíveis, limite a 10 ou 20 produtos
• Explore o histórico de custos: Identifique melhores horários e redes mais baratas
• Verifique produtos obrigatórios (INC 02/2018): Têm maior potencial de adoção
• Exporte seus resultados: Use CSV para análises avançadas em Excel/Planilhas
• Modo claro/escuro: No Histórico de Custos e Interface de Contratos, use o botão de lua/sol
• Auto-preenchimento: Na ferramenta de Implementação Controlada, use para gerar argumentos automaticamente

Perguntas Frequentes (FAQ)

Precisa de ajuda?

Se tiver dificuldades, sugestões ou encontrar algum problema, entre em contato:

• E-mail: fabiosilva@unipampa.edu.br
• Repositório: github.com/fabiosilva/agro-smart-cost