Como funcionam os pagamentos na Solana

Antes de criar fluxos de pagamento na Solana, você precisará entender cinco conceitos fundamentais: carteiras, stablecoins, token accounts, taxas e transações. Os pagamentos na Solana mapeiam claramente para sistemas de pagamento multi-moeda:

Assim como um cliente bancário tem uma única identidade mas mantém saldos separados para cada moeda, uma carteira Solana tem um endereço mas uma token account distinta para cada ativo que detém. Vamos detalhar cada componente.

Carteiras: remetentes e destinatários

Cada pagamento envolve duas partes, cada uma identificada por um endereço de carteira—uma chave pública única de 32 bytes (por exemplo, 7EcDhS...).

• Remetente: a carteira que inicia o pagamento. Deve ter saldo suficiente na stablecoin account e assinar a transação.
• Destinatário: a carteira de destino. Não precisa assinar ou ter um saldo existente.
• Pagador de taxa: a carteira opcional que paga a taxa. Pode ser usada para subsidiar ou permitir transações apenas com stablecoin entre utilizadores.

Pense nos endereços de carteira como números de conta bancária: públicos, seguros para partilhar e necessários para enviar ou receber fundos.

Stablecoins

Stablecoins são referidas como "tokens" na Solana. Tokens representam um tipo de ativo na rede. Cada token tem um identificador único chamado "endereço mint". Ao criar sistemas de pagamento, você fará referência a esses endereços mint para identificar o ativo com o qual está a interagir. Aqui estão alguns endereços mint de stablecoins comuns na mainnet:

Para mais informações sobre stablecoins na Solana, consulte a página de soluções Stablecoins.

Token accounts

As carteiras não armazenam tokens diretamente. Em vez disso, cada carteira tem autoridade sobre uma token account para cada tipo de token que detém. Os pagamentos são efetuados através da transferência de tokens de uma token account do remetente para uma token account do destinatário do mesmo mint:

Token accounts

Uma Associated Token Account é uma token account determinística associada a uma carteira e mint específicos. Dado um endereço de carteira e mint, o endereço ATA é sempre o mesmo.

1. Uma ATA por mint. Uma carteira tem exatamente uma ATA para USDC, uma para USDT, etc.
2. Deve existir antes de receber. Não é possível enviar tokens para uma ATA que não existe.
3. O remetente normalmente cria. Se a ATA do destinatário não existir, o remetente pode criá-la como parte da transação de pagamento.

import { findAssociatedTokenPda } from "@solana-program/token";

const [receiverATA] = await findAssociatedTokenPda({
  mint: USDG_MINT_ADDRESS,
  owner: receiverWallet.address,
  tokenProgram: TOKEN_PROGRAM_ADDRESS
});

Token Programs

Na Solana, os programas são lógica executável que governa o estado das contas. As token accounts são geridas por um Token Program—o código on-chain que verifica transferências e atualiza saldos atomicamente.

A Solana tem dois Token Programs:

Token-2022 (também chamado de "Token Extensions") adiciona funcionalidades como hooks de transferência, taxas de transferência e transferências confidenciais. Ambos os programas funcionam de forma semelhante para transferências básicas, mas você deve usar o correto ao derivar ATAs.

Por que isto é importante

O Token Program usado para criar um token governa as instruções e o estado da conta para o token. Se você usar o programa errado, não conseguirá transferir o token.

ATAs são derivados de três entradas: wallet + mint + token_program. Usar o programa errado produz um endereço completamente diferente:

import {
  findAssociatedTokenPda,
  TOKEN_PROGRAM_ADDRESS
} from "@solana-program/token";
import { TOKEN_2022_PROGRAM_ADDRESS } from "@solana-program/token-2022";

// USDC uses Token Program
const [usdcAta] = await findAssociatedTokenPda({
  mint: USDC_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_PROGRAM_ADDRESS // ✓ Correct
});

// ❌ This will produce a different address because it uses the wrong program
const [wrongUsdcAta] = await findAssociatedTokenPda({
  mint: USDC_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_2022_PROGRAM_ADDRESS // ❌ Wrong program
});

// PYUSD uses Token-2022
const [pyusdAta] = await findAssociatedTokenPda({
  mint: PYUSD_MINT,
  owner: walletAddress,
  tokenProgram: TOKEN_2022_PROGRAM_ADDRESS // ✓ Correct
});

O mesmo princípio aplica-se às instruções de transferência. Cada Token Program tem a sua própria instrução de transferência, e você deve invocar a correta:

import { getTransferInstruction } from "@solana-program/token";
import { getTransferInstruction as getTransferInstruction22 } from "@solana-program/token-2022";

// For USDC (Token Program)
const usdcTransferIx = getTransferInstruction({
  source: senderUsdcAta,
  destination: receiverUsdcAta,
  authority: senderWallet,
  amount: 1_000_000n // 1 USDC (6 decimals)
});

// For PYUSD (Token-2022)
const pyusdTransferIx = getTransferInstruction22({
  source: senderPyusdAta,
  destination: receiverPyusdAta,
  authority: senderWallet,
  amount: 1_000_000n // 1 PYUSD (6 decimals)
});

// *Note*: Most token program JS Client functions include the ability
// to specify the token program address. Generally, defining it is a
// good practice to ensure you are fully aware of the program you are using
const usdcTransferIx2 = getTransferInstruction(
  {
    source: senderUsdcAta,
    destination: receiverUsdcAta,
    authority: senderWallet,
    amount: 1_000_000n // 1 USDC (6 decimals)
  },
  { tokenProgram: TOKEN_PROGRAM_ADDRESS }
);

Enviar uma instrução de transferência para o programa errado falhará. O programa valida que possui as contas de token envolvidas—contas criadas pelo Token Program não podem ser transferidas via Token-2022, e vice-versa.

Para verificar qual programa um token ou conta de token usa, obtenha o mint ou a conta de token e verifique o seu campo owner:

import { createSolanaRpc, address } from "@solana/kit";

const rpc = createSolanaRpc("https://api.mainnet-beta.solana.com");
const accountInfo = await rpc.getAccountInfo(address(mintAddress)).send();

// The owner field tells you which program manages this token
const tokenProgram = accountInfo.value?.owner;
// Returns: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA (Token Program)
//      or: TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb (Token-2022)

Para aplicações de pagamento, armazene o endereço correto do programa juntamente com cada token suportado:

const SUPPORTED_TOKENS = {
  USDC: {
    mint: "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v",
    program: TOKEN_PROGRAM_ADDRESS,
    decimals: 6
  },
  PYUSD: {
    mint: "2b1kV6DkPAnxd5ixfnxCpjxmKwqjjaYmCZfHsFu24GXo",
    program: TOKEN_2022_PROGRAM_ADDRESS,
    decimals: 6
  }
};

Token Extensions

O Token Extensions Program (Token 2022) fornece mais funcionalidades através de instruções extras referidas como extensions. Extensions são funcionalidades opcionais que você pode adicionar a um token mint ou token account.

Para mais informações sobre Token Extensions, consulte a documentação de Token Extensions.

Taxas

Os pagamentos na Solana envolvem até três componentes de custo:

Custo total por pagamento: Menos de $0,001 para a maioria das transferências. Se criar um novo token account, espere ~$0,40 no total.

Transações e instruções

Uma transação é a unidade atómica de execução na Solana—ou todas as operações têm sucesso, ou nenhuma tem. Cada transação contém uma ou mais instruções, que são comandos individuais (por exemplo, "transferir 10 USDC", "criar token account").

Uma transação de pagamento típica pode incluir duas instruções: criar o token account do recetor (se necessário), depois transferir tokens. Ambas executam atomicamente—sem estados parciais. Como verá em Processamento de pagamentos, você pode agrupar múltiplos pagamentos numa única transação para reduzir custos e aumentar o débito.

Juntando tudo

Um fluxo de pagamento típico:

1. Recolher informações. Obter os endereços das carteiras do remetente e destinatário e o endereço de cunhagem do token a ser transferido.
2. Derivar ATAs. Determinar as contas de token para ambas as partes.
3. Construir e assinar. Construir a transação com as instruções de transferência necessárias, assinar com a chave do remetente.
4. Enviar e confirmar. A transação é liquidada em menos de um segundo.

Próximos passos