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:
declare module '../../registry.js' {
export namespace WormholeRegistry {
interface ProtocolToInterfaceMapping<N, C> {
TokenBridge: TokenBridge<N, C>;
}
interface ProtocolToPlatformMapping {
TokenBridge: EmptyPlatformMap<'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:
declare module '@wormhole-foundation/sdk-connect' {
export namespace WormholeRegistry {
interface PlatformToNativeAddressMapping {
Evm: EvmAddress;
}
}
}
registerNative(_platform, EvmAddress);
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
:
export const transferWithPayloadLayout = <
const P extends CustomizableBytes = undefined
>(
customPayload?: P
) =>
[
payloadIdItem(3),
...transferCommonLayout,
{ name: 'from', ...universalAddressItem },
customizableBytes({ name: 'payload' }, customPayload),
] as const;
Registrar Payloads: Utilize
registerPayloadTypes
para mapear literais de payload a seus layouts:
registerPayloadTypes('NomeDoProtocolo', payloadsNomeadosDoProtocolo);
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:
const layout = getPayloadLayout('NomeDoProtocolo:NomeDoPayload');
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:
export const payloadFactory = new Map<LayoutLiteral, Layout>();
export function registerPayloadType(
protocol: ProtocolName,
name: string,
layout: Layout
) {
const payloadLiteral = composeLiteral(protocol, name);
if (payloadFactory.has(payloadLiteral)) {
throw new Error(`Payload type ${payloadLiteral} already registered`);
}
payloadFactory.set(payloadLiteral, layout);
}
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:
export function layoutDiscriminator<B extends boolean = false>(
layouts: readonly Layout[],
allowAmbiguous?: B
): Discriminator<B> {
const [distinguishable, discriminator] = internalBuildDiscriminator(layouts);
if (!distinguishable && !allowAmbiguous) {
throw new Error('Cannot uniquely distinguish the given layouts');
}
return (
!allowAmbiguous
? (encoded: BytesType) => {
const layout = discriminator(encoded);
return layout.length === 0 ? null : layout[0];
}
: discriminator
) as Discriminator<B>;
}
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
:
export const transferWithPayloadLayout = <
const P extends CustomizableBytes = undefined
>(
customPayload?: P
) =>
[
payloadIdItem(3),
...transferCommonLayout,
{ name: 'from', ...universalAddressItem },
customizableBytes({ name: 'payload' }, customPayload),
] as const;
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:
const tokenBridgePayloads = ['Transfer', 'TransferWithPayload'] as const;
export const getTransferDiscriminator = lazyInstantiate(() =>
payloadDiscriminator([_protocol, tokenBridgePayloads])
);
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:
declare module '../../registry.js' {
export namespace WormholeRegistry {
interface PayloadLiteralToLayoutMapping
extends RegisterPayloadTypes<
'TokenBridge',
typeof tokenBridgeNamedPayloads
> {}
}
}
registerPayloadTypes('TokenBridge', tokenBridgeNamedPayloads);
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