Referencia de la API RPC

La interfaz HTTP que un nodo ofrece a las carteras: cuatro endpoints, JSON para el estado y los errores, y una codificación binaria compacta para bloques y pagos.

La URL base del nodo público de pruebas es https://node.tint.top. La interfaz nunca ve una clave ni un importe: una cartera envía pagos ya terminados y lee bloques completos, que descifra ella misma.

Endpoints

Método y ruta	Responde con
`GET /v1/status`	El estado de la cadena, como JSON.
`GET /v1/blocks/{height}`	Un bloque finalizado, en la codificación wire.
`GET /v1/blocks?from=N`	Los bloques con pagos desde la altura N en adelante, como un lote de bloques.
`POST /v1/transactions`	Recibe un pago en la codificación wire; responde con su identificador como JSON.

GET /v1/status

request

curl -s https://node.tint.top/v1/status

response (example values)

{
  "chain_id": 6073471695170043905,
  "height": 128431,
  "tip": "9f3c…e21a",
  "genesis": "04b7…c9d0",
  "queued": 0,
  "pools": [
    { "asset": 1, "native": 20000000000000, "other": 10000000000000, "fee_bps": 30 }
  ]
}

Campo	Significado
`chain_id`	Identificador de la red, incorporado en cada firma y en cada hash de bloque.
`height`	Altura del último bloque finalizado.
`tip`	Hash del último bloque finalizado, en hexadecimal.
`genesis`	Hash del primer bloque, en hexadecimal. Dos redes de pruebas pueden compartir un `chain_id`; esto las distingue.
`queued`	Pagos a la espera de un bloque.
`pools[].asset`	La moneda que el pool intercambia con la nativa (1 es `TUSD`).
`pools[].native`, `pools[].other`	Lo que contiene el pool, en unidades (1 moneda = 100,000,000 unidades), según el último bloque finalizado.
`pools[].fee_bps`	La comisión del pool en diezmilésimas; 30 es el 0,3 %.

GET /v1/blocks/{height}

Devuelve un bloque finalizado como application/octet-stream. Un bloque finalizado nunca cambia, así que la respuesta lleva Cache-Control: public, max-age=31536000, immutable. Una altura no numérica responde invalid_height; una desconocida, not_found.

GET /v1/blocks?from=N

Devuelve los bloques que contienen pagos desde la altura N en adelante, como un único lote de bloques (application/octet-stream), junto con la última altura que cubre la respuesta (through). Una cartera que se está poniendo al día vuelve a preguntar desde la altura siguiente a through. La respuesta crece con la cadena, por lo que se envía con Cache-Control: no-store. from debe ser un número entero.

POST /v1/transactions

Envía un pago terminado en la codificación wire como cuerpo de la petición. Lo construye la cartera; el formato se define en el módulo wire.rs de tint-core: campos de ancho fijo, una única codificación válida por valor, sin bytes sobrantes.

request

curl -s -X POST https://node.tint.top/v1/transactions \
  -H 'content-type: application/octet-stream' \
  --data-binary @payment.bin

response

{ "txid": "5be1…07af" }

Una transacción empieza con el activo (u32), una altura de caducidad (u64) y un tipo (0 para un pago, 1 para un intercambio), seguidos de un paquete: indicadores, un balance de valor, un ancla, el número de acciones y las acciones con su prueba. Un intercambio añade la moneda comprada, el importe pagado y un segundo paquete.

Errores

Los errores son JSON: {"error":{"code":"...","message":"..."}}.

HTTP	code	Significado
400	`malformed`	El cuerpo no es un pago.
400	`invalid_height`	La altura o `from` no es un número entero.
404	`not_found`	No hay un bloque finalizado en esta altura, o no existe ese recurso.
409	`double_spend`	Una nota de este pago ya está gastada.
409	`conflict`	Otro pago en espera gasta alguna de las mismas notas.
409	`price_moved`	El pool ya no da lo que pide este intercambio.
413	`too_large`	El pago es más grande de lo que permite la cadena.
422	`rejected`	El pago incumple una regla de la cadena; el mensaje indica cuál.
429	`rate_limited`	Esta dirección de cliente ha agotado su presupuesto de peticiones. Reintenta tras el tiempo indicado en la cabecera `Retry-After`.
500	`internal`	El nodo no pudo comprobar o codificar.
503	`busy`, `queue_full`	El nodo está verificando otros pagos o su cola está llena. Inténtalo de nuevo; `Retry-After: 1`.

Límites de frecuencia

Por defecto cada dirección de cliente puede hacer 50 peticiones por segundo de forma sostenida, con una ráfaga de 100, y se verifican como máximo 4 pagos a la vez entre todos los clientes. Los operadores pueden cambiar ambos valores. Detrás de un proxy inverso el nodo cuenta los clientes por la última dirección que el proxy escribió en X-Forwarded-For; no se fía de las entradas anteriores.

Ejemplo: seguir la cadena

python (server side)

import json, time, urllib.request

BASE = "https://node.tint.top"

while True:
    with urllib.request.urlopen(f"{BASE}/v1/status", timeout=10) as r:
        status = json.load(r)
    print(status["height"], status["queued"])
    time.sleep(5)

Lo que un operador de nodo aún puede saber por esta interfaz es la dirección de red desde la que llegó un pago. Los importes, los remitentes y los destinatarios están dentro de la prueba y de las notas cifradas.