IDLs (Lenguaje de Definición de Interfaz)

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, además de ofrecer la posibilidad de generar clientes en diferentes lenguajes de programación.

Por qué los IDLs son importantes

Estandarización → Un formato compartido para las interfaces de los programas.
Experiencia del desarrollador → Genera SDKs de cliente automáticamente.
Componibilidad → Otros desarrolladores pueden interactuar con tu programa sin necesidad de leer su código fuente.
Legibilidad → Cualquiera puede leer las instrucciones del programa y los datos de 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 Legacy en la interfaz del Solana Explorer. En esta transacción puedes ver la instrucción decodificada de un juego 2048, incluyendo pushInDirection y su dirección.

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

Seguimiento de cambios en cuentas

Puedes suscribirte fácilmente a los cambios de cuentas en tu programa utilizando los tipos de 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)
  );
});

Para definiciones de eventos, suscripciones, decodificación de logs y CPI, backfills, versionado de esquemas y pruebas, consulta Anchor Events.

Decodificación de transacciones

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

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 cuando compilas tu programa.
Se almacena en target/idl/<program>.json.
Los tipos de 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í hay 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, ... } 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 legacy (anteriores a 0.30) usaban campos como name y version en el nivel superior e isMut/isSigner en las cuentas. Puedes convertir IDLs legacy usando anchor idl convert o recompilando con Anchor v0.30+. Si necesitas convertir un IDL legacy 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 la 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 consultar 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 juegos.

Cliente Python

Para Python puedes usar la biblioteca AnchorPy.

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

IDLs sin Anchor

No todos los programas están construidos 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 Codama Macros para generar un IDL de Codama. Codama convierte IDLs de Anchor/Shank a un IDL de Codama. Para obtener un IDL de Anchor, genéralo con Anchor (o usa anchor idl convert para proyectos legacy).
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. Las herramientas de IA como Cursor pueden ayudarte a escribir el IDL, pero siempre debes verificarlo con el código fuente del programa; la forma más recomendable 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 agregando 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 metadata program. En el program metadata program, todos los IDLs de los programas y la información de security.txt como nombre, contacto e ícono se almacenan en PDAs del program metadata program.

Cuenta IDL de Anchor

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

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

Primera vez (inicialización de 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 de utilidad:

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 lo tanto, 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 metadata program es un programa que te permite almacenar los IDLs del programa y la información de security.txt como nombre, contacto e ícono 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 metadata program en la documentación del program metadata program.

Nota: En el momento de 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 el despliegue de programas es usar un Multisig como Squads y, para hacer este proceso 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 luego 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 las herramientas.
Documenta los errores personalizados → mejora la UX para los clientes.
Verifica las compilaciones → asegúrate de que el IDL coincida 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, debes 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 se han actualizado, y es una de las razones por las que se creó el program metadata program. Con PMP, podrás tener diferentes seeds para tu programa y gestionar el versionado de esa manera. El diseño para eso 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 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 hace posible el rico ecosistema de herramientas y SDKs que existe hoy en día.

IDL - una interfaz de programa fácil de usar