Lectura de objetos de Sui mediante RPC: getObject, campos dinámicos y paginación

Respuesta directa: cómo leer objetos de Sui correctamente

Para leer objetos de Sui mediante JSON-RPC, primero debe comprender que un objeto de Sui no es un simple par clave-valor. Cada objeto se identifica por un ID de objeto de 32 bytes, tiene una versión entera que se incrementa en cada escritura y un digest (hash) que también cambia con cada escritura. La propiedad puede ser de dirección, de objeto, compartida o inmutable. Para obtener el estado actual de un objeto, llame a suix_getObject (o el heredado sui_getObject) con el ID del objeto. Para obtener varios objetos en una sola solicitud, use suix_multiGetObjects. Para listar los objetos propiedad de una dirección, use suix_getOwnedObjects con un filtro opcional. Los campos dinámicos, que permiten que los objetos aniden datos arbitrarios, se leen por separado mediante suix_getDynamicFields (para paginarlos) y suix_getDynamicFieldObject (para obtener uno solo). La paginación se basa en cursores y debe manejar correctamente los campos nextCursor y hasNextPage para evitar bucles. Esta guía recorre cada método con ejemplos ejecutables y una lista de verificación para solucionar problemas.

El modelo de objetos de Sui: ID, versión, digest y propiedad

En Sui, todo es un objeto. El modelo basado en Move almacena los objetos en un mapa global con clave de ObjectID de 32 bytes. Cada objeto tiene una version (un entero que aumenta monótonamente) y un digest (un hash del contenido y la versión del objeto). Cuando un objeto se muta, su versión se incrementa y su digest cambia. Este triple (ID, versión, digest) es la base de todas las lecturas. La propiedad puede ser de uno de cuatro tipos: propiedad de dirección (controlada por una sola dirección), propiedad de objeto (propiedad de otro objeto, lo que permite estructuras jerárquicas), compartida (accesible por cualquiera, a menudo utilizada para estado compartido) e inmutable (no se puede mutar, como los paquetes publicados).

La documentación oficial de Sui explica que los objetos pueden estar envueltos dentro de otros objetos, lo que afecta su visibilidad. Por ejemplo, un objeto envuelto ya no es accesible directamente por su ID; está 'oculto' dentro del objeto padre. Esta es una fuente común de confusión cuando una llamada a getObject devuelve no encontrado aunque el objeto exista en la cadena.

Cuando lee un objeto, recibe su estado actual, incluida la disposición de data (por ejemplo, moveObject o package), el propietario y la referencia (ID, versión, digest). Si solicita solo la referencia (estableciendo showContent en falso), obtiene una respuesta ligera que es útil para rastrear cambios sin descargar el contenido completo.

Lectura de objetos: sui_getObject y suix_multiGetObjects

El método principal para leer un solo objeto es suix_getObject (el heredado sui_getObject está obsoleto pero aún funciona en muchos nodos). Toma un ID de objeto y un conjunto de opciones de visualización (por ejemplo, showContent, showOwner, showType). La respuesta incluye el objectId, version, digest, owner y el campo data con el tipo Move y los campos.

Para lecturas por lotes, use suix_multiGetObjects con una matriz de IDs y las mismas opciones de visualización. Esto es eficiente cuando necesita obtener varios objetos en un solo viaje de ida y vuelta, lo que reduce la latencia y el uso de límites de velocidad. Tenga en cuenta que el orden de la respuesta coincide con el orden de la solicitud, y si un objeto no existe, la entrada correspondiente será null.

Aquí hay un ejemplo de curl ejecutable que utiliza un endpoint RPC público de Sui (reemplace la URL con su propio proveedor si es necesario). El ejemplo obtiene un objeto conocido (una moneda Sui) e imprime la respuesta:

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getObject",
    "params": [
      "0x2::sui::SUI",
      {
        "showContent": true,
        "showOwner": true,
        "showType": true
      }
    ]
  }'

Listado de objetos propiedad: suix_getOwnedObjects y filtros

Para enumerar los objetos propiedad de una dirección, use suix_getOwnedObjects. Este método devuelve los objetos 'principales' propiedad de una dirección, es decir, objetos que son directamente propiedad de la dirección y no están envueltos dentro de otro objeto. No devuelve campos dinámicos ni saldos de monedas de forma predeterminada. Para filtrar por tipo o paquete, use el parámetro filter con filtros StructType o Package.

Por ejemplo, para listar todas las monedas SUI propiedad de una dirección, filtraría por 0x2::coin::Coin<0x2::sui::SUI>. La respuesta incluye un cursor para la paginación. Aquí hay un ejemplo de curl:

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getOwnedObjects",
    "params": [
      "0xYOUR_ADDRESS",
      {
        "filter": {
          "StructType": "0x2::coin::Coin<0x2::sui::SUI>"
        },
        "options": {
          "showContent": true,
          "showOwner": true
        },
        "limit": 10
      }
    ]
  }'

Campos dinámicos: lectura de datos anidados

Los objetos de Sui pueden contener campos dinámicos, que son pares clave-valor almacenados en el propio objeto. Estos campos permiten estructuras de datos flexibles que se pueden agregar o eliminar con el tiempo. Los campos dinámicos no forman parte del esquema fijo del objeto; se almacenan por separado y deben leerse con métodos dedicados.

Para paginar todos los campos dinámicos de un objeto padre, use suix_getDynamicFields con el ID del objeto padre, un cursor y un límite. La respuesta incluye una lista de nombres de campos dinámicos (codificados en base58) y sus tipos, junto con un nextCursor para la paginación. Para obtener el valor de un campo dinámico específico, use suix_getDynamicFieldObject con el ID del padre y el nombre del campo (como un objeto DynamicFieldName con type y value).

Aquí hay un ejemplo de paginación a través de campos dinámicos:

curl -X POST https://fullnode.mainnet.sui.io:443 \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "suix_getDynamicFields",
    "params": [
      "0xPARENT_OBJECT_ID",
      null,  // cursor
      10     // limit
    ]
  }'

Paginación con cursores: evitar bucles y datos faltantes

Todos los métodos de lista en Sui RPC (por ejemplo, suix_getOwnedObjects, suix_getDynamicFields) utilizan paginación basada en cursor. La respuesta incluye un campo nextCursor y un booleano hasNextPage. Para obtener la siguiente página, pase el nextCursor como parámetro de cursor en la siguiente solicitud. Si hasNextPage es falso, ha llegado al final.

Un error común es usar el mismo cursor repetidamente, lo que provoca un bucle infinito. Siempre actualice el cursor desde la respuesta. Además, tenga en cuenta que el parámetro limit está limitado por el proveedor del nodo; el valor predeterminado suele ser 50, pero puede variar. Si establece un límite superior al máximo, el nodo puede devolver un error o limitarlo silenciosamente. Consulte la documentación de su proveedor para conocer el límite exacto.

Aquí hay una tabla de resultados para completar y registrar sus propios resultados de paginación:

• | Página | Cursor utilizado | Objetos devueltos | nextCursor | hasNextPage |
• |------|-------------|------------------|------------|-------------|
• | 1 | null | [complete] | [complete] | [complete] |
• | 2 | [complete] | [complete] | [complete] | [complete] |
• | ... | ... | ... | ... | ... |

Lectura de versiones históricas y nodos de archivo

Para leer una versión histórica específica de un objeto, debe solicitarla explícitamente. El método suix_getObject acepta un parámetro version opcional (¿como parte de SuiObjectDataOptions? En realidad, el método estándar no admite versiones; debe usar suix_tryGetPastObject o similar). En la API heredada, sui_getObject no admite versiones; debe usar sui_tryGetPastObject (ahora suix_tryGetPastObject) para obtener una versión pasada. Este método requiere el ID del objeto y el número de versión deseado.

Sin embargo, las versiones pasadas solo están disponibles en nodos de archivo que almacenan el historial completo. Un fullnode que no es un nodo de archivo solo tendrá el estado más reciente y un historial limitado de checkpoints. Si solicita una versión que no está disponible, el nodo devuelve un error. Para aplicaciones que necesitan el historial completo de objetos, debe conectarse a un proveedor RPC de archivo. OnFinality ofrece nodos de archivo de Sui y datos históricos que conservan el historial completo.

Alternativamente, puede rastrear los cambios de objetos mediante eventos o suix_getObject con showPreviousTransaction para ver la última transacción que modificó el objeto, pero eso no le brinda el historial completo.

Lista de verificación de solución de problemas: fallas comunes y correcciones

Al leer objetos de Sui, puede encontrar varios problemas comunes. Use esta lista de verificación para diagnosticarlos y corregirlos:

• Objeto no encontrado: Si suix_getObject devuelve null o un error, el objeto puede haber sido envuelto, eliminado o nunca haber existido. Verifique el ID del objeto por errores tipográficos. Si el objeto fue envuelto, ya no es accesible directamente; debe leerlo a través de los campos dinámicos de su objeto padre.
• Semántica de objetos inmutables: Los objetos inmutables (como los paquetes) nunca cambian. Su versión siempre es 1 y el digest es constante. Si espera un incremento de versión, probablemente esté mirando el objeto equivocado.
• El campo no existe: Al usar suix_getDynamicFieldObject, asegúrese de que el nombre y el tipo del campo coincidan exactamente con la clave almacenada. Los nombres de campos dinámicos están codificados en base58 y son sensibles al tipo. Una discrepancia devuelve un error.
• Versión no disponible: Si solicita una versión histórica en un nodo que no es de archivo, obtiene un error. Use un nodo de archivo o ajuste su consulta a la versión más reciente.
• Uso incorrecto del cursor: Siempre use el nextCursor de la respuesta anterior. Si pasa el mismo cursor, puede entrar en un bucle infinito. Además, asegúrese de manejar hasNextPage correctamente.
• Límites de paginación: El parámetro limit está limitado por el proveedor. Si lo excede, el nodo puede devolver un error o truncar los resultados. Consulte la documentación de su proveedor para conocer el límite máximo. En OnFinality, los límites están documentados y pueden variar según el plan; consulte Precios de RPC.

Limitaciones y compensaciones de las lecturas de objetos

Leer objetos de Sui mediante RPC tiene limitaciones inherentes. Primero, suix_getOwnedObjects solo devuelve objetos de propiedad principal; no incluye objetos anidados en campos dinámicos ni monedas que no sean de propiedad directa. Para obtener un inventario completo, debe recorrer recursivamente los campos dinámicos, lo que puede ser costoso.

Segundo, las lecturas de objetos son instantáneas. Para rastrear cambios a lo largo del tiempo, debe sondear la versión y el digest del objeto, o suscribirse a eventos. El sondeo puede ser intensivo en límites de velocidad; considere usar suscripciones WebSocket para actualizaciones en tiempo real. La guía de OnFinality sobre suscripciones a eventos WebSocket de Sui explica cómo configurarlo.

Tercero, la API JSON-RPC está migrando hacia un SDK tipado. En Sui 2.0, muchos métodos sin procesar se están eliminando gradualmente en favor de métodos SDK que abstraen la capa RPC. Esta migración no es disruptiva por ahora, pero debe planear actualizar su código. La Guía de migración JSON-RPC de Sui oficial proporciona detalles.

Finalmente, el costo de leer muchos objetos puede acumularse. Las lecturas por lotes con suix_multiGetObjects son más eficientes que las llamadas individuales. Para la extracción de datos a gran escala, considere usar un servicio de datos dedicado o indexación.

Próximos pasos y lecturas adicionales

Ahora que comprende cómo leer objetos de Sui, puede aplicar este conocimiento para crear rastreadores de activos, sistemas de inventario o cualquier aplicación que necesite consultar el estado en cadena. Para profundizar su comprensión, explore los siguientes recursos:

• Guía de RPC de Sui (Asistente de RPC) – Referencia rápida para todos los métodos RPC de Sui.

• Simulación de transacciones de Sui con devInspectTransaction – Aprenda a simular transacciones sin confirmarlas.

• Latencia y rendimiento de RPC de Sui – Comprenda los factores de latencia y cómo optimizar sus llamadas.

• Nodos de archivo de Sui y datos históricos – Acceda al historial completo de objetos.

• Suscripciones a eventos WebSocket de Sui – Obtenga actualizaciones en tiempo real sobre cambios de objetos.

• Centro de aprendizaje de OnFinality – Más tutoriales y guías.

• Servicio de API – Endpoints RPC administrados de OnFinality.

• Precios de RPC – Comprenda los límites de velocidad y los costos.

• Descripción general de la red Sui – Información general de la red Sui.