Comment Utiliser getProgramAccounts

​

Cas d’Utilisation Courants

• Trouver Tous les Comptes de Jetons pour une Emission : Découvrez tous les détenteurs d’un jeton SPL spécifique.
• Récupérer les Données Spécifiques à l’Utilisateur : Récupérez tous les comptes créés par un programme pour un utilisateur particulier (par exemple, les positions d’un utilisateur dans un protocole DeFi, leur état de jeu dans un jeu Play-to-Earn).
• Lister Toutes les Instances d’un Type de Compte Personnalisé : Si votre programme définit une structure de compte spécifique, getProgramAccounts peut trouver toutes les instances de cette structure.
• Surveiller l’État du Programme : Observer tous les comptes liés à un programme pour suivre son état général ou son activité.
• Construire des Outils d’Exploration et d’Analyse : Agréger des données sur les programmes et leurs comptes associés.

​

Paramètres de Requête

1. programId (string, requis) :
   • La clé publique encodée en base-58 du programme dont vous souhaitez récupérer les comptes.
   • Exemple : "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA" (pour le Programme SPL Token).
2. options (object, optionnel) : Un objet de configuration avec les champs suivants :
   • commitment (string) : Spécifie le niveau d’engagement (par exemple, "finalized", "confirmed").
   • encoding (string) : Encodage pour le champ data dans chaque compte retourné. Par défaut "base64".
     • "base58" : Alternative plus lente pour les données binaires.
     • "base64" : Encodage standard base64 pour les données binaires.
     • "base64+zstd" : Données binaires encodées en base64, compressées avec zstd.
     • "jsonParsed" : Si le nœud RPC dispose d’un analyseur pour le type de compte du programme (par exemple, SPL Token, Stake), le champ data sera un objet JSON structuré. Cela est fortement recommandé pour la lisibilité et la facilité d’utilisation.
   • filters (array) : Un tableau d’objets de filtre à appliquer aux comptes. Ceci est crucial pour la performance et la pertinence. Vous pouvez utiliser jusqu’à 4 filtres. Les filtres courants incluent :
     • dataSize (object) :
       • dataSize (u64) : Filtre les comptes par leur longueur de données en octets. Exemple : { "dataSize": 165 } (pour les comptes SPL Token).
     • memcmp (object) : Comparaison de la mémoire. Compare une tranche des données du compte avec les octets fournis.
       • offset (usize) : L’offset en octets dans les données du compte à partir duquel commencer la comparaison.
       • bytes (string) : Une chaîne encodée en base-58 des octets à faire correspondre. La chaîne d’octets doit être inférieure à 129 octets.
       • Exemple : Pour trouver les comptes de jetons pour une émission spécifique, vous utiliseriez memcmp avec offset: 0 (où l’adresse de l’émission est stockée dans un compte de jetons) et bytes défini sur la clé publique de l’émission.
   • dataSlice (object) : Ne renvoie qu’une tranche spécifique des données de chaque compte. Utile pour les grands comptes lorsque vous avez besoin uniquement de données partielles.
     • offset (usize) : L’offset en octets à partir duquel commencer la tranche.
     • length (usize) : Le nombre d’octets à renvoyer.
     • Remarque : dataSlice est principalement pour les encodages binaires, pas jsonParsed.
   • withContext (boolean) : Si true, la réponse sera un objet RpcResponse contenant un context (avec slot) et le value (le tableau des comptes). Si false ou omis, il renvoie généralement juste le tableau des comptes. Le comportement peut varier légèrement selon le fournisseur RPC.
   • minContextSlot (u64) : L’emplacement minimal où la requête peut être évaluée.

​

Structure de la Réponse

• pubkey (string) : La clé publique encodée en base-58 du compte.
• account (object) :
  • lamports (u64) : Solde du compte en lamports.
  • owner (string) : Clé publique encodée en base-58 du programme qui possède ce compte (ce sera le programId que vous avez interrogé).
  • data (string, array, ou object) : Les données du compte, formatées selon le paramètre encoding.
    • Pour jsonParsed : Un objet JSON représentant l’état désérialisé du compte.
    • Pour base64 : Un tableau ["encoded_string", "base64"].
  • executable (boolean) : Si le compte est exécutable (c’est-à-dire un programme lui-même).
  • rentEpoch (u64) : L’époque à laquelle ce compte devra payer le loyer.
  • space (u64, optionnel) : La longueur des données du compte en octets. Parfois appelé data.length si les données sont un tampon, ou partie de la structure analysée.

​

Exemples

​

1. Trouver Tous les Comptes de Jetons pour une Emission Spécifique (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. Trouver Tous les Comptes de Jetons Détenus par un Portefeuille Spécifique

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

​

Filtrage Avancé

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

​

Types de Filtres

• memcmp : Filtrer les comptes qui correspondent à un modèle spécifique à un offset donné
• dataSize : Filtrer les comptes par leur taille de données exacte
• Filtres multiples : Toutes les conditions doivent être satisfaites (ET logique)

​

Conseils pour les Développeurs

• Performance : getProgramAccounts peut être intensif en ressources sur les nœuds RPC, surtout sans filtres ou pour les programmes avec de nombreux comptes. Utilisez toujours des filtres (dataSize, memcmp) et dataSlice lorsque possible pour réduire la portée des requêtes et la taille de la réponse.
• Grands Ensembles de Résultats : Pour les requêtes retournant de nombreux résultats, la réponse pourrait être tronquée ou expirer. Utilisez le filtrage pour réduire la portée, ou envisagez getProgramAccountsV2 pour la prise en charge de la pagination.
• Limites de Taux : Soyez attentif aux limites de taux des fournisseurs RPC, car les appels fréquents ou lourds à getProgramAccounts peuvent atteindre ces limites.
• Connaissance de la Disposition des Données : Une utilisation efficace de memcmp nécessite de comprendre la disposition en octets des données de compte que vous interrogez.
• Disponibilité jsonParsed : L’encodage jsonParsed dépend que le nœud RPC dispose d’un analyseur pour les types de comptes du programme spécifique. Il est largement pris en charge pour les programmes courants comme SPL Token.

​

Pagination pour les Grands Jeux de Données

• Pagination basée sur un curseur : Définissez limit (1-10,000) et utilisez paginationKey pour naviguer à travers les résultats
• Mises à jour incrémentales : Utilisez changedSinceSlot pour récupérer uniquement les comptes modifiés depuis un emplacement spécifique
• Meilleure performance : Empêche les expirations et réduit l’utilisation de la mémoire
• Comportement de la pagination : La fin de la pagination est uniquement indiquée lorsque aucun compte n’est retourné. Moins de comptes que la limite peuvent être retournés en raison du filtrage - continuez la pagination jusqu’à ce que paginationKey soit nul

// 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éthodes Connexes