Como Usar getTokenAccountsByDelegate

​

Casos Comuns de Uso

• Listar Ativos Delegados: Exibir todas as contas de token para as quais uma carteira ou programa específico recebeu autoridade delegada.
• Gerenciamento Automatizado de Tokens: Serviços que executam ações em nome dos usuários (por exemplo, formadores de mercado automatizados, protocolos de staking que gerenciam recompensas tokenizadas) podem usar isso para encontrar contas com as quais estão autorizados a interagir.
• Auditoria de Delegações: Revisar quais contas delegaram autoridade para um endereço específico.
• Revogação de Delegações: Identificar contas de token das quais a autoridade delegada precisa ser revogada (embora a revogação em si seja uma transação separada).

​

Parâmetros de Solicitação

1. delegatePubkey (string, obrigatório): A chave pública codificada em base-58 da conta do delegado cujas contas de token associadas você deseja encontrar.
2. filter (objeto, obrigatório): Um objeto JSON que deve especificar mint ou programId para filtrar as contas:
   • mint (string): A chave pública codificada em base-58 de um token mint específico. Se fornecido, a consulta retornará apenas contas de token deste tipo específico que estão delegadas para delegatePubkey.
   • programId (string): A chave pública codificada em base-58 do programa de token que possui as contas. Isso geralmente será o programa padrão SPL Token (TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA) ou o programa Token-2022 (TokenzQdBNbLqP5VEhdkAS6EPFLC1PHnBqCXEpPxuEb).
3. options (objeto, opcional): Um objeto de configuração opcional com os seguintes campos comuns:
   • commitment (string, opcional): Especifica o nível de comprometimento.
   • encoding (string, opcional): A codificação para dados de conta. "jsonParsed" é altamente recomendada, pois retorna informações de conta legíveis para humanos. Outras opções incluem "base64", "base64+zstd". O padrão é "base64" se não especificado.
   • dataSlice (objeto, opcional): Permite recuperar apenas uma fatia específica dos dados da conta. Contém campos offset (usize) e length (usize). Aplicável apenas para codificações base58, base64, ou base64+zstd.
   • minContextSlot (u64, opcional): O slot mínimo em que a solicitação pode ser avaliada.

​

Estrutura de Resposta

• pubkey (string): A chave pública codificada em base-58 da própria conta de token.
• account (objeto): Um objeto contendo informações detalhadas sobre a conta de token:
  • lamports (u64): O saldo de lamports da conta de token (para isenção de aluguel).
  • owner (string): A chave pública do programa que possui esta conta (por exemplo, o programa Token).
  • data: Os dados da conta. Se a codificação "jsonParsed" for usada, isso será um objeto com um campo program (por exemplo, "spl-token") e um campo parsed contendo informações estruturadas:
    • parsed.info: Um objeto com detalhes como:
      • mint (string): O endereço de mint do token.
      • owner (string): O proprietário da conta de token (não o delegado).
      • tokenAmount (objeto): O saldo total de tokens nesta conta (amount, decimals, uiAmount, uiAmountString).
      • delegate (string): A chave pública do delegado (deve corresponder ao delegatePubkey da solicitação).
      • delegatedAmount (objeto): A quantidade de tokens que o delegado está autorizado a gerenciar (amount, decimals, uiAmount, uiAmountString).
      • isNative (boolean): Indica se a conta possui SOL encapsulado.
      • state (string): O estado da conta de token (por exemplo, "initialized").
    • parsed.type (string): O tipo da conta (por exemplo, "account").
  • executable (boolean): Se a conta é executável.
  • rentEpoch (u64): A época em que esta conta deverá aluguel novamente.
  • space (u64, se jsonParsed não for usado): O comprimento dos dados brutos da conta em bytes.

{
  "jsonrpc": "2.0",
  "result": {
    "context": {
      "slot": 183458000
    },
    "value": [
      {
        "pubkey": "SomeTokenAccountPubkey1...",
        "account": {
          "data": {
            "program": "spl-token",
            "parsed": {
              "info": {
                "delegate": "DelegatePubkeyProvidedInRequest...",
                "delegatedAmount": {
                  "amount": "1000000000",
                  "decimals": 9,
                  "uiAmount": 1.0,
                  "uiAmountString": "1.0"
                },
                "isNative": false,
                "mint": "TokenMintPubkey...",
                "owner": "ActualOwnerOfTheTokenAccount...",
                "state": "initialized",
                "tokenAmount": {
                  "amount": "5000000000",
                  "decimals": 9,
                  "uiAmount": 5.0,
                  "uiAmountString": "5.0"
                }
              },
              "type": "account"
            },
            "space": 165
          },
          "executable": false,
          "lamports": 2039280,
          "owner": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // SPL Token Program
          "rentEpoch": 382
        }
      }
      // ... potentially other token accounts delegated to the same delegate
    ]
  },
  "id": 1
}

​

Exemplos de Código

# Replace <DELEGATE_PUBKEY> and <TOKEN_MINT_PUBKEY> or <TOKEN_PROGRAM_ID>
# Example using programId (SPL Token Program)
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByDelegate",
    "params": [
      "<DELEGATE_PUBKEY>",
      { "programId": "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" },
      { "encoding": "jsonParsed" }
    ]
  }' \
  <YOUR_RPC_URL>

# Example using a specific mint
curl -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getTokenAccountsByDelegate",
    "params": [
      "<DELEGATE_PUBKEY>",
      { "mint": "<TOKEN_MINT_PUBKEY>" },
      { "encoding": "jsonParsed", "commitment": "confirmed" }
    ]
  }' \
  <YOUR_RPC_URL>

const { Connection, PublicKey } = require('@solana/web3.js');

async function findDelegatedAccounts(delegateAddress, filter, encoding = 'jsonParsed') {
  // Replace with your RPC endpoint
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');
  const delegatePubKey = new PublicKey(delegateAddress);

  try {
    let actualFilter;
    if (filter.mint) {
      actualFilter = { mint: new PublicKey(filter.mint) };
    } else if (filter.programId) {
      actualFilter = { programId: new PublicKey(filter.programId) };
    } else {
      console.error("Filter must contain either 'mint' or 'programId'");
      return;
    }

    const accounts = await connection.getTokenAccountsByDelegate(
      delegatePubKey,
      actualFilter,
      { encoding }
    );

    console.log(`Found ${accounts.value.length} token accounts delegated to ${delegateAddress}:`);
    accounts.value.forEach(accInfo => {
      console.log(`  Token Account: ${accInfo.pubkey.toBase58()}`);
      if (encoding === 'jsonParsed' && accInfo.account.data.parsed) {
        console.log(`    Mint: ${accInfo.account.data.parsed.info.mint}`);
        console.log(`    Owner: ${accInfo.account.data.parsed.info.owner}`);
        console.log(`    Delegated Amount: ${accInfo.account.data.parsed.info.delegatedAmount.uiAmountString}`);
      }
      // console.log(JSON.stringify(accInfo.account.data, null, 2)); // For full data
    });

  } catch (error) {
    console.error(`Error fetching token accounts by delegate for ${delegateAddress}:`, error);
  }
}

// Replace with an actual delegate public key
const exampleDelegate = '4Nd1mBQtrMJVYVfKf2PJy9NZUZdTAsp7D4xWLs4gDB4T'; 

// Example 1: Find all SPL Token program accounts delegated to `exampleDelegate`
findDelegatedAccounts(exampleDelegate, { programId: 'TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA' });

// Example 2: Find accounts for a specific mint (e.g., USDC) delegated to `exampleDelegate`
// const usdcMint = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';
// findDelegatedAccounts(exampleDelegate, { mint: usdcMint });

​

Dicas para Desenvolvedores

• Requisito de Filtro: Você deve fornecer mint ou programId no parâmetro de filtro. Não é possível consultar todas as contas delegadas para todos os tipos de token sem um desses filtros.
• Codificação: Usar "jsonParsed" para a opção encoding é altamente recomendado para facilitar o manuseio dos dados, pois decodifica os dados binários da conta em um formato JSON estruturado.
• Desempenho: Consultar com programId pode ser mais intensivo em recursos do que consultar com mint, especialmente se o delegado tiver autoridade sobre muitos tipos de token diferentes. Alguns provedores de RPC podem ter limites de taxa mais rígidos para este método.
• Quantidade Delegada: O delegatedAmount na resposta indica o número máximo de tokens que o delegado está atualmente autorizado a usar. Isso pode ser menos que o total tokenAmount na conta.
• Revogação de Delegação: Este método apenas recupera informações. Para revogar uma delegação, o proprietário da conta de token deve enviar uma instrução Revoke para o programa SPL Token.