Construção de Protocolos e Payloads

Construção de Protocolos e Payloads Introdução O SDK TypeScript do Wormhole fornece um sistema flexível e poderoso para integrar a comunicação cross-chain em suas aplicações. Uma característica chave do SDK é sua 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 irá ajudá-lo a entender como construir protocolos e payloads no SDK, cobrindo:

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 para garantir compatibilidade e confiabilidade
Exemplos do mundo real utilizando 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 SDK do Wormhole, um protocolo representa uma funcionalidade ou característica significativa que opera em várias blockchains. Protocolos fornecem a estrutura para lidar com 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 relatar payloads
NTT (Native Token Transfers) - gerencia o movimento de tokens nativos entre blockchains

Os protocolos são definidos por:

Um nome - um identificador string (por exemplo, TokenBridge, Ntt)
Um conjunto de payloads - estes representam as ações ou mensagens específicas suportadas pelo protocolo, como Transfer ou TransferWithPayload

Cada protocolo é registrado no SDK do Wormhole, permitindo que os desenvolvedores aproveitem seus recursos predefinidos ou o estendam com payloads personalizados.

O que é um Payload? Um payload é um pedaço estruturado 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 cross-chain complexas.

Cada payload é definido como:

Um layout - descreve o formato binário dos campos do payload
Um literal - combina o nome do protocolo e o nome do payload em um identificador único (por exemplo, TokenBridge:Transfer)

Ao registrar payloads, os desenvolvedores podem garantir a segurança de tipos e permitir a 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 tipo precisa. Por exemplo, no protocolo TokenBridge:

O protocolo é registrado sob o namespace TokenBridge
Payloads como Transfer ou AttestMeta são vinculados ao protocolo para lidar com operações específicas

Entender 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 enquanto mantém 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 através das redes (N) e blockchains (C). Isso garante segurança de tipo, semelhante ao forte tipagem, ao evitar erros de execução se as definições do protocolo estiverem incorretas.
Vinculação de protocolos a plataformas - especifica implementações específicas da plataforma, se necessário, ou usa mapeamentos padrão para protocolos agnósticos à plataforma

Por exemplo, aqui está 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 requerem comportamentos específicos de plataforma. Por exemplo, o Wormhole Registry compatível com EVM mapeia endereços nativos para blockchains 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 da plataforma EVM para mais detalhes.

Registrar Payloads O registro de payloads permite que os desenvolvedores definam, serializem e manipulem tipos personalizados de mensagens dentro de seus protocolos. Ele estabelece a conexão entre um protocolo e seus payloads, garantindo integração perfeita, segurança de tipos e eficiência de tempo de execução.

Este processo vincula um protocolo aos seus payloads usando uma combinação de:

Literais de Payload - identificadores únicos no formato <ProtocolName>:<PayloadName>. Esses literais mapeiam cada payload para um layout
Layouts de Payload - estruturas que definem a representação binária dos dados do payload
A fábrica de payloads - um registro centralizado de tempo de execução que mapeia literais de payload para layouts para resolução dinâmica e serialização

Esses componentes trabalham juntos para simplificar a definição e o gerenciamento dos payloads do protocolo.

Como o Registro de Payloads Funciona O registro de payloads envolve:

Definir layouts de payload - criar 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 - usar registerPayloadTypes para mapear literais de payload para seus layouts:

registerPayloadTypes('ProtocolName', protocolNamedPayloads);

Acessar payloads registrados - usar a função getPayloadLayout para buscar o layout de um literal de payload específico. Esse método garante que o layout correto seja recuperado dinamicamente e de forma segura:

const layout = getPayloadLayout('ProtocolName:PayloadName');

Essas etapas vinculam literais de payload aos seus layouts, permitindo o manuseio dinâmico no tempo de execução.

A Fábrica de Payloads No núcleo 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 para seu layout de forma única. A função registerPayloadType adiciona payloads individuais, enquanto registerPayloadTypes suporta o registro em massa.

Essa implementação garante manuseio dinâmico e eficiente de payloads no tempo de execução.

Integrar Protocolos com Payloads Integrar payloads com protocolos permite identificação dinâmica através de literais de payload, enquanto a serialização e desserialização garantem que sua representação binária seja compatível entre blockchains.

Discriminadores de Payload Discriminadores de payload são mecanismos no SDK do Wormhole que identificam dinamicamente e mapeiam payloads recebidos para seus respectivos layouts no tempo de execução. Eles são relevantes para protocolos como o TokenBridge, permitindo o manuseio eficiente de tipos diversos de payloads enquanto garantem segurança de tipos e integração consistente.

Como os Discriminadores Funcionam Os discriminadores avaliam dados binários serializados e determinam o layout correspondente ao inspecionar campos fixos ou padrões dentro dos dados. Cada layout de payload está associado a um literal de payload (por exemplo, TokenBridge:Transfer ou TokenBridge:TransferWithPayload).

Esse sistema garante:

Identificação dinâmica no tempo de execução - os payloads são analisados com base no seu conteúdo, mesmo que um único protocolo manipule múltiplos tipos de payloads
Garantia estrita de tipos - os discriminadores usam mapeamentos de layout para evitar 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> {
  // Lógica interna para determinar layouts distinguíveis
  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 apropriado para um payload serializado fornecido. O parâmetro allowAmbiguous determina se layouts com características sobrepostas são permitidos.

Exemplo Real: Protocolo Token Bridge Integrar protocolos com seus respectivos payloads exemplifica como o SDK do Wormhole aproveita layouts e mecanismos de registro seguros de tipos para garantir comunicação cross-chain eficiente. Esta seção foca em como protocolos como o TokenBridge usam payloads para facilitar operações específicas.

Token Bridge Protocol e Payloads O protocolo TokenBridge permite transferências de tokens cross-chain através de seus payloads. Payloads chave incluem:

Transfer - lida com operações básicas de transferência de tokens
TransferWithPayload - estende o payload Transfer para incluir dados personalizados, aprimorando a funcionalidade

Payloads são registrados no protocolo TokenBridge via a interface PayloadLiteralToLayoutMapping, que vincula literais de payload (por exemplo, TokenBridge:Transfer) aos seus layouts.

Além disso, o protocolo usa layouts reutilizáveis como transferCommonLayout e os estende em layouts mais especializados, como transferWithPayloadLayout.

Usar o Discriminador Para gerenciar múltiplos payloads, o protocolo TokenBridge utiliza um discriminador para distinguir entre tipos de payloads dinamicamente. Por exemplo:

const tokenBridgePayloads = ['Transfer', 'TransferWithPayload'] as const;

export const getTransferDiscriminator = lazyInstantiate(() =>
  payloadDiscriminator([_protocol, tokenBridgePayloads])
);

A função getTransferDiscriminator avalia dinamicamente payloads usando layouts predefinidos, garantindo que cada tipo de payload seja processado de acordo com sua estrutura única e layout seguro de tipos.

Registrar Payloads no Protocolo Aqui Construção de Protocolos e Payloads Introdução O SDK TypeScript do Wormhole fornece um sistema flexível e poderoso para integrar a comunicação cross-chain em suas aplicações. Uma característica chave do SDK é sua 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 irá ajudá-lo a entender como construir protocolos e payloads no SDK, cobrindo:

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 para garantir compatibilidade e confiabilidade
Exemplos do mundo real utilizando 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.

Exemplos de Protocolos:

TokenBridge - permite transferências de tokens cross-chain, incluindo operações como transferir tokens e relatar payloads
NTT (Native Token Transfers) - gerencia o movimento de tokens nativos entre blockchains

Os protocolos são definidos por:

Um nome - um identificador string (por exemplo, TokenBridge, Ntt)
Um conjunto de payloads - estes representam as ações ou mensagens específicas suportadas pelo protocolo, como Transfer ou TransferWithPayload

Cada protocolo é registrado no SDK do Wormhole, permitindo que os desenvolvedores aproveitem seus recursos predefinidos ou o estendam com payloads personalizados.

Cada payload é definido como:

Um layout - descreve o formato binário dos campos do payload
Um literal - combina o nome do protocolo e o nome do payload em um identificador único (por exemplo, TokenBridge:Transfer)

Ao registrar payloads, os desenvolvedores podem garantir a segurança de tipos e permitir a 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 tipo precisa. Por exemplo, no protocolo TokenBridge:

O protocolo é registrado sob o namespace TokenBridge
Payloads como Transfer ou AttestMeta são vinculados ao protocolo para lidar com operações específicas

Entender a conexão entre esses componentes é importante para personalizar ou estender o SDK conforme suas necessidades.

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 através das redes (N) e blockchains (C). Isso garante segurança de tipo, semelhante ao forte tipagem, ao evitar erros de execução se as definições do protocolo estiverem incorretas.
Vinculação de protocolos a plataformas - especifica implementações específicas da plataforma, se necessário, ou usa mapeamentos padrão para protocolos agnósticos à plataforma

Por exemplo, aqui está 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.

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 da plataforma EVM para mais detalhes.

Este processo vincula um protocolo aos seus payloads usando uma combinação de:

Literais de Payload - identificadores únicos no formato <ProtocolName>:<PayloadName>. Esses literais mapeiam cada payload para um layout
Layouts de Payload - estruturas que definem a representação binária dos dados do payload
A fábrica de payloads - um registro centralizado de tempo de execução que mapeia literais de payload para layouts para resolução dinâmica e serialização

Esses componentes trabalham juntos para simplificar a definição e o gerenciamento dos payloads do protocolo.

Como o Registro de Payloads Funciona O registro de payloads envolve:

Definir layouts de payload - criar 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 - usar registerPayloadTypes para mapear literais de payload para seus layouts:

registerPayloadTypes('ProtocolName', protocolNamedPayloads);

Acessar payloads registrados - usar a função getPayloadLayout para buscar o layout de um literal de payload específico. Esse método garante que o layout correto seja recuperado dinamicamente e de forma segura:

const layout = getPayloadLayout('ProtocolName:PayloadName');

Essas etapas vinculam literais de payload aos seus layouts, permitindo o manuseio dinâmico no tempo de execução.

A Fábrica de Payloads No núcleo 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);
}

Essa implementação garante manuseio dinâmico e eficiente de payloads no tempo de execução.

Esse sistema garante:

Identificação dinâmica no tempo de execução - os payloads são analisados com base no seu conteúdo, mesmo que um único protocolo manipule múltiplos tipos de payloads
Garantia estrita de tipos - os discriminadores usam mapeamentos de layout para evitar 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> {
  // Lógica interna para determinar layouts distinguíveis
  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>;
}

Token Bridge Protocol e Payloads O protocolo TokenBridge permite transferências de tokens cross-chain através de seus payloads. Payloads chave incluem:

Transfer - lida com operações básicas de transferência de tokens
TransferWithPayload - estende o payload Transfer para incluir dados personalizados, aprimorando a funcionalidade

Payloads são registrados no protocolo TokenBridge via a interface PayloadLiteralToLayoutMapping, que vincula literais de payload (por exemplo, TokenBridge:Transfer) aos seus layouts.

Além disso, o protocolo usa layouts reutilizáveis como transferCommonLayout e os estende em layouts mais especializados, como transferWithPayloadLayout.

Usar o Discriminador Para gerenciar múltiplos payloads, o protocolo TokenBridge utiliza um discriminador para distinguir entre tipos de payloads dinamicamente. Por exemplo:

const tokenBridgePayloads = ['Transfer', 'TransferWithPayload'] as const;

export const getTransferDiscriminator = lazyInstantiate(() =>
  payloadDiscriminator([_protocol, tokenBridgePayloads])
);

Registrar Payloads no Protocolo Aqui está o exemplo de como o registro dos payloads TokenBridge é feito dentro do SDK:

registerPayloadTypes('TokenBridge', [
  'Transfer',
  'TransferWithPayload',
  'AttestMeta',
]);

Conclusão O SDK TypeScript do Wormhole fornece uma abordagem sólida e modular para lidar com a comunicação cross-chain. A definição e o registro de protocolos e payloads garantem segurança de tipos e extensibilidade, permitindo que desenvolvedores integrem funcionalidades complexas de forma eficiente e confiável. O uso de layouts e discriminadores assegura que a comunicação entre blockchains seja consistente, sem comprometer a performance ou segurança.

PreviousData Layouts NextQueries

Last updated 6 months ago