Jettons en TON: arquitectura TEP-74, transferencias y verificación

Alcance y los dos significados de jettons

La palabra jettons tiene dos historias no relacionadas. En numismática, los jetons (también escritos jettons) eran fichas de conteo similares a monedas producidas en Europa aproximadamente entre los siglos XIII y XVIII y utilizadas en tableros de conteo. En ingeniería blockchain, los jettons son el estándar de tokens fungibles de The Open Network (TON), especificado como TEP-74. Este artículo cubre solo el significado en TON; el sentido histórico es un contexto útil pero no algo que implementes.

La respuesta directa a qué es un jetton en TON: es un token fungible cuyo contrato maestro contiene los metadatos y el suministro total, mientras que el saldo de cada titular vive en un contrato de billetera jetton separado propiedad de ese titular. Las transferencias son mensajes entre estos contratos, no una única actualización de saldo en un solo libro mayor. Esa distinción impulsa casi todas las diferencias operativas con los tokens al estilo ERC-20.

• TEP-74 define el maestro de jettons, la billetera jetton y la estructura del mensaje de transferencia.
• Cada titular tiene su propio contrato de billetera jetton por cada jetton.
• Las transferencias son mensajes internos asíncronos, por lo que la confirmación no es instantánea como lo sería una actualización de saldo en un solo contrato.

Requisitos previos y supuestos

Necesitas un endpoint RPC de TON que admita los métodos que planeas llamar, una billetera con fondos para cualquier transferencia que intentes y familiaridad básica con las direcciones de TON (workchains, formas rebotables versus no rebotables). Los ejemplos a continuación usan marcadores como RPC_URL, JETTON_MASTER_ADDRESS y PRIVATE_KEY; sustituye tus propios valores y nunca confirmes claves reales.

Los ejemplos de código usan llamadas estándar de estilo HTTP JSON-RPC contra un endpoint de TON. Los nombres exactos de los métodos y las formas de las respuestas pueden variar según el proveedor, así que trata los fragmentos como un procedimiento a adaptar, no como un contrato de API fijo. Para la selección de endpoints, la comparación del Asistente RPC de endpoints RPC de TON es el lugar adecuado para elegir un proveedor concreto; este artículo se centra en la mecánica de los jettons y el método de verificación.

Cómo se estructura el modelo de jettons TEP-74

Un contrato maestro de jettons es el registro. Almacena los metadatos del token (nombre, símbolo, decimales), rastrea el suministro total y sabe cómo derivar la dirección de una billetera jetton para un propietario dado. No almacena el saldo de cada titular en un solo lugar.

Un contrato de billetera jetton se despliega por cada par (jetton, propietario). Contiene el saldo de ese propietario e implementa los comportamientos de transferencia, quema y notificación de quema. Cuando envías jettons, tu contrato de billetera envía un mensaje interno al contrato de billetera de destino, que acredita el saldo y puede enviar una notificación de vuelta al contrato del propietario de destino si se especifica uno.

Este diseño distribuido es el modelo mental principal que debes mantener: para encontrar el saldo de jettons de alguien, primero debes resolver la dirección de su billetera jetton desde el maestro y luego consultar esa billetera. Consultar solo el maestro te da el suministro y los metadatos, no los saldos individuales.

• Maestro: metadatos, suministro total, derivación de la dirección de la billetera.
• Billetera jetton: saldo por propietario y lógica de transferencia.
• Mensaje de transferencia: cantidad, destino, dirección de respuesta, carga útil de reenvío opcional y cantidad de reenvío.

Lectura de metadatos y suministro total de jettons

El primer paso de diagnóstico para cualquier integración de jettons es confirmar que estás hablando con el contrato maestro correcto y leer sus metadatos. Una llamada curl ejecutable contra un endpoint JSON-RPC de TON normalmente ejecuta un get-method en el maestro. El nombre exacto del método depende de tu proveedor; el patrón a continuación muestra la forma de una invocación de get-method.

Ejecuta esto contra tu propio RPC_URL y compara el símbolo y los decimales devueltos con lo que muestra un explorador de bloques para la misma dirección maestra. Una discrepancia suele significar que consultaste el contrato equivocado o un proxy que reescribe las respuestas.

curl -sS -X POST "$RPC_URL" \
  -H 'Content-Type: application/json' \
  -d '{
    "jsonrpc": "2.0",
    "id": 1,
    "method": "runGetMethod",
    "params": {
      "address": "JETTON_MASTER_ADDRESS",
      "method": "get_jetton_data",
      "stack": []
    }
  }'

Resolución de la dirección de la billetera jetton de un titular

Dado que los saldos viven en contratos de billetera por propietario, no puedes leer un saldo directamente desde el maestro. Debes derivar o buscar la dirección de la billetera jetton del propietario. Muchos proveedores exponen un método auxiliar para esto; si el tuyo no lo hace, puedes llamar al get-method de dirección de billetera del maestro con la dirección del propietario como argumento.

El fragmento de Python a continuación muestra el procedimiento: llama al maestro para obtener la dirección de la billetera de un propietario, luego llama a esa billetera para leer su saldo. Usa un cliente JSON-RPC genérico y valores de marcador, así que adapta los nombres de los métodos a la superficie documentada de tu proveedor.

import json, os, urllib.request

RPC_URL = os.environ["RPC_URL"]
MASTER = os.environ["JETTON_MASTER_ADDRESS"]
OWNER = os.environ["OWNER_ADDRESS"]

def rpc(method, params):
    body = json.dumps({"jsonrpc": "2.0", "id": 1, "method": method, "params": params}).encode()
    req = urllib.request.Request(RPC_URL, data=body, headers={"Content-Type": "application/json"})
    with urllib.request.urlopen(req, timeout=30) as r:
        return json.load(r)

# Step 1: resolve the jetton wallet for this owner from the master
wallet = rpc("runGetMethod", {
    "address": MASTER,
    "method": "get_wallet_address",
    "stack": [["slice", OWNER]],
})
print("wallet lookup:", json.dumps(wallet, indent=2))

# Step 2: read the balance from the resolved wallet contract
# (substitute the wallet address returned above)
balance = rpc("runGetMethod", {
    "address": "RESOLVED_JETTON_WALLET_ADDRESS",
    "method": "get_wallet_data",
    "stack": [],
})
print("wallet data:", json.dumps(balance, indent=2))

Ejecución de una transferencia de jettons y qué esperar

Una transferencia de jettons es un mensaje interno desde tu billetera jetton a la billetera jetton de destino. En la práctica, envías un mensaje a tu propio contrato de billetera jetton indicándole que transfiera una cantidad especificada a un propietario de destino, con una dirección de respuesta para recibir la confirmación. Como los mensajes de TON son asíncronos, el patrón de verificación correcto es: enviar, capturar el hash del mensaje o la referencia de la transacción, y luego sondear hasta que el saldo de la billetera de destino refleje la transferencia.

No trates un envío exitoso como prueba de liquidación. La transferencia puede rebotar si la billetera de destino no está desplegada y el mensaje es rebotable, o puede fallar a nivel del contrato de billetera. Verifica siempre leyendo el saldo de la billetera jetton de destino después de que se confirme la transacción.

• Envía a tu billetera jetton, no directamente a la dirección sin procesar del destinatario.
• Incluye una dirección de respuesta para que puedas observar el mensaje de confirmación.
• Usa mensajes no rebotables solo cuando aceptes intencionalmente el riesgo de perder fondos hacia una billetera no desplegada.
• Verifica la liquidación volviendo a leer el saldo de la billetera de destino, no confiando en la respuesta del envío.

Un procedimiento de verificación con una tabla de resultados

Usa el siguiente procedimiento para confirmar una transferencia de jettons de extremo a extremo. Registra cada observación en una tabla para poder comparar ejecuciones y detectar regresiones. La tabla a continuación es una plantilla; completa tus propios valores medidos en lugar de asumir cualquier número.

Las condiciones de aprobación son la lógica de verificación; los valores medidos son tuyos para capturar. Si el paso 5 nunca muestra un aumento, la transferencia probablemente rebotó o la billetera de destino no estaba desplegada. Si el paso 6 no muestra una disminución, es posible que el mensaje no haya llegado a tu contrato de billetera.

Solución de problemas comunes de jettons

La mayoría de los problemas de integración de jettons se dividen en unas pocas categorías: dirección maestra incorrecta, derivación de billetera incorrecta, sincronización asíncrona y manejo de rebotes. Resuélvelos en orden en lugar de adivinar.

Si los metadatos parecen incorrectos, probablemente estés consultando el maestro equivocado o una respuesta en caché. Si un saldo se lee como cero para una dirección que crees que tiene jettons, confirma que resolviste la billetera jetton desde el maestro y propietario correctos, y que el formato de la dirección del propietario (rebotable versus no rebotable) coincide con cómo se creó la billetera. Si una transferencia parece enviada pero el destino nunca acredita, verifica si la billetera de destino estaba desplegada y si el mensaje era rebotable.

• Dirección maestra incorrecta: los metadatos y el suministro no coincidirán con el explorador.
• Formato de propietario incorrecto: la derivación de la billetera devuelve un contrato diferente al esperado.
• Liquidación asíncrona: sondear demasiado pronto muestra saldos obsoletos.
• Mensaje rebotable a billetera no desplegada: los fondos vuelven al remitente tras un rebote.
• TON insuficiente para gas: el mensaje de transferencia nunca se ejecuta.

Limitaciones y compensaciones del modelo distribuido

El diseño de billetera por propietario mejora la escalabilidad al evitar un único contrato caliente que cada transferencia deba tocar, pero traslada la complejidad a los clientes. Debes resolver direcciones de billetera, manejar la confirmación asíncrona y razonar sobre el estado de despliegue. Los indexadores y exploradores ocultan parte de esto, pero cualquier integración seria debería implementar los pasos de resolución y verificación por sí misma.

También hay una advertencia de medición: la latencia y las tasas de éxito dependen en gran medida del endpoint RPC que uses, no solo del protocolo. No asumas que una transferencia es rápida o lenta basándote en un proveedor. Ejecuta el procedimiento de verificación anterior contra el endpoint que elijas y registra tus propios tiempos. Para opciones de infraestructura, consulta las opciones de nodo dedicado de OnFinality y la página de precios de RPC para comparar niveles de compromiso antes de decidir una ruta de producción.

Próximos pasos para integraciones en producción

Una vez que puedas leer metadatos, resolver billeteras y verificar transferencias, el siguiente paso es endurecer: añadir reintentos con retroceso alrededor de las llamadas a get-method, persistir las referencias de mensajes para poder reconciliar tras reinicios y monitorear los saldos de destino en lugar de confiar en las respuestas de envío. Si operas a escala, considera un nodo dedicado para que tus consultas de jettons no compitan con el tráfico compartido.

Para la selección de endpoints específicamente, usa la guía del Asistente RPC sobre endpoints RPC de TON en lugar de codificar un proveedor aquí. Combínalo con el directorio de redes de OnFinality para confirmar qué redes y servicios se ajustan a tu arquitectura, y revisa la descripción general del servicio de API si necesitas acceso gestionado en lugar de infraestructura autoalojada.

• Persiste los hashes de mensajes y reconcilia de forma asíncrona.
• Añade claves de idempotencia alrededor del envío de transferencias.
• Monitorea tanto las billeteras jetton del remitente como las del destino.
• Vuelve a ejecutar la tabla de verificación después de cualquier cambio de endpoint.