v1 Migration

Visão Geral A funcionalidade Wormhole Connect foi atualizada para a versão 1.0, trazendo um design modernizado e melhorias no roteamento para transferências de tokens nativo-a-nativo mais rápidas. Esta versão estável vem com várias mudanças que podem afetar a configuração do aplicativo, exigindo atualizações menores na sua integração.

Este guia ajudará você a migrar para a nova versão em apenas alguns passos simples. Ao seguir este guia de migração, você aprenderá a:

• Atualizar para o pacote mais recente do Connect

• Aplicar as alterações de configuração no objeto WormholeConnectConfig

• Compreender as novas capacidades de roteamento e opções de plugins

Essas atualizações garantem um melhor desempenho e uma experiência de integração mais suave.

Para a documentação completa sobre a versão anterior do Wormhole Connect, consulte o guia do Wormhole Connect.

Atualizar o Pacote Connect Para iniciar o processo de migração, atualize o pacote npm do Wormhole Connect para a versão mais recente 1.0. Atualizar para a versão mais recente proporciona acesso aos novos recursos e melhorias, incluindo o design modernizado e as capacidades de roteamento aprimoradas.

Execute o seguinte comando no seu terminal:

npm install @wormhole-foundation/wormhole-connect@^1.0

Este comando instala a versão estável mais recente do Wormhole Connect e prepara seu ambiente para as novas mudanças de configuração.

Atualizar o Objeto WormholeConnectConfig Na versão 1.0, o objeto WormholeConnectConfig passou por várias mudanças significativas. A maioria dessas mudanças são menores e podem ser aplicadas rapidamente. Abaixo está um resumo das principais alterações, seguido de exemplos detalhados.

Resumo das Mudanças Importantes

• Os nomes das chains agora estão capitalizados: solana → Solana

• A propriedade env foi renomeada para network e agora está capitalizada: mainnet → Mainnet

• networks foram renomeados para chains, com nomes capitalizados

• routes foram atualizados para usar plugins de rota

• nttGroups removidos em favor da configuração de plugins de rota

• tokensConfig atualizado, com uma nova chave wrappedTokens adicionada

• Muitas propriedades relacionadas à UI foram consolidadas sob uma chave ui de nível superior

• customTheme e mode foram removidos, substituídos por uma propriedade theme de nível superior

Essas mudanças são explicadas em mais detalhes abaixo, com exemplos para fácil referência.

Capitalizar os Nomes das Chains Na versão 1.0, os nomes das chains agora são consistentes com o tipo Chain do Wormhole TypeScript SDK e devem ser capitalizados. Isso afeta todas as propriedades de configuração onde uma chain é referenciada, incluindo rpcs, rest, graphql e chains.

v0.x

const config: WormholeConnectConfig = {
  rpcs: {
    ethereum: 'INSERT_ETH_RPC_URL',
    solana: 'INSERT_SOLANA_RPC_URL',
  },
};

v1.x

const config: WormholeConnectConfig = {
  rpcs: {
    Ethereum: 'INSERT_ETH_RPC_URL',
    Solana: 'INSERT_SOLANA_RPC_URL',
  },
};

Você pode encontrar a lista completa de nomes de chains suportados no Wormhole TypeScript SDK.

Renomear env para network A propriedade env foi renomeada para network, com valores capitalizados. Essa mudança afeta como você configura os ambientes Testnet e Mainnet.

v0.x

const config: WormholeConnectConfig = {
  env: 'testnet',
};

v1.x

const config: WormholeConnectConfig = {
  network: 'Testnet',
};

Se você não definir explicitamente o valor da rede, o Connect irá usar o valor padrão Mainnet.

// Defaults to Mainnet
const config: WormholeConnectConfig = {};

Para mais informações, consulte a lista de constantes de rede.

Renomear networks para chains A propriedade networks, que permitia a listagem de cadeias, agora foi renomeada para chains, e os nomes das cadeias são capitalizados.

v0.x v1.x

const config: WormholeConnectConfig = {
  networks: ['solana', 'ethereum'],
};

Atualizar rotas para usar plugins de rota A propriedade routes na versão 1.0 do Wormhole Connect foi significativamente aprimorada. Anteriormente, routes era uma simples lista de strings. A versão mais recente foi transformada em um sistema flexível de plugins, permitindo incluir rotas específicas para vários protocolos.

Por padrão, se a propriedade routes não for configurada, o Wormhole Connect fornecerá rotas para dois protocolos principais:

• Wormhole Token Bridge

• CCTP

Para a maioria dos casos de uso, os integradores precisam de mais do que as rotas padrão. A nova propriedade routes permite especificar quais protocolos incluir e excluir, assim como adicionar rotas de terceiros quando necessário.

Plugins de rota disponíveis O pacote @wormhole-foundation/wormhole-connect oferece uma variedade de plugins de rota para dar flexibilidade no manuseio de diferentes protocolos. Você pode escolher entre as seguintes opções de rota para sua integração:

• AutomaticCCTPRoute

• nttRoutes

• MayanRouteSWIFT

Além dessas rotas, os desenvolvedores podem criar rotas personalizadas para seus próprios protocolos baseados no Wormhole. Exemplos podem ser encontrados nos repositórios GitHub de NTT e Mayan.

Para mais detalhes sobre a interface de plugins de rota, consulte o código de rota no Wormhole TypeScript SDK.

Agora que você conhece os plugins de rota disponíveis, vamos explorar alguns exemplos de como configurá-los.

Exemplo: Oferecer Apenas Transferências CCTP Para configurar o Wormhole Connect para oferecer apenas transferências de USDC via a rota CCTP, utilize a seguinte configuração:

import WormholeConnect, {
  AutomaticCCTPRoute,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  routes: [AutomaticCCTPRoute],
};

<WormholeConnect config={config} />;

Exemplo: Oferecer Todas as Rotas Padrão e Plugins de Terceiros Neste exemplo, o Wormhole Connect é configurado com rotas para os protocolos padrão (Token Bridge e CCTP), assim como protocolos de terceiros como Native Token Transfers (NTT) e Mayan Swap.

import WormholeConnect, {
  DEFAULT_ROUTES,
  nttRoutes,
  MayanRouteSWIFT,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

import { myNttConfig } from './consts'; // Configuração personalizada de NTT

const config: WormholeConnectConfig = {
  routes: [...DEFAULT_ROUTES, ...nttRoutes(myNttConfig), MayanRouteSWIFT],
};

<WormholeConnect config={config} />;

Essa flexibilidade de plugin permite combinar rotas padrão (como Token Bridge e CCTP) com protocolos de terceiros, oferecendo controle completo sobre quais rotas estarão disponíveis na sua aplicação.

Atualizar a Estrutura de tokensConfig Na versão 1.0 do Wormhole Connect, a propriedade tokensConfig foi atualizada para simplificar a estrutura e melhorar a flexibilidade no manuseio de tokens entre cadeias. A configuração anterior foi simplificada e uma nova chave, wrappedTokens, foi introduzida para lidar melhor com ativos estrangeiros.

Mudanças principais no tokensConfig:

• Nomes de cadeias capitalizados - agora todos os nomes de cadeias, como ethereum, devem ser capitalizados, como Ethereum, para manter a consistência com o resto do SDK do Wormhole.

• wrappedTokens - essa nova chave substitui foreignAssets e define os endereços de tokens envoltos em cadeias estrangeiras, facilitando o gerenciamento de transferências entre cadeias.

• Decimais simplificados - ao invés de usar um mapa de valores decimais para diferentes cadeias, agora basta fornecer um valor de decimais para a cadeia nativa do token.

v0.x v1.x Na estrutura antiga, o campo foreignAssets definia a presença do token em outras cadeias e os decimais eram mapeados por várias cadeias.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  tokensConfig: {
    WETH: {
      key: 'WETH',
      symbol: 'WETH',
      nativeChain: 'ethereum',
      icon: Icon.ETH,
      tokenId: {
        chain: 'ethereum',
        address: '0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2',
      },
      coinGeckoId: 'ethereum',
      color: '#62688F',
      decimals: { Ethereum: 18, default: 8 },
      foreignAssets: {
        Solana: {
          address: '7vfCXTUXx5WJV5JADk17DUJ4ksgau7utNKj4b963voxs',
          decimals: 8,
        },
      },
    },
  },
};

Atualizar a Configuração de NTT Na versão 1.0 do Wormhole Connect, a propriedade nttGroups, que era usada para configurar Native Token Transfers (NTT), foi removida. Agora, a configuração do NTT é passada diretamente para o construtor da rota NTT. Essa atualização simplifica a configuração e proporciona mais flexibilidade ao definir rotas de NTT.

Mudanças principais:

• Remoção de nttGroups - a propriedade nttGroups foi removida da configuração e agora é passada como argumento para a função nttRoutes.

• Configuração direta da rota NTT - as rotas de NTT agora são definidas de maneira mais explícita, permitindo uma estrutura mais organizada ao especificar tokens, cadeias e gerenciadores.

Essa mudança simplifica o processo de configuração, proporcionando uma forma mais limpa e flexível de lidar com rotas de NTT entre diferentes cadeias.

v0.x v1.x Na versão anterior, nttGroups definia os gerenciadores de NTT e transceptores para diferentes tokens entre várias cadeias.

import WormholeConnect, {
  nttRoutes,
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  nttGroups: {
    Lido_wstETH: {
      nttManagers: [
        {
          chainName: 'ethereum',
          address: '0xb948a93827d68a82F6513Ad178964Da487fe2BD9',
          tokenKey: 'wstETH',
          transceivers: [
            {
              address: '0xA1ACC1e6edaB281Febd91E3515093F1DE81F25c0',
              type: 'wormhole',
            },
          ],
        },
        {
          chainName: 'bsc',
          address: '0x6981F5621691CBfE3DdD524dE71076b79F0A0278',
          tokenKey: 'wstETH',
          transceivers: [
            {
              address: '0xbe3F7e06872E0dF6CD7FF35B7aa4Bb1446DC9986',
              type: 'wormhole',
            },
          ],
        },
      ],
    },
  },
};

Atualização da Configuração da UI Na versão 1.0 do Wormhole Connect, a configuração da interface do usuário (UI) foi significativamente atualizada. Várias propriedades relacionadas à UI, que antes estavam espalhadas, agora foram consolidadas sob uma nova chave chamada ui, tornando a configuração da interface mais organizada e fácil de gerenciar.

Principais mudanças na UI:

• Propriedades da UI consolidadas: Muitas propriedades relacionadas à interface foram movidas para a nova chave ui de nível superior para melhor organização.

• Remoção de customTheme e mode: Essas propriedades foram removidas e substituídas por uma nova propriedade chamada theme, que simplifica a definição de temas e permite a troca dinâmica entre temas.

Propriedades da UI As seguintes propriedades, que antes eram definidas no nível raiz da configuração, agora fazem parte da chave ui:

• explorer → ui.explorer: Especifica o explorador a ser usado para visualizar transações.

• bridgeDefaults → ui.defaultInputs: Define os valores de entrada padrão para a ponte, como as cadeias de origem e destino e o token.

• pageHeader → ui.pageHeader: Define o título e o cabeçalho da página.

• menu → ui.menu: Define os itens do menu exibidos na interface.

• searchTx → ui.searchTx: Configura a funcionalidade de pesquisa de transações.

• partnerLogo → ui.partnerLogo: Exibe o logo de um parceiro na interface.

• walletConnectProjectId → ui.walletConnectProjectId: Integra o WalletConnect à interface.

• showHamburgerMenu → ui.showHamburgerMenu: Habilita ou desabilita o menu hambúrguer para navegação.

Além disso, existem duas novas propriedades sob ui:

• ui.title: Define o título exibido no canto superior esquerdo da UI. O valor padrão é "Wormhole Connect".

• ui.getHelpUrl: URL que será renderizada quando ocorrer um erro desconhecido, permitindo que os usuários busquem ajuda. Isso pode ser vinculado a um servidor do Discord ou a qualquer outro canal de suporte.

import WormholeConnect, {
  WormholeConnectConfig,
} from '@wormhole-foundation/wormhole-connect';

const config: WormholeConnectConfig = {
  ui: {
    title: 'My Custom Bridge Example',
    getHelpUrl: 'https://examplehelp.com/',
    menu: [
      {
        label: 'Support',
        href: 'https://examplehelp.com/support',
        target: '_blank',
        order: 1, // Ordem de aparecimento no menu
      },
      {
        label: 'About',
        href: 'https://examplehelp.com/about',
        target: '_blank',
        order: 2,
      },
    ],
    showHamburgerMenu: false,
  },
};

Remoção das Propriedades customTheme e mode Na versão 1.0, as propriedades customTheme e mode, que antes eram usadas para definir temas, foram removidas. Elas foram substituídas por uma nova propriedade de nível superior chamada theme, que oferece mais flexibilidade e atualizações dinâmicas para os temas.

Detalhes Importantes:

• A propriedade theme não faz parte do objeto de configuração e é passada separadamente para o Wormhole Connect.

• A configuração não pode ser modificada após o Wormhole Connect ser montado, mas o tema pode ser atualizado dinamicamente para suportar mudanças, como alternância entre os modos claro e escuro ou atualização de esquemas de cores.

const config: WormholeConnectConfig = {
  customTheme: {
    primaryColor: '#4266f5',
    secondaryColor: '#ff5733',
  },
  mode: 'dark',
};

<WormholeConnect config={config} />;

Propriedades Removidas Várias propriedades de configuração foram removidas na versão 1.0 do Wormhole Connect. Essas chaves não têm mais efeito, e fornecer valores para elas na configuração não resultará em alterações.

Propriedades removidas do config:

• cta

• cctpWarning

• pageSubHeader

• moreTokens

• moreChains

• ethBridgeMaxAmount

• wstETHBridgeMaxAmount

• customTheme

• mode

Se a sua configuração atual incluir alguma dessas propriedades, você pode removê-las com segurança, pois não são mais suportadas na versão 1.0.

Usando a Versão Hospedada no CDN do Wormhole Connect Para aqueles que estão utilizando a versão hospedada no CDN do Wormhole Connect, a instalação e a integração do pacote foram atualizadas. Agora, é necessário instalar o pacote Connect pelo npm e usar a nova função utilitária wormholeConnectHosted.

Instalar e Integrar a Versão Hospedada Instale o pacote Connect via npm:

npm install @wormhole-foundation/wormhole-connect@^1.0

Após a instalação do pacote, você pode incorporar o Wormhole Connect na sua página com o seguinte código:

import { wormholeConnectHosted } from '@wormhole-foundation/wormhole-connect';

const container = document.getElementById('connect')!;

wormholeConnectHosted(container);

Exemplo: Configuração Personalizada para a Versão Hospedada A função wormholeConnectHosted aceita dois parâmetros: config e theme. Isso permite personalizar as rotas e aplicar um tema diretamente na versão hospedada. Aqui está um exemplo de como passar uma configuração personalizada:

import {
  wormholeConnectHosted,
  MayanRoute,
} from '@wormhole-foundation/wormhole-connect';

const container = document.getElementById('connect')!;

wormholeConnectHosted(container, {
  config: {
    routes: [MayanRoute],
    eventHandler: (e) => {
      console.log('Connect event', e);
    },
  },
  theme: {
    background: {
      default: '#004547',
    },
  },
});

Neste exemplo, o objeto config define as rotas (neste caso, usando a rota Mayan), enquanto o objeto theme permite personalizar a interface do Connect (por exemplo, cor de fundo).