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ı çözümlemesine olanak tanır; ayrıca farklı programlama dillerinde istemci oluşturma imkânı sunar.

IDL'ler Neden Önemlidir

Standardizasyon → 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 gezginlerde program talimatlarını ve hesap verilerini okuyabilir.

IDL'lerle Neler Yapabilirsiniz

Talimat ve Hesap Verilerini Çözümleme

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

TypeScript istemcinizde talimatları ve hesap verilerini Solana JS yardımcıları kullanarak çözümleyebilirsiniz.

Anchor Olaylarını veya 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)
  );
});

Örneğin, programınızda Anchor olayları yayımlayabilir ve ardından bu olayları kaydedebilir, bir veritabanına yazabilir ya da bir Telegram sohbetine mesaj göndermek gibi amaçlarla kullanabilirsiniz.

// 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(),
});

Bunun için olayları ayrıştırmak amacıyla Solana JS yardımcıları kullanabilirsiniz. İşte Telegram sohbetine mesaj göndermek için Anchor olaylarını kullanan bir örnek uygulama.

İşlemleri Çözümleme

Ayrıca Solana JS yardımcıları kullanarak istemcinizde işlemleri de çözümleyebilirsiniz. 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 geçmek istediğiniz bir programı bulun, IDL'yi indirin ve ardından tercih ettiğiniz dilde bir istemci oluşturun.

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

Anchor'da IDL'ler

Anchor çerçevesini kullanıyorsanız:

IDL, programınızı oluşturduğunuzda otomatik olarak üretilir.
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 üstündeki program kimliği.
metadata: program/arayüzle ilgili { name, version, spec, ... } bilgileri.
instructions: accounts, args ve bir discriminator içeren çağrılabilir metotlar.
accounts: program tarafından açığa çıkarılan 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üşüm 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 C# istemcisiyle nasıl etkileşime geçileceği hakkında daha fazla bilgiyi Solana oyunlar ön ayarında veya Oyunlar belgelerinde okuyabilirsiniz.

Python İstemcisi

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

Gelecekte Codama renderer'ları kullanılarak daha fazla istemci oluşturucu mevcut olacaktır.

Anchor Olmadan IDL'ler

Tüm programlar Anchor ile oluşturulmaz.
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 için şu anda geliştirilme aşamasındadır. İşte Codama IDL oluşturmak için Codama Makroları hâlâ devam eden bir örnek. Codama, Anchor/Shank IDL'lerini Codama IDL'sine dönüştürür. Anchor IDL elde etmek için Anchor ile oluşturun (ya da eski projeler için anchor idl convert kullanın).
Codama makroları tamamen hazır olana kadar Shank IDL oluşturmak ve ardından bunu Codama IDL'sine dönüştürmek için Metaplex Shank da kullanabilirsiniz.
Ayrıca IDL'yi elle de yazabilirsiniz (Anchor veya Codama formatlarında), ancak bu çok güvenilir değildir. Cursor gibi yapay zeka araçları IDL yazmaya yardımcı olabilir, ancak IDL'yi her zaman programın kaynak koduyla doğrulamalısınız; daha iyi bir yol, Anchor, Codama veya Metaplex Shank kullanmaktır.

IDL'leri Zincir Üstünde Depolama

IDL'leri zincir üstüne yüklemek için iki yol vardır. En yaygın ve standart olanı Anchor IDL hesabıdır. Anchor'ın IDL'lerinizi zincir üstüne yüklemenize olanak tanıma biçimi, programınıza IDL'lerinizi zincir üstünde yüklemenizi ve güncellemenizi sağlayan ek talimatlar ekleyerek gerçekleşir. Bu, programa biraz ekstra boyut ekler ve program metadata programının oluşturulmasının nedeni budur. program account metadata programında tüm program IDL'leri ve ad, iletişim ve simge 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 üstünde saklar.

IDL'ler, Anchor IDL hesabına zincir üstünde 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 yapılan 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 izinsiz olduğunu 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 belgelerinde okuyabilirsiniz.

Program Metadata Programı (PMP)

Program metadata programı, program IDL'lerini ve ad, iletişim ve simge gibi security.txt bilgilerini zincir üstünde depolamanıza olanak tanıyan bir programdır. Bu, gelecekte IDL'leri zincir üstünde depolamanın standart yolu olacak.

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

Program metadata programı hakkında daha fazla bilgiyi program metadata programı belgelerinde 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 mümkün olduğunca kolaylaştırmak için Solana GitHub Actions iş akışlarını kullanmaktır.

Bu sayede program otomatik olarak yükseltilecek, IDL yüklenecek, derleme doğrulanacak ve ardından multisig'inizin imzalayıp programı dağıtması için bir işlem önerilecektir.

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

IDL Sürüm Yönetimi

Şu anda Anchor ile zincir üstünde aynı anda yalnızca bir IDL sürümüne sahip olabilirsiniz. Bu, programınızda değişiklik yapmak istediğinizde yeni bir IDL sürümü yüklemeniz gerektiği anlamına gelir; tercihen programı yükselttiğinizle aynı anda. İstemciler henüz güncellenmemişse bu 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'lere sahip olabilecek ve bu şekilde sürüm yönetimi yapabileceksiniz. Bunun tasarımı henüz tamamen kesinleşmemiştir ve tartışmaya açıktır.

Daha Fazla Okuma

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

Solana'daki IDL'lerin temelleri bunlardır. IDL'ler, zincir üstündeki programlar ile zincir dışı istemciler arasındaki köprüdür ve bugün gördüğünüz zengin araç ve SDK ekosistemine olanak tanır.

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