Wormhole Relayer

Introdução Os relayers implantados pelo Wormhole fornecem um mecanismo para que contratos em uma blockchain enviem mensagens para contratos em outra, sem a necessidade de infraestrutura off-chain. Através do módulo de relayer do Wormhole, os desenvolvedores podem usar um provedor de entrega não confiável para transportar VAAs, eliminando a necessidade de construir e manter soluções de relaying personalizadas. A opção de executar um relayer personalizado está disponível para necessidades mais complexas.

Esta seção cobre os componentes e interfaces envolvidos no uso do módulo de relayer do Wormhole, como envio e recebimento de mensagens, garantias de entrega e considerações para construir aplicações cross-chain confiáveis e eficientes. Além disso, você encontrará detalhes sobre como lidar com cenários específicos de implementação e acompanhar o progresso da entrega de mensagens usando a ferramenta Wormhole CLI.

Começando com o Relayer Wormhole Antes de começar, é importante observar que a configuração do relayer implantado pelo Wormhole é atualmente limitada a ambientes EVM. A lista completa de blockchains nos ambientes EVM está na página de Redes Suportadas.

Para interagir com o relayer Wormhole, você precisará criar contratos nas blockchains de origem e destino para lidar com o envio e recebimento de mensagens. Não é necessário implementar lógica off-chain para aproveitar o relaying suportado pelo Wormhole.

Relayer Wormhole Os componentes destacados em azul devem ser implementados.

Interfaces do Relayer Wormhole Existem três interfaces relevantes para discutir ao utilizar o módulo de relayer do Wormhole:

• IWormholeRelayer: a interface principal pela qual você envia e recebe mensagens. Ela permite solicitar o envio de mensagens e VAAs.

• IWormholeReceiver: esta é a interface que você deve implementar. Ela permite que o provedor de entrega selecionado entregue mensagens/VAAs ao seu contrato.

• IDeliveryProvider: esta interface representa as informações de precificação de entrega para uma rede de relayers específica. Cada provedor de entrega implementa isso em cada blockchain que eles suportam para entrega.

Interagir com o Relayer Wormhole Para começar a interagir com o relayer Wormhole em seus contratos, você precisará importar a interface IWormholeRelayer e configurar uma referência usando o endereço do contrato para o relayer implantado pelo Wormhole na rede suportada de sua escolha.

Para integrar facilmente com a interface do relayer Wormhole, você pode usar o SDK Solidity do Wormhole.

Para recuperar o endereço do contrato do relayer Wormhole, consulte a seção de relayers na página de Endereços de Contrato.

Sua configuração inicial deve se parecer com o seguinte:

// SPDX-License-Identifier: MIT
pragma solidity ^0.8.26;

import "wormhole-solidity-sdk/interfaces/IWormholeRelayer.sol";

contract Example {
    IWormholeRelayer public wormholeRelayer;

    constructor(address _wormholeRelayer) {
        wormholeRelayer = IWormholeRelayer(_wormholeRelayer);
    }
}

O código fornecido configura a estrutura básica para que seu contrato interaja com o relayer Wormhole usando o endereço fornecido ao construtor. Ao utilizar métodos da interface IWormholeRelayer, você pode implementar funcionalidades de envio e recebimento de mensagens. As seções seguintes detalharão os métodos específicos que você precisará usar para essas tarefas.

Enviar uma Mensagem Para enviar uma mensagem para um contrato em outra blockchain EVM, você pode chamar o método sendPayloadToEvm fornecido pela interface IWormholeRelayer.

function sendPayloadToEvm(
    uint16 targetChain,     // ID da cadeia no formato Wormhole
    address targetAddress,  // Endereço do contrato na cadeia de destino
    bytes memory payload,   // Payload, codificado como bytes
    uint256 receiverValue,  // Quanto valor anexar à transação de entrega
    uint256 gasLimit        // Limite de gás para definir na transação de entrega
) external payable returns (
    uint64 sequence          // ID único e incremental, usado para identificar uma mensagem
);

O método sendPayloadToEvm é marcado como payable para receber o pagamento da taxa pela transação. O valor a ser anexado à invocação é determinado chamando o quoteEVMDeliveryPrice, que fornece uma estimativa do custo de gás na cadeia de destino.

function quoteEVMDeliveryPrice(
    uint16 targetChain,     // ID da cadeia no formato Wormhole
    uint256 receiverValue,  // Quanto valor anexar à transação de entrega
    uint256 gasLimit        // Limite de gás para anexar à transação de entrega
) external view returns (
    uint256 nativePriceQuote,  // Quanto valor anexar ao envio da chamada
    uint256 targetChainRefundPerGasUnused  // Reembolso por gás não utilizado na cadeia de destino
);

Este método deve ser chamado antes de enviar uma mensagem, e o valor retornado por nativePriceQuote deve ser anexado à chamada para enviar o payload para cobrir o custo da transação na cadeia de destino.

Em resumo, o envio de uma mensagem entre cadeias EVM pode ser tão simples quanto obter uma cotação de taxa e enviar a mensagem da seguinte forma:

// Obter uma cotação para o custo de gás da entrega
(cost, ) = wormholeRelayer.quoteEVMDeliveryPrice(
    targetChain,
    valueToSend,
    GAS_LIMIT
);

// Enviar a mensagem
wormholeRelayer.sendPayloadToEvm{value: cost}(
    targetChain,
    targetAddress,
    abi.encode(payload),
    valueToSend, 
    GAS_LIMIT
);

Receber uma Mensagem Para receber uma mensagem usando um relayer Wormhole, o contrato de destino deve implementar a interface IWormholeReceiver, como mostrado na seção anterior.

function receiveWormholeMessages(
    bytes memory payload,           // Mensagem passada pelo contrato de origem
    bytes[] memory additionalVaas,  // Quaisquer VAAs adicionais que sejam necessários (Nota: estas são não verificadas)
    bytes32 sourceAddress,          // Endereço do contrato de origem
    uint16 sourceChain,             // ID da cadeia Wormhole
    bytes32 deliveryHash            // Um hash dos conteúdos, útil para proteção contra replay
) external payable;

A lógica dentro do corpo da função pode ser qualquer lógica de negócios necessária para tomar ação no payload específico.

Garantias de Entrega O protocolo de relayer Wormhole tem como objetivo criar uma interface de serviço onde integradores e provedores de entrega mutuamente desconfiados possam trabalhar juntos para fornecer uma experiência contínua em dApps. Você não confia nos provedores de entrega com seus dados, e os provedores de entrega não confiam no seu contrato inteligente. O principal acordo entre os integradores e os provedores de entrega é que, quando uma entrega é solicitada, o provedor tentará entregar o VAA dentro do prazo de entrega estipulado pelo provedor.

Isso cria um mercado onde os provedores podem definir diferentes níveis de preço e garantias de serviço. Os provedores de entrega efetivamente aceitam o prêmio de risco de deslizamento ao entregar seus VAAs em troca de uma taxa fixa.

Status de Entrega Todas as entregas resultam em um dos seguintes quatro resultados antes do prazo de entrega do provedor. Quando ocorrem, esses resultados são emitidos como eventos EVM a partir do contrato relayer Wormhole. Os quatro possíveis resultados são:

(0) Sucesso da entrega (1) Falha do receptor (2) Sucesso da solicitação de encaminhamento (3) Falha da solicitação de encaminhamento

Falha do receptor é um cenário no qual o provedor selecionado tentou a entrega, mas não conseguiu completá-la com sucesso. As três possíveis causas para uma falha de entrega são:

• O contrato de destino não implementa a interface IWormholeReceiver

• O contrato de destino gerou uma exceção ou reverteu durante a execução de receiveWormholeMessages

• O contrato de destino excedeu o gasLimit especificado ao executar receiveWormholeMessages

Esses cenários podem ser evitados com o design correto por parte do integrador, e, portanto, cabe ao integrador resolvê-los. Qualquer outro cenário que cause uma entrega não realizada deve ser considerado uma falha em algum componente do sistema, incluindo, possivelmente, as próprias blockchains.

Sucesso da solicitação de encaminhamento e Falha da solicitação de encaminhamento representam quando a entrega foi bem-sucedida e o usuário solicitou um encaminhamento durante a entrega. Se o usuário tiver fundos suficientes para completar o encaminhamento, o encaminhamento será executado e o status será Sucesso da solicitação de encaminhamento. Caso contrário, será Falha da solicitação de encaminhamento.

Outras Considerações Alguns detalhes de implementação devem ser considerados durante o desenvolvimento para garantir segurança e uma boa experiência do usuário. Certifique-se de que seus esforços de engenharia consideraram adequadamente cada uma das seguintes áreas:

• Receber uma mensagem de um relayer

• Verificar o emissor esperado

• Chamar parseAndVerify em quaisquer VAAs adicionais

• Proteção contra replay

• Ordenação das mensagens (sem garantias sobre a ordem das mensagens entregues)

• Encaminhamento e encadeamento de chamadas

• Reembolso por pagamento excessivo de gasLimit

• Reembolso por pagamento excessivo de valor enviado

Acompanhar o Progresso das Mensagens com o Wormhole CLI Embora não sejam necessários programas off-chain, um desenvolvedor pode querer acompanhar o progresso das mensagens em trânsito. Para rastrear o progresso das mensagens em trânsito, use o comando status da ferramenta Wormhole CLI. Como exemplo, você pode usar os seguintes comandos para acompanhar o status de uma transferência, fornecendo o ambiente, a rede de origem e o hash da transação para o comando worm status:

Mainnet Testnet

worm status mainnet ethereum INSERT

_WORMHOLE_MSG_HASH