IDL:t (Interface Definition Language)

IDL tulee sanoista Interface Definition Language (rajapintamäärittelykieli).
Solanassa IDL:t ovat JSON-tiedostoja, jotka kuvaavat ohjelman rajapinnan. Ne mahdollistavat tutkijoiden ja käyttäjien ohjelmakomentojensa, tilitietojensa ja ohjelmien virheiden dekoodauksen sekä tarjoavat mahdollisuuden generoida asiakkaita eri ohjelmointikielillä.

Miksi IDL:t ovat tärkeitä

Standardointi → Yhteinen muoto ohjelmien rajapinnoille.
Kehittäjäkokemus → Generoi asiakaskirjastot automaattisesti.
Yhteensopivuus → Muut kehittäjät voivat olla vuorovaikutuksessa ohjelmasi kanssa ilman lähdekoodin lukemista.
Luettavuus → Kaikki voivat lukea ohjelmakäskyjä ja tilitietoja tutkijoissa ilman ohjelman lähdekoodin lukemista.

Mitä IDL:illä voi tehdä

Käskyjen ja tilitietojen dekoodaus

Kaikki tutkijat käyttävät ohjelma-IDL:iä käskyjen ja tilitietojen dekoodaukseen. Tässä voit nähdä Anchor 0.30.1

ja Legacy IDL -esimerkin Solana Explorer -käyttöliittymässä. Tässä transaktiossa näet dekoodatun käskyn 2048-pelille, mukaan lukien pushInDirection ja sen suunnan.

Voit dekoodata käskyjä ja tilitietoja TypeScript-asiakkaassasi käyttämällä Solana JS -apuvälineitä.

Anchor-tapahtumien tai tilimuutosten jäsentäminen

Voit helposti tilata tilimuutoksia ohjelmassasi käyttämällä generoituja TypeScript-tyyppejä.

import { Connection } from "@solana/web3.js";
const connection = new Connection("https://api.devnet.solana.com");

// Fetch account once
const account = await program.account.counter.fetch(counterPda);

// Subscribe via websocket to account changes
program.account.counter.subscribe(counterPda).on("change", (account) => {
  console.log("Account changed:", account);
});

// Or use decoder to decode any account or instruction data
connection.onAccountChange(counterPda, (accInfo) => {
  console.log(
    "Account changed:",
    program.coder.accounts.decode("counterData", account.data)
  );
});

Voit esimerkiksi lähettää Anchor-tapahtumia ohjelmassasi ja sitten kirjata nämä tapahtumat, tallentaa ne tietokantaan tai käyttää niitä esimerkiksi viestin lähettämiseen Telegram-chattiin.

// Emit the purchase event
emit!(PurchaseMade {
    buyer: *ctx.accounts.signer.key,
    product_name: name,
    price,
    timestamp: Clock::get()?.unix_timestamp,
    table_number,
    receipt_id,
    telegram_channel_id: ctx.accounts.receipts.telegram_channel_id.clone(),
    store_name: ctx.accounts.receipts.store_name.clone(),
    receipts_account: ctx.accounts.receipts.key(),
});

Tätä varten voit käyttää Solana JS -apuvälineitä tapahtumien jäsentämiseen. Tässä on esimerkkitoteutus, joka käyttää Anchor-tapahtumia viestien julkaisemiseen Telegram-chattiin.

Transaktioiden dekoodaus

Voit myös dekoodata transaktioita asiakkaassasi käyttämällä Solana JS -apuvälineitä. Tämä antaa sinulle tyypitetyn objektin koko transaktiosta.

Rakenna oma asiakkaasi

IDL:ää käyttämällä voit luoda oman asiakkaasi monilla eri kielillä. Etsi vain ohjelma, jonka kanssa haluat olla vuorovaikutuksessa, lataa IDL ja generoi sitten asiakas haluamallasi ohjelmointikielellä.

Tässä on esimerkki siitä, miten asiakkaan voi generoida TypeScriptillä.

IDL:t Anchorissa

Jos käytät Anchor-kehystä:

IDL generoidaan automaattisesti, kun rakennat ohjelmasi.
Se sijaitsee polussa target/idl/<program>.json.
TypeScript-tyypit generoidaan kansioon target/types/<program>.ts.
Ohjelman osoite tallennetaan IDL:ään (idl.address).

anchor build
cat target/idl/counter.json

IDL:n rakenne

Tässä on minimaalinen esimerkki (Anchor v0.30+ -spesifikaatio):

{
  "address": "6khKp4BeJpCjBY1Eh39ybiqbfRnrn2UzWeUARjQLXYRC",
  "metadata": {
    "name": "counter",
    "version": "0.1.0",
    "spec": "0.1.0"
  },
  "instructions": [
    {
      "name": "increment",
      "discriminator": [11, 18, 104, 9, 104, 174, 59, 33],
      "accounts": [{ "name": "counter", "writable": true }],
      "args": []
    }
  ],
  "accounts": [
    {
      "name": "Counter",
      "discriminator": [255, 176, 4, 245, 188, 253, 124, 25]
    }
  ],
  "types": [
    {
      "name": "Counter",
      "type": {
        "kind": "struct",
        "fields": [{ "name": "count", "type": "u64" }]
      }
    }
  ]
}

address: ketjussa olevan ohjelman tunnus.
metadata: { name, version, spec, ... } ohjelmasta/rajapinnasta.
instructions: kutsuttavat metodit, joilla on accounts, args ja discriminator.
accounts: ohjelman paljastamat tilityypit (erottimineen).
types: käskyjen/tilien viittaamat struct/enum/tyyppialiakset.
events / errors / constants: valinnaiset määrittelyt tapahtumille, virhekoodeille ja vakioille.

Huomio: Anchor v0.30 esitteli uuden IDL-spesifikaation. Vanhat IDL:t (ennen v0.30) käyttivät kenttiä kuten name, version ylimmällä tasolla sekä isMut/isSigner tileissä. Voit muuntaa vanhat IDL:t käyttämällä anchor idl convert tai rakentamalla uudelleen Anchor v0.30+:lla. Jos tarvitset muuntaa vanhan IDL:n uuteen spesifikaatioon lennossa, voit myös käyttää tätä muunnoskoodia. Tämä on hyödyllistä esimerkiksi, jos ylläpidät Solana-tutkijaa ja haluat säilyttää taaksepäin yhteensopivuuden.

TypeScript-asiakas

Anchor generoi myös automaattisesti TypeScript-asiakkaan puolestasi. Löydät generoidun asiakkaan target/types-kansiosta.

Sitten asiakkaassasi (TypeScript, v0.30+) voit kutsua ohjelmakäskyjä ja hakea tilejä yhtä helposti kuin tässä:

import { AnchorProvider, Program } from "@coral-xyz/anchor";
import idl from "./counter.json";

const provider = AnchorProvider.local();
const program = new Program(idl, provider);
await program.methods.increment().rpc();

C#-asiakas

C#-asiakkaan generoimiseksi voit käyttää seuraavaa komentoa:

cd program
dotnet tool install Solana.Unity.Anchor.Tool <- run once
dotnet anchorgen -i target/idl/counter.json -o target/idl/Counter.cs

Voit lukea lisää C#-asiakkaan käytöstä Unityn kanssa Solana-pelien presetistä tai pelidokumentaatiosta.

Python-asiakas

Pythonille voit käyttää AnchorPy-kirjastoa.

Lisää asiakkaiden generaattoreita tulee saataville Codama-renderöijien avulla tulevaisuudessa.

IDL:t ilman Anchoria

Kaikki ohjelmat eivät ole rakennettu Anchorilla.
Natiiveille Solana-ohjelmille:

Työkalu nimeltä Codama on parhaillaan kehitteillä IDL:ien generoimiseksi Rustista makrojen avulla tai muuntamalla Anchor-IDL:iä. Tässä on kesken oleva esimerkki Codama-makroista Codama IDL:n generoimiseksi. Codama muuntaa Anchor/Shank IDL:t Codama IDL:ksi. Anchor IDL:n saamiseksi generoi se Anchorilla (tai käytä anchor idl convert vanhoille projekteille).
Kunnes Codama-makrot ovat täysin valmiit, voit myös käyttää Metaplex Shankia Shank IDL:n generoimiseen ja sitten muuntaa sen Codama IDL:ksi.
Voit myös kirjoittaa IDL:n käsin (Anchor- tai Codama-muodossa), mutta tämä ei ole kovin luotettavaa. Tekoälytyökalut kuten Cursor voivat auttaa IDL:n kirjoittamisessa, mutta sinun tulee aina tarkistaa IDL ohjelman lähdekoodia vasten – parempi tapa on käyttää Anchoria, Codamaa tai Metaplex Shankia.

IDL:ien tallentaminen ketjuun

IDL:ien lataamiseen ketjuun on kaksi tapaa. Yleisin ja standardein on Anchor IDL account. Anchor mahdollistaa IDL:ien lataamisen ketjuun lisäämällä ohjelmaan lisäkäskyjä, joiden avulla voit ladata ja päivittää IDL:iäsi ketjussa. Tämä lisää ohjelman kokoa, minkä vuoksi program metadata program luotiin. Program metadata program -ohjelmassa kaikki ohjelma-IDL:t ja security.txt-tiedot, kuten nimi, yhteystieto ja kuvake, tallennetaan program metadata programin PDA:ihin.

Anchor IDL Account

Anchor tallentaa IDL:t ketjuun ohjelmasi PDA:han.

IDL:t voidaan ladata ketjuun Anchor IDL accountiin.
Tämä mahdollistaa tutkijoiden, lompakoiden ja SDK:iden hakea IDL:n suoraan Solanasta.

Ensimmäinen kerta (alusta IDL account):

anchor idl init <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Päivitykset (myöhemmät päivitykset auktoriteetin toimesta):

anchor idl upgrade <PROGRAM_ID> -f target/idl/counter.json --provider.cluster devnet

Hyödyllisiä asiaan liittyviä komentoja:

anchor idl fetch -o idl.json <PROGRAM_ID>
anchor idl authority <PROGRAM_ID>
anchor idl set-authority -p <PROGRAM_ID> -n <NEW_AUTHORITY>
anchor idl erase-authority -p <PROGRAM_ID>

Huomaa, että oletuksena Anchor IDL accountin luominen on lupavapaa. Lataa siis IDL:si mahdollisimman pian ja aseta sen jälkeen auktoriteetti.

Voit lukea lisää Anchor IDL accountista Anchor-dokumentaatiosta.

Program Metadata Program (PMP)

Program metadata program on ohjelma, jonka avulla voit tallentaa ohjelma-IDL:t ja security.txt-tiedot, kuten nimen, yhteystiedon ja kuvakkeen, ketjuun. Tästä tulee todennäköisesti tulevaisuudessa standarditapa tallentaa IDL:t ketjuun.

npx @solana-program/program-metadata write idl <program-id> ./idl.json

Voit lukea lisää program metadata programista program metadata program -dokumentaatiosta.

Huomio: Artikkelin viimeisimmän päivityksen hetkellä PMP ei ole vielä kaikkien tutkijoiden tukema.

Parhaat käytännöt

Paras käytäntö ohjelman käyttöönotoissa on käyttää Multisigiä, kuten Squads, ja tehdä tästä prosessista mahdollisimman helppo käyttämällä Solana GitHub Actions -työnkulkuja.

Näin ohjelma päivitetään automaattisesti, IDL ladataan, rakentaminen varmennetaan ja ehdotetaan transaktio Multisigillesi allekirjoitettavaksi ja ohjelman käyttöönottamiseksi.

Pidä IDL:t ajan tasalla → Päivitä IDL aina, kun teet muutoksia ohjelmaasi.
Lataa IDL:t ketjuun → läpinäkyvyyden ja työkalujen tuen vuoksi.
Dokumentoi mukautetut virheet → parantaa asiakkaiden käyttökokemusta.
Varmenna rakentaminen → varmista, että IDL vastaa käyttöönotettua ohjelmaa.

IDL:ien versiointi

Tällä hetkellä Anchorilla voi olla ketjussa vain yksi versio IDL:stä kerrallaan. Tämä tarkoittaa, että jos haluat tehdä muutoksia ohjelmaasi, sinun täytyy ladata uusi versio IDL:stä, mieluiten samaan aikaan kuin päivität ohjelman. Tämä voi johtaa ongelmiin, jos asiakkaat eivät ole vielä päivitetty, ja tämä on yksi syy miksi program metadata program kirjoitettiin. PMP:n avulla sinulla voi olla eri siemeniä ohjelmallesi ja tehdä versiointi sen avulla. Tämä suunnittelu ei ole vielä täysin valmis ja on avoinna keskustelulle.

Lisälukemista

Anchor Docs IDL:istä → generoi IDL:t ja asiakkaat automaattisesti. (TypeScript, C#, Python)
Codama → IDL-työkalut ja asiakkaiden generaattorit (Rust, JS/TS, Umi/Kit jne.).
Program Metadata Program → tallenna IDL:t ja security.txt-tiedot ketjuun.

Nämä ovat IDL:ien perusteet Solanassa. Ne ovat silta ketjussa olevien ohjelmien ja ketjun ulkopuolisten asiakkaiden välillä, mahdollistaen sen rikkaan ekosysteemin työkaluja ja SDK:ita, jonka näet tänään.

IDL – helppokäyttöinen ohjelmaliitäntä