Construindo Protocolos e Payloads
O Wormhole TypeScript SDK fornece um sistema flexÃvel e poderoso para integrar comunicação cross-chain em suas aplicações. Uma caracterÃstica chave do SDK é a capacidade de definir protocolos—unidades modulares que representam funcionalidades distintas—e seus payloads associados, que encapsulam os dados necessários para operações especÃficas dentro desses protocolos.
Este guia ajudará você a entender como construir protocolos e payloads no SDK, abordando:
O papel dos protocolos e payloads na comunicação cross-chain
A mecânica do registro de protocolos e payloads usando o SDK
Melhores práticas para criar layouts fortemente tipados, garantindo compatibilidade e confiabilidade
Exemplos práticos usando o TokenBridge como implementação de referência
Ao final deste guia, você terá uma compreensão sólida de como definir, registrar e usar protocolos e payloads em seus projetos.
O que é um Protocolo?
No Wormhole SDK, um protocolo representa uma funcionalidade significativa que opera em várias blockchains. Os protocolos fornecem a estrutura para manipular tipos especÃficos de mensagens, transações ou operações de maneira consistente e padronizada.
Exemplos de Protocolos:
TokenBridge: permite transferências de tokens cross-chain, incluindo operações como transferir tokens e retransmitir payloads
NTT (Native Token Transfers): gerencia movimentações de tokens nativos entre chains
Os protocolos são definidos por:
Um nome: um identificador de string (ex: TokenBridge, Ntt)
Um conjunto de payloads: representam ações ou mensagens especÃficas suportadas pelo protocolo, como Transfer ou TransferWithPayload
Cada protocolo é registrado no Wormhole SDK, permitindo que os desenvolvedores aproveitem suas funcionalidades predefinidas ou estendam-no com payloads personalizados.
O que é um Payload?
Um payload é uma peça estruturada de dados que encapsula os detalhes de uma operação especÃfica dentro de um protocolo. Ele define o formato, campos e tipos de dados usados em uma mensagem ou transação. Payloads garantem consistência e segurança de tipos ao lidar com operações complexas cross-chain.
Cada payload é definido como:
Um layout: descreve o formato binário dos campos do payload
Um literal: combina o nome do protocolo e do payload em um identificador único (ex: TokenBridge:Transfer)
Ao registrar payloads, os desenvolvedores podem garantir segurança de tipos e habilitar serialização e desserialização para operações especÃficas do protocolo.
Registrar Protocolos e Payloads
Protocolos e payloads trabalham juntos para permitir a comunicação cross-chain com segurança de tipos precisa. Por exemplo, no protocolo TokenBridge:
O protocolo é registrado sob o namespace TokenBridge
Payloads como Transfer ou AttestMeta estão vinculados ao protocolo para tratar operações especÃficas
Compreender a conexão entre esses componentes é importante para personalizar ou estender o SDK conforme suas necessidades.
Registrar Protocolos
Registrar um protocolo estabelece sua conexão com a infraestrutura do Wormhole, garantindo que ele interaja perfeitamente com payloads e plataformas, mantendo segurança de tipos e consistência.
Como o Registro de Protocolos Funciona
O registro de protocolos envolve duas tarefas principais:
Mapeamento de protocolos para interfaces: conecta o protocolo à sua interface correspondente, definindo seu comportamento esperado entre redes (N) e chains (C). Isso garante segurança de tipos, semelhante ao strong typing, evitando erros em tempo de execução se as definições do protocolo estiverem incorretas
Vinculação de protocolos à s plataformas: especifica implementações especÃficas de plataforma, se necessário, ou utiliza mapeamentos padrão para protocolos independentes de plataforma
Por exemplo, o registro do protocolo TokenBridge:
Este trecho de código:
Mapeia o protocolo TokenBridge para sua interface, definindo como ele opera
Vincula o protocolo a um mapeamento de plataforma padrão via EmptyPlatformMap
Você pode ver a implementação completa no arquivo do protocolo TokenBridge.
Protocolos EspecÃficos de Plataforma
Alguns protocolos exigem comportamento especÃfico de plataforma. Por exemplo, o Wormhole Registry compatÃvel com EVM mapeia endereços nativos para chains baseadas em Ethereum:
Isso garante que EvmAddress seja registrado como o tipo de endereço nativo para plataformas compatÃveis com EVM. Veja o arquivo de endereços de plataforma EVM para mais detalhes.
Registro de Payloads
O registro de payloads permite que os desenvolvedores definam, serializem e gerenciem tipos de mensagens personalizados dentro de seus protocolos. Ele estabelece a conexão entre um protocolo e seus payloads, garantindo integração sem falhas, imposição de tipos e eficiência em tempo de execução.
Este processo vincula um protocolo aos seus payloads utilizando uma combinação de:
Literais de Payload: identificadores exclusivos no formato
<NomeDoProtocolo>:<NomeDoPayload>
. Esses literais mapeiam cada payload a um layout.Layouts de Payload: estruturas que definem a representação binária dos dados do payload.
A Fábrica de Payload: um registro centralizado em tempo de execução que mapeia literais de payloads a layouts para resolução e serialização dinâmica.
Esses componentes trabalham juntos para otimizar a definição e o gerenciamento dos payloads de protocolos.
Como Funciona o Registro de Payloads
O registro de payloads envolve os seguintes passos:
Definir Layouts de Payload: Crie layouts para estruturar seus payloads. Por exemplo, um protocolo pode usar um layout
TransferWithPayload
:
Registrar Payloads: Utilize
registerPayloadTypes
para mapear literais de payload a seus layouts:
Acessar Payloads Registrados: Use a função
getPayloadLayout
para recuperar o layout de um literal de payload especÃfico. Isso garante que o layout correto seja obtido de forma dinâmica e segura:
Esses passos vinculam os literais de payload aos seus layouts, permitindo um gerenciamento eficiente em tempo de execução.
A Fábrica de Payloads
No coração do processo de registro de payloads está a payloadFactory
, um registro que gerencia o mapeamento entre literais de payload e layouts:
A
payloadFactory
garante que cada literal de payload seja mapeado de forma única para seu layout.A função
registerPayloadType
adiciona payloads individuais, enquantoregisterPayloadTypes
suporta o registro em massa.Esta implementação assegura o manuseio dinâmico e eficiente de payloads em tempo de execução.
Integrando Protocolos com Payloads
Integrar payloads a protocolos permite a identificação dinâmica por meio de literais de payload, enquanto a serialização e desserialização asseguram que sua representação binária seja compatÃvel entre diferentes blockchains.
Discriminadores de Payloads
Os discriminadores de payload são mecanismos no SDK do Wormhole que identificam e mapeiam dinamicamente os payloads recebidos para seus respectivos layouts em tempo de execução. Eles são essenciais para protocolos como o TokenBridge, permitindo o manejo eficiente de diferentes tipos de payloads enquanto garantem a segurança de tipos e integração consistente.
Como Funciona o Discriminador
Discriminadores avaliam os dados binários serializados e determinam o layout correspondente do payload inspecionando campos ou padrões fixos nos dados. Cada layout de payload é associado a um literal de payload (ex.: TokenBridge:Transfer
ou TokenBridge:TransferWithPayload
).
Este sistema assegura:
Identificação dinâmica em tempo de execução: os payloads são analisados com base em seu conteúdo, mesmo que um único protocolo manipule múltiplos tipos de payload.
Imposição rÃgida de tipos: discriminadores utilizam mapeamentos de layouts para impedir que payloads inválidos sejam processados.
Aqui está um exemplo de como o SDK do Wormhole constrói um discriminador para distinguir entre layouts de payloads:
A função layoutDiscriminator
recebe uma lista de layouts e gera uma função que pode identificar o layout adequado para um dado payload serializado. O parâmetro allowAmbiguous
determina se layouts com caracterÃsticas sobrepondo podem ser permitidos.
Exemplo Real: Protocolo Token Bridge
Integrar protocolos aos seus respectivos payloads exemplifica como o SDK do Wormhole aproveita layouts e mecanismos de registro com segurança de tipo para garantir comunicação eficiente entre blockchains. Esta seção se concentra em como protocolos como o TokenBridge usam payloads para facilitar operações especÃficas.
Protocolo Token Bridge e Payloads
O protocolo TokenBridge permite transferências de tokens entre blockchains por meio de seus payloads. Alguns payloads importantes incluem:
Transfer: lida com operações básicas de transferência de tokens.
TransferWithPayload: estende o payload Transfer para incluir dados personalizados, ampliando sua funcionalidade.
Os payloads são registrados no protocolo TokenBridge via a interface PayloadLiteralToLayoutMapping
, que vincula literais de payload (ex.: TokenBridge:Transfer
) aos seus layouts.
Adicionalmente, o protocolo usa layouts reutilizáveis como transferCommonLayout
e os estende em layouts mais especializados, como transferWithPayloadLayout
:
Este layout inclui:
Um
payloadIdItem
para identificar o tipo de payload.Campos comuns para detalhes de tokens e destinatários.
Um campo de payload personalizável para dados adicionais.
Uso do Discriminador
Para gerenciar múltiplos payloads, o protocolo TokenBridge utiliza um discriminador para distinguir entre tipos de payload dinamicamente. Por exemplo:
A função getTransferDiscriminator
avalia dinamicamente os payloads usando layouts predefinidos, garantindo que cada tipo de payload seja processado de acordo com sua estrutura única e layout seguro.
Registrar Payloads nos Protocolos
Aqui está como o protocolo TokenBridge conecta seus payloads ao SDK do Wormhole:
Este registro vincula os literais de payload do TokenBridge aos seus respectivos layouts, habilitando a serialização e desserialização em tempo de execução.
Payloads do Token Bridge
Os seguintes payloads estão registrados para o protocolo TokenBridge:
AttestMeta: utilizado para atestação de metadados de tokens.
Transfer: facilita as transferências de tokens.
TransferWithPayload: adiciona um payload customizado às transferências de tokens.
Esses payloads e seus layouts são definidos no arquivo de layout do TokenBridge.
Outros Protocolos: Transferências de Tokens Nativos (NTT)
Embora este guia se concentre no protocolo TokenBridge, outros protocolos, como o NTT, seguem uma estrutura semelhante.
O NTT gerencia a transferência de tokens nativos entre blockchains.
Payloads como
WormholeTransfer
eWormholeTransferStandardRelayer
são registrados no protocolo utilizando os mesmos padrões para literais de payload e layouts.Os mesmos mecanismos de registro seguro de tipos e discriminadores de payload se aplicam, garantindo confiabilidade e extensibilidade.
Para mais detalhes, você pode explorar a implementação do NTT no SDK.
Last updated