Arbitrum SDK

O que é o Arbitrum SDK?

Arbitrum SDK é um kit de ferramentas para desenvolvedores criarem aplicativos que interagem com as redes Arbitrum, especialmente quando um aplicativo precisa de bridge de tokens, mensagens cross-chain, detecção de rede, acompanhamento de transações ou acesso aos contratos da bridge da Arbitrum.

No universo cripto, o termo geralmente se refere ao pacote TypeScript @arbitrum/sdk, projetado para interações do lado do cliente com redes Arbitrum.

O SDK ajuda os desenvolvedores a evitar a criação de toda a lógica de bridge de baixo nível do zero, pois oferece classes tipadas e métodos auxiliares para operações comuns da Arbitrum.

De acordo com o repositório oficial do Arbitrum SDK no GitHub, o SDK oferece funções auxiliares e acesso às interfaces dos contratos inteligentes subjacentes para a criação de aplicativos na Arbitrum.

Para os usuários, o Arbitrum SDK é uma infraestrutura invisível que pode viabilizar ações como depositar ETH, transferir tokens ERC-20 por bridge, sacar ativos ou verificar se uma transação cross-chain foi concluída.

Para os desenvolvedores, o Arbitrum SDK é uma camada prática entre um aplicativo e os contratos inteligentes que gerenciam a comunicação da cadeia principal para a cadeia secundária e da cadeia secundária para a cadeia principal.

Como o Arbitrum SDK se encaixa no ecossistema Arbitrum

Arbitrum é um ecossistema de escalabilidade da Ethereum que oferece execução de menor custo, experiências mais rápidas para os usuários e ambientes blockchain dedicados a aplicativos cripto.

A documentação mais ampla da Arbitrum descreve o ecossistema como uma infraestrutura para aplicativos, tokenização e redes dedicadas, o que torna as ferramentas de SDK importantes tanto para desenvolvedores de aplicativos quanto para operadores de redes.

O SDK principal é comumente usado com Arbitrum One, Arbitrum Nova e redes Arbitrum personalizadas que seguem o modelo de cadeia principal e cadeia secundária.

Nesse modelo, a cadeia principal é aquela que fornece liquidação, mensagens ou suporte de infraestrutura, enquanto a cadeia secundária é a rede Arbitrum que recebe ativos, mensagens ou solicitações de execução.

Essa nomenclatura de cadeia principal e cadeia secundária se tornou mais importante no Arbitrum SDK v4, pois o SDK agora usa uma terminologia mais geral, aplicável a ambientes Layer 2 e Layer 3.

O guia oficial de migração para o Arbitrum SDK v4 explica que muitas referências antigas a L1 e L2 foram substituídas pelos termos cadeia principal e cadeia secundária para oferecer melhor suporte ao ecossistema Arbitrum mais amplo.

Por que o Arbitrum SDK é importante

O Arbitrum SDK é importante porque é difícil criar aplicativos cripto cross-chain com segurança sem ferramentas confiáveis.

Uma bridge de tokens simples pode parecer uma única transferência para o usuário, mas, nos bastidores, pode envolver aprovações, gateways, contratos inbox, tickets retryable, verificações de status, períodos de contestação e execução de outbox.

O SDK reduz essa complexidade ao reunir muitas dessas etapas em classes e métodos reutilizáveis.

Isso é importante para carteiras, aplicativos descentralizados, bridges, dashboards, jogos, ferramentas de pagamento, interfaces de trading e produtos financeiros on-chain que precisam movimentar ativos ou mensagens entre redes.

Sem um SDK, os desenvolvedores precisariam interagir diretamente com os contratos da bridge e gerenciar manualmente muitos casos especiais.

Com um SDK, os desenvolvedores podem se concentrar mais na experiência do usuário, na segurança das transações, na exibição de saldos e na lógica do aplicativo.

Principais funções do Arbitrum SDK

Transferência de ativos por bridge

Um dos usos mais importantes do Arbitrum SDK é transferir ativos por bridge entre uma cadeia principal e uma cadeia secundária Arbitrum.

O SDK inclui classes de bridge, como EthBridger e Erc20Bridger, para movimentar ativos nativos e tokens ERC-20.

A visão geral oficial da Arbitrum sobre bridges explica que a transferência de tokens por bridge e as mensagens cross-chain são elementos fundamentais para criar soluções na Arbitrum.

Quando um usuário deposita ETH ou outro token nativo em uma rede Arbitrum, o SDK pode ajudar a preparar e enviar a transação necessária.

Quando um usuário deposita tokens ERC-20, o SDK pode ajudar a aprovar o gateway, iniciar o depósito e aguardar o processamento da transação na cadeia secundária.

O guia oficial da Arbitrum para depósitos de tokens mostra como Erc20Bridger é usado para aprovar um gateway e depositar tokens ERC-20.

Mensagens cross-chain

O Arbitrum SDK também oferece suporte a mensagens cross-chain, que permitem que um contrato ou aplicativo envie dados ou instruções entre uma cadeia principal e uma cadeia secundária.

As mensagens cross-chain são importantes porque muitos aplicativos cripto precisam fazer mais do que transferir tokens.

Um sistema de governança pode precisar transmitir instruções de execução, um aplicativo de pagamentos pode precisar acionar uma lógica de liquidação e um jogo pode precisar sincronizar o estado entre redes.

O guia oficial da Arbitrum sobre mensagens cross-chain descreve @arbitrum/sdk como uma biblioteca TypeScript para transferir tokens por bridge e enviar mensagens entre cadeias principais e secundárias da Arbitrum.

O SDK oferece interfaces tipadas que facilitam a criação, os testes e o monitoramento desses fluxos de mensagens.

Acompanhamento do status das transações

O Arbitrum SDK ajuda os desenvolvedores a acompanhar se uma transação cross-chain está pendente, concluída, com falha ou pronta para a próxima etapa.

Isso é especialmente útil porque as atividades cross-chain costumam envolver mais de um ciclo de vida de transação.

Um depósito da cadeia principal para a cadeia secundária pode envolver uma transação na cadeia principal, seguida pela execução na cadeia secundária.

Um saque da cadeia secundária para a cadeia principal pode envolver o início na cadeia secundária, um período de contestação e a execução final na cadeia principal.

O SDK oferece ferramentas para que os desenvolvedores recuperem mensagens dos recibos de transação e verifiquem seu status.

Isso ajuda os aplicativos a mostrar aos usuários o andamento correto, em vez de deixá-los confusos depois do envio da primeira transação.

Configuração de rede

O Arbitrum SDK pode ajudar a identificar redes Arbitrum e recuperar a configuração correta para uma cadeia secundária de destino.

Isso é importante porque diferentes redes Arbitrum podem ter IDs de cadeia, endereços de bridge, endereços de gateway de tokens, tokens nativos e relações de liquidação diferentes.

Uma configuração correta de rede reduz o risco de enviar uma transação ao contrato de bridge errado.

Também ajuda os aplicativos a oferecer suporte a várias redes Arbitrum sem codificar manualmente cada endereço.

Classes importantes do Arbitrum SDK

EthBridger

EthBridger é usado quando um aplicativo precisa transferir ETH ou o token nativo de uma rede Arbitrum compatível por bridge.

Os desenvolvedores podem usá-lo para depositar ativos da cadeia principal na cadeia secundária ou iniciar saques da cadeia secundária de volta para a cadeia principal.

O guia oficial de depósitos de ETH e mensagens mostra como EthBridger pode simplificar depósitos em uma cadeia secundária Arbitrum.

Essa classe é útil para carteiras, aplicativos de pagamento e qualquer interface cripto que precise oferecer suporte à movimentação de ativos nativos na Arbitrum.

Erc20Bridger

Erc20Bridger é usado para depósitos e saques de tokens ERC-20.

Pode ajudar com fluxos de aprovação, interações com gateways, transações de depósito, início de saques e acompanhamento de mensagens.

A transferência de tokens ERC-20 por bridge é mais complexa do que a transferência de ativos nativos, pois os tokens podem precisar passar por gateways padrão, gateways personalizados ou outra lógica de bridge de tokens.

O SDK facilita esse fluxo ao oferecer aos desenvolvedores uma interface consistente para muitas tarefas comuns de transferência de tokens por bridge.

ParentToChildMessage

ParentToChildMessage representa uma mensagem enviada de uma cadeia principal para uma cadeia secundária Arbitrum.

Essa classe é útil quando um aplicativo precisa monitorar se um depósito ou ticket retryable foi executado na cadeia secundária.

As mensagens da cadeia principal para a secundária são frequentemente usadas em depósitos, chamadas de contratos e instruções cross-chain.

Elas estão intimamente relacionadas aos tickets retryable, um mecanismo central da Arbitrum para a execução confiável de mensagens.

ChildToParentMessage

ChildToParentMessage representa uma mensagem enviada de uma cadeia secundária Arbitrum de volta para uma cadeia principal.

Essa classe é importante para saques, pois as mensagens da cadeia secundária para a principal exigem um período de espera antes de poderem ser executadas na cadeia principal.

O guia oficial da Arbitrum para saques de tokens explica que os saques levam aproximadamente 6.4 dias para serem finalizados por causa do período de contestação.

Os aplicativos podem usar as ferramentas de mensagens do SDK para mostrar se um saque ainda está aguardando, pronto para execução ou concluído.

Tickets retryable e o Arbitrum SDK

Os tickets retryable são uma parte essencial das mensagens da cadeia principal para a secundária na Arbitrum.

Um ticket retryable é um mecanismo que permite que uma transação na cadeia principal crie uma solicitação de execução na cadeia secundária.

A documentação oficial da Arbitrum sobre tickets retryable explica que eles separam o envio na cadeia principal da execução na cadeia secundária.

Esse design é útil porque a execução cross-chain pode depender dos limites de gas, dos custos de envio, dos lances de taxa, do tamanho dos dados de chamada e da taxa base da cadeia secundária.

O Arbitrum SDK pode ajudar a estimar os parâmetros de gas dos tickets retryable e preparar os dados de transação necessários para criá-los.

Para um usuário de cripto, os tickets retryable costumam ficar ocultos por trás da interface de uma bridge ou de um aplicativo.

Para um desenvolvedor, entender os tickets retryable é essencial para criar depósitos e chamadas de contratos confiáveis na Arbitrum.

Arbitrum SDK v4 e suporte ao modelo de cadeia principal e secundária

O Arbitrum SDK v4 introduziu mudanças que melhoram o suporte a estruturas de redes Arbitrum mais flexíveis.

A mudança mais visível é a substituição da antiga nomenclatura L1 e L2 pelos termos cadeia principal e cadeia secundária.

Essa mudança é útil porque, dependendo do design, uma cadeia secundária Arbitrum pode liquidar na Ethereum, em outra rede Arbitrum ou em uma configuração diferente de cadeia principal.

O guia de migração da v4 também menciona mudanças nos tipos de rede, em AssetBridger, Erc20Bridger e nas classes de mensagens.

Os desenvolvedores que atualizam integrações antigas devem consultar o guia oficial de migração antes de atualizar o código de produção.

Isso é especialmente importante para interfaces de bridge, rastreadores de saque e aplicativos que oferecem suporte a várias redes Arbitrum.

Arbitrum SDK versus Arbitrum Chain SDK

Arbitrum SDK e Arbitrum Chain SDK são ferramentas relacionadas, mas não são iguais.

Arbitrum SDK, geralmente instalado como @arbitrum/sdk, é usado principalmente em tarefas no nível do aplicativo, como transferências por bridge, mensagens e leitura de dados das redes Arbitrum.

Arbitrum Chain SDK, geralmente instalado como @arbitrum/chain-sdk, foi projetado para criar, implantar e configurar redes Arbitrum personalizadas.

O guia oficial de implantação do Arbitrum Chain SDK explica como o Chain SDK pode ajudar a criar uma nova rede Arbitrum ao preparar configurações e parâmetros de implantação.

O Chain SDK também pode ajudar a gerar a configuração de um nó Nitro após a implantação de uma rede.

O guia oficial de configuração de nós da Arbitrum explica que prepareNodeConfig pode gerar um objeto de configuração JSON para um nó Nitro.

Uma maneira simples de lembrar a diferença é que Arbitrum SDK serve para aplicativos que usam redes Arbitrum, enquanto Arbitrum Chain SDK serve para equipes que lançam ou operam redes Arbitrum.

Como os desenvolvedores instalam o Arbitrum SDK

Os desenvolvedores costumam instalar o Arbitrum SDK pelo npm usando o nome do pacote @arbitrum/sdk.

O comando de instalação geralmente é npm install @arbitrum/sdk.

Os desenvolvedores também podem usar gerenciadores de pacotes como yarn ou pnpm, dependendo da configuração do projeto.

Após a instalação, o desenvolvedor conecta o SDK a providers, signers e configurações de rede das cadeias principais e secundárias utilizadas.

Em seguida, o aplicativo usa classes do SDK, como EthBridger, Erc20Bridger, ParentToChildMessage e ChildToParentMessage, para criar o fluxo desejado.

Como o SDK interage com transações blockchain reais, os desenvolvedores devem testar as integrações em redes de teste compatíveis antes de usar fundos reais.

Exemplos de uso do Arbitrum SDK

Transferências de ativos em carteiras

Uma carteira cripto pode usar o Arbitrum SDK para permitir que os usuários movimentem ativos para dentro e para fora das redes Arbitrum.

A carteira pode usar as ferramentas de status do SDK para mostrar quando um depósito chegou à cadeia secundária ou quando um saque está pronto para ser executado na cadeia principal.

Isso melhora a experiência do usuário, pois as transações cross-chain podem parecer confusas ou incompletas.

Aplicativos descentralizados

Um aplicativo descentralizado pode usar o Arbitrum SDK para permitir que os usuários financiem suas contas em uma rede Arbitrum diretamente de uma cadeia principal.

Isso é útil para aplicativos de DeFi, pagamentos, jogos, NFTs e ativos do mundo real que buscam simplificar a integração de usuários.

O aplicativo pode combinar transferências por bridge, acompanhamento de status e chamadas de contratos inteligentes em um único fluxo guiado.

Emissores de tokens

Um emissor de tokens pode usar ferramentas do SDK e a documentação da Arbitrum sobre bridges para viabilizar a movimentação de tokens entre cadeias principais e secundárias.

Isso pode facilitar o uso do token em aplicativos baseados na Arbitrum.

Os emissores de tokens ainda devem analisar cuidadosamente os requisitos do gateway, pois o comportamento personalizado do token pode exigir uma configuração de bridge personalizada.

Operadores de redes

As equipes que lançam redes Arbitrum personalizadas podem usar o Arbitrum Chain SDK para preparar parâmetros de implantação, configurar definições do rollup e gerar configurações de nós.

Depois que a rede estiver ativa, elas também podem usar @arbitrum/sdk na camada do aplicativo.

Essa combinação permite que uma equipe gerencie tanto a configuração da infraestrutura quanto os fluxos dos aplicativos voltados aos usuários.

Benefícios do Arbitrum SDK

• • Simplifica depósitos e saques de tokens entre cadeias principais e secundárias.
  • Oferece acesso tipado aos contratos inteligentes de bridge e mensagens.
  • Reduz o processamento manual de recibos de transações cross-chain.
  • Ajuda os desenvolvedores a estimar e acompanhar a execução de tickets retryable.
  • Oferece suporte a relações mais flexíveis entre cadeias principais e secundárias no SDK v4.
  • Melhora a experiência do usuário nos aplicativos ao ajudar a exibir o andamento correto das transações.

Riscos e considerações para desenvolvedores

O Arbitrum SDK facilita o desenvolvimento, mas não elimina a necessidade de uma revisão de segurança cuidadosa.

Os desenvolvedores ainda precisam proteger as chaves privadas, validar os endereços dos tokens, confirmar a configuração da rede e testar todos os fluxos de bridge.

IDs de cadeia incorretos, endpoints RPC errados, endereços de gateway inválidos ou gas insuficiente podem causar falhas ou atrasos nas transações.

Os usuários também devem entender que os saques de uma cadeia secundária para uma cadeia principal podem levar vários dias, pois o sistema precisa respeitar o período de contestação.

Os aplicativos devem explicar isso claramente antes de o usuário iniciar um saque.

Os desenvolvedores devem evitar aprovações ilimitadas de tokens, a menos que o produto tenha um bom motivo para solicitá-las.

Também devem monitorar as atualizações das dependências, pois os pacotes do SDK podem introduzir mudanças incompatíveis, especialmente em atualizações de versões principais.

Boas práticas para usar o Arbitrum SDK

Os desenvolvedores devem começar pela documentação oficial e pelo repositório oficial do GitHub antes de criar uma integração de produção.

Devem usar a versão atual do SDK e consultar as notas de migração ao atualizar versões antigas.

Devem testar depósitos, saques, falhas em tickets retryable, resgate manual e execução de outbox em um ambiente seguro antes do lançamento.

Devem exibir aos usuários estados claros das transações, como pendente, enviada, aguardando o período de contestação, pronta para execução, concluída e com falha.

Devem validar os metadados dos tokens e a configuração da bridge antes de exibir um token como compatível com transferências por bridge.

Devem evitar ocultar o prazo dos saques, pois os usuários precisam saber quando os fundos estarão disponíveis na cadeia principal.

Devem criar interfaces que expliquem as taxas, os requisitos de gas e as regras de reembolso antes de o usuário assinar uma transação.

FAQ

O que é o Arbitrum SDK, em termos simples?

Arbitrum SDK é um kit de ferramentas para desenvolvedores que ajuda aplicativos cripto a transferir ativos por bridge, enviar mensagens e acompanhar transações entre redes Arbitrum.

O Arbitrum SDK serve apenas para bridges de tokens?

Não. O Arbitrum SDK é comumente usado para bridges de tokens, mas também oferece suporte a mensagens cross-chain, configuração de redes, processamento de recibos de transação e acompanhamento do status de mensagens.

Qual linguagem de programação o Arbitrum SDK usa?

O pacote principal @arbitrum/sdk é uma biblioteca TypeScript comumente usada em aplicativos cripto feitos em JavaScript e TypeScript.

Qual é a diferença entre EthBridger e Erc20Bridger?

EthBridger é usado para movimentar ETH ou tokens nativos, enquanto Erc20Bridger é usado para depósitos e saques de tokens ERC-20.

Por que os saques da Arbitrum demoram?

Os saques de uma cadeia secundária Arbitrum para uma cadeia principal exigem um período de contestação antes que a mensagem possa ser executada na cadeia principal.

O Arbitrum SDK cria novas redes Arbitrum?

O pacote principal @arbitrum/sdk é usado principalmente para fluxos de bridge e mensagens no nível do aplicativo, enquanto @arbitrum/chain-sdk é a ferramenta usada para criar e configurar redes Arbitrum.

Os usuários precisam instalar o Arbitrum SDK?

Usuários comuns não precisam instalar o Arbitrum SDK, pois os desenvolvedores o utilizam em carteiras, bridges, dashboards e aplicativos descentralizados.

Onde os desenvolvedores encontram recursos oficiais do Arbitrum SDK?

Os desenvolvedores podem consultar o repositório oficial do SDK, a página do pacote no npm e a documentação da Arbitrum sobre mensagens cross-chain.

Conclusão

Arbitrum SDK é um kit de ferramentas essencial para desenvolvedores que criam aplicativos cripto com bridges, mensagens e fluxos de transações cross-chain da Arbitrum.

Ele ajuda os desenvolvedores a interagir com contratos de bridge complexos por meio de classes TypeScript e métodos auxiliares mais simples.

Entre seus recursos mais importantes estão a transferência de ativos nativos por bridge, a transferência de tokens ERC-20, mensagens da cadeia principal para a secundária, acompanhamento de mensagens da cadeia secundária para a principal, suporte a tickets retryable e configuração de redes.

O Arbitrum SDK v4 é especialmente importante porque reflete o modelo mais amplo de cadeia principal e cadeia secundária usado nas implantações modernas da Arbitrum.

Para os usuários, o SDK pode proporcionar experiências de bridge mais simples e um acompanhamento mais claro das transações.

Para os desenvolvedores, ele reduz o trabalho de integração de baixo nível, mas ainda exige testes cuidadosos, revisão de segurança e comunicação clara com os usuários.

À medida que a Arbitrum continua oferecendo suporte a mais aplicativos e ambientes de redes dedicadas, o Arbitrum SDK permanece como uma das principais ferramentas para conectar produtos cripto ao ecossistema Arbitrum.