Solidity SDK

O Wormhole Solidity SDK simplifica a comunicação cross-chain em redes compatíveis com EVM, fornecendo interfaces essenciais em Solidity, bibliotecas utilitárias e ferramentas de teste. Ele permite que os desenvolvedores construam aplicativos descentralizados (dApps) cross-chain seguros e eficientes sem a necessidade de interação manual com os contratos principais do Wormhole em várias blockchains.

Ao abstrair interações complexas, o SDK reduz drasticamente o custo operacional associado ao desenvolvimento cross-chain. Ele oferece:

Interfaces Unificadas - os desenvolvedores podem usar um conjunto padronizado de interfaces Solidity para lidar com mensagens cross-chain, transferências de tokens e aprovações de ações verificáveis (VAAs), sem precisar gerenciar a infraestrutura subjacente. Entrega Automática de Mensagens - o SDK aproveita a infraestrutura de retransmissor do Wormhole, entregando automaticamente mensagens entre as blockchains, reduzindo a necessidade de intervenção manual e simplificando a gestão de gás na blockchain de destino. Integração Transparente com os Serviços Wormhole - o SDK se integra com o TokenBridge do Wormhole e o CCTP da Circle, oferecendo mecanismos integrados para transferências de ativos cross-chain, facilitando a implementação de pontes de tokens e mensagens cross-chain. Ferramentas de Testes e Desenvolvimento - inclui ferramentas abrangentes para testes locais e simulação, permitindo que os desenvolvedores validem a lógica cross-chain antes do lançamento, minimizando o risco de erros em ambientes de produção.

Esses recursos otimizam significativamente o fluxo de trabalho de desenvolvimento, reduzindo a complexidade e oferecendo ferramentas compatíveis com várias versões do EVM. Isso ajuda os desenvolvedores a evitar problemas causados por diferenças de equivalência EVM entre as blockchains.

Instalação Para instalar o SDK, use o Foundry e Forge. Isso irá adicionar as bibliotecas necessárias ao seu projeto:

forge install wormhole-foundation/wormhole-solidity-sdk@v0.1.0

Ao desenvolver aplicativos cross-chain, verifique se as blockchains que você está segmentando são compatíveis com a versão do EVM que está utilizando. Por exemplo, o opcode PUSH0 (introduzido no Solidity 0.8.20) pode não estar disponível em todas as blockchains. Para evitar problemas de compatibilidade, você pode definir a versão do EVM no seu arquivo foundry.toml:

evm_version = "paris"

Isso garante compatibilidade entre todas as blockchains segmentadas, mesmo que algumas ainda não suportem as atualizações mais recentes do EVM.

Considerações Importantes Antes de implantar aplicativos usando o Wormhole Solidity SDK, tenha em mente as seguintes considerações:

• Compatibilidade de versão - o SDK está em evolução, sendo crucial usar versões com tags para produção, pois o ramo principal pode introduzir alterações incompatíveis.

• Remapeamento de IERC-20 - o SDK fornece um mecanismo de remapeamento para lidar com conflitos entre diferentes implementações do IERC-20, garantindo integração tranquila com outras bibliotecas.

• Testes - devido às dependências cross-chain, é fundamental testar todas as integrações para evitar problemas em ambientes de produção.

Conceitos e Componentes O Wormhole Solidity SDK consiste em componentes essenciais que facilitam a comunicação cross-chain, permitindo que os desenvolvedores interajam com a infraestrutura do Wormhole de forma segura e eficiente. Abaixo estão os principais conceitos e contratos com os quais você lidará ao trabalhar com o SDK.

Mensagens Cross-Chain com o Wormhole Relayer SDK O contrato WormholeRelayerSDK.sol simplifica a comunicação cross-chain e transferências de ativos, integrando vários módulos necessários, incluindo o relayer do Wormhole. Ao automatizar a entrega de mensagens entre as blockchains, o relayer do Wormhole elimina a necessidade de os desenvolvedores gerenciarem a infraestrutura de relayers ou lidarem com o gás na blockchain de destino. Os provedores de entrega cuidam do payload da mensagem, garantindo comunicação segura e eficiente.

Você pode consultar a documentação do relayer do Wormhole para mais detalhes.

Principais módulos do SDK incluem:

• Base.sol - o módulo central para comunicação cross-chain. Ele fornece funções utilitárias como onlyWormholeRelayer() e setRegisteredSender(), garantindo que apenas mensagens de relayers confiáveis sejam processadas.

• TokenBase.sol - este módulo expande a funcionalidade de mensagens básicas para suportar transferências de tokens cross-chain, incluindo utilitários para enviar e receber tokens de forma segura entre blockchains compatíveis com EVM.

• CCTPBase.sol - projetado para o Cross-Chain Transfer Protocol (CCTP) da Circle, este módulo gerencia transferências de ativos, como USDC, entre blockchains, incluindo funcionalidades para enviar e receber ativos baseados em CCTP.

• CCTPAndTokenBase.sol - um módulo combinado que suporta transferências de tokens e ativos baseados em CCTP em uma única implementação, simplificando o desenvolvimento para aplicativos que precisam lidar com ambos os tipos de transferências.

O Wormhole Solidity SDK oferece uma estrutura unificada para comunicação cross-chain. Os desenvolvedores podem selecionar módulos específicos com base nos requisitos de seu aplicativo, seja para mensagens, transferências de tokens ou CCTP. Cada módulo inclui medidas de segurança integradas, garantindo que apenas remetentes ou relayers autorizados sejam aceitos, protegendo o aplicativo contra interações não autorizadas.

Base Contract Overview O contrato Base.sol é uma parte fundamental do Wormhole Solidity SDK, fornecendo funções auxiliares essenciais e modificadores para gerenciar mensagens cross-chain de forma segura via o Wormhole Relayer. Ele lida com o registro de remetentes e validação de mensagens, garantindo que apenas remetentes autorizados de blockchains específicas possam enviar mensagens.

• onlyWormholeRelayer() - um modificador que garante que apenas mensagens autorizadas do contrato relayer do Wormhole sejam processadas, restringindo o acesso a certas funções.

modifier onlyWormholeRelayer() {
    require(
        msg.sender == address(wormholeRelayer),
        "Msg.sender is not Wormhole Relayer"
    );
    _;
}

• setRegisteredSender() - restringe a aceitação de mensagens a um remetente registrado de uma blockchain específica, garantindo que as mensagens sejam processadas apenas de fontes confiáveis.

function setRegisteredSender(
    uint16 sourceChain,
    bytes32 sourceAddress
) public {
    require(
        msg.sender == registrationOwner,
        "Not allowed to set registered sender"
    );
    registeredSenders[sourceChain] = sourceAddress;
}

Essas medidas de segurança garantem que as mensagens venham da fonte correta e sejam processadas de forma segura. Consulte o contrato completo Base.sol abaixo para mais detalhes.

Base.sol

// SPDX-License-Identifier: Apache 2
pragma solidity ^0.8.19;

import "wormhole-sdk/interfaces/IWormholeReceiver.sol";
import "wormhole-sdk/interfaces/IWormholeRelayer.sol";
import "wormhole-sdk/interfaces/IWormhole.sol";
import "wormhole-sdk/Utils.sol";

abstract contract Base {
    IWormholeRelayer public immutable wormholeRelayer;
    IWormhole public immutable wormhole;

    address registrationOwner;
    mapping(uint16 => bytes32) registeredSenders;

    constructor(address _wormholeRelayer, address _wormhole) {
        wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
        wormhole = IWormhole(_wormhole);
        registrationOwner = msg.sender;
    }

    modifier onlyWormholeRelayer() {
        require(
            msg.sender == address(wormholeRelayer),
            "Msg.sender is not Wormhole Relayer"
        );
        _;
    }

    modifier isRegisteredSender(uint16 sourceChain, bytes32 sourceAddress) {
        require(
            registeredSenders[sourceChain] == sourceAddress,
            "Not registered sender"
        );
        _;
    }

    /**
     * Sets the registered address for 'sourceChain' to 'sourceAddress'
     * So that for messages from 'sourceChain', only ones from 'sourceAddress' are valid
     *
     * Assumes only one sender per chain is valid
     * Sender is the address that called 'send' on the Wormhole Relayer contract on the source chain)
     */
    function setRegisteredSender(
        uint16 sourceChain,
        bytes32 sourceAddress
    ) public {
        require(
            msg.sender == registrationOwner,
            "Not allowed to set registered sender"
        );
        registeredSenders[sourceChain] = sourceAddress;
    }
}

Interface para Mensagens Cross-Chain

O SDK Solidity do Wormhole interage com o relayer do Wormhole para enviar e receber mensagens entre cadeias compatíveis com EVM. As interfaces IWormholeRelayer e IWormholeReceiver são centrais para a comunicação cross-chain, permitindo a entrega de mensagens de forma segura e eficiente.

Para informações detalhadas sobre como implementar essas interfaces, consulte a documentação das Interfaces do Relayer do Wormhole. Esta seção cobre:

• IWormholeRelayer – Métodos para enviar mensagens cross-chain, VAAs e transferências de tokens.

• IWormholeReceiver – A implementação necessária para receber mensagens cross-chain.

• quoteEVMDeliveryPrice() – Como estimar gás e taxas para transações cross-chain.

Essas interfaces reduzem a complexidade do desenvolvimento de dApps cross-chain ao abstrair os detalhes da infraestrutura de relayer, garantindo que a entrega de mensagens seja tratada de maneira eficiente.

Conceitos Avançados

Para desenvolvedores interessados em explorar tópicos avançados, as seguintes seções oferecem insights sobre aspectos chave da funcionalidade do SDK.

Manipulação de Erros e Revertimentos

O SDK define vários erros personalizados para ajudar os desenvolvedores a lidar com problemas comuns, como taxas de gás incorretas, remetentes inválidos e mais. Por exemplo, InvalidMsgValue é disparado quando o valor da mensagem para uma mensagem enviada é incorreto.

error InvalidMsgValue(uint256 msgValue, uint256 totalFee);

Uso

Esta seção cobre mensagens cross-chain e transferências de tokens, mostrando como usar o SDK Solidity do Wormhole em cenários reais.

Enviar uma Mensagem Cross-Chain

Para enviar uma mensagem cross-chain, herde do contrato base fornecido pelo SDK e use seus métodos auxiliares para definir sua mensagem e endereço do remetente. Aqui está um exemplo básico:

pragma solidity ^0.8.19;

import "@wormhole-foundation/wormhole-solidity-sdk/src/WormholeRelayer/Base.sol";

contract CrossChainSender is Base {
    constructor(
        address _wormholeRelayer,
        address _wormhole
    ) Base(_wormholeRelayer, _wormhole) {}

    function sendMessage(
        bytes memory message,
        uint16 targetChain,
        bytes32 targetAddress
    ) external payable {
        // Registrar o remetente e enviar mensagem através do WormholeRelayer
        setRegisteredSender(targetChain, msg.sender);
        onlyWormholeRelayer().sendPayloadToEvm(
            targetChain,
            address(targetAddress),
            message,
            0,
            500_000
        );
    }
}

Este contrato estende o Base.sol e permite o envio seguro de mensagens cross-chain utilizando o WormholeRelayer.

Enviar Tokens Entre Cadeias

O SDK permite transferências de tokens de forma fluida entre cadeias compatíveis com EVM, além do envio de mensagens. Para facilitar as transferências de tokens cross-chain, você pode estender os contratos base TokenSender e TokenReceiver do SDK.

pragma solidity ^0.8.19;

import "@wormhole-foundation/wormhole-solidity-sdk/src/WormholeRelayer/TokenBase.sol";

contract CrossChainTokenSender is TokenSender {
    constructor(
        address _wormholeRelayer,
        address _wormhole
    ) TokenSender(_wormholeRelayer, _wormhole) {}

    function sendToken(
        address token,
        uint256 amount,
        uint16 targetChain,
        bytes32 targetAddress
    ) external payable {
        // Enviar tokens entre as cadeias
        transferTokenToTarget(token, amount, targetChain, targetAddress);
    }
}

Neste exemplo, TokenSender inicia uma transferência de tokens para outra cadeia. As utilidades internas do SDK tratam a transferência de tokens de forma segura, garantindo que os VAAs sejam gerados e processados corretamente.

Receber Tokens Entre Cadeias

Para receber tokens na cadeia de destino, implemente um contrato que herde de TokenReceiver e sobrescreva a função receiveWormholeMessages.

pragma solidity ^0.8.19;

import "@wormhole-foundation/wormhole-solidity-sdk/src/WormholeRelayer/TokenBase.sol";

contract CrossChainTokenReceiver is TokenReceiver {
    constructor(
        address _wormholeRelayer,
        address _wormhole
    ) TokenReceiver(_wormholeRelayer, _wormhole) {}

    // Função para lidar com tokens recebidos de outra cadeia
    function receiveWormholeMessages(
        bytes memory payload,
        bytes[] memory additionalMessages,
        bytes32 sourceAddress,
        uint16 sourceChain,
        bytes32 deliveryHash
    ) external payable override {
        // Processar os tokens recebidos aqui
        receiveTokens(payload);
    }
}

Neste exemplo, TokenReceiver permite que o contrato lide com tokens enviados da cadeia de origem. Assim que a mensagem cross-chain for recebida, a função receiveWormholeMessages processa os tokens recebidos. Sempre valide a autenticidade e a origem da mensagem.

Nota

Sempre verifique a origem das mensagens e tokens recebidos para evitar o acesso não autorizado ao seu contrato. Consulte a seção de Verificação do Emissor para mais detalhes.

Ambiente de Testes

O SDK inclui suporte nativo para testes baseados no Forge, permitindo testar suas aplicações cross-chain localmente antes de implantá-las em produção. Recomenda-se testar com a mesma versão do compilador Solidity e configuração que você planeja usar em produção, para detectar possíveis problemas cedo.

Para um exemplo detalhado, consulte os repositórios abaixo:

• Mensagens cross-chain
• Transferência de tokens cross-chain