Taxas de Transferência

A extensão Taxa de Transferência permite que mints Token-2022 cobrem uma taxa em cada transferência, retida em contas de token até ser colhida para um coletor de taxas. Ela permite receita on-chain sem programas de transferência personalizados.

Receita

spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1

--transfer-fee-maximum-fee é um valor de UI, não unidades base brutas - 1 limita a taxa a um token, 1000000 a limitaria a um milhão.

use anchor_spl::token_interface::{Mint, TokenAccount, TokenInterface};
// Use os helpers de CPI do spl-token-2022 para harvest_withheld_tokens_to_mint.
// Transferências em um mint com taxa devem usar transfer_checked - Token-2022 rejeita
// a instrução Transfer não verificada em mints que carregam uma taxa de transferência.

Quando usar isso:

• Receita de protocolo em transferências secundárias
• Ativos do mundo real tokenizados com taxas do emissor
• Tokens de fidelidade com mecânicas de redistribuição
• Substituir rastreamento de taxa off-chain frágil

Exemplo de Trabalho

# Cria um mint com taxa de 1% (100 bps) e um teto de taxa de 1 token.
# Todos os valores de spl-token aqui são valores de UI, não unidades base brutas.
MINT=$(spl-token create-token \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb \
  --decimals 6 \
  --transfer-fee-basis-points 100 \
  --transfer-fee-maximum-fee 1 | awk '/Creating token/{print $3}')
 
spl-token create-account "$MINT" --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
spl-token mint "$MINT" 10 --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
 
# Transfere 1 token (bruto 1_000_000) - o destinatário recebe menos; taxa retida.
# A CLI emite TransferChecked, que é exigido em um mint com taxa.
spl-token transfer "$MINT" 1 <RECIPIENT> --fund-recipient \
  --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb
 
spl-token display <RECIPIENT_ATA> --program-id TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb

O que isso demonstra:

• Taxa calculada em basis points (100 bps = 1%) limitada pelo maximum_fee
• Valor retido permanece na conta do destinatário ou remetente conforme configuração até a colheita
• Carteiras devem exibir o valor líquido, não a entrada bruta da transferência

Mergulho Profundo

Como Funciona

• Configuração da taxa de transferência armazenada na extensão do mint (bps, taxa máxima, autoridade de taxa de transferência)
• Na TransferChecked, o programa move a porção da taxa para um bucket retido nas contas. O Token-2022 rejeita o Transfer não verificado obsoleto em um mint com taxa, pois não pode verificar os decimais para os cálculos da taxa.
• HarvestWithheldTokensToMint agrega as taxas retidas ao mint.
• WithdrawWithheldTokensFromMint envia as taxas coletadas para o ATA do coletor.

Cálculo da Taxa

Notas de TypeScript

// Ao construir transferências, busque o mint com as extensões analisadas
// Exiba: valor, taxa estimada, líquido para o destinatário
// Inclua instruções de colheita em bots de processamento do tesouro

Armadilhas

• Usuários surpresos com o valor líquido recebido - A UX espera o valor bruto. Correção: exiba o detalhamento da taxa antes de assinar.
• Taxas retidas presas em ATAs - sem um processo de colheita. Correção: automatize harvest_withheld em um bot de manutenção.
• Incompatibilidade com DEX - roteadores podem não passar contas de extensão. Correção: verifique o suporte a Token-2022 em Jupiter/Meteora.
• Estouro de basis points - máximo de 10_000 bps (100%). Correção: valide na criação do mint.
• Assumir a instrução de transferência clássica - construtores spl_token::instruction::* chamam check_program_account e retornam IncorrectProgramId para o ID do Token-2022, e o Token-2022 rejeita o Transfer não verificado em mints com taxa, independentemente. Correção: ramifique com base no proprietário do mint, em seguida, use spl_token_2022::instruction::transfer_checked (ou anchor_spl::token_interface, que despacha para ambos os programas).
• Tratar valores da CLI como brutos - --transfer-fee-maximum-fee e cada valor de mint/transfer são valores de UI. Correção: passe 1, não 1000000, para um teto de um token.

Alternativas

FAQs

Relacionados

• Noções Básicas de Token-2022 - ID do programa
• Transfer Hooks - lógica de transferência personalizada
• Melhores Práticas do Token-2022 - verificações do cliente

Versões da stack: Esta página foi escrita para Agave 4.1.1, Solana CLI 3.0.10, Anchor 0.32.1, anchor-lang 0.32.1, Rust 1.91.1, @solana/kit 7.0.0, Surfpool 0.12.0 e LiteSVM 0.6.x.