Ohjeen rakenne

Ohjeen rakenne

Instruction koostuu kolmesta kentästä:

• program_id: Kutsuttavan ohjelman ID.
• accounts: Taulukko tilin metadatasta
• data: Tavutaulukko lisädatalla data, jota ohje käyttää.

pub struct Instruction {
    /// Pubkey of the program that executes this instruction.
    pub program_id: Pubkey,
    /// Metadata describing accounts that should be passed to the program.
    pub accounts: Vec<AccountMeta>,
    /// Opaque data passed to the program for its own interpretation.
    pub data: Vec<u8>,
}

Program ID

Ohjeen program_id on ohjelman julkinen avain -osoite, joka sisältää ohjeen suorituslogiikan. Ajoympäristö käyttää tätä kenttää ohjatakseen ohjeen oikealle ohjelmalle käsittelyä varten.

Tilin metadata

Ohjeen accounts-taulukko on järjestetty lista AccountMeta-rakenteista. Metadata on toimitettava jokaiselle tilille, jonka kanssa ohje on vuorovaikutuksessa. Validaattori käyttää tätä metadataa määrittääkseen, mitkä transaktiot voivat suorittua rinnakkain. Transaktiot, jotka kirjoittavat eri tileille, voivat suorittua rinnakkain.

Alla oleva kaavio kuvaa transaktiota, joka sisältää yhden ohjeen. Ohjeen accounts-taulukko sisältää metadatan kahdelle tilille.

Transaktio yhdellä ohjeella. Ohje sisältää kaksi AccountMeta-rakennetta accounts-taulukossaan.

Jokaisessa AccountMeta-rakenteessa on kolme kenttää:

• pubkey: Tilin julkinen avain -osoite
• is_signer: Asetetaan arvoon true, jos tilin on allekirjoitettava transaktio
• is_writable: Asetetaan arvoon true, jos ohje muokkaa tilin dataa

pub struct AccountMeta {
    /// An account's public key.
    pub pubkey: Pubkey,
    /// True if an `Instruction` requires a `Transaction` signature matching `pubkey`.
    pub is_signer: bool,
    /// True if the account data or metadata may be mutated during program execution.
    pub is_writable: bool,
}

Data

Ohjeen data-kenttä on tavutaulukko, joka kertoo ohjelmalle, mikä funktio kutsutaan ja toimittaa kyseisen funktion argumentit. Data alkaa tyypillisesti erottelutavulla tai indeksitavulla, joka tunnistaa kohdistuvan funktion, ja sen jälkeen tulevat sarjallistetut argumentit. Koodausmuodon määrittelee kukin ohjelma (esimerkiksi Borsh-sarjallistus tai mukautettu asettelu).

Yleisiä koodauskäytäntöjä:

• Ydinohjelmat (System, Stake, Vote): Käyttävät Bincode-sarjallistettua enum-varianttiindeksiä, jota seuraavat sarjallistetut argumentit.
• Anchor-ohjelmat: Käyttävät 8-tavuista erottelutapaa (ensimmäiset 8 tavua "global:<function_name>":n SHA-256-tiivisteestä), jota seuraavat Borsh-sarjallistetut argumentit.

Ajoympäristö ei tulkitse data-kenttää. Se välitetään sellaisenaan ohjelman process_instruction-tulokohtaan.

Käännetty ohje

Kun ohjeet sarjallistetaan transaktioviestiin, niistä tulee CompiledInstruction-rakenteita, jotka korvaavat kaikki julkiset avaimet kompakteilla kokonaislukuindekseillä viestin account_keys-taulukkoon.

Esimerkki: SOL-siirto-ohje

Alla oleva esimerkki näyttää SOL-siirto-ohjeen rakenteen.

import { generateKeyPairSigner, lamports } from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";

// Generate sender and recipient keypairs
const sender = await generateKeyPairSigner();
const recipient = await generateKeyPairSigner();

// Define the amount to transfer
const LAMPORTS_PER_SOL = 1_000_000_000n;
const transferAmount = lamports(LAMPORTS_PER_SOL / 100n); // 0.01 SOL

// Create a transfer instruction for transferring SOL from sender to recipient
const transferInstruction = getTransferSolInstruction({
  source: sender,
  destination: recipient.address,
  amount: transferAmount
});

console.log(JSON.stringify(transferInstruction, null, 2));

import { generateKeyPairSigner, lamports } from "@solana/kit";
import { getTransferSolInstruction } from "@solana-program/system";

// Generate sender and recipient keypairs
const sender = await generateKeyPairSigner();
const recipient = await generateKeyPairSigner();

// Define the amount to transfer
const LAMPORTS_PER_SOL = 1_000_000_000n;
const transferAmount = lamports(LAMPORTS_PER_SOL / 100n); // 0.01 SOL

// Create a transfer instruction for transferring SOL from sender to recipient
const transferInstruction = getTransferSolInstruction({
  source: sender,
  destination: recipient.address,
  amount: transferAmount
});

console.log(JSON.stringify(transferInstruction, null, 2));

Alla oleva koodi näyttää edellisten koodiesimerkkien tulosteen. Muoto vaihtelee SDK:iden välillä, mutta huomaa, että jokainen ohje sisältää samat kolme vaadittua tietoa: program_id, accounts, data.

{
  "accounts": [
    {
      "address": "Hu28vRMGWpQXN56eaE7jRiDDRRz3vCXEs7EKHRfL6bC",
      "role": 3,
      "signer": {
        "address": "Hu28vRMGWpQXN56eaE7jRiDDRRz3vCXEs7EKHRfL6bC",
        "keyPair": {
          "privateKey": {},
          "publicKey": {}
        }
      }
    },
    {
      "address": "2mBY6CTgeyJNJDzo6d2Umipw2aGUquUA7hLdFttNEj7p",
      "role": 1
    }
  ],
  "programAddress": "11111111111111111111111111111111",
  "data": {
    "0": 2,
    "1": 0,
    "2": 0,
    "3": 0,
    "4": 128,
    "5": 150,
    "6": 152,
    "7": 0,
    "8": 0,
    "9": 0,
    "10": 0,
    "11": 0
  }
}

Alla olevat esimerkit näyttävät, kuinka siirto-ohje rakennetaan manuaalisesti. (Expanded Instruction-välilehti on toiminnallisesti vastaava kuin Instruction-välilehti.)

const transferAmount = 0.01; // 0.01 SOL

const transferInstruction = getTransferSolInstruction({
  source: sender,
  destination: recipient.address,
  amount: transferAmount * LAMPORTS_PER_SOL
});