Resumen
# Sui Docs: dónde encontrar referencias de SDK, Move, RPC y nodos
La documentación oficial de Sui en docs.sui.io es el mejor punto de partida para desarrollar sobre Sui. Organiza el material en torno a los primeros pasos, el desarrollo con Move, las aplicaciones onchain, el stack de Sui, las referencias de API y SDK, la operación de nodos y la gestión de datos. La ruta adecuada depende de si estás aprendiendo el modelo de objetos, desplegando un paquete, consultando datos u operando infraestructura.
Para el desarrollo de aplicaciones, comienza con la documentación oficial del SDK de Sui para TypeScript y los recursos de Move; después, selecciona una API RPC para acceder a la red. Las herramientas y la superficie de API actuales de Sui pueden cambiar, por lo que debes tratar los ejemplos heredados de JSON-RPC como sensibles a la versión y confirmar los métodos compatibles en la documentación actual del SDK y del proveedor. OnFinality puede proporcionar una API RPC o una opción de infraestructura de nodo dedicado cuando un proyecto necesita acceso gestionado o un mayor control sobre su entorno de nodos.
Esta página relaciona las principales rutas de documentación de Sui con decisiones prácticas de desarrollo. También muestra cómo validar un endpoint sin asumir que un flujo de trabajo genérico de Ethereum JSON-RPC se aplica a Sui.
Puntos clave
- Usa docs.sui.io como fuente principal para la documentación actual de desarrollo, API y operación de nodos de Sui.
- Consulta el material sobre Move y el modelo de objetos antes de diseñar flujos de transacciones y paquetes.
- Usa el SDK de Sui para TypeScript para consultas desde el cliente, construcción de transacciones, firma y utilidades relacionadas.
- Trata los ejemplos antiguos de JSON-RPC como sensibles a la versión y verifica la compatibilidad actual de la API antes de implementarlos.
- Elige una API RPC gestionada para el acceso de aplicaciones o evalúa un nodo dedicado cuando el control operativo y el aislamiento sean requisitos.
- Prueba por separado las lecturas, el envío de transacciones, la gestión de errores y la identidad de la red antes del lanzamiento en producción.
Comienza con la ruta de documentación que corresponda a tu tarea
La documentación de Sui es lo bastante amplia como para que buscar un único ejemplo aislado de RPC pueda llevarte al punto de partida equivocado. Usa primero el mapa de tareas siguiente y después consulta la referencia correspondiente. La documentación oficial es la fuente de autoridad para el comportamiento del protocolo, los comandos de CLI, los detalles del framework de Move y las indicaciones actuales del SDK.
La documentación del SDK de Sui para TypeScript resulta especialmente útil para los desarrolladores de aplicaciones. Incluye la instalación, los paquetes modulares, las ubicaciones de red, los clientes, los keypairs, las transacciones y las utilidades relacionadas con los faucets. El SDK no sustituye la comprensión del modelo de objetos de Sui: el diseño de transacciones, la propiedad, los objetos compartidos y las transacciones programables aún requieren consultar la documentación conceptual.
Para los equipos de infraestructura, las secciones sobre operadores de nodos y gestión de datos son más relevantes que los tutoriales de aplicaciones. Estas secciones cubren las responsabilidades y los componentes necesarios para operar un full node de Sui, mientras que un proveedor RPC puede eliminar parte del trabajo operativo del equipo de aplicaciones.
- Aprender Sui o Move: comienza por Getting Started, Move y el material sobre el modelo de objetos.
- Desarrollar una aplicación en TypeScript: usa el SDK actual de Sui para TypeScript y su referencia de cliente.
- Desplegar un paquete: consulta conjuntamente la documentación sobre paquetes, entornos, gas, publicación y actualizaciones.
- Consultar o indexar datos: lee la referencia de API y evalúa si las lecturas RPC normales son suficientes para el historial y el volumen necesarios.
- Operar infraestructura: usa la documentación de full nodes, validadores y gestión de datos en lugar de ejemplos destinados únicamente a aplicaciones.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Tarea principal | Comenzar aquí | Evita mezclar instrucciones de aplicaciones, protocolo y operación de nodos |
| Desarrollo de paquetes Move | Documentación del lenguaje Move, paquetes, objetos y transacciones | El modelo de ejecución centrado en objetos de Sui afecta al diseño de paquetes y transacciones |
| Integración del cliente | Referencias actuales del cliente y las transacciones del SDK de TypeScript | El SDK abstrae la construcción de solicitudes y proporciona utilidades específicas de Sui |
| Acceso RPC o a nodos | Referencia actual de la API y documentación del proveedor o del full node | La disponibilidad de endpoints y la compatibilidad de métodos pueden variar según la generación de la API y el proveedor |
Guía de decisión: ¿RPC gestionado, nodo dedicado o nodo operado por tu equipo?
Elige una API RPC gestionada cuando el requisito inmediato sea conectar una aplicación: leer objetos, inspeccionar transacciones, enviar transacciones firmadas o mantener un servicio sin asumir el despliegue y mantenimiento de un nodo. Confirma los métodos, la retención de datos, el modelo de autenticación, las políticas de solicitudes y los transportes compatibles antes de implementar.
Un nodo dedicado es una opción distinta de disponer simplemente de un límite de solicitudes más alto. Puede ser relevante cuando una carga de trabajo necesita un entorno gestionado por separado, una propiedad predecible de la configuración, aislamiento frente a otros tenants o una vía hacia servicios de datos especializados. Estos requisitos deben documentarse y validarse con el proveedor de infraestructura.
Opera tu propio full node cuando la participación en el protocolo, el control local de los datos, las integraciones personalizadas o la independencia operativa justifiquen el coste de almacenamiento, actualizaciones, monitorización, sincronización y respuesta ante incidentes. La documentación oficial de nodos de Sui debe ser la fuente de los requisitos de recursos y versiones; no los deduzcas de la arquitectura de nodos de otra cadena.
- Usa una API RPC para el camino más corto entre una aplicación y los datos de la red Sui.
- Evalúa un nodo dedicado cuando el aislamiento de la carga de trabajo o la propiedad de la infraestructura sean más importantes que la configuración más sencilla.
- Elige infraestructura operada por tu equipo solo después de tener en cuenta las responsabilidades de sincronización, almacenamiento, actualizaciones, seguridad y guardias.
- Mantén una abstracción del proveedor en la aplicación para que los cambios de endpoint no obliguen a reescribir la lógica de transacciones.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| API RPC gestionada | Métodos compatibles, autenticación, políticas de solicitudes, alcance de los datos y transporte | Es la opción más adecuada para equipos que necesitan acceso a la red sin operar un nodo |
| Infraestructura de nodo dedicado | Aislamiento, propiedad de la configuración, límite de soporte y requisitos de datos | Es útil cuando un servicio compartido no se ajusta a las restricciones operativas de la carga de trabajo |
| Full node operado por tu equipo | Hardware, almacenamiento, actualizaciones, monitorización, copias de seguridad y procedimientos ante incidentes | Proporciona más control, pero transfiere la responsabilidad operativa continua a tu equipo |
Conceptos de SDK y RPC de Sui que los desarrolladores deben separar
El SDK de Sui para TypeScript es una biblioteca cliente, no la red en sí. Ayuda a las aplicaciones a construir solicitudes, trabajar con tipos de datos de Sui, crear transacciones e interactuar con una ubicación de red configurada. El servicio RPC situado detrás del cliente sigue determinando qué métodos de API, límites, datos históricos y comportamiento de envío están disponibles.
Los ejemplos de Sui no deben copiarse de un tutorial de Ethereum sin comprobar el modelo y la API. Sui utiliza Move y un modelo de activos orientado a objetos, y su flujo de transacciones incluye conceptos específicos de Sui, como entradas de objetos, objetos de gas, bloques de transacciones programables y publicación de paquetes. Una solicitud sintácticamente válida en otro ecosistema puede ser conceptualmente incorrecta para Sui.
La documentación actual del SDK enumera las ubicaciones de red y muestra ejemplos de configuración del cliente. En producción, sustituye la configuración de desarrollo por el endpoint y las credenciales proporcionados por el proveedor RPC seleccionado, y mantén los secretos fuera del control de versiones.
- Fija versiones compatibles del SDK y revisa las notas de versión antes de actualizar.
- Mantén explícita la selección de red en la configuración en lugar de codificarla directamente en la lógica de negocio.
- Separa los clientes de lectura del código de firma de transacciones siempre que sea posible.
- Trata las claves privadas, los tokens de API y el material de firma como secretos independientes con controles de acceso diferentes.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Responsabilidad del SDK | Construcción del cliente, serialización, creación de transacciones y asistentes de firma | Son responsabilidades de la aplicación implementadas por la biblioteca |
| Responsabilidad del RPC | Gestión de solicitudes, compatibilidad de métodos, control de acceso y disponibilidad de datos | El endpoint es la dependencia externa que tu aplicación debe monitorizar |
| Responsabilidad de la aplicación | Reintentos, idempotencia, clasificación de errores, seguridad de claves y observabilidad | El acceso del proveedor no elimina la necesidad de un comportamiento seguro de la aplicación |
Configuración del endpoint sin asumir una URL pública
La configuración del repositorio de OnFinality para Sui no proporciona un valor chainInfo.rpcUrls. Por esa razón, este artículo no publica un endpoint público supuesto. Usa la página actual de la red Sui o tu cuenta de OnFinality para obtener la URL RPC y las credenciales aplicables, y después inyéctalas mediante variables de entorno.
Un patrón de configuración sin placeholders debe dejar clara la separación necesaria. El endpoint pertenece a la configuración del despliegue, mientras que el cliente del SDK sigue siendo responsable de las solicitudes específicas de Sui. El constructor exacto del cliente y los métodos compatibles deben seguir la versión actual de la documentación oficial del SDK.
- Guarda la URL RPC en un secreto o variable de entorno del despliegue en lugar de confirmarla en el repositorio.
- Confirma que el endpoint apunta a Sui Mainnet al desplegar tráfico de producción; no reutilices la configuración de testnet.
- Registra conjuntamente la versión del SDK, el endpoint del proveedor y el entorno de red para conseguir lanzamientos reproducibles.
- Añade una comprobación de inicio que verifique la identidad de la red antes de aceptar tráfico de la aplicación.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Origen del endpoint | Configuración actual del servicio Sui de OnFinality o panel de la cuenta | Evita depender de URLs obsoletas o no oficiales |
| Selección del entorno | Mainnet, testnet, red local u otro entorno compatible indicado explícitamente | Las direcciones y los datos no son intercambiables entre entornos |
| Credenciales | Formato de autenticación y política de almacenamiento de secretos | Los encabezados incorrectos o los tokens expuestos pueden bloquear solicitudes o crear riesgos de seguridad |
Flujo de trabajo reproducible para validar Sui RPC
Valida la conectividad antes de depurar la lógica de la aplicación. Comienza con una lectura de bajo coste compatible con el proveedor, confirma el formato de la respuesta y después prueba una consulta representativa de objeto o transacción. No consideres que una respuesta HTTP correcta demuestra que todos los métodos de Sui o las consultas históricas están disponibles.
Para un flujo de transacciones, prueba por separado la simulación o inspección cuando sea compatible, la firma, el envío y la posterior recuperación del estado. Registra los identificadores de solicitud y clasifica los fallos por autenticación, transporte, compatibilidad de métodos, validación de entradas, políticas de límites o estado de la red. Esto facilita el diagnóstico de cambios de proveedor y actualizaciones del SDK.
Una sonda de monitorización práctica debe usar una lectura conocida y segura, y generar alertas tanto ante fallos de transporte como ante una forma de respuesta inesperada. Evita realizar una solicitud a un faucet, publicar un paquete o enviar una transacción como comprobación de estado.
- Comprueba la conectividad DNS y TLS desde la misma región o runtime que utiliza la aplicación.
- Verifica la autenticación de forma independiente de la validación del payload.
- Confirma la identidad de red devuelta e inspecciona el esquema de la respuesta.
- Mide la tasa de errores y el tiempo de respuesta por método en lugar de utilizar un único valor agregado.
- Usa reintentos limitados con backoff y evita reintentar a ciegas envíos no idempotentes.
- Mantén un segundo endpoint configurado solo cuando la aplicación pueda gestionar de forma segura las diferencias de compatibilidad de métodos y frescura de los datos.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Síntoma del fallo | Respuesta 401, 403 o relacionada con la autenticación | Es posible que la solicitud no haya llegado a la validación del método |
| Síntoma del fallo | Error de método inexistente o de API heredada | El ejemplo puede estar dirigido a una API antigua de Sui o a un método no compatible con el proveedor |
| Síntoma del fallo | Error de objeto, transacción o argumento no válido | El endpoint puede funcionar mientras el payload específico de Sui es incorrecto |
| Síntoma del fallo | Timeout, error de gateway o fallo de transporte intermitente | Investiga por separado la ruta de red, el tamaño de la solicitud, el comportamiento de reintento y el estado del proveedor |
Mantenimiento de la documentación y transición a producción
La documentación de Sui es sensible a la versión. Antes de un lanzamiento, consulta la documentación oficial, la documentación del paquete del SDK, las notas de versión del repositorio y la referencia de métodos del proveedor seleccionado. Presta especial atención a los cambios relacionados con la obsolescencia de la API, los formatos de transacción, las actualizaciones de paquetes y la configuración de nodos.
Mantén un runbook interno con el nombre de la red, el origen del endpoint, la versión del SDK, los métodos compatibles, la política de reintentos, la vía de escalación y el procedimiento de rollback. Enlaza las páginas canónicas de precios de RPC y redes RPC compatibles de OnFinality al evaluar una expansión comercial o a varias redes.
Si la aplicación crece desde lecturas sencillas hasta flujos de indexación, analítica o transacciones de gran volumen, reevalúa la arquitectura en lugar de asumir que una conexión RPC normal constituye un pipeline de datos completo. Una API RPC gestionada, la infraestructura de nodo dedicado y una capa de indexación especializada resuelven problemas diferentes.
- Vuelve a validar las suposiciones sobre endpoints y métodos después de actualizar el SDK o el protocolo.
- Documenta si la carga de trabajo necesita estado actual, datos históricos, suscripciones, trazas o indexación.
- Asigna un responsable para la configuración del proveedor y otro distinto para la seguridad de la firma.
- Revisa los costes y las compensaciones operativas antes de añadir más endpoints o infraestructura dedicada.
- Usa la documentación oficial de Sui para los hechos del protocolo y la documentación del proveedor para el comportamiento específico del servicio.
| Criterio | Qué revisar | Por qué importa |
|---|---|---|
| Aplicación de estado actual | Lecturas RPC, envío de transacciones y observabilidad básica | Una API gestionada puede cubrir la integración inicial |
| Aplicación con gran volumen de datos | Historial, paginación, indexación y requisitos de retención | El acceso RPC por sí solo puede no proporcionar el modelo de consulta deseado |
| Comprador de infraestructura | Aislamiento, límite de soporte, diseño de failover y trabajo operativo total | El endpoint más barato no es necesariamente la opción operativa más sencilla |
Preguntas frecuentes
¿Dónde está la documentación oficial de Sui?
La documentación principal está disponible en docs.sui.io. Incluye material de introducción, desarrollo con Move y de aplicaciones, referencias del SDK y la API, componentes de Sui Stack, operación de full nodes y orientación sobre gestión de datos.
¿Qué documentación de Sui debería leer primero como desarrollador de TypeScript?
Comienza con la documentación oficial del SDK de Sui para TypeScript y sus secciones sobre instalación, clientes, ubicaciones de red, transacciones y keypairs. Lee junto con los ejemplos del SDK el modelo de objetos y los conceptos de transacciones de Sui para que el código se ajuste a su modelo de ejecución.
¿Sui utiliza el mismo flujo de trabajo JSON-RPC que Ethereum?
No. Sui tiene su propio modelo de datos, entorno de programación basado en Move, estructuras de transacciones y convenciones de API. Los ejemplos antiguos de JSON-RPC también pueden ser sensibles a la versión, por lo que debes verificar la compatibilidad actual de los métodos en la documentación oficial del SDK y del proveedor.
¿Debería operar un full node de Sui o usar un proveedor RPC?
Usa una API RPC gestionada cuando tu requisito principal sea el acceso de la aplicación y no quieras operar infraestructura de nodos. Considera un nodo dedicado o un full node operado por tu equipo cuando el aislamiento, el control de la configuración, los datos locales o la independencia operativa justifiquen una responsabilidad adicional.
¿Cómo obtengo un endpoint RPC de Sui de OnFinality?
Comienza en la página de la red Sui de OnFinality o en la configuración de tu cuenta para obtener el endpoint actual y los datos de autenticación. El endpoint debe inyectarse mediante la configuración del despliegue, no copiarse de un ejemplo público no verificado.