¿Qué es la API de Polkadot y cómo elegir la correcta?

Guía rápida de decisión: ¿qué API de Polkadot deberías usar?

Antes de entrar en detalles, aquí tienes una forma práctica de decidir qué biblioteca de cliente se adapta a tu proyecto. El ecosistema Polkadot tiene tres APIs principales de JavaScript/TypeScript, y la elección depende de tus prioridades: seguridad de tipos, estado de mantenimiento y si quieres usar un cliente ligero o un endpoint RPC remoto.

Si estás comenzando un proyecto nuevo, Polkadot-API es la opción recomendada por el ecosistema. Es moderna, totalmente tipada y construida para el cliente ligero. Si estás manteniendo una aplicación existente que ya usa Polkadot.js, puedes continuar, pero ten en cuenta que está en modo mantenimiento. Dedot es una alternativa sólida si prefieres un estilo de API diferente.

Para el endpoint RPC, puedes usar un endpoint público, pero para producción, considera un proveedor de RPC confiable como OnFinality. OnFinality ofrece endpoints RPC para Polkadot y muchas otras redes, con precios que se adaptan a tus necesidades.

¿Qué es la API de Polkadot?

La API de Polkadot es un conjunto de bibliotecas e interfaces que permiten a los desarrolladores interactuar con cadenas basadas en Polkadot y Substrate. Proporciona métodos para consultar el estado de la cadena, enviar transacciones y escuchar eventos. La API abstrae las llamadas JSON-RPC subyacentes, manejando la codificación y decodificación de datos, para que puedas concentrarte en construir tu aplicación.

Existen varias implementaciones, cada una con su propia filosofía y características. Las más destacadas son Polkadot-API (a menudo llamada papi), Polkadot.js API y Dedot. Comprender sus diferencias es crucial para elegir la herramienta adecuada para tu proyecto.

Polkadot-API (papi): la opción moderna y con seguridad de tipos

Polkadot-API es un conjunto de bibliotecas relativamente nuevo diseñado con una filosofía de "cliente ligero primero". Está construido sobre la nueva especificación JSON-RPC y aprovecha el poder de los clientes ligeros como Smoldot. Esto significa que puedes ejecutar un nodo en el navegador, reduciendo la dependencia de endpoints RPC centralizados.

Las características clave incluyen:

• API totalmente tipada: Los tipos y la documentación se generan a partir de los metadatos en cadena, por lo que tu IDE proporciona autocompletado y verificación de tipos para cada operación.
• Soporte de primera clase para lecturas de almacenamiento, constantes, transacciones, eventos y llamadas de runtime: Obtienes una API completa para todas las interacciones con la cadena.
• Múltiples conexiones: Puedes conectarte a varias cadenas simultáneamente, lo cual es útil para aplicaciones entre cadenas.
• Compatibilidad con actualizaciones de runtime: Genera múltiples descriptores y realiza comprobaciones de compatibilidad para prepararte para actualizaciones de runtime.
• Ligero: El paquete principal tiene menos de 50kB y utiliza importaciones dinámicas para mantener tu dApp rápida.
• BigInt nativo: Utiliza el BigInt nativo de JavaScript en lugar de grandes bibliotecas BigNumber.
• APIs de Promise y Observable: Elige el estilo que se adapte a tus preferencias de codificación.

Aquí tienes un ejemplo rápido de cómo usar Polkadot-API para consultar el saldo de una cuenta:

import { createClient } from "polkadot-api";
import { getSmProvider } from "polkadot-api/sm-provider";
import { startFromWorker } from "polkadot-api/smoldot/from-worker";
import { chainSpec } from "polkadot-api/chains/polkadot";

const smoldot = startFromWorker(new Worker("./smoldot.js"));
const chain = await smoldot.addChain({ chainSpec });
const client = createClient(getSmProvider(chain));

const api = client.getTypedApi();
const balance = await api.query.System.Account.getValue("ADDRESS");
console.log(balance);

Este ejemplo usa un cliente ligero, pero también puedes conectarte a un endpoint RPC remoto usando getWsProvider de polkadot-api/ws-provider.

Polkadot.js API: el estándar heredado

La API de Polkadot.js ha sido el estándar durante años. Proporciona envoltorios fáciles de usar para llamadas JSON-RPC y maneja toda la codificación y decodificación. Sin embargo, ahora está en modo mantenimiento y ya no se desarrolla activamente. La documentación oficial para desarrolladores de Polkadot recomienda que los proyectos nuevos usen Polkadot-API o Dedot en su lugar.

A pesar de esto, muchos proyectos existentes todavía dependen de ella. Si estás trabajando con una base de código heredada, es posible que necesites usarla. Aquí tienes un ejemplo básico:

const { ApiPromise, WsProvider } = require("@polkadot/api");

async function main() {
  const provider = new WsProvider("wss://rpc.polkadot.io");
  const api = await ApiPromise.create({ provider });

  const balance = await api.query.system.account("ADDRESS");
  console.log(balance.toHuman());
}

main();

Ten en cuenta que la API de Polkadot.js genera dinámicamente su interfaz basada en los metadatos de la cadena. Ofrece tres categorías principales: api.consts, api.query y api.tx.

Dedot: una alternativa TypeScript-first

Dedot es otra API TypeScript-first con mantenimiento activo. Su objetivo es proporcionar una experiencia más ergonómica y con seguridad de tipos que Polkadot.js. Soporta tanto clientes ligeros como endpoints RPC remotos. Si prefieres un diseño de API diferente, vale la pena considerar Dedot.

Endpoints RPC: públicos vs. privados

Al usar cualquier API de Polkadot, necesitas un endpoint RPC para conectarte. Los endpoints públicos, como wss://rpc.polkadot.io, son gratuitos pero a menudo tienen límites de velocidad y pueden no ser confiables para producción. Para aplicaciones de producción, debes usar un proveedor de RPC dedicado que ofrezca mayor rendimiento, datos de archivo y mejor tiempo de actividad.

OnFinality proporciona endpoints RPC de Polkadot que son confiables y escalables. También puedes consultar redes compatibles para ver todas las cadenas disponibles. Para detalles de precios, visita precios de RPC.

Cómo conectarse a un endpoint RPC de Polkadot

Independientemente de la biblioteca de API que elijas, necesitarás configurar el endpoint. Aquí tienes un ejemplo usando Polkadot-API con un proveedor WebSocket:

import { createClient } from "polkadot-api";
import { getWsProvider } from "polkadot-api/ws-provider";

const client = createClient(getWsProvider("wss://rpc.polkadot.io"));
const api = client.getTypedApi();

// Ahora puedes consultar el estado de la cadena
const header = await api.query.System.Number.getValue();
console.log("Número de bloque actual:", header);

Para Polkadot.js, puedes usar WsProvider como se mostró anteriormente. Asegúrate siempre de que tu endpoint soporte WebSocket para suscripciones en tiempo real.

Errores comunes y solución de problemas

Al trabajar con la API de Polkadot, puedes encontrar problemas. Aquí tienes algunos comunes y cómo resolverlos:

• Errores de conexión: Si estás usando un endpoint público, puede tener límites de velocidad o estar caído. Cambia a un proveedor confiable o usa un cliente ligero.
• Discrepancias de tipos: Si estás usando Polkadot-API, asegúrate de tener la especificación de cadena correcta y que tus descriptores estén actualizados después de las actualizaciones de runtime.
• Fallos de transacción: Revisa los mensajes de error y asegúrate de tener suficiente saldo para las tarifas. Usa los métodos api.tx correctamente.
• Problemas de rendimiento: Para consultas pesadas, considera usar nodos de archivo o infraestructura dedicada.

Conclusiones clave

• La API de Polkadot es esencial para interactuar con cadenas basadas en Polkadot.
• Polkadot-API es la opción moderna, con seguridad de tipos y mantenimiento activo para proyectos nuevos.
• Polkadot.js API está en modo mantenimiento; úsala solo para proyectos heredados.
• Dedot es una alternativa viable con diseño TypeScript-first.
• Elige un proveedor de RPC confiable como OnFinality para cargas de trabajo de producción.

Preguntas frecuentes

¿Cuál es la diferencia entre Polkadot-API y Polkadot.js API?

Polkadot-API es una biblioteca moderna, totalmente tipada y centrada en el cliente ligero, mientras que Polkadot.js API es más antigua, con tipos dinámicos y en modo mantenimiento. Los proyectos nuevos deberían preferir Polkadot-API.

¿Puedo usar un cliente ligero con Polkadot-API?

Sí, Polkadot-API está construida para clientes ligeros, lo que te permite ejecutar un nodo en el navegador sin depender de endpoints RPC remotos.

¿Qué endpoint RPC debería usar para producción?

Para producción, usa un proveedor de RPC confiable como OnFinality para garantizar alta disponibilidad y rendimiento. Los endpoints públicos no se recomiendan para cargas de trabajo de producción.

¿Está obsoleta la API de Polkadot.js?

Está en modo mantenimiento, lo que significa que ya no se desarrolla activamente. Todavía funciona, pero se anima a los proyectos nuevos a usar Polkadot-API o Dedot.

¿Cómo elijo entre Polkadot-API y Dedot?

Ambas tienen mantenimiento activo y seguridad de tipos. Polkadot-API tiene un enfoque más fuerte en clientes ligeros y es la opción recomendada por el ecosistema. Dedot ofrece un estilo de API diferente; puedes evaluar ambas para ver cuál se adapta mejor a tu proyecto.