IDLs (Linguagem de Definição de Interface)

IDL significa Interface Definition Language (Linguagem de Definição de Interface).
Na Solana, IDLs são arquivos JSON que descrevem a interface de um programa. Eles permitem que exploradores e usuários decodifiquem instruções do programa, dados de contas e erros do programa, além de oferecer a possibilidade de gerar clientes em diferentes linguagens de programação.

Por que IDLs são importantes

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

O que você pode fazer com IDLs

Decodificação de dados de instruções e contas

Todos os exploradores usam IDLs de programas para decodificar instruções e dados de contas. Aqui você pode ver um exemplo de Anchor 0.30.1 e de uma IDL legada na interface do Solana Explorer. Nesta transação você pode ver a instrução decodificada para um jogo 2048, incluindo pushInDirection e sua direção.

Você pode decodificar instruções e dados de contas no seu cliente TypeScript usando os helpers do Solana JS.

Análise de alterações em contas

Você pode assinar facilmente alterações de contas no seu programa usando 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)
  );
});

Para definições de eventos, assinaturas, decodificação de logs e CPI, backfills, versionamento de esquema e testes, consulte Eventos do Anchor.

Decodificar transações

Você também pode decodificar transações no seu cliente usando os helpers do Solana JS. Isso fornecerá um objeto tipado da transação inteira.

Crie seu próprio cliente

Usando uma IDL, você pode criar seu próprio cliente em várias linguagens. Basta encontrar um programa com o qual você queira interagir, baixar a IDL e então gerar um cliente na linguagem de sua preferência.

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

IDLs no Anchor

Se você estiver usando o framework Anchor:

A IDL é gerada automaticamente quando você compila seu programa.
Ela fica em target/idl/<program>.json.
Os tipos TypeScript são gerados em target/types/<program>.ts.
O endereço do programa é armazenado na IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomia de uma 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 on-chain.
metadata: { name, version, spec, ... } sobre o programa/interface.
instructions: métodos chamáveis com accounts, args e um discriminator.
accounts: tipos de conta 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.

Observação: o Anchor v0.30 introduziu uma nova especificação de IDL. IDLs legadas (pré-0.30) usavam campos como name, version no nível superior e isMut/isSigner em contas. Você pode converter IDLs legadas usando anchor idl convert ou recompilar com Anchor v0.30+. Se precisar converter uma IDL legada para a nova especificação em tempo real, você também pode usar este código de conversão. Isso é útil, por exemplo, se você mantém um explorador da Solana e quer manter compatibilidade retroativa.

Cliente TypeScript

O Anchor também gerará automaticamente um cliente TypeScript para você. Você pode encontrar o cliente gerado na pasta target/types.

Então, no seu cliente (TypeScript, v0.30+), você pode chamar instruções do programa e buscar contas de forma tão simples quanto 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#, você pode usar 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

Você pode ler mais sobre como interagir com um cliente C# a partir do Unity no preset de jogos da Solana ou na documentação de jogos.

Cliente Python

Para Python, você pode usar a biblioteca AnchorPy.

Mais geradores de clientes estarão disponíveis usando renderizadores do Codama no futuro.

IDLs sem Anchor

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

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

Armazenamento de IDLs on-chain

Há duas formas de fazer upload de IDLs on-chain. A mais usada e padrão é a conta IDL do Anchor. A forma como o Anchor permite que você faça upload das suas IDLs on-chain é adicionando instruções adicionais ao seu programa que permitem fazer upload e atualizar suas IDLs on-chain. Isso adiciona algum tamanho extra ao programa, e é por isso que o programa de metadados de programa foi criado. No programa de metadados de programa, todas as IDLs de programas e informações de security.txt, como nome, contato e ícone, são armazenadas em PDAs do programa de metadados de programa.

Conta IDL do Anchor

O Anchor salva IDLs on-chain em uma PDA do seu programa.

IDLs podem ser enviadas on-chain para a conta IDL do Anchor.
Isso permite que exploradores, carteiras e SDKs busquem a IDL diretamente da Solana.

Primeira vez (inicializar a conta IDL):

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

Upgrades (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>

Observe que, por padrão, a geração da conta IDL do Anchor não exige permissão. Portanto, faça upload da sua IDL o quanto antes e, em seguida, defina uma autoridade.

Você pode ler mais sobre a conta IDL do Anchor na documentação do Anchor.

Programa de Metadados de Programa (PMP)

O programa de metadados de programa é um programa que permite armazenar as IDLs de programa e informações de security.txt, como nome, contato e ícone, on-chain. Esta provavelmente será a forma padrão de armazenar IDLs on-chain no futuro.

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

Você pode ler mais sobre o programa de metadados de programa na documentação do programa de metadados de programa.

Observação: até a última atualização do artigo, o PMP ainda não é compatível com todos os exploradores.

Boas práticas

A melhor prática para deploys de programas é usar um Multisig como Squads e, para tornar esse processo o mais simples possível, você usa os workflows de GitHub Actions da Solana.

Assim, o programa será atualizado automaticamente, a IDL enviada, a build verificada e então haverá uma transação proposta para seu multisig assinar e fazer o deploy do programa.

Mantenha as IDLs atualizadas → Sempre atualize a IDL quando fizer alterações no seu programa.
Faça upload de IDLs on-chain → para transparência e suporte a ferramentas.
Documente erros personalizados → melhora a UX para clientes.
Verifique builds → garanta que a IDL corresponda ao programa implantado.

Versionamento de IDLs

Atualmente, com Anchor, você só pode ter uma versão da IDL on-chain por vez. Isso significa que, se quiser fazer alterações no seu programa, você precisa fazer upload de uma nova versão da IDL, preferencialmente ao mesmo tempo em que atualiza o programa. Isso pode causar problemas se os clientes ainda não tiverem sido atualizados, e é uma das razões pelas quais o programa de metadados de programa foi criado. Com o PMP, você poderá ter seeds diferentes para seu programa e fazer o versionamento dessa forma. O design disso ainda não está completamente finalizado e está aberto para discussão.

Leitura adicional

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

Esses são os fundamentos das IDLs na Solana. Elas são a ponte entre programas on-chain e clientes off-chain, viabilizando o rico ecossistema de ferramentas e SDKs que você vê hoje.

IDL - uma interface de programa fácil de usar