Ethers.js (biblioteca JavaScript)

O que é Ethers.js?

Ethers.js é uma biblioteca de código aberto para JavaScript e TypeScript usada para conectar aplicativos, carteiras, scripts e ferramentas de desenvolvimento à Ethereum e a outras redes blockchain compatíveis com EVM.

Ela oferece funções reutilizáveis para ler dados da blockchain, enviar transações, gerenciar contas, assinar mensagens, interagir com contratos inteligentes, decodificar logs de eventos e trabalhar com formatos de dados da Ethereum.

Em vez de criar manualmente cada solicitação JSON-RPC ou codificar cada chamada de contrato inteligente, o desenvolvedor pode usar objetos e métodos do ethers.js que cuidam de grande parte do trabalho técnico.

A documentação oficial do ethers.js descreve a biblioteca como uma ferramenta completa e compacta para interagir com a blockchain Ethereum e seu ecossistema.

Ethers.js é comumente usado em interfaces de aplicativos descentralizados, serviços de blockchain no servidor, carteiras de criptomoedas, sistemas automatizados de monitoramento, scripts de teste, ferramentas de pagamento e fluxos de implantação de contratos inteligentes.

A biblioteca não opera uma blockchain própria nem fornece consenso para a Ethereum.

Ela funciona como uma camada de software entre um aplicativo e um nó Ethereum, uma carteira ou um serviço RPC compatível.

Ethers.js é escrito em TypeScript e inclui declarações de tipo integradas, que podem ajudar os desenvolvedores a detectar determinados erros antes da execução de um aplicativo.

O projeto é distribuído sob a licença MIT e mantido em seu repositório público de código-fonte do ethers.js.

Qual é a versão atual do Ethers.js?

Em 16 de julho de 2026, a versão documentada mais recente é ethers v6.17.0.

O repositório oficial informa que a versão 6.17.0 foi lançada em 18 de junho de 2026.

A versão atual também pode ser consultada na página oficial do pacote ethers.

Os desenvolvedores devem verificar a versão atual antes de instalar a biblioteca, pois os lançamentos podem incluir correções de bugs, atualizações de rede, melhorias de segurança e suporte a novos protocolos.

Em geral, um projeto deve fixar a versão da dependência em um arquivo de lock de pacotes, para que os ambientes de desenvolvimento, teste e produção usem a mesma versão do pacote.

Instalar automaticamente uma versão futura desconhecida sem testá-la pode introduzir mudanças incompatíveis ou inesperadas nas dependências.

O que o Ethers.js faz?

Ethers.js oferece um conjunto de ferramentas para interagir com sistemas blockchain no estilo Ethereum.

Ele pode conectar um aplicativo a um nó Ethereum por meio de JSON-RPC, WebSocket ou da interface de uma carteira no navegador.

Também pode consultar saldos de contas, blocos, transações, dados de taxas, código de contratos inteligentes, logs de eventos e informações da rede.

É possível criar e gerenciar carteiras, derivar contas de frases mnemônicas, criptografar chaves privadas e assinar mensagens ou transações.

A biblioteca pode usar uma ABI de contrato inteligente para codificar chamadas de função e decodificar valores retornados.

Ela pode enviar transações que alteram o estado por meio de um signer e aguardar que essas transações recebam confirmações de bloco.

Também pode estimar gas, formatar unidades de criptomoedas, calcular hashes, recuperar endereços de assinatura e validar endereços Ethereum.

Esses recursos permitem que os desenvolvedores se concentrem na lógica do aplicativo, em vez de reconstruir a comunicação de baixo nível com a blockchain do zero.

Como instalar o Ethers.js?

Ethers.js costuma ser instalado pelo sistema de pacotes npm, usando o nome de pacote ethers.

As instruções oficiais de instalação fornecem o comando npm install ethers para projetos Node.js.

Após a instalação, o desenvolvedor pode importar o namespace completo ethers ou importar classes e funções específicas.

A versão 6 é compatível com padrões modernos de módulos JavaScript e permite importar muitas funções diretamente do pacote principal.

Importações seletivas podem ajudar ferramentas de bundling a incluir somente o código necessário para o aplicativo.

Aplicativos para navegador também podem usar uma versão em módulo ECMAScript, embora aplicativos de produção devam seguir um processo controlado de dependências e build, em vez de carregar código não verificado de uma fonte desconhecida.

Os desenvolvedores nunca devem instalar um pacote apenas porque seu nome é parecido com o de uma biblioteca popular de cripto; pacotes maliciosos podem imitá-la.

Antes da instalação, devem ser verificados o nome do pacote, as informações do publicador, o repositório, a versão, os dados de integridade e o arquivo de lock de dependências.

Como o Ethers.js se conecta a uma blockchain

Ethers.js se comunica com a infraestrutura da blockchain por meio de um provider.

Um provider é uma conexão somente de leitura que permite ao aplicativo solicitar informações da blockchain e simular transações.

O provider envia solicitações a um nó Ethereum ou a outro endpoint RPC compatível.

Entre as solicitações comuns estão verificar um saldo em ETH, consultar um bloco, ler o estado de um contrato, estimar gas, obter informações sobre taxas e pesquisar logs de eventos.

Em geral, o provider não contém uma chave privada e não pode autorizar sozinho uma transação da conta de um usuário.

A documentação oficial de providers do ethers.js descreve as classes de provider e as operações de blockchain disponíveis por meio delas.

Um aplicativo de produção confiável deve usar uma conexão RPC com capacidade, disponibilidade, acesso a dados históricos, controles de segurança e limites de solicitações adequados.

Endpoints públicos ou compartilhados podem ser úteis em testes, mas podem ficar lentos ou indisponíveis quando a demanda é alta.

O que é um provider no Ethers.js?

Um provider é uma abstração que representa uma conexão a uma rede compatível com Ethereum.

Ele oferece aos desenvolvedores uma interface JavaScript consistente, mesmo quando a conexão ou o método de transporte do nó subjacente é diferente.

Um provider JSON-RPC se comunica com um nó por meio de solicitações JSON-RPC padrão.

Um provider WebSocket pode manter uma conexão persistente, útil para receber novos blocos, atividades pendentes e notificações de eventos.

Um provider para navegador encapsula uma interface de carteira injetada que segue o padrão comum de providers para navegadores.

Um provider de fallback pode combinar várias fontes de dados e comparar ou priorizar as respostas conforme sua configuração.

Providers podem consultar dados públicos, mas não devem ser confundidos com signers que autorizam ações de uma conta.

O que é um BrowserProvider?

BrowserProvider é a classe do ethers.js v6 comumente usada para conectar um aplicativo web a um provider Ethereum injetado no navegador.

O provider injetado normalmente é fornecido por um ambiente de carteira que permite ao usuário aprovar o acesso à conta e as transações.

O aplicativo pode criar um BrowserProvider a partir da interface injetada e, em seguida, solicitar um signer para uma conta aprovada.

Conectar-se a uma carteira não dá automaticamente ao aplicativo acesso à chave privada dela.

Normalmente, a carteira mantém as credenciais de assinatura em seu próprio ambiente protegido e solicita a aprovação do usuário para cada assinatura ou transação.

Os aplicativos devem explicar claramente por que solicitam acesso à conta e evitar pedir assinaturas antes que o usuário compreenda a ação.

O que é um signer no Ethers.js?

Um signer é uma abstração que representa uma conta Ethereum capaz de autorizar mensagens e transações.

O signer pode usar como base uma chave privada, uma carteira derivada de frase mnemônica, um dispositivo de assinatura por hardware, uma carteira de navegador, uma conta inteligente ou outro sistema de assinatura.

A documentação oficial da interface Signer explica que um signer representa uma conta blockchain e pode oferecer suporte a configurações avançadas de assinatura nas quais a chave privada não fica diretamente disponível ao aplicativo.

Em geral, um signer pode retornar seu endereço, assinar uma mensagem, estimar o gas de uma transação, preencher campos da transação e enviar uma transação autorizada.

As operações disponíveis dependem da implementação do signer.

Um signer conectado a um provider pode usar dados da rede ao preparar e enviar uma transação.

Um signer desconectado pode conseguir assinar dados localmente, mas talvez não consiga transmitir a transação resultante.

Provider vs. Signer no Ethers.js

Um provider lê dados da blockchain, enquanto um signer autoriza ações associadas a uma conta.

Um provider pode verificar um saldo ou simular uma função de contrato sem ter uma chave privada.

Um signer pode aprovar uma transferência de tokens, implantar um contrato ou enviar outra transação que altere o estado.

Muitos objetos do ethers.js se comportam de maneira diferente conforme estejam conectados a um provider ou a um signer.

Um contrato conectado somente a um provider normalmente pode executar operações de leitura.

O mesmo contrato conectado a um signer pode preparar e enviar transações que alteram o estado, quando o signer tem a autoridade e os fundos necessários.

Separar providers de signers ajuda os desenvolvedores a não misturar o acesso a dados públicos com o controle de contas sensíveis.

O que é uma carteira no Ethers.js?

A classe Wallet do ethers.js é um signer cuja base é uma chave privada.

Ela pode derivar um endereço Ethereum, assinar mensagens e transações e enviar transações quando conectada a um provider.

Uma carteira pode ser criada a partir de uma chave privada, gerada aleatoriamente, restaurada de uma frase mnemônica compatível ou descriptografada de um keystore JSON criptografado.

A documentação oficial de carteiras do ethers.js descreve a criação de carteiras, carteiras determinísticas hierárquicas, arquivos JSON criptografados, frases mnemônicas e funções de assinatura.

Uma carteira no servidor pode ser útil para automações controladas, mas colocar uma chave privada sem restrições no código-fonte do aplicativo representa um grave risco de segurança.

Chaves privadas não devem ser enviadas a um repositório de código, incorporadas a um pacote público para navegador, impressas em logs nem compartilhadas por mensagens comuns.

Sistemas de assinatura de produção devem usar controles de acesso, segredos criptografados, permissões limitadas, backups seguros e monitoramento de transações adequados à quantidade de cripto gerenciada.

O Ethers.js armazena os fundos dos usuários?

Ethers.js não atua como custodiante nem guarda criptomoedas para os usuários.

É uma biblioteca de software que pode criar ou interagir com objetos de assinatura e contas blockchain.

Os fundos continuam sob o controle da chave privada, do contrato inteligente ou do sistema de carteira externa associado ao endereço.

Se um desenvolvedor usar ethers.js para criar uma carteira, ele ou o usuário será responsável por proteger os dados de recuperação.

A perda da chave privada ou da frase mnemônica pode tornar as criptomoedas associadas permanentemente inacessíveis.

A exposição da chave pode permitir que outra pessoa transfira os ativos.

Como o Ethers.js interage com contratos inteligentes

Ethers.js usa a classe Contract para representar um contrato inteligente implantado.

Uma instância de contrato é criada com um endereço de destino, uma ABI e, opcionalmente, um provider ou signer.

A ABI descreve as funções externas, os eventos, os erros e os tipos de dados do contrato.

Ethers.js usa essas informações para gerar métodos JavaScript chamáveis e decodificar respostas da blockchain.

A documentação oficial da API Contract explica que o runner conectado, geralmente um provider ou signer, determina quais operações o contrato pode executar.

Uma chamada de leitura pode consultar o saldo de um token, um endereço de titularidade, uma configuração de protocolo ou outro valor público.

Uma chamada que altera o estado pode transferir tokens, aprovar gastos, depositar garantias, votar, resgatar recompensas ou realizar outra ação definida pelo contrato.

Chamar um método de contrato pelo ethers.js não comprova que o contrato é seguro.

O desenvolvedor ainda precisa verificar o endereço do contrato, a ABI, as permissões, a rede, o comportamento esperado e as premissas de segurança.

O que é uma ABI?

ABI é a sigla de Application Binary Interface (interface binária de aplicativo).

Ela define como um software externo se comunica com a interface de chamadas de um contrato inteligente.

Uma ABI descreve nomes de funções, tipos de entrada e saída, estruturas de eventos, erros personalizados e regras de mutabilidade.

Ethers.js usa uma ABI para converter valores JavaScript legíveis em dados de transação codificados.

Também decodifica bytes retornados e logs de eventos em valores que um aplicativo consegue interpretar.

A documentação oficial de ABI do ethers.js aborda interfaces, fragmentos, codificação, decodificação, eventos, erros e formatos de ABI legíveis por humanos.

Uma ABI incorreta pode fazer o aplicativo codificar a chamada de função errada ou decodificar incorretamente os dados retornados.

Os desenvolvedores devem obter ABIs de artefatos de build verificados ou de fontes confiáveis do projeto.

O que é a classe Interface?

A classe Interface representa uma ABI em um formato que o ethers.js pode usar para codificar e decodificar.

Ela pode codificar dados de funções, decodificar resultados, calcular tópicos de eventos, analisar dados de entrada de transações e interpretar erros personalizados de contratos.

Isso é útil quando o desenvolvedor precisa de controle de baixo nível sem criar um objeto Contract completo.

Uma Interface também pode ajudar ferramentas de monitoramento a identificar qual função de contrato uma transação tentou chamar.

Ela pode decodificar logs quando a definição correta do evento é conhecida.

As informações decodificadas devem sempre ser associadas ao contrato correto, pois contratos diferentes podem usar a mesma assinatura de função ou evento.

Como ler dados de contratos inteligentes

Uma chamada de contrato inteligente somente de leitura usa o estado atual da blockchain sem criar uma transação.

A chamada é executada localmente pelo nó conectado e normalmente não custa gas, pois não é adicionada à blockchain.

Com o ethers.js, o desenvolvedor pode ler valores como saldos de tokens, permissões de gasto, proprietários de contratos, parâmetros de protocolo e registros armazenados.

O resultado representa o estado no bloco usado pelo provider.

Endpoints RPC diferentes podem retornar resultados ligeiramente distintos por algum tempo se estiverem sincronizados em alturas de bloco diferentes.

Leituras históricas podem exigir um nó de arquivo que preserve o estado antigo solicitado.

Uma chamada de leitura também pode falhar se o contrato reverter, a ABI estiver errada, o endereço não tiver o código esperado ou o provider não tiver os dados necessários.

Como enviar transações de contratos inteligentes

Um método de contrato que altera o estado exige um signer, pois precisa ser autorizado por uma conta.

Ethers.js codifica o método e os argumentos nos dados da transação e solicita que o signer a autorize.

A transação também pode incluir um valor em criptomoeda nativa, limite de gas, configurações de taxas, nonce e chain ID.

Após a autorização, a transação é transmitida pelo provider conectado.

O resultado inicial geralmente é uma resposta de transação que contém o hash e os detalhes enviados.

Em seguida, o desenvolvedor pode aguardar o recibo da transação e o número de confirmações escolhido.

Não há garantia de que uma transação enviada será bem-sucedida, pois o estado da blockchain pode mudar antes da execução.

Respostas e recibos de transação

Uma resposta de transação descreve uma transação enviada ou identificada por um provider.

Ela pode incluir hash, remetente, destinatário, nonce, dados, valor, informações de gas e campos relacionados à rede.

O recibo da transação fica disponível depois que ela é incluída em um bloco.

O recibo registra o status da execução, o gas utilizado, informações do bloco, resultados da criação de contratos e logs de eventos emitidos.

Os aplicativos devem verificar o status do recibo antes de considerar uma transação bem-sucedida.

Um hash comprova que existe um identificador de transação, mas não comprova que a operação solicitada ao contrato foi concluída com êxito.

O método waitForTransaction do provider pode aguardar a inclusão e o número de confirmações escolhido.

Estimativa de gas no Ethers.js

Ethers.js pode solicitar a um provider uma estimativa da quantidade de gas que uma transação deve consumir.

O nó simula a transação proposta com base no estado atual da blockchain.

A estimativa pode falhar se a transação simulada for revertida.

A documentação oficial do provider alerta que a estimativa de gas é um cálculo de melhor esforço, pois o estado da blockchain continua mudando.

Uma transação que passa na estimativa pode falhar mais tarde se saldos, permissões, preços, armazenamento do contrato ou outras condições mudarem.

Quando apropriado, os desenvolvedores podem adicionar uma margem razoável, mas um limite de gas extremamente alto não corrige uma lógica de contrato inválida.

Em geral, o usuário paga pelo gas efetivamente consumido, e não pela parte não utilizada do limite de gas.

Como trabalhar com ETH e unidades de tokens

Os valores de ETH e dos tokens são armazenados como números inteiros em suas menores unidades.

Internamente, o ETH costuma ser medido em wei, e um ETH equivale a 10 elevado à potência de 18 wei.

Ethers.js oferece utilitários como parseEther, formatEther, parseUnits e formatUnits.

Essas funções ajudam a converter strings decimais legíveis em valores inteiros da blockchain e a converter valores inteiros de volta em texto legível.

A documentação oficial de conversão de unidades do ethers.js explica como converter valores decimais com segurança.

Os desenvolvedores devem evitar cálculos comuns de ponto flutuante do JavaScript para saldos exatos de tokens, pois erros de arredondamento podem gerar valores incorretos em transações.

O valor real de decimals do token deve ser confirmado no contrato correto, em vez de ser presumido pelo símbolo.

BigInt no Ethers.js v6

Ethers.js v6 usa BigInt do JavaScript para muitos valores inteiros grandes.

Quantias de Ethereum, valores de gas, nonces e números inteiros de contratos podem ultrapassar o limite seguro dos números comuns do JavaScript.

O guia de migração da v5 para a v6 explica que a classe BigNumber anterior foi substituída pelo tipo BigInt nativo do ES2020 em muitas operações.

Valores BigInt usam aritmética inteira e não podem ser combinados diretamente com valores Number comuns do JavaScript.

Também não representam quantias fracionárias de tokens sem que elas sejam convertidas nas menores unidades inteiras do token.

Ao migrar código antigo, os desenvolvedores devem revisar cálculos, comparações, serialização, formatação da interface e armazenamento em bancos de dados.

Utilitários de endereço

Ethers.js oferece funções para validar, normalizar, comparar e criar endereços Ethereum.

Um endereço checksum usa uma combinação de letras maiúsculas e minúsculas para ajudar a detectar alguns erros de digitação.

O utilitário getAddress pode normalizar um endereço válido e rejeitar determinados formatos de checksum inválidos.

O fato de um endereço ser tecnicamente válido não comprova que ele pertence ao usuário ou contrato pretendido.

Os aplicativos devem comparar endereços com fontes confiáveis e evitar mostrar apenas versões abreviadas durante confirmações sensíveis.

Um invasor pode criar outro endereço com caracteres iniciais e finais semelhantes.

Resolução de nomes

Ethers.js pode resolver registros de nomes Ethereum compatíveis em endereços por meio de um provider conectado.

Também pode fazer consultas reversas quando um endereço configurou um nome principal compatível.

Um nome legível pode facilitar o uso, mas o aplicativo ainda deve exibir ou disponibilizar o endereço resolvido antes de uma transferência de alto valor.

Os registros de nomes podem mudar com o tempo, e um nome pode ser resolvido de forma diferente em outra rede.

Os aplicativos devem lidar com nomes não resolvidos e registros inválidos, em vez de enviar silenciosamente para um resultado inesperado.

Como assinar mensagens com o Ethers.js

Ethers.js pode assinar mensagens legíveis por humanos e recuperar o endereço associado a uma assinatura válida.

A assinatura de mensagens pode ser usada para autenticação de contas, comprovação de controle, votações, permissões e autorizações off-chain.

O guia oficial de assinatura do ethers.js recomenda usar conteúdo legível sempre que possível, para que o usuário entenda o que está aprovando.

Uma assinatura nem sempre transfere fundos por si só, mas algumas assinaturas podem autorizar ações posteriores na blockchain.

Quando relevante, os aplicativos devem incluir domínio, finalidade, nonce, validade e contexto da chain.

Os usuários nunca devem assinar uma mensagem pouco clara só porque a solicitação não mostra uma taxa de gas.

Dados tipados EIP-712

EIP-712 define um formato de assinatura estruturado que permite às carteiras exibir campos tipados em vez de uma sequência de bytes ilegível.

Ethers.js pode codificar, assinar, gerar hash e verificar dados tipados compatíveis.

Dados tipados podem ser usados para permissões de tokens, ordens de marketplace, ações de governança, autorização de contas e outras aprovações off-chain.

Os dados de domínio podem incluir nome, versão, chain ID e contrato verificador para reduzir o risco de repetição da assinatura.

Os desenvolvedores devem configurar corretamente o domínio e os tipos, pois um campo ausente ou um contexto de chain incorreto pode enfraquecer a proteção.

Antes de assinar dados estruturados, os usuários devem verificar o gastador solicitado, o valor, a validade, o contrato e a rede.

Logs de eventos e listeners de contratos

Ethers.js pode consultar logs históricos de eventos de contratos inteligentes e acompanhar novos eventos.

Um evento de contrato é definido pela ABI e armazenado nos recibos de transação quando emitido durante uma execução bem-sucedida.

Os desenvolvedores podem criar filtros para parâmetros específicos de eventos, como um endereço ou identificador de token.

Um listener em tempo real pode atualizar uma interface quando ocorre uma transferência, depósito, negociação, votação ou outra ação de contrato.

Os aplicativos não devem depender apenas de uma conexão em tempo real, pois interrupções do WebSocket podem fazer notificações serem perdidas.

Um indexador confiável deve reconciliar eventos por intervalo de blocos, armazenar hashes de blocos, evitar processamento duplicado e lidar com reorganizações da blockchain.

Um evento emitido não comprova que o contrato emissor é confiável, pois qualquer contrato pode criar uma assinatura de evento conhecida.

Hashing e utilitários criptográficos

Ethers.js inclui utilitários para gerar hashes de dados, calcular seletores de função, processar assinaturas, derivar endereços e lidar com formatos de codificação Ethereum.

Entre as operações comuns estão hashing Keccak-256, hashing de mensagens, codificação compactada, codificação RLP e recuperação de assinaturas.

A documentação oficial de hashing do ethers.js explica recursos auxiliares para mensagens, dados tipados, nomes, identificadores e dados de autorização.

As APIs criptográficas devem ser usadas conforme o padrão Ethereum pertinente, e não combinadas de maneira improvisada.

Assinar no formato de hash errado pode gerar assinaturas incompatíveis ou vulnerabilidades de segurança.

Os desenvolvedores devem incluir separação de domínio quando os mesmos dados puderem ser reutilizados em outro contexto.

Implantação de contratos com o Ethers.js

Ethers.js oferece ContractFactory para implantar contratos inteligentes.

Uma factory é criada a partir do bytecode do contrato, de uma ABI e de um signer.

A transação de implantação pode incluir argumentos do construtor e um valor opcional em criptomoeda nativa.

Após o envio, o desenvolvedor deve aguardar a inclusão da transação de implantação antes de presumir que o contrato existe no endereço previsto.

O endereço implantado deve ser salvo junto com o chain ID, as configurações do compilador, a versão do código-fonte, os argumentos do construtor e o hash da transação de implantação.

Uma implantação bem-sucedida não comprova que o contrato é seguro, foi inicializado corretamente ou está sob o controle do administrador pretendido.

Contratos de produção devem ser testados e passar por uma análise de segurança apropriada antes de gerenciar ativos valiosos.

Ethers.js em aplicativos para navegador

Um aplicativo descentralizado para navegador pode usar ethers.js para conectar a interface do usuário a uma carteira e a um provider de blockchain.

O aplicativo pode exibir saldos, solicitar a troca de rede, ler contratos, estimar transações e pedir à carteira que assine ações aprovadas.

As chaves privadas devem permanecer na carteira, e não ser copiadas para o código do front-end.

Em geral, todo código enviado a um navegador pode ser inspecionado pelo usuário ou por um invasor.

Chaves secretas de API e credenciais privilegiadas de assinatura não devem ser incorporadas ao pacote público do aplicativo.

A interface deve apresentar detalhes claros das transações e lidar com rejeição da carteira, incompatibilidade de rede, falha de RPC, transações pendentes, reversões, tempo limite de confirmação e mudanças de conta.

Ethers.js em aplicativos no servidor

Um serviço no servidor pode usar ethers.js para monitorar dados da blockchain, enviar transações controladas, gerar relatórios, verificar assinaturas e operar fluxos de cripto no backend.

Aplicativos no servidor podem se conectar diretamente a um nó RPC ou usar um endpoint gerenciado.

Um backend que assina transações deve proteger suas credenciais de assinatura contra desenvolvedores, logs, backups, sistemas de build e processos não autorizados.

Sistemas de alto valor devem considerar uma infraestrutura de assinatura isolada, políticas de transação, limites de saque, fluxos de aprovação e controles de emergência.

Um servidor também deve acompanhar cuidadosamente os nonces das transações quando vários processos enviam transações da mesma conta.

O uso duplicado ou conflitante de nonce pode fazer transações substituírem umas às outras ou permanecerem pendentes.

Ethers.js e redes compatíveis com EVM

Ethers.js pode se conectar a muitas redes compatíveis com EVM que disponibilizam interfaces JSON-RPC no estilo Ethereum.

O aplicativo deve fornecer o endpoint RPC correto, o chain ID, as informações sobre o ativo nativo usado para pagar gas e os endereços dos contratos da rede selecionada.

O mesmo endereço de carteira pode ter saldos e históricos de transações diferentes em chains distintas.

Um contrato implantado em determinado endereço de uma rede pode não existir ou ter código diferente em outra rede.

A compatibilidade com EVM também não garante comportamento idêntico de gas, tipos de transação, finalidade, extensões RPC ou detalhes de execução de contratos inteligentes.

Cada integração de rede deve ser testada individualmente.

Principais mudanças do Ethers.js v5 para a v6

Ethers.js v6 introduziu grandes mudanças de arquitetura e API em relação à versão 5.

O guia de migração aponta o uso ampliado de recursos modernos do ES6 como uma das principais mudanças.

O BigInt nativo substituiu a classe BigNumber anterior em muitas operações com números inteiros.

Os objetos Contract usam o comportamento Proxy do JavaScript para resolver métodos dinamicamente.

Muitas classes e utilitários foram transferidos para a exportação principal do pacote, em vez de serem acessados por namespaces aninhados antigos.

A classe Web3Provider anterior foi substituída por BrowserProvider para encapsular providers comuns injetados no navegador.

As APIs de transação, assinatura, contrato, provider e utilitários também receberam mudanças de nomenclatura e estrutura.

O código existente da v5 não deve ser atualizado apenas pela alteração da versão do pacote.

O guia oficial de migração do ethers.js v6 deve ser seguido, e o aplicativo deve ser testado novamente por completo.

O Ethers.js v5 ainda tem suporte?

A política de segurança do ethers.js informa que a maior parte do trabalho de manutenção se concentra na versão principal mais recente.

Ela também informa que a versão 5 recebe atualizações de segurança, enquanto versões principais mais antigas não têm suporte.

Desenvolvedores que mantêm um aplicativo na versão 5 devem instalar a atualização de segurança v5 mais recente disponível e avaliar uma migração planejada para a v6.

O uso prolongado de uma versão legada pode criar riscos de compatibilidade e manutenção, mesmo quando ainda estão disponíveis correções de segurança críticas.

As informações atuais de suporte estão publicadas na política oficial de segurança do ethers.js.

Riscos de segurança ao usar o Ethers.js

Ethers.js pode ajudar aplicativos a interagir com sistemas blockchain, mas não torna segura uma lógica de aplicativo insegura.

Um desenvolvedor pode usar a biblioteca corretamente e ainda assim chamar um contrato inteligente malicioso ou assinar uma transação prejudicial.

Chain IDs, endereços de contrato, ABIs, casas decimais, premissas de gas ou domínios de assinatura incorretos podem causar perdas financeiras.

Um endpoint RPC comprometido pode retornar dados falsos ou incompletos, atrasar transações ou ocultar atividades relevantes da blockchain.

Uma dependência ou um processo de build comprometido pode alterar o comportamento do aplicativo antes que o código chegue aos usuários.

Uma chave privada vazada pode permitir que um invasor contorne todas as proteções da interface do usuário.

A segurança exige gerenciamento seguro de chaves, dependências confiáveis, verificação de contratos, validação de entradas, simulação de transações, monitoramento e testes independentes.

Segurança de chaves privadas

Uma chave privada nunca deve ser colocada no código-fonte do navegador nem enviada a um repositório.

Ela não deve ser incluída diretamente em um arquivo público de configuração, chamado de suporte, captura de tela ou log do aplicativo.

Variáveis de ambiente podem reduzir exposições acidentais, mas não constituem um sistema de segurança completo.

Qualquer pessoa com acesso ao ambiente do processo, à plataforma de implantação, à memória do servidor ou à configuração do build ainda pode ter acesso à chave.

Sistemas de produção devem separar as permissões de assinatura do acesso geral ao aplicativo.

As chaves devem ser substituídas quando houver suspeita de comprometimento, embora isso exija transferir o controle para um novo endereço blockchain ou atualizar as funções autorizadas do contrato.

Segurança de dependências e da cadeia de suprimentos

Os desenvolvedores devem instalar ethers.js somente de sua fonte autêntica de pacotes.

Um pacote com nome escrito incorretamente pode conter código malicioso criado para roubar chaves privadas ou alterar destinatários de transações.

Arquivos de lock e verificações de integridade ajudam a garantir que instalações automatizadas usem versões de dependências revisadas.

Os avisos de atualização de segurança devem ser acompanhados pelo repositório oficial e pelos registros do pacote.

Aplicativos de produção devem testar as atualizações de dependências antes da implantação.

Pacotes e scripts não utilizados devem ser removidos, pois cada dependência aumenta a possível superfície de ataque.

Risco de provider RPC

Um provider RPC fornece as informações da blockchain usadas por um aplicativo ethers.js.

Se o provider ficar indisponível, o aplicativo talvez não consiga carregar saldos ou enviar transações.

Se houver atraso, o aplicativo poderá exibir informações desatualizadas.

Um endpoint malicioso pode tentar apresentar incorretamente o estado da chain, as estimativas de gas ou o status das transações.

Aplicativos que lidam com decisões financeiras importantes podem comparar respostas de vários nós independentes ou operar sua própria infraestrutura de nós.

O chain ID retornado pelo provider deve ser verificado antes de solicitar uma assinatura.

Quando apropriado, a conexão com o provider deve usar transporte criptografado e credenciais controladas.

Simulação de transações e tratamento de erros

Ethers.js pode simular chamadas e estimar gas antes do envio de uma transação.

A simulação pode identificar muitas reversões prováveis, mas não garante o sucesso futuro.

O estado da blockchain pode mudar entre a simulação e a execução efetiva.

Quando possível, os aplicativos devem decodificar erros de contratos e apresentar uma explicação útil ao usuário.

Devem diferenciar rejeição da carteira, falha de RPC, fundos insuficientes, falha na estimativa de gas, substituição de transação, reversão da execução e tempo limite de confirmação.

Uma mensagem de erro genérica pode levar os usuários a repetir uma transação sem necessidade ou assinar outra ação sem entender o problema original.

Vantagens do Ethers.js

Ethers.js oferece uma interface compacta que abrange muitas tarefas comuns de desenvolvimento Ethereum.

A separação entre provider e signer ajuda a criar limites de segurança mais claros.

A classe Contract reduz a quantidade de codificação manual de ABI necessária para interações com contratos inteligentes.

As declarações de TypeScript integradas melhoram o suporte do editor e podem detectar alguns usos incorretos de parâmetros.

A biblioteca reúne utilitários de carteira, assinatura, endereço, unidades, hashing, transações e eventos em um só pacote.

É de código aberto e conta com documentação e testes abrangentes.

Seu design voltado para EVM é útil em muitas redes blockchain compatíveis.

Limitações do Ethers.js

Ethers.js não opera um nó Ethereum e ainda exige acesso à infraestrutura da blockchain.

Não audita contratos inteligentes nem garante que um endereço seja confiável.

Não protege automaticamente chaves privadas armazenadas de forma descuidada por um aplicativo.

Não pode reverter uma transação confirmada na blockchain.

Não pode garantir que uma estimativa de gas, resultado simulado ou resposta RPC continuará precisa.

Não elimina a necessidade de compreender contas Ethereum, transações, gas, assinaturas, ABIs, logs de eventos e permissões de contratos inteligentes.

Os desenvolvedores também precisam gerenciar separadamente a segurança da interface, bancos de dados, acesso ao backend, implantação, monitoramento e requisitos regulatórios.

Exemplo de fluxo de transação com Ethers.js

Suponha que um aplicativo descentralizado permita a um usuário transferir um token compatível.

Primeiro, o aplicativo cria um provider conectado à rede selecionada.

Confirma o chain ID e solicita acesso à conta aprovada do usuário por meio da interface da carteira.

O aplicativo cria um signer e uma instância de Contract usando o endereço verificado do token e sua ABI.

Em seguida, consulta as casas decimais do token e o saldo do usuário.

O valor legível da transferência é convertido na menor unidade inteira do token com parseUnits.

O aplicativo solicita uma estimativa de gas ao método do contrato e prepara a transação.

A carteira exibe o destinatário, o contrato, a rede, o valor e as informações de taxa para aprovação do usuário.

Depois que o usuário assina, o signer transmite a transação pelo provider.

O aplicativo recebe uma resposta de transação e exibe o hash.

Aguarda o recibo e verifica se a execução foi bem-sucedida.

Por fim, atualiza o saldo do token e registra a transação confirmada.

Esse fluxo mostra como providers, signers, contratos, ABIs, conversão de unidades, estimativa de gas e recibos funcionam juntos no ethers.js.

Erros comuns no Ethers.js

Um erro comum é incorporar uma chave privada ao JavaScript do front-end.

Outro é usar um endereço de contrato ou uma ABI não verificados.

Um terceiro é misturar valores Number comuns com valores BigInt.

Um quarto é tratar uma transação enviada como confirmada antes de receber um recibo bem-sucedido.

Um quinto é presumir que uma estimativa de gas bem-sucedida garante a execução da transação.

Um sexto é usar cálculos de ponto flutuante para quantias de tokens.

Um sétimo é ignorar o chain ID ao conectar uma carteira ou assinar dados tipados.

Um oitavo é não lidar com substituições e descartes de transações nem com reorganizações da blockchain.

Um nono é atualizar do ethers.js v5 para a v6 sem revisar as mudanças incompatíveis da API.

Um décimo é confiar em um pacote, endpoint RPC ou contrato inteligente apenas por usar um nome conhecido.

Perguntas frequentes

Para que serve o ethers.js?

Ethers.js é usado para desenvolver aplicativos JavaScript e TypeScript que leem dados da blockchain, gerenciam carteiras, assinam mensagens, enviam transações e interagem com contratos inteligentes Ethereum.

Ethers.js é uma criptomoeda?

Não. Ethers.js é uma biblioteca de software e não tem uma criptomoeda oficial nem um token de investimento.

Ethers.js é uma carteira?

Ethers.js inclui classes de carteira e ferramentas de assinatura, mas a biblioteca não é, por si só, um serviço de carteira custodial.

Qual é a versão mais recente do ethers.js?

Em 16 de julho de 2026, a versão documentada mais recente é ethers v6.17.0, publicada em 18 de junho de 2026.

O ethers.js pode se conectar à Ethereum?

Sim. Ethers.js se conecta à Ethereum por meio de um provider que se comunica com um nó Ethereum ou endpoint RPC compatível.

O ethers.js funciona com outras chains EVM?

Sim. Ele pode funcionar com muitas redes compatíveis com EVM que oferecem interfaces JSON-RPC no estilo Ethereum.

Qual é a diferença entre provider e signer?

Um provider lê dados públicos da blockchain, enquanto um signer autoriza mensagens e transações que alteram o estado de uma conta.

O que é um objeto Contract no ethers.js?

Um objeto Contract combina o endereço do contrato, uma ABI e um provider ou signer para oferecer métodos JavaScript chamáveis para um contrato inteligente implantado.

O ethers.js exige uma ABI?

Em geral, é necessária uma ABI para codificar e decodificar com praticidade as funções, os eventos e os erros nomeados de contratos inteligentes.

O ethers.js armazena chaves privadas?

A biblioteca pode criar objetos de carteira que contêm credenciais de assinatura na memória do aplicativo, mas o armazenamento e a proteção das chaves continuam sendo responsabilidade do desenvolvedor.

É seguro colocar uma chave privada em um aplicativo para navegador?

Não. Usuários, invasores, extensões ou scripts comprometidos podem inspecionar e roubar chaves privadas colocadas no código do navegador.

Uma chamada de contrato somente de leitura custa gas?

Uma chamada somente de leitura feita por meio de um provider normalmente é simulada por um nó e não gera uma taxa on-chain.

Por que o ethers.js usa BigInt?

BigInt oferece suporte aos números inteiros exatos e grandes necessários para saldos de cripto, valores de gas, nonces e dados de contratos inteligentes, sem a perda de precisão dos números comuns do JavaScript.

O ethers.js pode estimar gas?

Sim. Ele pode solicitar uma estimativa de gas a um nó, mas ela se baseia no estado atual e não garante o sucesso da transação futura.

O ethers.js pode reverter uma transação?

Não. Ethers.js pode enviar transações, mas não reverter uma mudança de estado confirmada na blockchain.

O ethers.js pode acompanhar eventos de contratos inteligentes?

Sim. Ele pode consultar logs históricos e se inscrever para receber novos eventos de contrato por meio de um provider adequado.

O que mudou do ethers.js v5 para a v6?

A versão 6 introduziu BigInt nativo, recursos modernos de JavaScript, importações revisadas, classes de provider atualizadas, métodos de contrato baseados em Proxy e várias mudanças de API.

O ethers.js é de código aberto?

Sim. Ethers.js está disponível publicamente sob a licença MIT.

O ethers.js tem um token oficial?

Não. O projeto oficial informa que ethers não tem um token.

Onde os desenvolvedores devem relatar um problema de segurança do ethers.js?

Os desenvolvedores devem seguir as instruções para relatar vulnerabilidades em caráter privado na política oficial de segurança do ethers.js, em vez de divulgar publicamente um problema ainda não corrigido.

Conclusão

Ethers.js é uma biblioteca JavaScript e TypeScript que oferece aos desenvolvedores de cripto uma maneira estruturada de interagir com a Ethereum e redes blockchain compatíveis com EVM.

Ela oferece providers para ler dados da blockchain, signers para autorizar ações de contas, carteiras para gerenciar credenciais de assinatura e objetos Contract para interagir com contratos inteligentes.

Também inclui utilitários para codificação de ABI, decodificação de eventos, assinatura de mensagens, dados tipados, endereços, hashes, estimativas de gas, recibos de transação e conversão de unidades de criptomoedas.

A versão principal atual é ethers.js v6, que usa recursos modernos de JavaScript, como BigInt e métodos de contrato baseados em Proxy.

Em 16 de julho de 2026, a versão documentada mais recente é ethers v6.17.0.

Ethers.js pode simplificar o desenvolvimento de blockchain, mas não elimina os riscos de exposição de chaves privadas, contratos maliciosos, endereços incorretos, endpoints RPC não confiáveis, comprometimento de dependências ou transações irreversíveis.

Os desenvolvedores devem verificar as fontes dos pacotes, fixar as versões das dependências, proteger as credenciais de assinatura, confirmar os chain IDs, validar endereços de contratos, usar ABIs corretas e testar cada fluxo de transação.

Os aplicativos também devem lidar com simulações malsucedidas, rejeição da carteira, indisponibilidade de RPC, transações pendentes ou substituídas, reversões, confirmações e reorganizações de chain.

Com práticas de segurança cuidadosas, ethers.js oferece uma base poderosa para criar carteiras, sistemas de pagamento com cripto, aplicativos descentralizados, ferramentas de análise, serviços de monitoramento e automações de contratos inteligentes.

Compreender o ethers.js ajuda os desenvolvedores a conectar aplicativos JavaScript a sistemas blockchain sem confundir a biblioteca com um serviço de carteira, uma rede blockchain ou uma criptomoeda.