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 sen, että selaimet ja käyttäjät voivat purkaa ohjelmakäskyjä, tilidataa ja ohjelman virheitä, ja tarjoavat mahdollisuuden luoda asiakaskirjastoja eri ohjelmointikielillä.

Miksi IDL:t ovat tärkeitä

Standardointi → Yhteinen formaatti ohjelmarajapinnoille.
Kehittäjäkokemus → Luo asiakaskirjastot automaattisesti.
Yhteensopivuus → Muut kehittäjät voivat käyttää ohjelmaasi ilman lähdekoodin lukemista.
Luettavuus → Kaikki voivat lukea ohjelmakäskyjä ja tilidataa selaimissa ilman ohjelman lähdekoodin lukemista.

Mitä IDL:illä voi tehdä

Käsky- ja tilidatan purkaminen

Kaikki selaimet käyttävät ohjelmien IDL:iä käskyjen ja tilidatan purkamiseen. Tässä näet Anchor 0.30.1

ja Legacy IDL -esimerkit Solana Explorerin käyttöliittymässä. Tässä transaktiossa näet puretun käskyn 2048-pelille, mukaan lukien pushInDirection ja sen suunta.

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

Tilimuutosten seuranta

Voit helposti tilata ohjelmasi tilimuutokset käyttämällä luotuja 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)
  );
});

Tapahtumienmäärittelyistä, tilauksista, lokin ja CPI:n purkamisesta, täydennyksistä, skeeman versioinnista ja testauksesta katso Anchor Events.

Transaktioiden purkaminen

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

Rakenna oma asiakkaasi

IDL:n avulla voit luoda oman asiakkaasi monilla kielillä. Löydät vain ohjelman, jonka kanssa haluat toimia, lataat IDL:n ja voit sitten luoda asiakkaan haluamallasi kielellä.

Tässä on esimerkki siitä, miten luodaan asiakas TypeScriptillä.

IDL:t Anchorissa

Jos käytät Anchor-kehystä:

IDL luodaan automaattisesti, kun rakennat ohjelmasi.
Se sijaitsee polussa target/idl/<program>.json.
TypeScript-tyypit luodaan hakemistoon 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 oleva ohjelmatunnus.
metadata: { name, version, spec, ... } ohjelmasta/rajapinnasta.
instructions: kutsuttavat metodit, joilla on accounts, args ja discriminator.
accounts: ohjelman paljastamat tilityypit (diskriminaattoreineen).
types: struct/enum/tyyppialiaset, joihin käskyt/tilit viittaavat.
events / errors / constants: valinnaiset määrittelyt tapahtumille, virhekoodeille ja vakioille.

Huomio: Anchor v0.30 esitteli uuden IDL-spesifikaation. Vanhoissa IDL:issä (ennen versiota 0.30) käytettiin ylätason kenttiä kuten name ja version sekä isMut/isSigner tileissä. Voit muuntaa vanhat IDL:t komennolla anchor idl convert tai rakentaa uudelleen Anchor v0.30+:lla. Jos sinun täytyy muuntaa vanha IDL uuteen spesifikaatioon lennosta, voit myös käyttää tätä muunnoskoodia. Tämä on hyödyllistä esimerkiksi, jos ylläpidät Solana-selainta ja haluat säilyttää taaksepäin yhteensopivuuden.

TypeScript-asiakas

Anchor luo myös automaattisesti TypeScript-asiakkaan sinulle. Löydät luodun 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 luomiseksi 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ää siitä, miten C#-asiakkaan kanssa toimitaan Unityssä Solana-pelipreseteistä tai pelien dokumentaatiosta.

Python-asiakas

Pythonille voit käyttää AnchorPy-kirjastoa.

Lisää asiakasohjelmageneraattoreita tulee saataville Codama-renderöijien kautta tulevaisuudessa.

IDL:t ilman Anchoria

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

Työkalu nimeltä Codama on parhaillaan kehitteillä luomaan IDL:iä Rustista makrojen avulla tai muuntamalla Anchor-IDL:iä. Tässä on kesken oleva esimerkki Codama Macros -makroista Codama-IDL:n luomiseen. Codama muuntaa Anchor/Shank-IDL:t Codama-IDL:ksi. Saat Anchor-IDL:n luomalla sen Anchorilla (tai käyttämällä anchor idl convert vanhoihin projekteihin).
Kunnes Codama-makrot ovat täysin valmiita, voit myös käyttää Metaplex Shankia luomaan Shank-IDL:n ja muuntaa se sitten Codama-IDL:ksi.
Voit myös kirjoittaa IDL:n käsin (Anchor- tai Codama-formaatissa), mutta tämä ei ole kovin luotettavaa. Tekoälytyökalut kuten Cursor voivat auttaa IDL:n kirjoittamisessa, mutta sinun tulisi aina tarkistaa IDL ohjelman lähdekoodista, ja parempi tapa on käyttää Anchoria, Codamaa tai Metaplex Shankia.

IDL:ien tallentaminen ketjuun

On kaksi tapaa ladata IDL:iä ketjuun. Käytetyin ja vakiomuotoisin on Anchor IDL -tili. Anchor mahdollistaa IDL:ien lataamisen ketjuun lisäämällä ohjelmaan ylimääräisiä käskyjä, joiden avulla voit ladata ja päivittää IDL:iäsi ketjussa. Tämä lisää ohjelman kokoa jonkin verran, minkä vuoksi ohjelmaMetadata-ohjelma luotiin. Ohjelmaметadata-ohjelmassa kaikki ohjelmien IDL:t ja security.txt-tiedot, kuten nimi, yhteystieto ja kuvake, tallennetaan ohjelmaMetadata-ohjelman PDA:hin.

Anchor IDL -tili

Anchor tallentaa IDL:t ketjuun ohjelmasi PDA:han.

IDL:t voidaan ladata ketjuun Anchor IDL -tilille.
Tämä mahdollistaa sen, että selaimet, lompakot ja SDK:t voivat hakea IDL:n suoraan Solanasta.

Ensimmäinen kerta (alusta IDL-tili):

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ä siihen 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ä oletusarvoisesti Anchor IDL -tilin luominen on lupavapaata. Lataa siis IDL:si mahdollisimman pian ja aseta sen jälkeen auktoriteetti.

Voit lukea lisää Anchor IDL -tilistä Anchorin dokumentaatiosta.

Program Metadata Program (PMP)

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

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

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

Huomio: Artikkelin viimeisimmän päivityksen aikaan PMP:tä ei vielä tueta kaikissa selaimissa.

Parhaat käytännöt

Paras käytäntö ohjelman käyttöönotossa on käyttää Multisigiä kuten Squads, ja jotta tämä prosessi olisi mahdollisimman helppo, käytä Solana GitHub Actions -työnkulkuja.

Näin ohjelma päivitetään automaattisesti, IDL ladataan, rakenne varmennetaan ja sen jälkeen ehdotetaan transaktiota, jonka multisigisi allekirjoittaa ja ottaa ohjelman käyttöön.

Pidä IDL:t ajan tasalla → Päivitä IDL aina, kun teet muutoksia ohjelmaasi.
Lataa IDL:t ketjuun → läpinäkyvyyden ja työkalutuen vuoksi.
Dokumentoi mukautetut virheet → parantaa asiakkaiden käyttökokemusta.
Varmenna rakenteet → 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 aiheuttaa ongelmia, jos asiakkaita ei ole vielä päivitetty, ja se on yksi syy, miksi program metadata program kirjoitettiin. PMP:n avulla voit käyttää erilaisia siemeniä ohjelmaasi varten ja tehdä versioinnin sen kautta. Suunnitelma ei ole vielä täysin lopullinen ja on avoin keskustelulle.

Lisälukemista

Anchorin dokumentaatio IDL:istä → luo IDL:t ja asiakkaat automaattisesti. (TypeScript, C#, Python)
Codama → IDL-työkalut ja asiakasohjelmageneraattorit (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 nykyisen rikkaan työkalujen ja SDK:iden ekosysteemin.

IDL – helppokäyttöinen ohjelmarajapinta