Como criar um frontend web para Smart Contract com ReactJS (Ethers)

Revisado em 09/03/23!

Smart Contracts são algoritmos que rodam em cima da blokchain da Ethereum e compatíveis. Através de programação usando a linguagem Solidity é possível fazer pagamentos usando cripto, criar protocolos DeFi, salvar dados na blockchain, transferir a propriedade de NFTs e muito mais. Explorei a linguagem Solidity e a criação de Smart Contracts neste outro tutorial aqui do blog.

No entanto, Smart Contracts são como se fossem o backend da Web3: eles não possuem qualquer interface gráfica para que os usuários possam interagir com eles, como se fossem web APIs, entende?

Se você quer que usuários comuns consigam usar dos recursos da sua aplicação é necessário que você forneça alguma maneira simples e visual deles interagirem com o mesmo, criar uma aplicação de fato e não apenas um contrato. A estas aplicações que se conectam a smart contracts nós chamamos de dapps, ou decentralized applications (aplicações descentralizadas).

Você pode criar um dapp com qualquer tecnologia, mas quando o assunto é dapps web não vai conseguir fugir de JavaScript. E ainda no espectro do JavaScript existem muitas opções de tecnologias, sendo que a que recomendo utilizar é a ReactJS, que já apresentei em mais detalhes em outros tutoriais aqui do blog.

Então neste tutorial eu vou te mostrar como você pode criar uma aplicação ReactJS muito simples que servirá de interface para um smart contract bem simples também, que eu já publiquei na blockchain da Binance (BSC) em outra oportunidade. Apesar de estar nesta blockchain, qualquer blockchain compatível com Ethereum vai funcionar da mesma forma. Este tutorial vai usar a lib EthersJS, caso esteja procurando tutorial com a lib Web3.js, use este aqui.

Se preferir, pode acompanhar este mesmo conteúdo com o vídeo abaixo.

Vamos lá!

#1 – Estruturando o Projeto

O link do smart contract que vamos usar é este aqui e ele está publicado na Testnet. Recomendo que dê uma olhada nele e faça alguns testes pelo painel do BSC Scan mesmo (link que forneci), a fim de entender do que se trata, embora te adianto que não tem nada de incrível, é apenas um CRUD de informações na blockchain.

Para fazer as operações de leitura você não precisará de nenhum tipo de autenticação, mas para conseguir fazer as operações de escrita você precisará pagar as taxas da rede (mesmo sendo rede de teste) e portanto estar conectado no BSC Scan com uma carteira de criptomoedas, sendo que a que recomendo é a MetaMask, que ensino a criar e configurar para testes no vídeo abaixo.

Ainda falando do smart contract, no link que passei antes, se você for na aba Contract, seção Code, encontrará o código fonte do mesmo e outra informação que precisamos para nossa integração, o ABI. ABI é uma sigla para Application Binary Interface (Interface de Aplicação Binária), algo como uma especificação de como este contrato deve ser invocado, caso queira consumir suas funções. Copie este ABI para um arquivo abi.json (o qual eu reproduzo abaixo), vamos precisar dele mais tarde.

[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"customer","type":"tuple"}],"name":"addCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"count","outputs":[{"internalType":"uint32","name":"","type":"uint32"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"","type":"uint32"}],"name":"customers","outputs":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"},{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"newCustomer","type":"tuple"}],"name":"editCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"}],"name":"getCustomer","outputs":[{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"","type":"tuple"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"}],"name":"removeCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"}]

[{"inputs":[],"stateMutability":"nonpayable","type":"constructor"},{"inputs":[{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"customer","type":"tuple"}],"name":"addCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[],"name":"count","outputs":[{"internalType":"uint32","name":"","type":"uint32"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"","type":"uint32"}],"name":"customers","outputs":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"},{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"newCustomer","type":"tuple"}],"name":"editCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"}],"name":"getCustomer","outputs":[{"components":[{"internalType":"string","name":"name","type":"string"},{"internalType":"uint8","name":"age","type":"uint8"}],"internalType":"struct StoreCustomers.Customer","name":"","type":"tuple"}],"stateMutability":"view","type":"function"},{"inputs":[{"internalType":"uint32","name":"id","type":"uint32"}],"name":"removeCustomer","outputs":[],"stateMutability":"nonpayable","type":"function"}]

Agora que temos o smart contract que vamos usar, pegamos o ABI dele e estamos com a MetaMask instalada e configurada para a mesma rede (Testnet da BSC), é hora de criarmos nossa aplicação React. Para isso vamos usar o utilitário create-react-app, como abaixo.

npx create-react-app dapp-react

1	npx create-react-app dapp-react

Para se certificar de que foi criado corretamente, rode o projeto com npm start antes de avançar e veja se funciona.

Agora certifique-se de guardar o seu arquivo abi.json na raiz da sua aplicação React e instale também a dependência que vamos usar para comunicação com a blockchain através da carteira MetaMask, o pacote Ethers.

npm i ethers

1	npm i ethers

#2 – Operação de Leitura

Em nosso projeto React vamos implementar a interface de apenas duas operações, a pesquisa de um cadastro e a inserção de um novo. Com base nestas duas operações, uma de leitura e outra de escrita, você terá a base necessária para avançar em outras operações e até mesmo usando outros contratos.

Para a operação de leitura devemos criar uma interface em nosso App.js que espere receber o ID de um customer cadastrado no respectivo contrato e um botão para fazer a pesquisa por ele, como abaixo.

import { useState } from 'react';
import { ethers } from 'ethers';
import ABI from './abi.json';
import './App.css';

function App() {

  const [customerId, setCustomerId] = useState("0");
  const [error, setError] = useState("");

  function onSearchClick() {
    console.log(customerId);
  }

  return (
    <div className="App">
      <header className="App-header">
        <p>
          <label>Customer ID: <input type="number" value={customerId} onChange={(evt) => setCustomerId(evt.target.value)} /></label>
        </p>
        <p>
          <input type="button" value="Search" onClick={onSearchClick} />
        </p>
        <p style="color:red;">
          {error}
        </p>
      </header>
    </div>
  );
}

export default App;

import { useState } from 'react';

import { ethers } from 'ethers';

import ABI from './abi.json';

import './App.css';

function App() {

const [customerId, setCustomerId] = useState("0");

const [error, setError] = useState("");

function onSearchClick() {

console.log(customerId);

}

return (

<p>

<label>Customer ID: <input type="number" value={customerId} onChange={(evt) => setCustomerId(evt.target.value)} /></label>

</p>

<p>

</p>

{error}

</p>

</header>

</div>

);

}

export default App;

Repare que já adicionei todos os imports que vamos usar no topo do arquivo (incluindo o ABI) e os states de controle do botão e das mensagens de erro, respectivamente. Também já deixei posicionada uma função para o click do botão e que por enquanto serve apenas para lhe ajudar a testar no console do navegador se está funcionando tudo como deveria até o momento.

Assim que estiver com esta primeira parte do frontend concluída, é hora de fazermos o seu comportamento de fato. Para isso, vamos criar uma função doSearch que vai se conectar em nossa carteira, configurar o contrato com o qual vamos nos comunicar e fazer a chamada na blockchain.

const CONTRACT_ADDRESS = "0xE9956c971B72aD74F249E616828df613F03E858b";

async function doSearch() {
  if (!window.ethereum) return setError(`No MetaMask found!`);

  const provider = new ethers.BrowserProvider(window.ethereum);

  const accounts = await provider.send("eth_requestAccounts", []);
  if (!accounts || !accounts.length) return setError('Wallet not found/allowed!');

  try {
    const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);
    const customer = await contract.getCustomer(customerId);
    alert(JSON.stringify(customer));
  } catch (err) {
    setError(err.message);
  }
}

function onSearchClick() {
  setError('');
  doSearch();
}

const CONTRACT_ADDRESS = "0xE9956c971B72aD74F249E616828df613F03E858b";

async function doSearch() {

if (!window.ethereum) return setError(`No MetaMask found!`);

const provider = new ethers.BrowserProvider(window.ethereum);

const accounts = await provider.send("eth_requestAccounts", []);

if (!accounts || !accounts.length) return setError('Wallet not found/allowed!');

try {

const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

const customer = await contract.getCustomer(customerId);

alert(JSON.stringify(customer));

} catch (err) {

setError(err.message);

}

function onSearchClick() {

setError('');

doSearch();

}

Aqui valem uma série de explicações.

Primeiro, eu defini uma constante para guardar o endereço do nosso contrato na blockchain. Você pega isso facilmente quando publica o seu contrato ou consultando ele no explorer da sua blockchain (BSC Scan no nosso caso).

Segundo, nossa função doSearch começa verificando se tem uma carteira instalada no seu browser, retornando erro caso contrário. Se tiver, usaremos o objeto window.ethereum (que é injetado no browser pela MetaMask) para configurar nosso provider. Um provider é a configuração de conexão com a blockchain. Até a versão 5 do ethers usávamos Web3Provider, agora ele se chama BrowserProvider (ethers 6).

Agora, com este provider nós enviamos um comando eth_requestAccounts que serve para pedir permissão à carteira para conversar com a blockchain. Isso vai fazer a sua MetaMask abrir no navegador e pedir a sua permissão. Uma vez dada esta permissão para a aplicação, ela não precisa mais ser concedida.

Tendo a permissão para conexão, é hora de configurarmos qual contrato vamos conversar. Fazemos isso declarando um novo Contract e informando em seu construtor o endereço, o ABI e a carteira/provider devidamente autorizada.

Com o contrato configurado, podemos chamar funções JavaScript para cada uma das funções presentes no ABI do smart contract, sendo que aqui estamos chamando a função getCustomer que, segundo o ABI, espera um customerId por parâmetro e devolve um objeto customer.

Se você testar, verá que já funciona normalmente.

E com isso concluímos a primeira funcionalidade do nosso dapp.

#3 – Operação de Escrita

A próxima funcionalidade que vamos adicionar no nosso dapp é de cadastrar novos dados na blockchain usando aquele mesmo smart contract de antes. Para isso teremos um processo relativamente semelhante, motivo pelo qual eu vou extrair parte do código anterior para uma nova função, a fim de podermos reaproveitar o máximo possível.

async function getProvider() {
  if (!window.ethereum) throw new Error(`No MetaMask found!`);

  const provider = new ethers.BrowserProvider(window.ethereum);

  const accounts = await provider.send("eth_requestAccounts", []);
  if (!accounts || !accounts.length) throw new Error('Wallet not found/allowed!');
  return provider;
}

async function doSearch() {
  try {
    const provider = await getProvider();
    const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);
    const customer = await contract.getCustomer(customerId);
    alert(JSON.stringify(customer));
  } catch (err) {
    setError(err.message);
  }
}

async function getProvider() {

if (!window.ethereum) throw new Error(`No MetaMask found!`);

const provider = new ethers.BrowserProvider(window.ethereum);

const accounts = await provider.send("eth_requestAccounts", []);

if (!accounts || !accounts.length) throw new Error('Wallet not found/allowed!');

return provider;

}

async function doSearch() {

try {

const provider = await getProvider();

const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

const customer = await contract.getCustomer(customerId);

alert(JSON.stringify(customer));

} catch (err) {

setError(err.message);

}

Agora, vamos personalizar o nosso frontend adicionando mais algumas tags HTML para criar um rápido formulário abaixo do anterior. Repare que vou adicionar os novos states e a nova função de save bem no início.

const [name, setName] = useState("");
const [age, setAge] = useState("");

function onSaveClick(){
  console.log({name, age});
}

return (
  <div className="App">
    <header className="App-header">
      <p>
        <label>Customer ID: <input type="number" value={customerId} onChange={(evt) => setCustomerId(evt.target.value)} /></label>
      </p>
      <p>
        <input type="button" value="Search" onClick={onSearchClick} />
      </p>
      <hr />
      <p>
        <label>Name: <input type="text" value={name} onChange={(evt) => setName(evt.target.value)} /></label>
      </p>
      <p>
        <label>Age: <input type="number" value={age} onChange={(evt) => setAge(evt.target.value)} /></label>
      </p>
      <p>
        <input type="button" value="Save" onClick={onSaveClick} />
      </p>
      <p>
        {error}
      </p>
    </header>
  </div>
);

const [name, setName] = useState("");

const [age, setAge] = useState("");

function onSaveClick(){

console.log({name, age});

}

return (

<p>

<label>Customer ID: <input type="number" value={customerId} onChange={(evt) => setCustomerId(evt.target.value)} /></label>

</p>

<p>

</p>

<hr />

<p>

<label>Name: <input type="text" value={name} onChange={(evt) => setName(evt.target.value)} /></label>

</p>

<p>

<label>Age: <input type="number" value={age} onChange={(evt) => setAge(evt.target.value)} /></label>

</p>

<p>

</p>

<p>

{error}

</p>

</header>

</div>

);

Agora a programação do salvamento se torna bem simples pois já deixamos quase tudo pronto nas funções anteriores, mas ao invés de usar o objeto simples de contrato, agora precisamos de um objeto um pouco mais complexo, com permissão de assinatura, o que chamamos de contract signer.

async function getContractSigner() {
  const provider = await getProvider();
  const signer = await provider.getSigner();
  const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);
  return contract.connect(signer);
}

async function doSave() {
  try {
    const contract = await getContractSigner();
    const tx = await contract.addCustomer({ name, age });
    alert(JSON.stringify(tx));
  } catch (err) {
    setError(err.message);
  }
}

async function getContractSigner() {

const provider = await getProvider();

const signer = await provider.getSigner();

const contract = new ethers.Contract(CONTRACT_ADDRESS, ABI, provider);

return contract.connect(signer);

}

async function doSave() {

try {

const contract = await getContractSigner();

const tx = await contract.addCustomer({ name, age });

alert(JSON.stringify(tx));

} catch (err) {

setError(err.message);

}

O signer é basicamente uma autorização para gastar fundos. Quando chamamos getSigner ativamos a carteira MetaMask do usuário que pedir o consentimento do mesmo no navegador, pois toda transação envolve custos, pagos com o saldo do usuário na moeda da rede (ETH na Ethereum, BNB na BSC, etc).

Uma vez que o usuário autorize a transação, podemos fazer a conexão de fato no contrato, mas agora autenticados e fazer a chamada à função que desejamos invocar, addCustomer neste caso.

Como retorno você terá um objeto de transação, cujo hash é a única informação que nos importa no momento.

E com isso agora você sabe como implementar chamadas de leitura e de escrita em qualquer smart contract de blockchains compatíveis com a EVM (Ethereum Virtual Machine). Caso queira aprender a criar smart contracts, este tutorial pode te ajudar.

Quer aprender a fazer deploy desse dapp na rede IPFS? Confira no vídeo abaixo.