Transferir USDC via CCTP

Neste guia, mostraremos como transferir USDC nativo entre diferentes redes blockchain utilizando o Protocolo de Transferência entre Cadeias (CCTP) da Circle e o Wormhole TypeScript SDK.

Tradicionalmente, transferências entre cadeias usando o CCTP envolvem várias etapas manuais, como iniciar a transferência na cadeia de origem, transmitir mensagens entre as cadeias e cobrir taxas de gás nas cadeias de origem e destino. Sem o TypeScript SDK, os desenvolvedores precisam lidar com essas operações independentemente, o que adiciona complexidade e aumenta a chance de erros, especialmente ao lidar com o pagamento de taxas de gás na cadeia de destino e a gestão do token nativo de gás.

O Wormhole TypeScript SDK simplifica esse processo oferecendo envio automatizado de transferências e o gerenciamento das taxas de gás na cadeia de destino. Ele também oferece a opção de incluir tokens nativos de gás para uma execução contínua. Isso reduz o custo para o desenvolvedor, torna as transferências mais rápidas e confiáveis, além de melhorar a experiência do usuário.

Neste guia, exploraremos primeiro a teoria por trás do CCTP e, em seguida, forneceremos um tutorial passo a passo para integrar o Wormhole TypeScript SDK no seu aplicativo, facilitando transferências de USDC entre múltiplas cadeias.

Conceitos Principais Ao transferir ativos entre cadeias, existem duas abordagens principais para lidar com o processo de transferência: manual e automatizada. Abaixo, destacamos as diferenças entre essas abordagens e como elas impactam a experiência do usuário:

• Transferências Manuais: envolvem três etapas principais: iniciar a transferência na cadeia de origem, buscar a atestação da Circle para verificar a transferência e completar a transferência na cadeia de destino.

• Transferências Automatizadas: simplificam o processo ao lidar automaticamente com atestações da Circle e finalização. Com o envio automatizado do Wormhole, você só precisa iniciar a transferência, e o restante é gerenciado para você.

Pré-requisitos Antes de começar, verifique se você tem os seguintes itens:

• Node.js e npm instalados em sua máquina

• TypeScript instalado globalmente

• Tokens USDC nas cadeias compatíveis. Este tutorial usa Avalanche e Sepolia como exemplos.

• Uma carteira com uma chave privada, financiada com tokens nativos (Testnet ou Mainnet) para taxas de gás.

Cadeias Compatíveis O Wormhole SDK suporta uma ampla gama de cadeias EVM e não-EVM, permitindo que você facilite transferências entre cadeias de maneira eficiente. Você pode encontrar uma lista completa das cadeias compatíveis no repositório do Wormhole SDK no GitHub, que cobre ambientes Testnet e Mainnet.

Configuração do Projeto Nesta seção, você configurará seu projeto para transferir USDC entre cadeias usando o SDK do Wormhole e o CCTP da Circle. Orientaremos você na inicialização do projeto, instalação de dependências e preparação do ambiente para transferências entre cadeias.

• Inicializar o Projeto: comece criando um novo diretório para o seu projeto e inicializando-o com npm, que criará o arquivo package.json do seu projeto.

mkdir cctp-circle
cd cctp-circle
npm init -y

• Instalar Dependências: instale as dependências necessárias, incluindo o SDK do Wormhole e bibliotecas auxiliares.

npm install @wormhole-foundation/sdk dotenv

• Configurar Variáveis de Ambiente: para armazenar com segurança sua chave privada, crie um arquivo .env na raiz do seu projeto.

touch .env

Dentro do arquivo .env, adicione sua chave privada.

ETH_PRIVATE_KEY="INSIRA_SUA_CHAVE_PRIVADA"
SOL_PRIVATE_KEY="INSIRA_SUA_CHAVE_PRIVADA"

Nota: Certifique-se de que sua chave privada contenha fundos USDC e tokens nativos para taxas de gás tanto na cadeia de origem quanto na de destino.

• Criar um Arquivo helpers.ts: para simplificar a interação entre as cadeias, crie um arquivo para armazenar funções auxiliares para buscar sua chave privada, configurar signatários para diferentes cadeias e gerenciar a transmissão de transações.

mkdir helpers
touch helpers/helpers.ts

Abra o arquivo helpers.ts e adicione o seguinte código:

import {
  ChainAddress,
  ChainContext,
  Network,
  Signer,
  Wormhole,
  Chain,
} from '@wormhole-foundation/sdk';
import evm from '@wormhole-foundation/sdk/evm';
import solana from '@wormhole-foundation/sdk/solana';
import { config } from 'dotenv';
config();

export interface SignerStuff<N extends Network, C extends Chain> {
  chain: ChainContext<N, C>;
  signer: Signer<N, C>;
  address: ChainAddress<C>;
}

// Função para buscar variáveis de ambiente (como sua chave privada)
function getEnv(key: string): string {
  const val = process.env[key];
  if (!val) throw new Error(`Missing environment variable: ${key}`);
  return val;
}

// Função de configuração de signatário para diferentes plataformas blockchain
export async function getSigner<N extends Network, C extends Chain>(chain: ChainContext<N, C>): Promise<{
  chain: ChainContext<N, C>;
  signer: Signer<N, C>;
  address: ChainAddress<C>;
}> {
  let signer: Signer;
  const platform = chain.platform.utils()._platform;

  switch (platform) {
    case 'Solana':
      signer = await (
        await solana()
      ).getSigner(await chain.getRpc(), getEnv('SOL_PRIVATE_KEY'));
      break;
    case 'Evm':
      signer = await (
        await evm()
      ).getSigner(await chain.getRpc(), getEnv('ETH_PRIVATE_KEY'));
      break;
    default:
      throw new Error('Unsupported platform: ' + platform);
  }

  return {
    chain,
    signer: signer as Signer<N, C>,
    address: Wormhole.chainAddress(chain.chain, signer.address()),
  };
}

• Criar o Script Principal: crie um novo arquivo chamado manual-transfer.ts para armazenar seu script para transferir USDC entre cadeias.

touch src/manual-transfer.ts

Abra o arquivo manual-transfer.ts e comece importando os módulos necessários do SDK e arquivos auxiliares.

import { wormhole } from '@wormhole-foundation/sdk';
import evm from '@wormhole-foundation/sdk/evm';
import solana from '@wormhole-foundation/sdk/solana';
import { getSigner } from './helpers/helpers';

• Transferências Manuais: nas transferências manuais de USDC, você realiza cada etapa do processo de transferência entre cadeias individualmente. Essa abordagem permite maior controle e flexibilidade sobre como a transferência é executada, o que pode ser útil em cenários onde você precisa personalizar certos aspectos da transferência, como o gerenciamento de gás, seleção específica de cadeias ou assinatura manual de transações.

Esta seção o guiará por uma transferência manual de USDC entre cadeias usando o Wormhole SDK e o CCTP da Circle.

Configurar o Ambiente de Transferência

Configurar Detalhes da Transferência Antes de iniciar uma transferência entre cadeias, você deve configurar o contexto da cadeia e os signatários para as cadeias de origem e destino.

• Inicializar o SDK do Wormhole: inicialize a função wormhole para o ambiente Testnet e especifique as plataformas (EVM e Solana) para oferecer suporte.

código(async function () {
  const wh = await wormhole('Testnet', [evm, solana]);
})();

Você pode substituir 'Testnet' por 'Mainnet' se desejar realizar transferências na Mainnet.

Configurar as cadeias de origem e destino - especifique a cadeia de origem (Avalanche) e a cadeia de destino (Sepolia) usando o método getChain. Isso nos permite definir onde enviar o USDC e onde recebê-los:

const sendChain = wh.getChain('Avalanche');
  const rcvChain = wh.getChain('Sepolia');

Configurar os signatários - use a função getSigner para recuperar os signatários responsáveis por assinar as transações nas respectivas cadeias. Isso garante que as transações sejam corretamente autorizadas tanto na cadeia de origem quanto na cadeia de destino:

const source = await getSigner(sendChain);
  const destination = await getSigner(rcvChain);

Definir o valor da transferência - o valor de USDC a ser transferido é especificado. Neste caso, estamos transferindo 0,1 USDC, que é analisado e convertido para as unidades base esperadas pelo SDK do Wormhole:

const amt = 100_000n;

Definir o modo de transferência - especificamos que a transferência deve ser manual definindo automatic = false. Isso significa que você precisará gerenciar os passos de atestação e finalização por conta própria:

const automatic = false;

Iniciar a Transferência

Para começar o processo de transferência manual, você precisa primeiro criar o objeto de transferência e depois iniciar manualmente a transferência na cadeia de origem.

Criar o objeto de transferência do Circle - a função wh.circleTransfer() cria um objeto com os detalhes da transferência, como o valor de USDC, os endereços de origem e destino, e o modo. No entanto, isso não inicia a transferência em si:

const xfer = await wh.circleTransfer(
    amt,
    source.address,
    destination.address,
    automatic
  );

Iniciar a transferência - a função initiateTransfer envia a transação na cadeia de origem. Isso envolve assinar e enviar a transação usando o signatário de origem. Ela retornará uma lista de IDs de transações (srcTxIds) que você pode usar para rastrear a transferência:

const srcTxids = await xfer.initiateTransfer(source.signer);
  console.log(`Transferência iniciada: `, srcTxids);

Buscar a Atestação do Circle (VAA)

Depois de iniciar a transferência na cadeia de origem, você deve buscar a VAA (Atestação de Valor Vinculado) do Circle. A VAA serve como prova criptográfica de que o CCTP reconheceu a transferência com sucesso. A transferência não pode ser concluída na cadeia de destino até que essa atestação seja obtida.

Definir um tempo limite - buscar a atestação pode levar algum tempo, então é comum definir um tempo limite. Neste exemplo, definimos o tempo limite para 60 segundos:

const timeout = 60 * 1000; // Timeout em milissegundos (60 segundos)

Buscar a atestação - após iniciar a transferência, você pode usar a função fetchAttestation() para recuperar a VAA. Essa função aguardará até que a atestação esteja disponível ou até que o tempo limite especificado seja alcançado:

const attestIds = await xfer.fetchAttestation(timeout);
  console.log(`Atestação recebida: `, attestIds);

Os attestIds conterão os detalhes da atestação obtida, que o Wormhole usará para completar a transferência na cadeia de destino.

Completar a Transferência na Cadeia de Destino

Após obter a VAA corretamente, o último passo é completar a transferência na cadeia de destino (Sepolia neste exemplo). Isso envolve resgatar a VAA, o que move os USDC da custódia do Circle para a cadeia de destino.

Use a função completeTransfer() para finalizar a transferência na cadeia de destino. Isso exige que o signatário de destino assine e envie a transação para a cadeia de destino:

const dstTxids = await xfer.completeTransfer(destination.signer);
  console.log(`Transferência concluída: `, dstTxids);

  console.log('Status da transferência Circle: ', xfer);

  process.exit(0);

Os dstTxIds conterão os IDs das transações para a transferência na cadeia de destino, confirmando que a transferência foi concluída.

Você pode encontrar o código completo do script de transferência manual de USDC abaixo:

import { wormhole } from '@wormhole-foundation/sdk';
import evm from '@wormhole-foundation/sdk/evm';
import solana from '@wormhole-foundation/sdk/solana';
import { getSigner } from './helpers/helpers';

(async function () {
  const wh = await wormhole('Testnet', [evm, solana]);

  // Configurar as cadeias de origem e destino
  const sendChain = wh.getChain('Avalanche');
  const rcvChain = wh.getChain('Sepolia');

  // Configurar os signatários
  const source = await getSigner(sendChain);
  const destination = await getSigner(rcvChain);

  // Definir o valor da transferência (na unidade mais baixa, então 0.1 USDC = 100.000 unidades considerando 6 casas decimais)
  const amt = 100_000n;

  const automatic = false;

  // Criar o objeto de transferência do Circle
  const xfer = await wh.circleTransfer(
    amt,
    source.address,
    destination.address,
    automatic
  );

  console.log('Objeto de Transferência do Circle criado:', xfer);

  // Iniciar a transferência na cadeia de origem (Avalanche)
  console.log('Iniciando a Transferência');
  const srcTxids = await xfer.initiateTransfer(source.signer);
  console.log(`Transferência iniciada: `, srcTxids);

  // Aguardar a Atestação do Circle (VAA)
  const timeout = 60 * 1000; // Timeout em milissegundos (60 segundos)
  console.log('Aguardando a Atestação');
  const attestIds = await xfer.fetchAttestation(timeout);
  console.log(`Atestação recebida: `, attestIds);

  // Completar a transferência na cadeia de destino (Sepolia)
  console.log('Finalizando a Transferência');
  const dstTxids = await xfer.completeTransfer(destination.signer);
  console.log(`Transferência concluída: `, dstTxids);

  console.log('Status da Transferência Circle: ', xfer);

  process.exit(0);
})();

Executar a Transferência Manual

Para executar o script de transferência manual, você pode usar o ts-node para rodar o arquivo TypeScript diretamente:

npx ts-node src/manual-transfer.ts

Isso iniciará a transferência de USDC da cadeia de origem (Avalanche) e a completará na cadeia de destino (Sepolia).

Você pode monitorar o status da transação no explorador do Wormhole.

Completar uma Transferência Parcial

Em alguns casos, uma transferência manual pode começar, mas não terminar—por exemplo, se o usuário interromper sua sessão ou houver um problema antes que a transferência possa ser concluída. O SDK do Wormhole permite que você reconstrua o objeto de transferência a partir do hash da transação na cadeia de origem.

Esse recurso é útil para recuperar uma transferência incompleta ou para depuração.

Aqui está como você pode completar uma transferência parcial usando apenas a cadeia de origem e o hash da transação:

const xfer = await CircleTransfer.from(
    wh,
    {
      chain: 'Avalanche',
      txid: '0x6b6d5f101a32aa6d2f7bf0bf14d72bfbf76a640e1b2fdbbeeac5b82069cda4dd',
    },
    timeout
  );

  const dstTxIds = await xfer.completeTransfer(destination.signer);
  console.log('Transferência concluída: ', dstTxIds);

Você precisará fornecer os seguintes requisitos para completar a transferência parcial:

• ID da Transação (txId): o hash da transação na cadeia de origem onde a transferência foi iniciada

• Signatário da cadeia de destino (destination.signer): a carteira ou chave privada que pode autorizar e concluir a transferência na cadeia de destino. Esse signatário é o mesmo definido na configuração da transferência manual

Isso permite retomar o processo de transferência reconstruindo o objeto de transferência e completando-o na cadeia de destino. É especialmente conveniente para depuração ou quando há interrupções na transferência.

Você pode encontrar o código completo para o script de transferência manual de USDC abaixo:

import { CircleTransfer, wormhole } from '@wormhole-foundation/sdk';
import evm from '@wormhole-foundation/sdk/evm';
import solana from '@wormhole-foundation/sdk/solana';
import { getSigner } from '../helpers/helpers';

(async function () {
  // Inicializar o objeto Wormhole para o ambiente Testnet e adicionar as cadeias suportadas (evm e solana)
  const wh = await wormhole('Testnet', [evm, solana]);

  // Obter Contextos das cadeias -- esses mantêm uma referência a um cliente RPC em cache
  const rcvChain = wh.getChain('Sepolia');

  // Obter o signatário da chave local
  const destination = await getSigner(rcvChain);

  const timeout = 60 * 1000; // Timeout em milissegundos (60 segundos)

  // Reconstruir a transferência a partir do txid da origem
  const xfer = await CircleTransfer.from(
    wh,
    {
      chain: 'Avalanche',
      txid: '0x6b6d5f101a32aa6d2f7bf0bf14d72bfbf76a640e1b2fdbbeeac5b82069cda4dd',
    },
    timeout
  );

  const dstTxIds = await xfer.completeTransfer(destination.signer);
  console.log('Transferência concluída: ', dstTxIds);

  console.log('Status da Transferência Circle: ', xfer);

  process.exit(0);
})();

Transferências Automáticas

O processo de transferência automática simplifica as etapas automatizando a obtenção da atestação e a conclusão da transferência. Tudo o que você precisa fazer é iniciar a transferência.

Configurar o Ambiente de Transferência

Configurar os Detalhes da Transferência A configuração para transferências automáticas é semelhante à das transferências manuais, com a principal diferença sendo que a flag automatic está definida como true. Isso indica que o Wormhole lidará com as etapas de atestação e finalização para você:

const automatic = true;

Iniciar a Transferência

O processo de transferência é o mesmo que para transferências manuais. Você cria o objeto de transferência e depois inicia a transferência na cadeia de origem:

const xfer = await wh.circleTransfer(
    amt,
    source.address,
    destination.address,
    automatic
  );

Registrar Detalhes da Transferência

Após iniciar a transferência, você pode registrar os IDs das transações tanto da cadeia de origem quanto da cadeia de destino. Isso ajudará a acompanhar o progresso da transferência:

const srcTxids = await xfer.initiateTransfer(source.signer);
  console.log(`Transferência iniciada: `, srcTxids);

  process.exit(0);

Você pode encontrar o código completo para o script de transferência automática de USDC abaixo:

automatic-transfer.ts

import { wormhole } from '@wormhole-foundation/sdk';
import evm from '@wormhole-foundation/sdk/evm';
import solana from '@wormhole-foundation/sdk/solana';
import { getSigner } from '../helpers/helpers';

(async function () {
  // Inicializar o objeto Wormhole para o ambiente Testnet e adicionar as cadeias suportadas (evm e solana)
  const wh = await wormhole('Testnet', [evm, solana]);

  // Configurar as cadeias de origem e destino
  const sendChain = wh.getChain('Avalanche');
  const rcvChain = wh.getChain('Sepolia');

  // Configurar os signatários
  const source = await getSigner(sendChain);
  const destination = await getSigner(rcvChain);

  // Definir o valor da transferência (na menor unidade, então 0,1 USDC = 100.000 unidades assumindo 6 casas decimais)
  const amt = 100_000_001n;

  const automatic = true;

  // Criar o objeto de transferência Circle (somente USDC)
  const xfer = await wh.circleTransfer(
    amt,
    source.address,
    destination.address,
    automatic
  );

  console.log('Objeto de Transferência Circle criado:', xfer);

  // Iniciar a transferência na cadeia de origem (Avalanche)
  console.log('Iniciando a Transferência');
  const srcTxids = await xfer.initiateTransfer(source.signer);
  console.log(`Transferência Iniciada: `, srcTxids);

  process.exit(0);
})();

Executar a Transferência Automática

Assumindo que você tenha criado um novo arquivo automatic-transfer.ts para transferências automáticas no diretório src, use o seguinte comando para executá-lo com o ts-node:

npx ts-node src/automatic-transfer.ts

O relayer automático cuidará de buscar a atestação e concluir a transferência para você.

Recursos

Se você deseja explorar o projeto completo ou precisa de uma referência enquanto segue este tutorial, pode encontrar o código completo no repositório demo do GitHub do Wormhole. O repositório inclui todos os scripts de exemplo e configurações necessárias para realizar transferências cross-chain de USDC, incluindo transferências manuais, automáticas e parciais usando o SDK do Wormhole e o CCTP da Circle.

Conclusão

Neste tutorial, você ganhou experiência prática com o CCTP da Circle e o SDK do Wormhole. Aprendeu a realizar transferências manuais e automáticas de USDC entre várias cadeias e recuperar transferências parciais, se necessário.

Ao seguir esses passos, você aprendeu a:

• Configurar transferências cross-chain de USDC nativo entre cadeias suportadas

• Lidar tanto com o envio manual quanto com o envio automático de transações

• Recuperar e concluir transferências incompletas usando o hash da transação e o signatário da cadeia de destino