Cómo usar getProgramAccounts

El método RPC getProgramAccounts es una herramienta potente para consultar la blockchain de Solana. Te permite recuperar todas las cuentas que pertenecen a un programa específico en la cadena. Esto es esencial para una amplia variedad de aplicaciones, desde encontrar todas las cuentas de tokens asociadas con un usuario para una acuñación de token específica hasta descubrir todas las cuentas de datos específicas de un usuario para una aplicación descentralizada. Debido a la cantidad potencialmente grande de cuentas que puede poseer un programa, getProgramAccounts ofrece sólidas funciones de filtrado para ayudarte a limitar la búsqueda y recuperar de forma eficiente solo los datos que necesitas. Para las aplicaciones que necesitan consultar conjuntos muy grandes de cuentas de programas, considera usar getProgramAccountsV2, que admite paginación basada en cursor con tamaños de página configurables de hasta 10,000 cuentas por solicitud.

Casos de uso comunes

Encontrar todas las cuentas de tokens de una acuñación: Descubre todos los titulares de un token SPL específico.
Recuperar datos específicos de un usuario: Obtén todas las cuentas creadas por un programa para un usuario específico (por ejemplo, las posiciones de un usuario en un protocolo DeFi o su estado en un juego Play-to-Earn).
Enumerar todas las instancias de un tipo de cuenta personalizado: Si tu programa define una estructura de cuenta específica, getProgramAccounts puede encontrar todas las instancias de esa estructura.
Supervisar el estado del programa: Observa todas las cuentas relacionadas con un programa para hacer un seguimiento de su estado general o actividad.
Crear exploradores y herramientas de análisis: Agrega datos sobre los programas y sus cuentas asociadas.

Parámetros de solicitud

programId (string, obligatorio):
- La clave pública codificada en base 58 del programa cuyas cuentas quieres obtener.
- Ejemplo: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" (para el programa de tokens SPL).
options (object, opcional): Un objeto de configuración con los siguientes campos:
- commitment (string): Especifica el nivel de compromiso (por ejemplo, "finalized", "confirmed").
- encoding (string): Codificación del campo data dentro de cada cuenta devuelta. El valor predeterminado es "base64".
  - "base58": Alternativa más lenta para datos binarios.
  - "base64": Codificación base64 estándar para datos binarios.
  - "base64+zstd": Datos binarios codificados en base64 y comprimidos con zstd.
  - "jsonParsed": Si el nodo RPC tiene un analizador para el tipo de cuenta del programa (por ejemplo, SPL Token o Stake), el campo data será un objeto JSON estructurado. Se recomienda especialmente para facilitar la lectura y el uso.
- filters (array): Un arreglo de objetos de filtro que se aplicarán a las cuentas. Es fundamental para el rendimiento y la relevancia. Puedes usar hasta 4 filtros. Los filtros comunes incluyen:
  - dataSize (object):
    - dataSize (u64): Filtra las cuentas según la longitud de sus datos en bytes. Ejemplo: { "dataSize": 165 } (para cuentas de tokens SPL).
  - memcmp (object): Comparación de memoria. Compara una sección de los datos de la cuenta con los bytes proporcionados.
    - offset (usize): El desplazamiento en bytes dentro de los datos de la cuenta donde se iniciará la comparación.
    - bytes (string): Una cadena codificada en base 58 con los bytes que deben coincidir. La cadena de bytes debe tener menos de 129 bytes.
    - Ejemplo: Para encontrar cuentas de tokens de una acuñación específica, usarías memcmp con offset: 0 (donde se almacena la dirección de acuñación en una cuenta de token) e bytes establecido en la clave pública de la acuñación.
- dataSlice (object): Devuelve solo una sección específica de los datos de cada cuenta. Resulta útil para cuentas grandes cuando solo necesitas datos parciales.
  - offset (usize): El desplazamiento en bytes desde el que se iniciará la sección.
  - length (usize): La cantidad de bytes que se devolverá.
  - Nota: dataSlice está diseñado principalmente para codificaciones binarias, no para jsonParsed.
- withContext (boolean): Si es true, la respuesta será un objeto RpcResponse que contiene un context (con slot) y el value (el arreglo de cuentas). Si es false o se omite, normalmente solo devuelve el arreglo de cuentas. El comportamiento puede variar ligeramente según el proveedor de RPC.
- minContextSlot (u64): El slot mínimo en el que se puede evaluar la solicitud.

Estructura de la respuesta

La respuesta es un arreglo de objetos, donde cada objeto representa una cuenta encontrada e incluye:

pubkey (string): La clave pública de la cuenta codificada en base 58.
account (object):
- lamports (u64): Saldo de la cuenta en lamports.
- owner (string): Clave pública codificada en base 58 del programa que posee esta cuenta (será el programId que consultaste).
- data (string, array o object): Los datos de la cuenta, con el formato especificado por el parámetro encoding.
  - Para jsonParsed: Un objeto JSON que representa el estado deserializado de la cuenta.
  - Para base64: Un arreglo ["encoded_string", "base64"].
- executable (boolean): Indica si la cuenta es ejecutable (es decir, si es un programa).
- rentEpoch (u64): La época en la que esta cuenta deberá pagar alquiler nuevamente.
- space (u64, opcional): La longitud de los datos de la cuenta en bytes. A veces se denomina data.length si los datos son un búfer, o forma parte de la estructura analizada.

Si se usa withContext: true, este arreglo estará anidado en el campo value de un objeto RpcResponse.

Ejemplos

1. Encontrar todas las cuentas de tokens de una acuñación específica (USDC)

Este ejemplo encuentra todas las cuentas de tokens SPL que contienen USDC. Usa dataSize para filtrar cuentas de tokens (165 bytes) e memcmp para buscar coincidencias con la dirección de acuñación de USDC en el desplazamiento 0.

# 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 las cuentas de tokens que pertenecen a una billetera específica

Este ejemplo encuentra todas las cuentas de tokens SPL que pertenecen a una dirección de billetera específica. Usa dataSize (165 bytes) e memcmp en el desplazamiento 32 (donde se almacena la clave pública del propietario en una cuenta de token).

# 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();

Filtrado avanzado

Optimiza tus consultas con filtros para reducir el tamaño de la respuesta y mejorar el rendimiento:

// 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);

API Reference

getProgramAccounts

Tipos de filtros

memcmp: Filtra las cuentas que coincidan con un patrón específico en un desplazamiento determinado
dataSize: Filtra las cuentas según el tamaño exacto de sus datos
Varios filtros: Deben cumplirse todas las condiciones (operador AND lógico)

Consejos para desarrolladores

Rendimiento: getProgramAccounts puede consumir muchos recursos en los nodos RPC, especialmente sin filtros o para programas con muchas cuentas. Siempre que sea posible, usa filtros (dataSize, memcmp) e dataSlice para reducir el alcance de la consulta y el tamaño de la respuesta.
Conjuntos de resultados grandes: En consultas que devuelven muchos resultados, la respuesta puede truncarse o agotar el tiempo de espera. Usa filtros para reducir el alcance o considera getProgramAccountsV2 para obtener compatibilidad con la paginación.
Límites de frecuencia: Ten en cuenta los límites de frecuencia del proveedor de RPC, ya que las llamadas frecuentes o pesadas a getProgramAccounts pueden alcanzar estos límites.
Conocimiento del diseño de los datos: Para usar memcmp de forma eficaz, debes comprender la disposición en bytes de los datos de la cuenta que consultas.
Disponibilidad de jsonParsed: La codificación jsonParsed depende de que el nodo RPC tenga un analizador para los tipos de cuenta del programa específico. Es ampliamente compatible con programas comunes como SPL Token.

getProgramAccounts es un método indispensable para los desarrolladores que necesitan consultar e interactuar con conjuntos de cuentas pertenecientes a un programa. Dominar sus opciones de filtrado es clave para crear aplicaciones de Solana eficientes y robustas.

Paginación para conjuntos de datos grandes

Para aplicaciones que trabajan con programas que poseen una gran cantidad de cuentas (más de 10,000), usa getProgramAccountsV2, que ofrece:

Paginación basada en cursor: Establece limit (1-10,000) y usa paginationKey para navegar por los resultados
Actualizaciones incrementales: Usa changedSinceSlot para obtener solo las cuentas modificadas desde un slot específico
Mejor rendimiento: Evita que se agote el tiempo de espera y reduce el uso de memoria
Comportamiento de la paginación: El final de la paginación solo se indica cuando no se devuelve ninguna cuenta. Debido al filtrado, pueden devolverse menos cuentas que el límite; continúa la paginación hasta que paginationKey sea null

// 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

getProgramAccountsV2

Versión paginada con navegación basada en cursor para conjuntos de datos grandes

Comienza aquí

Datos en tiempo real

Trading de baja latencia

Datos históricos y de billeteras

Guías de métodos RPC

Preparación para producción

Uso de Orb

Otras guías prácticas

Cómo usar getProgramAccounts

Casos de uso comunes

Parámetros de solicitud

Estructura de la respuesta

Ejemplos

1. Encontrar todas las cuentas de tokens de una acuñación específica (USDC)

2. Encontrar todas las cuentas de tokens que pertenecen a una billetera específica

Filtrado avanzado

API Reference

Tipos de filtros

Consejos para desarrolladores

Paginación para conjuntos de datos grandes

Métodos relacionados

getProgramAccountsV2

​Casos de uso comunes

​Parámetros de solicitud

​Estructura de la respuesta

​Ejemplos

​1. Encontrar todas las cuentas de tokens de una acuñación específica (USDC)

​2. Encontrar todas las cuentas de tokens que pertenecen a una billetera específica

​Filtrado avanzado

API Reference

​Tipos de filtros

​Consejos para desarrolladores

​Paginación para conjuntos de datos grandes

​Métodos relacionados

getProgramAccountsV2

Casos de uso comunes

Parámetros de solicitud

Estructura de la respuesta

Ejemplos

1. Encontrar todas las cuentas de tokens de una acuñación específica (USDC)

2. Encontrar todas las cuentas de tokens que pertenecen a una billetera específica

Filtrado avanzado

Tipos de filtros

Consejos para desarrolladores

Paginación para conjuntos de datos grandes

Métodos relacionados