Adicionando automaticamente uma blockchain à MetaMask com Javascript

Esta é uma tradução de Bernardo Perelló. O artigo original em inglês de A.Ufano pode ser lido aqui.

Publicado 11/06/2022

ÍNDICE

1. - Detalhes necessários para importar uma rede no MetaMask
2. - Adicione uma blockchain à MetaMask com Javascript.
3. - MetaMask - códigos de erro RPC.
   • MetaMask - Erro de RPC: Nulo ou array esperado com pelo menos uma URL HTTPS de string válida.
   • MetaMask - Erro de RPC: Prefixo 0x esperado, não preenchido, String hexadecimal 'chainId' diferente de zero. Recebido: 122.
   • MetaMask - Erro de RPC: o ChainID retornado pela URL do RPC não corresponde.
4. - Exemplo da Web

Em um artigo anterior, expliquei como detectar e alterar a rede na MetaMask. Isso funciona muito bem se a blockchain à qual queremos nos conectar já estiver na configuração do MetaMask, mas se o usuário ainda não a tiver adicionado, isso falhará.

Neste artigo, vou explicar como criar um botão que adiciona automaticamente a blockchain que queremos à MetaMask, para que o usuário só precise clicar no botão e a MetaMask se conectará a ela.

Detalhes necessários para importar uma rede na MetaMask

Para adicionar automaticamente uma blockchain à MetaMask com Javascript, precisamos fornecer alguns detalhes:

1. ID da Chain: A ID única da rede. Você pode achar em Chainlist.
2. Nome da Chain: O nome no qual queremos salvar a blockchain.
3. URLs RPC: URL do nó da blockchain. Confira Chainstack para ter acesso gratuito a diversas blockchains.
4. Moeda nativa: que inclui nome, símbolo (2-6 caracteres) e número de casas decimais (18).
5. Explorer: A URL do explorer da blockchain. Opcional.

Por exemplo, os detalhes do Fuse são:

# Chain ID: 0x7a (which is 122)
# Name: Fuse Mainnet
# RPC URL: 'https://rpc.fuse.io'
# Currency name: FUSE
# Currency symbol: FUSE
# Currency decimals: 18
# Explorer: 'https://explorer.fuse.io/'

Adicione uma blockchain à MetaMask com Javascript

Assim que tivermos todos os detalhes da blockchain que queremos adicionar, podemos adicioná-la à MetaMask usando o método wallet_addEthereumChain. Em Parâmetros, precisaríamos passar todos os detalhes da rede conforme mostrado abaixo:

// Detalhes da blockchain FUSE
const chainId = '0x7a';
const rpcURL = 'https://rpc.fuse.io';
const networkName = 'Fuse Mainnet';
const currencyName = 'FUSE';
const currencySymbol = 'FUSE';
const explorerURL = 'https://explorer.fuse.io/';

const addNetwork = async () => {
  await window.ethereum.request({
    method: 'wallet_addEthereumChain',
    params: [
      {
        chainId: chainId,
        chainName: networkName,
        rpcUrls: [rpcURL],
        blockExplorerUrls: [explorerURL],
        nativeCurrency: {
          name: currencyName,
          symbol: currencySymbol, // 2-6 characters long
          decimals: 18,
        },
      },
    ],
  });
  // refresh
  window.location.reload();
};

MetaMask - Códigos de Erro RPC

MetaMask - Erro de RPC: Nulo ou array esperado com pelo menos uma URL HTTPS de string válida

{code: -32602, message: "Expected null or array with at least one valid str…ExplorerUrl'. Received: https://explorer.fuse.io/"}

Este erro ocorre quando estamos adicionando uma blockchain à MetaMask usando o wallet_addEthereumChain. Isso acontece porque estamos passando strings únicas como parâmetros no atributos rpcURLs ou blockExplorerUrls. Certifique-se de passar um array, mesmo que tenha apenas um único URL.

MetaMask - Erro de RPC: Prefixo 0x esperado, não preenchido, String hexadecimal 'chainId' diferente de zero. Recebido: 1222

{code: -32602, message: "Expected 0x-prefixed, unpadded, non-zero hexadecimal string 'chainId'. Received:\n122"}

Este erro ocorre quando estamos adicionando uma blockchain à MetaMask usando o método wallet_addEthereumChain. Acontece porque estamos passando o chainId como um inteiro em vez de usar uma string hexadecimal. Para transformar decimais em hexadecimais formatados em 0x, use esta ferramenta.

MetaMask - Erro RPC: O ChainID retornado pela URL do RPC não corresponde

{code: -32602, message: 'Chain ID returned by RPC URL https://rpc.fuse.io does not match 0x122', data: {chainId: '0x7a'}}

Este erro ocorre quando estamos adicionando uma blockchain à MetaMask usando o método wallet_addEthereumChain. Acontece porque o Chaind ID que estamos passando como parâmetro não corresponde ao Chaind ID retornado pela URL da RPC fornecida. Para corrigi-lo, basta alterar o Chaind ID com o retornado pelo rpc, que é mostrado na mensagem de erro, ou certifique-se de que a url do rpc corresponda à Chaind que você está adicionando.

Exemplo da Web

Aqui está um exemplo básico da web com um botão que aciona a MetaMask e adiciona a rede:

<!DOCTYPE html>
<html lang="en">
  <head>
    <meta charset="UTF-8" />
    <meta http-equiv="X-UA-Compatible" content="IE=edge" />
    <meta name="viewport" content="width=device-width, initial-scale=1.0" />
    <title>Adding blockchain to Metamask</title>
  </head>
  <body>
    <script>
      // Detalhes da blockchain FUSE
      const chainId = '0x7a';
      const rpcURL = 'https://rpc.fuse.io';
      const networkName = 'Fuse Mainnet';
      const currencyName = 'FUSE';
      const currencySymbol = 'FUSE';
      const explorerURL = 'https://explorer.fuse.io/';

      const addNetwork = async () => {
        if (!window.ethereum) {
          console.error('Metamask not detected');
          return;
        }
        await window.ethereum.request({
          method: 'wallet_addEthereumChain',
          params: [
            {
              chainId: chainId,
              chainName: networkName,
              rpcUrls: [rpcURL],
              blockExplorerUrls: [explorerURL],

              nativeCurrency: {
                name: currencyName,
                symbol: currencySymbol, // 2-6 characters long
                decimals: 18,
              },
            },
          ],
        });
        // refresh
        window.location.reload();
      };
    </script>
    <!-- The button  -->
    <button onClick="addNetwork()">Add Fuse</button>
  </body>
</html>