IDL'ler (Arayüz Tanım Dili)

IDL, Arayüz Tanım Dili (Interface Definition Language) anlamına gelir.
Solana'da IDL'ler, bir programın arayüzünü tanımlayan JSON dosyalarıdır. Gezginlerin ve kullanıcıların program talimatlarını, hesap verilerini ve program hatalarını çözmesine olanak tanır; farklı programlama dillerinde istemci üretme imkânı sunar.

IDL'lerin Önemi

Standartlaştırma → Program arayüzleri için ortak bir format.
Geliştirici Deneyimi → İstemci SDK'larını otomatik olarak oluşturun.
Birleştirilebilirlik → Diğer geliştiriciler, kaynak kodunu okumadan programınızla etkileşime girebilir.
Okunabilirlik → Herkes, programın kaynak kodunu okumadan talimatları ve hesap verilerini gezginlerde okuyabilir.

IDL'lerle Neler Yapabilirsiniz

Talimat ve Hesap Verilerini Çözme

Tüm Gezginler, talimatları ve hesap verilerini çözmek için program IDL'lerini kullanır. Burada Solana Explorer arayüzünde bir Anchor 0.30.1 ve bir Eski IDL örneği görebilirsiniz. Bu işlemde pushInDirection ve yönü dahil olmak üzere bir 2048 oyunu için çözülmüş talimatı görebilirsiniz.

TypeScript istemcinizde talimatları ve hesap verilerini çözmek için Solana JS yardımcılarını kullanabilirsiniz.

Hesap Değişikliklerini Ayrıştırma

Oluşturulan TypeScript türlerini kullanarak programınızdaki hesap değişikliklerine kolayca abone olabilirsiniz.

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

Olay tanımları, abonelikler, log ve CPI çözme, geri doldurma, şema sürümleme ve test için bkz. Anchor Events.

İşlemleri Çözme

İstemcinizde işlemleri çözmek için Solana JS yardımcılarını da kullanabilirsiniz. Bu, tüm işlemin türlendirilmiş bir nesnesini döndürür.

Kendi İstemcinizi Oluşturun

Bir IDL kullanarak birçok dilde kendi istemcinizi oluşturabilirsiniz. Etkileşime girmek istediğiniz bir programı bulun, IDL'yi indirin ve ardından tercih ettiğiniz dilde bir istemci oluşturabilirsiniz.

TypeScript'te istemci oluşturmanın nasıl yapıldığına dair bir örnek burada.

Anchor'da IDL'ler

Anchor framework'ünü kullanıyorsanız:

Programınızı derlediğinizde IDL otomatik olarak oluşturulur.
target/idl/<program>.json konumunda yer alır.
TypeScript türleri target/types/<program>.ts konumunda oluşturulur.
Program adresi IDL içinde saklanır (idl.address).

anchor build
cat target/idl/counter.json

Bir IDL'nin Anatomisi

İşte minimal bir örnek (Anchor v0.30+ spesifikasyonu):

{
  "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: zincir üzerindeki program ID'si.
metadata: Program/arayüz hakkında { name, version, spec, ... } bilgisi.
instructions: accounts, args ve discriminator içeren çağrılabilir metotlar.
accounts: Program tarafından sunulan hesap türleri (discriminator'larla birlikte).
types: Talimatlar/hesaplar tarafından başvurulan struct/enum/tür takma adları.
events / errors / constants: Olaylar, hata kodları ve sabitler için isteğe bağlı tanımlar.

Not: Anchor v0.30, yeni bir IDL spesifikasyonu sundu. Eski IDL'ler (0.30 öncesi) üst düzeyde name, version gibi alanlar ve hesaplarda isMut/isSigner kullanıyordu. Eski IDL'leri anchor idl convert kullanarak veya Anchor v0.30+ ile yeniden derleyerek dönüştürebilirsiniz. Eski bir IDL'yi anında yeni spesifikasyona dönüştürmeniz gerekiyorsa bu dönüştürme kodunu da kullanabilirsiniz. Bu, örneğin bir Solana gezgini yönetiyorsanız ve geriye dönük uyumluluğu korumak istiyorsanız işe yarar.

TypeScript İstemcisi

Anchor ayrıca sizin için otomatik olarak bir TypeScript istemcisi de oluşturur. Oluşturulan istemciyi target/types klasöründe bulabilirsiniz.

Ardından istemcinizde (TypeScript, v0.30+) program talimatlarını çağırabilir ve hesapları bu kadar kolay şekilde getirebilirsiniz:

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# İstemcisi

Bir C# istemcisi oluşturmak için aşağıdaki komutu kullanabilirsiniz:

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

Unity'de bir C# istemcisiyle nasıl etkileşime girileceği hakkında daha fazla bilgiyi Solana oyun ön ayarında veya Oyun dokümanlarında okuyabilirsiniz.

Python İstemcisi

Python için AnchorPy kütüphanesini kullanabilirsiniz.

Gelecekte Codama renderers kullanılarak daha fazla istemci üreteci mevcut olacaktır.

Anchor Olmadan IDL'ler

Tüm programlar Anchor ile geliştirilmez.
Yerel Solana programları için:

Codama adlı bir araç, makrolar aracılığıyla Rust'tan IDL oluşturmak veya Anchor IDL'lerini dönüştürmek amacıyla geliştirilmektedir. Bir Codama IDL oluşturmak için Codama Macros ile ilgili devam eden bir örnek mevcuttur. Codama, Anchor/Shank IDL'lerini Codama IDL'sine dönüştürür. Bir Anchor IDL elde etmek için Anchor ile oluşturun (veya eski projeler için anchor idl convert kullanın).
Codama makroları tamamen hazır olana kadar bir Shank IDL oluşturmak için Metaplex Shank'ı kullanabilir, ardından bunu bir Codama IDL'sine dönüştürebilirsiniz.
IDL'yi elle de yazabilirsiniz (Anchor veya Codama formatlarında), ancak bu pek güvenilir değildir. Cursor gibi yapay zeka araçları IDL'yi yazmaya yardımcı olabilir, ancak IDL'yi her zaman programın kaynak kodu ile doğrulamalısınız; daha iyi yöntem Anchor, Codama veya Metaplex Shank kullanmaktır.

IDL'leri Zincir Üzerinde Depolama

IDL'leri zincir üzerinde yüklemek için iki yol mevcuttur. En yaygın ve standart olanı Anchor IDL hesabıdır. Anchor, IDL'lerinizi zincir üzerinde yüklemenize programınıza ek talimatlar ekleyerek IDL'lerinizi zincir üzerinde yüklemenizi ve güncellemenizi sağlar. Bu, programa biraz ekstra boyut katar ve bu nedenle program metadata programı oluşturulmuştur. Program metadata programında tüm program IDL'leri ve name, contact ve icon gibi security.txt bilgileri program metadata program'ının PDA'larında saklanır.

Anchor IDL Hesabı

Anchor, IDL'leri programınızın bir PDA'sında zincir üzerinde saklar.

IDL'ler, Anchor IDL hesabına zincir üzerinde yüklenebilir.
Bu, gezginlerin, cüzdanların ve SDK'ların IDL'yi doğrudan Solana'dan almasına olanak tanır.

İlk kez (IDL hesabını başlatın):

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

Yükseltmeler (yetkili tarafından sonraki güncellemeler):

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

Kullanışlı ilgili komutlar:

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>

Varsayılan olarak Anchor IDL hesabı oluşturmanın izin gerektirmediğini unutmayın. Bu nedenle IDL'nizi mümkün olan en kısa sürede yükleyin ve ardından bir yetkili belirleyin.

Anchor IDL hesabı hakkında daha fazla bilgiyi Anchor dokümanlarında okuyabilirsiniz.

Program Metadata Programı (PMP)

Program metadata programı, program IDL'lerini ve name, contact ve icon gibi security.txt bilgilerini zincir üzerinde depolamanıza olanak tanıyan bir programdır. Bu, gelecekte IDL'leri zincir üzerinde saklamanın standart yolu olacaktır.

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

Program metadata programı hakkında daha fazla bilgiyi program metadata program dokümanlarında okuyabilirsiniz.

Not: Makalenin son güncellemesi itibarıyla PMP henüz tüm gezginler tarafından desteklenmemektedir.

En İyi Uygulamalar

Program dağıtımları için en iyi uygulama, Squads gibi bir Multisig kullanmak ve bu süreci olabildiğince kolaylaştırmak için Solana GitHub Actions iş akışlarını kullanmaktır.

Bu şekilde program otomatik olarak yükseltilir, IDL yüklenir, derleme doğrulanır ve ardından multisig'inizin imzalaması ve programı dağıtması için bir işlem önerilir.

IDL'leri güncel tutun → Programınızda değişiklik yaptığınızda IDL'yi her zaman güncelleyin.
IDL'leri zincir üzerinde yükleyin → şeffaflık ve araç desteği için.
Özel hataları belgeleyin → istemciler için kullanıcı deneyimini iyileştirir.
Derlemeleri doğrulayın → IDL'nin dağıtılan programla eşleştiğinden emin olun.

IDL Sürümlemesi

Şu anda Anchor ile zincirde aynı anda yalnızca bir IDL sürümüne sahip olabilirsiniz. Bu, programınızda değişiklik yapmak istediğinizde, tercihen programı yükselttiğinizle aynı anda IDL'nin yeni bir sürümünü yüklemeniz gerektiği anlamına gelir. Bu, istemciler henüz güncellenmemişse sorunlara yol açabilir ve program metadata programının yazılmasının nedenlerinden biridir. PMP ile programınız için farklı seed'ler kullanabilecek ve bu şekilde sürümleme yapabileceksiniz. Bunun tasarımı henüz tamamen kesinleşmemiş olup tartışmaya açıktır.

Daha Fazla Okuma

IDL'ler Hakkında Anchor Dokümanları → IDL'leri ve istemcileri otomatik olarak oluşturur. (TypeScript, C#, Python)
Codama → IDL araçları + istemci üreticileri (Rust, JS/TS, Umi/Kit vb.).
Program Metadata Program → IDL'leri ve security.txt bilgilerini zincir üzerinde depolayın.

Solana'daki IDL'lerin temellerini bu şekilde özetleyebiliriz. IDL'ler, zincir üzerindeki programlar ile zincir dışı istemciler arasındaki köprüdür ve bugün gördüğünüz zengin araç ve SDK ekosistemini mümkün kılar.

IDL - Kullanımı Kolay Bir Program Arayüzü