IDLs (Interface Definition Language)

IDL son las siglas de Interface Definition Language (Lenguaje de Definición de Interfaz).
En Solana, los IDLs son archivos JSON que describen la interfaz de un programa. Permiten a los exploradores y usuarios decodificar instrucciones de programas, datos de cuentas y errores de programas, y ofrecen la posibilidad de generar clientes en distintos lenguajes de programación.

Por qué importan los IDLs

Estandarización → Un formato compartido para las interfaces de programas.
Experiencia del desarrollador → Genera SDKs de cliente automáticamente.
Componibilidad → Otros desarrolladores pueden interactuar con tu programa sin leer su código fuente.
Legibilidad → Cualquiera puede leer las instrucciones del programa y los datos de las cuentas en los exploradores sin necesidad de leer el código fuente del programa.

Qué puedes hacer con los IDLs

Decodificación de instrucciones y datos de cuentas

Todos los exploradores utilizan los IDLs de los programas para decodificar instrucciones y datos de cuentas. Aquí puedes ver un ejemplo de Anchor 0.30.1 y uno de IDL heredado en la interfaz del Explorador de Solana. En esta transacción puedes ver la instrucción decodificada para un juego 2048, incluyendo pushInDirection y su dirección.

Puedes decodificar instrucciones y datos de cuentas en tu cliente TypeScript usando los helpers de Solana JS.

Análisis de eventos Anchor o cambios en cuentas

Puedes suscribirte fácilmente a los cambios de cuentas en tu programa usando los tipos TypeScript generados.

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

Por ejemplo, puedes emitir eventos Anchor en tu programa y luego registrar esos eventos, escribirlos en una base de datos o usarlos para, por ejemplo, enviar un mensaje a un chat de 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 ello puedes usar los helpers de Solana JS para analizar los eventos. Aquí hay una implementación de ejemplo que usa eventos Anchor para publicar mensajes en un chat de Telegram.

Decodificar transacciones

También puedes decodificar transacciones en tu cliente usando los helpers de Solana JS. Esto te proporcionará un objeto tipado de toda la transacción.

Construye tu propio cliente

Usando un IDL puedes crear tu propio cliente en muchos lenguajes. Solo tienes que encontrar un programa con el que quieras interactuar, descargar el IDL y luego generar un cliente en tu lenguaje preferido.

Aquí hay un ejemplo de cómo generar un cliente en TypeScript.

IDLs en Anchor

Si estás usando el framework Anchor:

El IDL se genera automáticamente al compilar tu programa.
Se ubica en target/idl/<program>.json.
Los tipos TypeScript se generan en target/types/<program>.ts.
La dirección del programa se almacena en el IDL (idl.address).

anchor build
cat target/idl/counter.json

Anatomía de un IDL

Aquí tienes un ejemplo mínimo (especificación 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: el ID del programa en la cadena.
metadata: { name, version, spec, ... } con información sobre el programa/interfaz.
instructions: métodos invocables con accounts, args y un discriminator.
accounts: tipos de cuentas expuestos por el programa (con discriminadores).
types: alias de structs/enums/tipos referenciados por instrucciones/cuentas.
events / errors / constants: definiciones opcionales para eventos, códigos de error y constantes.

Nota: Anchor v0.30 introdujo una nueva especificación de IDL. Los IDLs heredados (anteriores a 0.30) usaban campos como name y version en el nivel superior, e isMut/isSigner en las cuentas. Puedes convertir IDLs heredados usando anchor idl convert o recompilar con Anchor v0.30+. Si necesitas convertir un IDL heredado a la nueva especificación al vuelo, también puedes usar este código de conversión. Esto es útil, por ejemplo, si mantienes un explorador de Solana y quieres mantener compatibilidad con versiones anteriores.

Cliente TypeScript

Anchor también generará automáticamente un cliente TypeScript para ti. Puedes encontrar el cliente generado en la carpeta target/types.

Luego, en tu cliente (TypeScript, v0.30+), puedes llamar a las instrucciones del programa y obtener cuentas de forma tan sencilla como esta:

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 generar un cliente C# puedes usar el siguiente comando:

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

Puedes leer más sobre cómo interactuar con un cliente C# desde Unity en el preset de juegos de Solana o en la documentación de Games.

Cliente Python

Para Python puedes usar la biblioteca AnchorPy.

En el futuro habrá más generadores de clientes disponibles mediante los renderizadores de Codama.

IDLs sin Anchor

No todos los programas se construyen con Anchor.
Para los programas nativos de Solana:

Una herramienta llamada Codama está actualmente en desarrollo para generar IDLs desde Rust mediante macros o convirtiendo IDLs de Anchor. Aquí hay un ejemplo en progreso de Macros de Codama para generar un IDL de Codama. Codama convierte IDLs de Anchor/Shank en un IDL de Codama. Para obtener un IDL de Anchor, genéralo con Anchor (o usa anchor idl convert para proyectos heredados).
Hasta que las macros de Codama estén completamente listas, también puedes usar Metaplex Shank para generar un IDL de Shank y luego convertirlo a un IDL de Codama.
También puedes escribir el IDL a mano (en formato Anchor o Codama), aunque esto no es muy fiable. Herramientas de IA como Cursor pueden ayudarte a escribir el IDL, pero siempre debes verificarlo con el código fuente del programa; la mejor opción es usar Anchor, Codama o Metaplex Shank.

Almacenamiento de IDLs en la cadena

Hay dos formas de subir IDLs a la cadena. La más utilizada y estándar es la cuenta IDL de Anchor. La forma en que Anchor te permite subir tus IDLs a la cadena es añadiendo instrucciones adicionales a tu programa que te permiten subir y actualizar tus IDLs en la cadena. Esto añade algo de tamaño extra al programa, y por eso se creó el program account de metadatos. En el program account de metadatos se almacenan todos los IDLs de los programas y la información de security.txt, como nombre, contacto e icono, en PDAs del program account de metadatos.

Cuenta IDL de Anchor

Anchor guarda los IDLs en la cadena en una PDA de tu programa.

Los IDLs pueden subirse a la cadena a la cuenta IDL de Anchor.
Esto permite a los exploradores, wallets y SDKs obtener el IDL directamente desde Solana.

Primera vez (inicializar la cuenta IDL):

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

Actualizaciones (actualizaciones posteriores por parte de la autoridad):

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

Comandos relacionados útiles:

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>

Ten en cuenta que, por defecto, la generación de la cuenta IDL de Anchor no requiere permisos. Por eso, sube tu IDL lo antes posible y luego establece una autoridad.

Puedes leer más sobre la cuenta IDL de Anchor en la documentación de Anchor.

Program Metadata Program (PMP)

El program account de metadatos es un programa que te permite almacenar los IDLs del programa y la información de security.txt, como nombre, contacto e icono, en la cadena. Probablemente esta será la forma estándar de almacenar IDLs en la cadena en el futuro.

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

Puedes leer más sobre el program account de metadatos en la documentación del program account de metadatos.

Nota: En la última actualización de este artículo, el PMP aún no es compatible con todos los exploradores.

Buenas prácticas

La mejor práctica para los despliegues de programas es usar un Multisig como Squads y, para que este proceso sea lo más sencillo posible, usar los flujos de trabajo de GitHub Actions de Solana.

De esta forma, el programa se actualizará automáticamente, se subirá el IDL, se verificará la compilación y se propondrá una transacción para que tu multisig la firme y despliegue el programa.

Mantén los IDLs actualizados → Actualiza siempre el IDL cuando hagas cambios en tu programa.
Sube los IDLs a la cadena → para mayor transparencia y compatibilidad con herramientas.
Documenta los errores personalizados → mejora la UX para los clientes.
Verifica las compilaciones → asegúrate de que el IDL coincide con el programa desplegado.

Versionado de IDLs

Actualmente con Anchor solo puedes tener una versión del IDL en la cadena a la vez. Esto significa que si quieres hacer cambios en tu programa, necesitas subir una nueva versión del IDL, preferiblemente al mismo tiempo que actualizas el programa. Esto puede generar problemas si los clientes aún no han sido actualizados, y es una de las razones por las que se creó el program account de metadatos. Con PMP, podrás tener diferentes semillas para tu programa y gestionar el versionado de esa manera. El diseño para esto aún no está completamente definido y está abierto a debate.

Lecturas adicionales

Documentación de Anchor sobre IDLs → genera IDLs y clientes automáticamente. (TypeScript, C#, Python)
Codama → herramientas de IDL + generadores de clientes (Rust, JS/TS, Umi/Kit, etc.).
Program Metadata Program → almacena IDLs e información de security.txt en la cadena.

Esos son los fundamentos de los IDLs en Solana. Son el puente entre los programas en la cadena y los clientes fuera de ella, lo que permite el rico ecosistema de herramientas y SDKs que existe hoy en día.

IDL - una interfaz de programa fácil de usar