Lecture depuis le réseau

Lisez des données depuis le réseau Solana en récupérant différents comptes. Ce guide explique la structure des comptes Solana. Chaque compte Solana possède une adresse unique utilisée pour localiser les données onchain du compte. Les comptes Solana contiennent soit des données d'état, soit un programme exécutable.

Récupérer un compte de portefeuille

Un compte de portefeuille est un compte appartenant au System Program. Les comptes de portefeuille sont principalement utilisés pour détenir des SOL et signer des transactions. Lorsque des SOL sont envoyés pour la première fois à une nouvelle adresse, un compte système est automatiquement créé.

L'exemple ci-dessous crée un client Kit, génère un nouveau signataire, demande des SOL pour alimenter la nouvelle adresse, et récupère les données du compte depuis l'API RPC du client.

Fetch account

import { createClient, generateKeyPairSigner, lamports } from "@solana/kit";
import { solanaRpc, rpcAirdrop } from "@solana/kit-plugin-rpc";
import { generatedPayer } from "@solana/kit-plugin-signer";

const client = await createClient()
  .use(generatedPayer())
  .use(
    solanaRpc({
      rpcUrl: "http://localhost:8899",
      rpcSubscriptionsUrl: "ws://localhost:8900"
    })
  )
  .use(rpcAirdrop());

const signer = await generateKeyPairSigner();
console.log(`Address: ${signer.address}`);

// Funding an address with SOL automatically creates an account
await client.airdrop(signer.address, lamports(1_000_000_000n));

const accountInfo = await client.rpc.getAccountInfo(signer.address).send();

console.log(accountInfo);

Console

Click to execute the code.

Fetch account

import { createClient, generateKeyPairSigner, lamports } from "@solana/kit";
import { solanaRpc, rpcAirdrop } from "@solana/kit-plugin-rpc";
import { generatedPayer } from "@solana/kit-plugin-signer";

const client = await createClient()
  .use(generatedPayer())
  .use(
    solanaRpc({
      rpcUrl: "http://localhost:8899",
      rpcSubscriptionsUrl: "ws://localhost:8900"
    })
  )
  .use(rpcAirdrop());

const signer = await generateKeyPairSigner();
console.log(`Address: ${signer.address}`);

// Funding an address with SOL automatically creates an account
await client.airdrop(signer.address, lamports(1_000_000_000n));

const accountInfo = await client.rpc.getAccountInfo(signer.address).send();

console.log(accountInfo);

Console

Click to execute the code.

Lorsque vous récupérez un compte de portefeuille avec getAccountInfo(), Kit renvoie la réponse RPC affichée dans l'exemple de sortie à droite.

La réponse comporte deux champs de premier niveau : context décrit le moment où la lecture a eu lieu, et value contient les champs du compte renvoyés par la méthode RPC.

Le champ context indique le slot utilisé pour lire le compte ainsi que la version de l'API RPC qui a servi la réponse. Une lecture ultérieure peut renvoyer un slot ou une version d'API différent.

Le champ value contient l'état du compte renvoyé par la méthode RPC. Les étapes suivantes détaillent les champs contenus dans value dans l'ordre où ils apparaissent.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Le champ lamports contient le solde SOL du compte, mesuré en lamports, la plus petite unité de SOL.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Le champ data contient les données du compte stockées sous forme d'octets. Le RPC retourne les données du compte sous forme de tuple : la chaîne de données encodée, suivie de l'encodage. Pour les comptes portefeuille, la chaîne de données encodée est vide car le compte stocke 0 octet de données.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Le champ owner indique le programme propriétaire du compte. Pour les portefeuilles, le propriétaire est toujours le System Program, avec l'adresse 11111111111111111111111111111111.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Le champ executable indique si l'adresse du compte est appelable. true signifie que l'adresse représente un programme pouvant traiter des instructions. false signifie que le compte stocke un état, tel qu'un solde de portefeuille ou des données de compte, et n'est pas appelé en tant que programme. Les comptes portefeuille utilisent false.

Le champ rentEpoch est un champ hérité d'un mécanisme de rent obsolète. Ce champ est toujours retourné pour des raisons de compatibilité ascendante.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Le champ space indique le nombre d'octets contenus dans le champ data. Le champ space est retourné avec la réponse de récupération du compte, mais il ne fait pas partie du type de données du compte.

Pour l'exemple du compte portefeuille, le champ space est 0 car le champ data contient 0 octet de données.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Lorsque vous récupérez un compte de portefeuille avec getAccountInfo(), Kit renvoie la réponse RPC affichée dans l'exemple de sortie à droite.

La réponse comporte deux champs de premier niveau : context décrit le moment où la lecture a eu lieu, et value contient les champs du compte renvoyés par la méthode RPC.

Le champ value contient l'état du compte renvoyé par la méthode RPC. Les étapes suivantes détaillent les champs contenus dans value dans l'ordre où ils apparaissent.

Le champ lamports contient le solde SOL du compte, mesuré en lamports, la plus petite unité de SOL.

Le champ owner indique le programme propriétaire du compte. Pour les portefeuilles, le propriétaire est toujours le System Program, avec l'adresse 11111111111111111111111111111111.

Le champ rentEpoch est un champ hérité d'un mécanisme de rent obsolète. Ce champ est toujours retourné pour des raisons de compatibilité ascendante.

Pour l'exemple du compte portefeuille, le champ space est 0 car le champ data contient 0 octet de données.

Example output

{
  context: {
    slot: 420602714n,
    apiVersion: "3.1.6"
  },
  value: {
    lamports: 1000000000n,
    data: ["", "base64"],
    owner: "11111111111111111111111111111111",
    executable: false,
    rentEpoch: 0n,
    space: 0n
  }
}

Récupérer le Token Program

L'exemple ci-dessous récupère le Token Program pour illustrer la différence entre les comptes de portefeuille et les comptes de programme. Le Token Program définit des instructions pour travailler avec des tokens, comme la création et le transfert de tokens. Les programmes sont invoqués pour traiter les instructions. L'état du programme, tel que les données de tokens et les soldes, est stocké dans des comptes séparés appartenant au programme.

L'adresse du Token Program est le program account onchain. Pour simplifier, vous pouvez considérer l'adresse du programme comme le programme lui-même, car c'est cette adresse qui est utilisée pour l'invoquer. Pour les programmes évolutifs, le program account stocke des métadonnées et pointe vers un programdata account distinct qui contient le code exécutable déployé. Vous pouvez consulter le code source du Token Program source code ainsi que le program account sur le Solana Explorer.

Fetch program account

import { address, createClient, fetchJsonParsedAccount } from "@solana/kit";
import { solanaRpc } from "@solana/kit-plugin-rpc";
import { generatedPayer } from "@solana/kit-plugin-signer";

const client = await createClient()
  .use(generatedPayer())
  .use(
    solanaRpc({
      rpcUrl: "https://api.mainnet.solana.com"
    })
  );

const tokenProgramAddress = address(
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
);

const accountInfo = await client.rpc
  .getAccountInfo(tokenProgramAddress, {
    encoding: "base64"
  })
  .send();

console.log(accountInfo);

const parsedAccount = await fetchJsonParsedAccount(
  client.rpc,
  tokenProgramAddress
);

console.log(parsedAccount);

Console

Click to execute the code.

Fetch program account

import { address, createClient, fetchJsonParsedAccount } from "@solana/kit";
import { solanaRpc } from "@solana/kit-plugin-rpc";
import { generatedPayer } from "@solana/kit-plugin-signer";

const client = await createClient()
  .use(generatedPayer())
  .use(
    solanaRpc({
      rpcUrl: "https://api.mainnet.solana.com"
    })
  );

const tokenProgramAddress = address(
  "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA"
);

const accountInfo = await client.rpc
  .getAccountInfo(tokenProgramAddress, {
    encoding: "base64"
  })
  .send();

console.log(accountInfo);

const parsedAccount = await fetchJsonParsedAccount(
  client.rpc,
  tokenProgramAddress
);

console.log(parsedAccount);

Console

Click to execute the code.

Le Token Program est un program account exécutable. Les programmes partagent les mêmes champs de base que tous les comptes, mais présentent des différences clés.

L'exemple du Token Program utilise l'encodage base64 pour retourner les données brutes du program account.

Les étapes suivantes parcourent les champs contenus dans value dans l'ordre où ils apparaissent.

Le champ data stocke l'état du program account du BPF Upgradeable Loader. Le premier élément du tuple contient les données complètes du compte encodées en base64. Le second élément du tuple identifie l'encodage. Ici, les 36 octets comprennent les métadonnées et l'adresse du programdata account.

Pour les programmes évolutifs, l'état du program account pointe vers le programdata account distinct qui contient le code exécutable du programme.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

Le champ executable est défini sur true, ce qui indique que l'adresse du compte peut être invoquée en tant que programme.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

Le champ lamports contient le solde en SOL détenu par le program account. Les program accounts doivent disposer de suffisamment de lamports pour rester exempts de rent.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

Chaque program account est détenu par un programme chargeur. Pour le Token Program account, le owner est le BPF Upgradeable Loader.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

Le champ rentEpoch est un champ hérité d'un mécanisme de rent obsolète. Ce champ est toujours retourné pour des raisons de compatibilité ascendante.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

Le champ space indique la taille totale des données du program account en octets. La valeur space est seulement de 36 octets, car le program account stocke les métadonnées du chargeur et l'adresse du programdata account, et non le programme compilé complet.

Token program account

{
  context: {
    apiVersion: "3.1.14",
    slot: 420601581n
  },
  value: {
    data: ["AgAAACfxkLHTr5i4znFMROjK3/n4/EXLjl+sQgLv+BENl903", "base64"],
    executable: true,
    lamports: 2191440n,
    owner: "BPFLoaderUpgradeab1e11111111111111111111111",
    rentEpoch: 18446744073709551615n,
    space: 36n
  }
}

La réponse précédente a retourné le champ data du program account sous forme de tuple base64. La réponse désérialisée décode ces octets en champs nommés sur l'objet data. Le champ programData contient l'adresse du programdata account qui stocke le code du programme exécutable.

Parsed Token program account

{
  executable: true,
  lamports: 43712780n,
  programAddress: "BPFLoaderUpgradeab1e11111111111111111111111",
  space: 36n,
  address: "TokenkegQfeZyiNwAJbNbGKPFXCWuBvf9Ss623VQ5DA",
  data: {
    programData: "3gvYRKWyXRR9xKWe1ZjPhLY5ZJRN7KDB4rFZFGoJfFk2",
    parsedAccountMeta: { program: "bpf-upgradeable-loader", type: "program" }
  },
  exists: true
}