IDLs (Interface Definition Language)

IDL significa Interface Definition Language.
No Solana, os IDLs são ficheiros JSON que descrevem a interface de um programa. Permitem que exploradores e utilizadores descodifiquem instruções de programas, dados de contas e erros de programas, e oferecem a possibilidade de gerar clientes em diferentes linguagens de programação.

Por que os IDLs são Importantes

Padronização → Um formato partilhado para interfaces de programas.
Experiência do Desenvolvedor → Gere SDKs de clientes automaticamente.
Composabilidade → Outros desenvolvedores podem interagir com o seu programa sem ler o seu código-fonte.
Legibilidade → Todos podem ler instruções de programas e dados de contas em exploradores sem ler o código-fonte do programa.

O que pode fazer com os IDLs

Descodificar Dados de Instruções e Contas

Todos os Exploradores utilizam IDLs de programas para descodificar instruções e dados de contas. Aqui pode ver um exemplo de Anchor 0.30.1 e um exemplo de IDL Legado na interface do Solana Explorer. Nesta transação pode ver a instrução descodificada para um jogo 2048, incluindo pushInDirection e a sua direção.

Pode descodificar instruções e dados de contas no seu cliente TypeScript utilizando os helpers JS do Solana.

Processar Eventos Anchor ou Alterações de Contas

Pode subscrever facilmente a alterações de contas no seu programa utilizando os tipos TypeScript gerados.

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

Pode, por exemplo, emitir eventos Anchor no seu programa e depois registar esses eventos, escrevê-los numa base de dados ou utilizá-los para, por exemplo, enviar uma mensagem para um chat do Telegram.

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

Para isso, pode utilizar os helpers JS do Solana para processar os eventos. Aqui está uma implementação de exemplo que utiliza eventos Anchor para publicar mensagens num chat do Telegram.

Descodificar Transações

Também pode descodificar transações no seu cliente utilizando os helpers JS do Solana. Isto irá fornecer-lhe um objeto tipado de toda a transação.

Crie o seu próprio cliente

Utilizando um IDL, pode criar o seu próprio cliente em muitas linguagens. Basta encontrar um programa com o qual pretenda interagir, descarregar o IDL e depois gerar um cliente na sua linguagem preferida.

Aqui está um exemplo de como gerar um cliente em TypeScript.

IDLs no Anchor

Se estiver a utilizar o framework Anchor:

O IDL é gerado automaticamente quando compila o seu programa.
Fica localizado em target/idl/<program>.json.
Os tipos TypeScript são gerados em target/types/<program>.ts.
O endereço do programa é armazenado no IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomia de um IDL

Aqui está um exemplo mínimo (especificação Anchor v0.30+):

{
  "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: o ID do programa onchain.
metadata: { name, version, spec, ... } sobre o programa/interface.
instructions: métodos invocáveis com accounts, args e um discriminator.
accounts: tipos de contas expostos pelo programa (com discriminadores).
types: aliases de struct/enum/tipo referenciados por instruções/contas.
events / errors / constants: definições opcionais para eventos, códigos de erro, constantes.

Nota: O Anchor v0.30 introduziu uma nova especificação de IDL. Os IDLs legados (anteriores ao 0.30) utilizavam campos como name, version ao nível superior e isMut/isSigner nas contas. Pode converter IDLs legados utilizando anchor idl convert ou recompilar com Anchor v0.30+. Se precisar de converter um IDL legado para a nova especificação em tempo real, pode também utilizar este código de conversão. Isto é útil, por exemplo, se mantiver um explorador Solana e quiser manter compatibilidade com versões anteriores.

Cliente TypeScript

O Anchor também irá gerar automaticamente um cliente TypeScript para si. Pode encontrar o cliente gerado na pasta target/types.

Depois, no seu cliente (TypeScript, v0.30+), pode invocar instruções de programas e obter contas tão facilmente como isto:

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

Cliente C#

Para gerar um cliente C#, pode utilizar o seguinte comando:

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

Pode ler mais sobre como interagir com um cliente C# a partir do Unity em Solana games preset ou na documentação de Jogos.

Cliente Python

Para Python, pode utilizar a biblioteca AnchorPy.

Mais geradores de clientes estarão disponíveis utilizando os renderizadores Codama no futuro.

IDLs sem Anchor

Nem todos os programas são criados com Anchor.
Para programas nativos do Solana:

Uma ferramenta chamada Codama está atualmente em desenvolvimento para gerar IDLs a partir de Rust via macros ou convertendo IDLs Anchor. Aqui está um exemplo em progresso de Macros Codama para gerar um IDL Codama. O Codama converte IDLs Anchor/Shank num IDL Codama. Para obter um IDL Anchor, gere-o com Anchor (ou utilize anchor idl convert para projetos legados).
Até que as macros Codama estejam completamente prontas, pode também utilizar Metaplex Shank para gerar um IDL Shank e depois convertê-lo para um IDL Codama.
Também pode escrever o IDL manualmente (nos formatos Anchor ou Codama), mas isso não é muito fiável. Ferramentas de IA como o Cursor podem ajudá-lo a escrever o IDL, mas deve sempre verificar o IDL com o código-fonte do programa; a melhor abordagem é utilizar Anchor, Codama ou Metaplex Shank.

Armazenar IDLs Onchain

Existem duas formas de carregar IDLs onchain. A mais utilizada e padrão é a conta IDL do Anchor. A forma como o Anchor permite carregar os seus IDLs onchain é através da adição de instruções adicionais ao seu programa que permitem carregar e atualizar os seus IDLs onchain. Isto adiciona algum tamanho extra ao programa e foi por isso que o program metadata program foi criado. No program metadata program, todos os IDLs de programas e informações de security.txt como nome, contacto e ícone são armazenados em PDAs do program metadata program.

Conta IDL do Anchor

O Anchor guarda os IDLs onchain numa PDA do seu programa.

Os IDLs podem ser carregados onchain para a conta IDL do Anchor.
Isto permite que exploradores, carteiras e SDKs obtenham o IDL diretamente do Solana.

Primeira vez (inicializar a conta IDL):

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

Atualizações (atualizações subsequentes pela autoridade):

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

Comandos relacionados úteis:

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>

Note que, por padrão, a geração da conta IDL do Anchor é sem permissões. Por isso, carregue o seu IDL o mais rapidamente possível e depois defina uma autoridade.

Pode ler mais sobre a conta IDL do Anchor na documentação do Anchor.

Program Metadata Program (PMP)

O program metadata program é um programa que permite armazenar os IDLs de programas e informações de security.txt como nome, contacto e ícone onchain. Esta será provavelmente a forma padrão de armazenar IDLs onchain no futuro.

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

Pode ler mais sobre o program metadata program na documentação do program metadata program.

Nota: À data da última atualização do artigo, o PMP ainda não é suportado por todos os exploradores.

Boas Práticas

A melhor prática para implementações de programas é utilizar um Multisig como Squads e, para tornar este processo o mais simples possível, utilizar os workflows do Solana GitHub Actions.

Desta forma, o programa será automaticamente atualizado, o IDL carregado, a compilação verificada e será proposta uma transação para o seu multisig assinar e implementar o programa.

Mantenha os IDLs atualizados → Atualize sempre o IDL quando fizer alterações ao seu programa.
Carregue os IDLs onchain → para transparência e suporte de ferramentas.
Documente erros personalizados → melhora a UX para os clientes.
Verifique as compilações → certifique-se de que o IDL corresponde ao programa implementado.

Versionamento de IDLs

Atualmente, com o Anchor, só pode ter uma versão do IDL onchain de cada vez. Isto significa que, se quiser fazer alterações ao seu programa, precisa de carregar uma nova versão do IDL, de preferência ao mesmo tempo que atualiza o programa. Isto pode causar problemas se os clientes ainda não tiverem sido atualizados e é uma das razões pelas quais o program metadata program foi criado. Com o PMP, poderá ter diferentes seeds para o seu programa e fazer versionamento dessa forma. O design para isso ainda não está completamente finalizado e está aberto para discussão.

Leitura Adicional

Documentação Anchor sobre IDLs → gera automaticamente IDLs e clientes. (TypeScript, C#, Python)
Codama → ferramentas IDL + geradores de clientes (Rust, JS/TS, Umi/Kit, etc.).
Program Metadata Program → armazene IDLs e informações de security.txt onchain.

Estes são os conceitos básicos dos IDLs no Solana. São a ponte entre os programas onchain e os clientes off-chain, permitindo o rico ecossistema de ferramentas e SDKs que vemos hoje.

IDL - uma Interface de Programa fácil de usar