La API del nodo

Cada nodo de ZooBC sirve una API HTTP pública. Es la forma en que las billeteras, los exploradores, las herramientas de línea de comandos y cualquier página web leen la cadena y envían transacciones. Leer no necesita ninguna clave, ninguna cuenta ni ninguna clave de API, y la API responde a páginas alojadas en cualquier sitio. Escribir solo necesita una transacción firmada por su remitente.

Lo básico

• Dónde: HTTP/1.1 en texto plano, por defecto en el puerto 8080, con más de cien rutas bajo /api/v1/. El nodo también sirve la billetera web en / y en /wallet.
• Sin TLS en el nodo: los sitios públicos llegan a la API por HTTPS a través de una pasarela, que además pone delante un servicio de archivo para el historial profundo.
• Abierta a todas las páginas: cada respuesta lleva Access-Control-Allow-Origin: *, y la comprobación OPTIONS del navegador se responde de inmediato, así que una página de cualquier dominio puede llamar a la API (crear una app como una sola página HTML).
• Casi todo lecturas: todas las rutas salvo ocho son lecturas que no necesitan autenticación. Enviar una transacción no necesita ninguna clave de API, porque la transacción lleva su propia firma.
• Límites por dirección de cliente: 300 peticiones de escritura por minuto por defecto (por encima de eso el nodo responde 429 con una cabecera Retry-After); las lecturas no tienen límite salvo que el operador fije uno.

Lo que puedes leer

Todas las rutas de la segunda columna cuelgan de /api/v1/. /movements lista cada cambio del saldo de una cuenta con su causa, incluidos el alquiler pagado y las recompensas ganadas. /pubkey devuelve la clave pública de una cuenta nativa a partir de su dirección sola. Desde la versión 0.5.8, las rutas de la cadena indican la finalized_height y cada transacción un indicador finalized, que se activa cuando un bloque de la spine cofirmado cubre su bloque (finalidad y reversión).

Cualquiera puede consultar así cualquier dirección. La cadena registra claves, no nombres, así que la privacidad en ZooBC proviene de cómo se usan las direcciones, no de saldos ocultos (cuentas y direcciones).

Enviar una transacción

Un cliente construye los bytes de la transacción, firma el resumen vinculado a la cadena con la clave del remitente, usando el genesis_hash leído de /api/v1/node/info (firmar una transacción), y envía el resultado a POST /api/v1/transactions. No hace falta ningún SDK: bastan Ed25519, SHA3-256 y el hash del génesis.

El nodo responde HTTP 202, que significa «aceptada», no «hecha», y devuelve el hash de la transacción. Después, el cliente consulta /api/v1/transactions/<hash>/status, que pasa por:

1. staging y luego mempool, mientras la transacción espera a un bloque;
2. confirmed, con la altura del bloque, una vez que un bloque la incluye;
3. o rejected, con el motivo y la etapa, si se rechaza; not_found (404) si el nodo no la conoce.

Con un bloque cada 15 segundos, consultar cada par de segundos es más que suficiente. Antes de entregar mercancía a cambio de un pago, espera a la confirmación y, preferiblemente, al indicador de finalizada.

Si se pierde una respuesta, reenvía exactamente los mismos bytes firmados. El hash se calcula a partir de esos bytes, así que un nodo que ya tiene la transacción, incluso una ya incluida en un bloque, vuelve a responder 202, marcándola como duplicada, y solo se ejecuta una vez. Volver a firmar con una marca de tiempo nueva crea una transacción distinta, y así es como se producen los pagos dobles.

Peticiones firmadas y cancelación

Unas pocas peticiones llevan una firma propia: una firma Ed25519 sobre METHOD:PATH:TIMESTAMP:BODY, válida durante 300 segundos. Un cliente que falla 20 autenticaciones firmadas en 5 minutos queda bloqueado durante 300 segundos. Una transacción pendiente puede retirarse del conjunto de espera de un nodo con una petición DELETE firmada (mensajes firmados y cifrados).

Otras interfaces de un nodo

• Puerto 8001: la red entre pares de los nodos.
• Puerto 8545: un adaptador JSON-RPC al estilo de Ethereum, por defecto solo en la propia máquina del nodo, que usa MetaMask.
• Puerto 8332: un adaptador RPC al estilo de Bitcoin Core, desactivado por defecto, que necesita las credenciales propias del operador.

Véase también

• Crear una app como una sola página HTML
• Herramientas de línea de comandos
• Pasarelas
• Firmar una transacción
• El explorador y los nodos de archivo