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:

  1. 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;

  1. Registrar Payloads: Utilize registerPayloadTypes para mapear literais de payload a seus layouts:

registerPayloadTypes('NomeDoProtocolo', payloadsNomeadosDoProtocolo);

  1. 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, enquanto registerPayloadTypes 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 e WormholeTransferStandardRelayer 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.

PreviousData LayoutsNextSolidity SDK

Last updated