Integração com Smart Contracts com Node.js e Viem

A web3 está aí e cada vez mais as empresas estão querendo criar funcionalidades e até sistemas inteiros baseados na blockchain. Desta forma, para acompanhar esta tendência é importante que os programadores aprendam como implementar isto e felizmente a esta altura já existem muitas formas de fazer este tipo de integração, em especial com as blockchains baseadas em Ethereum ou EVM-compatible.

No tutorial de hoje eu vou ensinar como escrever aplicações Node.js que se conectam à blockchain e interagem com smart contratcs, fazendo consultas e transações neles. Não é imprescindível o conhecimento de smart contracts para implementar os exemplos de código, mas ajuda bastante, então deixo abaixo um vídeo sobre o assunto.

E se você já fez outro tutorial sobre integração com blockchain aqui no blog recentemente, pode aproveitar o mesmo projeto, mas não pule a parte de setup, dá uma revisada completa nela porque veremos algumas coisas novas aqui. Se não fez o outro tutorial e não sabe do que estou falando, não se preocupe, apenas segue o passo a passo abaixo que não tem erro.

Então vamos lá!

#1 – Setup

Neste tutorial vamos usar Node.js e ele não é indicado para quem nunca programou Node.js na vida. Inclusive você precisa ter esta ferramenta já instalada na sua máquina antes de começar. No vídeo abaixo ensino como instalar Node.js e VS Code, a ferramenta que uso para programar.

Depois de ter o Node.js instalado na sua máquina, o próximo passo é ter uma carteira de criptomoedas, já que para se comunicar com a blockchain é obrigatório ter uma. Como vamos programar para blockchains Ethereum, tem de ser uma carteira compatível com a mesma e eu recomendo a MetaMask. O vídeo abaixo ensina o que é e como criar a sua, gratuitamente.

A MetaMask vem por padrão configurada para a rede Mainnet da Ethereum, o que não é muito indicado para desenvolvimento. Indo no select de redes no topo dela você pode usar a opção “mostrar redes de teste” e habilitar o aparecimento da rede Sepolia, usada para testes e que vamos usar aqui. Mesmo sendo uma rede de testes você vai precisar de saldo em ETH para poder fazer transações para ela, então recomendo que use este Faucet PoW para ganhar algumas moedas. Basta conectar a sua carteira, colocar a minerar e em minutos terá saldo para usar na rede Sepolia. Caso tenha problemas com a Sepolia, outra opção é usar a BSC Testnet da Binance, que no vídeo que passei acima eu ensino a configurar na MetaMask ou qualquer outra rede compatível com EVM (Avalanche, Polygon, etc).

Para que nosso script possa assinar transações usando a sua carteira ele vai precisar da chave privada dela. Para obtê-la vá na MetaMask, acesse sua conta no canto superior esquerdo, depois nas reticências escolha Detalhes da Conta, como mostra a imagem abaixo, indo na opção “Private Keys”. Guarde a chave privada da rede Ethereum em um lugar seguro, vamos precisar dela logo mais.

Agora sim, temos todo o necessário para começar a programar, então vamos criar nosso projeto. Crie na sua máquina uma pasta viem-node e dentro dela rode o comando para inicialização do projeto.

Com o projeto inicializado, vamos instalar e inicializar o TypeScript na pasta e o TS-Node, pois a biblioteca que vamos usar a seguir é muito mais poderosa com ele.

Para que os types do Node que instalamos sejam interpretados corretamente, é importante ir no tsconfig.json e ajustar a seção types para inclui-los. Incluo abaixo outras configurações importantes que provavelmente você terá de ajustar a fim de obter os mesmos resultados com o tutorial.

Com o projeto inicializado, vamos instalar as dependências que usaremos.

O dotenv é para guardarmos as configurações de ambiente, enquanto que o Viem é o módulo que usaremos para comunicação com a blockchain. Ele nada mais faz do que abstrai todas as chamadas ao node RPC da blockchain que vamos nos conectar, facilitando toda a comunicação da nossa aplicação com o mesmo, já que usaremos boas e velhas funções JS. Mais que isso, ele infere tipos de uma maneira extremamente poderosa, sendo o seu maior trunfo frente às bibliotecas concorrentes no âmbito de web3.

Para configurar nossas variáveis de ambiente, crie um arquivo .env na raiz da aplicação e nele coloque as seguintes variáveis.

Atenção com a private key da sua carteira MetaMask: jamais informe ela, para ninguém. Também não versione esse arquivo .env, certifique-se de colocá-lo no seu .gitignore se estiver usando Git.

Agora ajuste no seu package.json para inicializar o projeto usando ts-node, para evitar a etapa de transpilação durante o desenvolvimento e ajuste o type do projeto também para suporte a sintaxe mais moderna do JS/TS.

Crie um index.ts em uma pasta src na raiz do projeto e teste um olá mundo com npm start para garantir que está tudo funcionando.

Agora terminamos o setup e podemos começar a programar.

#2 – Calls em Smart Contracts

Existem dois tipos de interações que você pode fazer com smart contracts: as calls e os sends.

As calls são chamadas somente de leitura, para pedir informações a um contrato como por exemplo o saldo de um token ou uma pesquisa. Já as sends são transações, ou seja, operações que escrevem novos dados na blockchain e portanto possuem taxas associadas para pagar o trabalho dos mineradores. Sim, enquanto calls são instantâneos, como se fossem chamadas GET de APIs, sends exigem mineração para registrar os novos dados.

A primeira coisa que você deve aprender é como fazer calls em contratos e depois como fazer sends/transacionar em contratos. Caso você possua algum smart contract publicado, pode usar ele, caso contrário use este meu aqui que é um exemplo de token ERC-20 (tutorial aqui) que você confere tudo que ele faz na aba contract do EtherScan. Para chamar este meu contrato ou qualquer outro, você precisa ter acesso ao ABI do contrato, a Application Binary Interface: um array JSON com objetos explicando todas as chamadas públicas que podem ser feitas, com seus parâmetros e retornos. Este ABI é necessário para que as bibliotecas consigam fazer as requests corretamente ao servidor RPC e se foi você que fez o deploy, tem acesso à API na pasta da compilação do seu contrato. Se não foi você, muitas vezes ele está disponível no EtherScan, que é o meu caso e que reproduzo abaixo o ABI para você.

Se for usar o meu contrato, pegue este ABI acima e coloque em um arquivo abi.json na pasta src do seu projeto. Além do ABI, a segunda configuração que será necessária é o endereço do seu contrato na variável CONTRACT_ADDRESS do .env, certifique-se de ter preenchido. Caso esteja usando o meu contrato, segue o endereço dele na Sepolia.

Para começarmos a programar, crie um arquivo index.ts na pasta src na raiz da sua aplicação e vamos começar importando as bibliotecas que precisamos e inicializando alguns objetos.

Aqui eu importei e configurei o dotenv, que vai carregar todas nossas variáveis de ambiente contidas no arquivo .env para a memória. Depois importei as funções e objetos do Viem que vamos precisar e por último importei o ABI a partir do arquivo JSON, usaremos ele mais tarde nas chamadas. Aquela tipagem ali do JSON é exigência do TypeScript e a rede que estou usando (Sepolia) pode ser substituída por qualquer outra EVM.

Essa configuração inicial é suficiente para fazer chamadas/calls, ou seja, operações apenas de leitura. Mais à frente vou falar da diferença para sends/transações.

Meu contrato é de um novo token ERC-20 chamado RSCoin, ele possui as operações padrões para tokens o que inclui chamadas para ver o saldo em frações de RSCoins. Primeiro, vamos criar rapidamente a função que pega e imprime o saldo de uma carteira que possua este token no console, como abaixo.

No exemplo acima eu criei um cliente público (somente leitura) com a blockchain Sepolia via HTTP. Com esse client eu posso enviar calls para a blockchain, incluindo funções de leitura em smart contracts, desde que eu tenha o ABI e endereço do mesmo, usando a função readContract.  Além dos dados de acesso ao contrato, ela vai pedir o nome da função que deseja chamar (functionName) e um array de parâmetros da função (args), sendo que neste caso é apenas um: o endereço a carteira a ser consultada.

A última linha é apenas para chamar a função quando rodarmos a aplicação e optei por passar a nossa carteira configurada no .env por parâmetro. O resultado deve ser a impressão do seu saldo em RSC (ou a moeda do contrato que usou). Confirme olhando na sua carteira cripto se veio corretamente.

Agora vamos fazer algo mais elaborado, uma transação!

#3 – Sends/Transactions em Smart Contracts

Além de calls, outra tarefa muito recorrente é a necessidade de fazer sends em contratos. Isso porque todas as funções de um contrato que exijam a escrita de dados na blockchain exige que você envie e pague por uma transação. Como estamos em uma rede ETH, as taxas de transação são sempre em ETH e para que uma transferência ocorra é necessário enviar uma transação para a rede, assinada pela carteira que vai invocar a função de escrita.

Se estiver usando o meu contrato de exemplo, tem algumas funções que podemos usar mesmo que você não tenha saldo em RSC (a moeda que inventei). Uma delas é a função approve que serve para você fornecer autorização para outra conta transferir RSCs da sua carteira, o que chamamos de transferência delegada. Se você não entende nada de tokens ERC-20, não se preocupe, é uma função inofensiva pois estamos falando de um token fictício (RSC).

Vamos criar a nossa função approvePrcTransfer no index.js, como abaixo, logo após alguns imports adicionais necessários. Esta função é diferente da anterior pois parte da complexidade é a autenticação, que é a primeira coisa que resolvemos aqui carregando chave privada e com ela gerando um objeto account e aqui vai um truque: a string da private key deve ser hexa, ou seja, iniciada em 0x, mas quando você copia da MetaMask geralmente vem sem o 0x na frente, por isso o ajuste que fiz ali..

Com essa account, mais as informações da rede (chain) e do nó RPC que vamos usar (transport), podemos inicializar um objeto do tipo wallet client. Diferente dos public clients, que somente fazem operações de leitura, os wallet clients são a forma como fazemos transações (operações de escrita) na blockchain com a biblioteca Viem. Essa é uma característica bem marcante dessa biblioteca, ter clientes distintos para leituras e escritas.

Na linha seguinte, chamamos a função writeContract do client e com ela montamos a nossa transação com os mesmos parâmetros que já aprendemos a usar antes, mas agora chamando a função approve do contrato e passando os dois argumentos que ela espera (a carteira spender e o valor a ser aprovado). Como retorno temos o hash da transação, para conferência no block explorer. Um exemplo de transação realizada com o código acima pode ser vista aqui.

E com isso você aprendeu como fazer calls e sends em smart contracts existentes na blockchain usando Node.js e a biblioteca Viem, com uma ajudinha da MetaMask.

Até o próximo tutorial!