Como Usar getProgramAccounts

​

Casos de Uso Comuns

• Encontrar Todas as Contas de Token para um Mint: Descubra todos os detentores de um token SPL específico.
• Recuperando Dados Específicos do Usuário: Busque todas as contas criadas por um programa para um usuário específico (por exemplo, as posições de um usuário em um protocolo DeFi, seu estado de jogo em um jogo Play-to-Earn).
• Listando Todas as Instâncias de um Tipo de Conta Personalizado: Se seu programa define uma estrutura específica de conta, getProgramAccounts pode encontrar todas as instâncias dessa estrutura.
• Monitoramento do Estado do Programa: Observando todas as contas relacionadas a um programa para rastrear seu estado ou atividade geral.
• Construindo Exploradores e Ferramentas de Análise: Agregando dados sobre programas e suas contas associadas.

​

Parâmetros de Solicitação

1. programId (string, obrigatório):
   • A chave pública codificada em base-58 do programa cujas contas você deseja buscar.
   • Exemplo: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" (para o Programa de Token SPL).
2. options (object, opcional): Um objeto de configuração com os seguintes campos:
   • commitment (string): Especifica o nível de compromisso (por exemplo, "finalized", "confirmed").
   • encoding (string): Codificação para o campo data dentro de cada conta retornada. O padrão é "base64".
     • "base58": Alternativa mais lenta para dados binários.
     • "base64": Codificação padrão base64 para dados binários.
     • "base64+zstd": Dados binários codificados em Base64 e comprimidos por zstd.
     • "jsonParsed": Se o nó RPC tiver um parser para o tipo de conta do programa (por exemplo, SPL Token, Stake), o campo data será um objeto JSON estruturado. Altamente recomendado para legibilidade e facilidade de uso.
   • filters (array): Uma matriz de objetos de filtro para aplicar às contas. Isto é crucial para desempenho e relevância. Você pode usar até 4 filtros. Filtros comuns incluem:
     • dataSize (object):
       • dataSize (u64): Filtra contas pelo comprimento de seus dados em bytes. Exemplo: { "dataSize": 165 } (para contas de Token SPL).
     • memcmp (object): Comparação de memória. Compara uma fatia dos dados da conta com os bytes fornecidos.
       • offset (usize): O deslocamento em bytes nos dados da conta onde começar a comparação.
       • bytes (string): Uma string codificada em base-58 dos bytes a serem correspondidos. A string de bytes deve ter menos de 129 bytes.
       • Exemplo: Para encontrar contas de token para um mint específico, você usaria memcmp com offset: 0 (onde o endereço do mint é armazenado em uma conta de token) e bytes definido para a chave pública do mint.
   • dataSlice (object): Retorna apenas uma fatia específica dos dados de cada conta. Útil para contas grandes quando você só precisa de dados parciais.
     • offset (usize): O deslocamento em bytes de onde começar a fatia.
     • length (usize): O número de bytes a serem retornados.
     • Nota: dataSlice é principalmente para codificações binárias, não jsonParsed.
   • withContext (boolean): Se true, a resposta será um objeto RpcResponse contendo um context (com slot) e o value (o array de contas). Se false ou omitido, normalmente retorna apenas o array de contas. O comportamento pode variar ligeiramente por provedor de RPC.
   • minContextSlot (u64): 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 conta.
• account (object):
  • lamports (u64): Saldo da conta em lamports.
  • owner (string): Chave pública codificada em base-58 do programa que possui esta conta (esta será a programId que você consultou).
  • data (string, array, ou object): Os dados da conta, formatados de acordo com o parâmetro encoding.
    • Para jsonParsed: Um objeto JSON representando o estado desserializado da conta.
    • Para base64: Um array ["encoded_string", "base64"].
  • executable (boolean): Se a conta é executável (ou seja, um programa em si).
  • rentEpoch (u64): A época em que esta conta deverá pagar o aluguel novamente.
  • space (u64, opcional): O comprimento dos dados da conta em bytes. Às vezes referido como data.length se os dados forem um buffer, ou parte da estrutura analisada.

​

Exemplos

​

1. Encontrar Todas as Contas de Token para um Mint Específico (USDC)

# Replace <api-key> with your Helius API key
# USDC Mint: EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v
# Token Program ID: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "jsonParsed",
        "filters": [
          { "dataSize": 165 },
          {
            "memcmp": {
              "offset": 0, 
              "bytes": "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v"
            }
          }
        ]
      }
    ]
  }'

// Replace <api-key> with your Helius API key
const { Connection, PublicKey } = require('@solana/web3.js');
const { TOKEN_PROGRAM_ID } = require('@solana/spl-token');

const USDC_MINT_ADDRESS = 'EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v';

async function findUsdcTokenAccounts() {
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');

  try {
    const accounts = await connection.getProgramAccounts(TOKEN_PROGRAM_ID, {
      encoding: 'jsonParsed',
      filters: [
        {
          dataSize: 165, // Standard token account size
        },
        {
          memcmp: {
            offset: 0, // Offset for the mint address in a token account
            bytes: USDC_MINT_ADDRESS, // Base-58 encoded mint address
          },
        },
      ],
    });

    console.log(`Found ${accounts.length} USDC token accounts.`);
    accounts.forEach((accountInfo, index) => {
      console.log(`--- Account ${index + 1} ---`);
      console.log(`  Pubkey: ${accountInfo.pubkey.toBase58()}`);
      // Accessing parsed data
      const parsedData = accountInfo.account.data.parsed.info;
      console.log(`  Owner: ${parsedData.owner}`);
      console.log(`  Amount: ${parsedData.tokenAmount.uiAmountString}`);
    });
  } catch (error) {
    console.error('Error fetching USDC token accounts:', error);
  }
}

findUsdcTokenAccounts();

​

2. Encontrar Todas as Contas de Token Possuídas por uma Carteira Específica

# Replace <api-key> with your Helius API key
# Example Wallet Address: Helioo21241PANoNdeG55722hgUnp2VawDgsz2g
# Token Program ID: TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA
curl https://mainnet.helius-rpc.com/?api-key=<api-key> -X POST -H "Content-Type: application/json" -d \
  '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "getProgramAccounts",
    "params": [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        "encoding": "jsonParsed",
        "filters": [
          { "dataSize": 165 },
          {
            "memcmp": {
              "offset": 32, 
              "bytes": "Helioo21241PANoNdeG55722hgUnp2VawDgsz2g"
            }
          }
        ]
      }
    ]
  }'

// Replace <api-key> with your Helius API key
const { Connection, PublicKey } = require('@solana/web3.js');
const { TOKEN_PROGRAM_ID } = require('@solana/spl-token');

const TARGET_WALLET_ADDRESS = 'Helioo21241PANoNdeG55722hgUnp2VawDgsz2g';

async function findWalletTokenAccounts() {
  const connection = new Connection('https://mainnet.helius-rpc.com/?api-key=<api-key>');

  try {
    const accounts = await connection.getProgramAccounts(TOKEN_PROGRAM_ID, {
      encoding: 'jsonParsed',
      filters: [
        {
          dataSize: 165, // Standard token account size
        },
        {
          memcmp: {
            offset: 32, // Offset for the owner address in a token account
            bytes: TARGET_WALLET_ADDRESS, // Base-58 encoded wallet address
          },
        },
      ],
    });

    console.log(`Found ${accounts.length} token accounts for wallet ${TARGET_WALLET_ADDRESS}.`);
    accounts.forEach((accountInfo, index) => {
      console.log(`--- Account ${index + 1} (${accountInfo.pubkey.toBase58()}) ---`);
      const parsedData = accountInfo.account.data.parsed.info;
      console.log(`  Mint: ${parsedData.mint}`);
      console.log(`  Amount: ${parsedData.tokenAmount.uiAmountString}`);
    });
  } catch (error) {
    console.error('Error fetching token accounts for wallet:', error);
  }
}

findWalletTokenAccounts();

​

Filtragem Avançada

// Example filtering by memcmp (memory comparison)
const response = await fetch(
  "https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY",
  {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify({
      jsonrpc: "2.0",
      id: "1",
      method: "getProgramAccounts",
      params: [
        "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA", // Solana Token Program
        {
          encoding: "jsonParsed",
          filters: [
            {
              dataSize: 165, // Size of token account data
            },
            {
              memcmp: {
                offset: 32, // Location of owner address in the token account
                bytes: "83astBRguLMdt2h5U1Tpdq5tjFoJ6noeGwaY3mDLVcri",
              },
            },
          ],
        },
      ],
    }),
  }
);
const data = await response.json();
console.log("Filtered program accounts data:", data);

​

Tipos de Filtro

• memcmp: Filtre contas que correspondem a um padrão específico em um deslocamento dado
• dataSize: Filtre contas por seu tamanho de dados exato
• Múltiplos filtros: Todas as condições devem ser satisfeitas (AND lógico)

​

Dicas para Desenvolvedores

• Desempenho: getProgramAccounts pode ser intensivo em recursos nos nós RPC, especialmente sem filtros ou para programas com muitas contas. Sempre use filtros (dataSize, memcmp) e dataSlice onde possível para reduzir o escopo da consulta e o tamanho da resposta.
• Conjuntos de Resultados Grandes: Para consultas que retornam muitos resultados, a resposta pode ser truncada ou sofrer um timeout. Use filtragem para reduzir o escopo ou considere getProgramAccountsV2 para suporte a paginação.
• Limites de Taxa: Fique atento aos limites de taxa do provedor RPC, já que chamadas frequentes ou pesadas de getProgramAccounts podem atingir esses limites.
• Conhecimento do Layout dos Dados: Uso eficaz de memcmp requer entendimento do layout de bytes dos dados da conta que você está consultando.
• Disponibilidade jsonParsed: A codificação jsonParsed depende de o nó RPC ter um parser para os tipos de conta do programa específico. É amplamente suportado para programas comuns como SPL Token.

​

Paginação para Conjuntos de Dados Grandes

• Paginação baseada em cursor: Defina limit (1-10.000) e use paginationKey para navegar pelos resultados
• Atualizações incrementais: Use changedSinceSlot para buscar apenas contas modificadas desde um slot específico
• Melhor desempenho: Evita timeouts e reduz o uso de memória
• Comportamento de paginação: Fim da paginação só é indicado quando nenhuma conta é retornada. Menos contas que o limite podem ser retornadas devido à filtragem - continue a paginação até paginationKey ser nulo

// Example: Paginated query for all token accounts
const response = await fetch("https://mainnet.helius-rpc.com/?api-key=YOUR_API_KEY", {
  method: "POST",
  headers: { "Content-Type": "application/json" },
  body: JSON.stringify({
    jsonrpc: "2.0",
    id: "1",
    method: "getProgramAccountsV2",
    params: [
      "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
      {
        encoding: "base64",
        filters: [{ dataSize: 165 }],
        limit: 5000
      }
    ]
  })
});

const data = await response.json();
console.log(`Found ${data.result.accounts.length} accounts`);
if (data.result.paginationKey) {
  console.log("More results available, use paginationKey for next page");
  // Continue pagination even if fewer than limit accounts were returned
} else {
  console.log("End of pagination - no more accounts available");
}

​

Métodos Relacionados