Desarrolladores

Referencia completa

Cada ruta, sus parámetros y la estructura de su respuesta:

Abrir la referencia de la API →  ·  vista alternativa

Ambas direcciones sirven el mismo documento.

Descargas

Los archivos que un operador ha publicado en esta pasarela se sirven en /dl/<name>. Los nombres son un único segmento de [A-Za-z0-9._-], y todo se envía como adjunto y nunca se renderiza: este origen también sirve la billetera, y una página renderizada aquí heredaría el origen de la billetera.

Los paquetes de versión están en /releases/<version>/<arch>/, y /releases/latest indica el actual. El instalador del nodo está en /install.

¿Está sana esta pasarela? comprobando…

/gateway/status informa de lo que esta pasarela sabe de sí misma y de los nodos a los que puede llegar: modo, dominio, cuántos nodos hay en su lista de permitidos y cuáles responden.

/gateway/system-stats informa sobre la máquina: CPU, memoria, disco, tiempo de actividad. De ahí salen las cifras de la página de la pasarela.

curl https://this-gateway/gateway/status
curl https://this-gateway/gateway/system-stats

Ninguno necesita clave. Ninguno expone nada sobre la cadena; para eso, usa /api/v1/…, más arriba.

Consultar un nodo específico

Las rutas de la cadena responden desde el nodo de archivo que elija esta pasarela. Para consultar un nodo concreto, pon su IP en el nombre de host, con guiones en lugar de puntos; un -p<port> opcional elige el puerto de la API:

curl https://ip-192-168-1-100.this-gateway/api/v1/node/info
curl https://ip-192-168-1-100-p8080.this-gateway/api/v1/node/info

Solo responden los nodos que están en la lista de permitidos de esta pasarela. Cualquier otro se rechaza en lugar de reenviarse, así que el nombre de host no puede usarse para llegar a hosts arbitrarios a través de la pasarela.

Retransmisor

La voz, el video y la pantalla compartida van de igual a igual; cuando un cortafuegos bloquea un enlace directo, un retransmisor transporta el tráfico a cambio de crédito. /relay/info informa de su dirección, su tarifa y el hash génesis de la cadena en la que liquida; una billetera lo compara con el de su propio nodo antes de pagar, porque un retransmisor de otra cadena no puede acreditar lo que se le paga.

curl https://this-gateway/relay/info

Panel de administración

Los controles propios de la pasarela están en zoobc.network/admin. El panel está protegido por admin_api_key de /etc/zoobc/gateway.json, que el instalador genera para cada máquina: no hay ninguna clave predeterminada.

La lista de permitidos

Una pasarela solo reenvía a los nodos que se le han indicado. Esa lista es lo que impide que la forma de nombre de host ip-… convierta la pasarela en un proxy abierto.

Las tres escrituras necesitan la clave de administración. En modo público, la pasarela también descubre nodos a partir del propio registro de la cadena; en modo privado, solo usa static_nodes.

Herramientas de versiones

La calculadora de hash de archivos calcula un SHA-256 en el navegador para cualquier cosa que quieras comprobar a mano, y /verify comprueba un paquete descargado contra los hashes que ha publicado la cadena.

Los dos documentos

Todo lo que necesita un equipo de billeteras de hardware está especificado aquí, y de forma completa en los dos PDF de abajo. Ambos se verificaron contra el nodo ZooBC v0.4.0 (zoobc-main en 7ad161a4) y contra vectores de transacción que aceptó un nodo v0.4.0 en vivo.

La versión 2.1 sustituye al borrador 1 en un aspecto sustancial: las firmas de las transacciones ahora están vinculadas a la cadena. Dos cambios rompen la compatibilidad para quien haya construido sobre el borrador 1: el digest de firma y el cuerpo de ApprovalEscrow. Nada implementa la antigua construcción v0.3.2, así que construye solo con el documento actual.

Resumen en una página

Lee primero estos cuatro

Cuatro puntos que condicionan una implementación más que todo lo demás.

Derivación de claves y direcciones

Referencia: zoobc-signer/extension/lib/zoobc-crypto.js, idéntica byte a byte a la billetera de referencia; equivalentes del lado del nodo en src/crypto/slip10.cpp.

seed = PBKDF2-HMAC-SHA512(NFKD(mnemonic), "mnemonic" + passphrase, 2048, 64)
I    = HMAC-SHA512("ed25519 seed", seed);  k = I[0..32], c = I[32..64]

for index in [44, 883, account]:                       # all hardened
    data = 0x00 || k || u32be(index + 0x80000000)
    I    = HMAC-SHA512(c, data);  k = I[0..32], c = I[32..64]

pubkey = Ed25519.publicKeyFromSeed(k)                  # k is the 32-byte seed

La cuenta 0 es m/44'/883'/0', la cuenta 1 es m/44'/883'/1', y así sucesivamente. La derivación de claves no se ve afectada por la vinculación a la cadena: un mismo conjunto de claves sirve para todas las cadenas ZooBC, solo cambia la firma.

La dirección de visualización se construye a partir de la clave pública, no de la cuenta de 36 bytes:

buf[35] = pubkey(32) || "ZBC"
h       = SHA3-256(buf);  buf[32..35] = h[0..3]        # 3-byte checksum
s       = base32(buf)                                   # RFC 4648 A-Z2-7, no padding, 56 chars
address = "ZBC_" + s[0..8] + "_" + s[8..16] + ...       # 7 groups, canonical length 66

La decodificación acepta guiones bajos, guiones, espacios o ningún separador, en mayúsculas o minúsculas, y la suma de verificación debe recalcularse y compararse. La suma de verificación SHA3 de 3 bytes de arriba es la definición que usan el código y la cadena, así que implementa a partir de ella y de la implementación de referencia de la especificación, que reproduce las direcciones de ejemplo.

Formato de transmisión de la transacción sin firmar

Fuente de verdad: src/util/transaction_util.cpp:144-270. El formato de transmisión no cambió en v0.4.0. Ninguna longitud ni desplazamiento de abajo se ve afectado por la vinculación a la cadena.

El byte final multi_party del bloque de depósito en garantía es obligatorio. Omitirlo, o escribir el marcador de ausencia de depósito en garantía con otro valor, solo produce "Invalid transaction signature" en el nodo, sin más diagnóstico.

Ejemplo resuelto, validado en la cadena

SendZBC de 1 ZBC a uno mismo, comisión de 0.05 ZBC, marca de tiempo 1700000000, sin depósito en garantía, sin mensaje. Es el vector 0 de los siete de la especificación.

01000000                 type = 1 (SendZBC)
01                       version
00f1536500000000         timestamp 1700000000
00000000 5e8eb28d...2152 sender    (type 0 + pubkey)
00000000 5e8eb28d...2152 recipient (type 0 + pubkey)
404b4c0000000000         fee 5 000 000
08000000                 body length 8
00e1f50500000000         body: amount 100 000 000
02000000                 no-escrow marker
00000000                 message length 0

Son 113 bytes. La preimagen de firma antepone 38 más:

5a42432d5458              tag "ZBC-TX"          6 bytes
090ab3c7...a61878         genesis hash         32 bytes
0100000001...00000000     the 113 bytes above 113 bytes
                                              ---------
                                              151 bytes

digest = SHA3-256(preimage) = f37e5340...4644fc, firma 9a3b044d...03bb07, tx_hash = f00a6692...ce78b0. Un nodo v0.4.0 en vivo devolvió HTTP 202 y exactamente ese hash.

Procedimiento de firma, lado del dispositivo

input : account_index, genesis_hash(32), unsigned_bytes

1. k      = SLIP10(m/44'/883'/account_index')
2. pub    = Ed25519.pub(k);  self = 00000000 || pub
3. parse unsigned_bytes; every length must land exactly at the end
4. require version == 1 and sender == self
5. decode body per type; render the approval screen; wait for the user
6. digest = SHA3-256("ZBC-TX" || genesis_hash || unsigned_bytes)
7. sig    = Ed25519.sign(k, digest)          # the digest IS the message
8. return sig(64), and tx_hash = SHA3-256(unsigned_bytes || sig) for the host to cross-check

Usa SHA3 en streaming para que el paso 6 no necesite toda la transacción en RAM. Introduce los 6 bytes de la etiqueta, luego los 32 bytes del génesis y después la transacción.

La etiqueta es el error de implementación más probable de toda la especificación. "ZBC-TX" son seis bytes ASCII, 5a 42 43 2d 54 58, sin terminador NUL y sin prefijo de longitud. Un firmware que añade un terminador a la cadena de texto, o que escribe siete bytes, produce una firma de apariencia válida que falla en la cadena con un error genérico y sin diagnóstico. Pruébalo contra el vector 0 antes que nada.

Lo que hace y lo que no hace la vinculación a la cadena

El host proporciona los 32 bytes del génesis; el dispositivo no los busca. Por tanto, la firma es independiente de la cadena, y una sola ruta de código sirve para testnet, devnet, mainnet y cualquier cadena ZooBC privada o paralela.

Así que sigue siendo conveniente una tabla de hashes génesis conocidos en el firmware, pero con un único fin: mostrar en pantalla un nombre de red fiable, recurriendo a "UNKNOWN CHAIN" más los primeros 8 caracteres hex cuando el hash no está en la tabla.

No rechaces por defecto las cadenas no reconocidas. El hash de devnet cambia con cada relanzamiento, y las cadenas privadas o paralelas son normales en ZooBC, así que un rechazo estricto deja el dispositivo inservible para la integración y para despliegues legítimos. Si un fabricante quiere ese bloqueo, que sea un ajuste explícito del usuario, desactivado por defecto.

Tipos de transacción: lo que debería incluir un firmware estándar

Id de tipo = group + 256 × subtype. Existen cincuenta y seis tipos. Estos tres cubren pagar en ZBC, pagar con cualquier token y completar un depósito en garantía, y sus cuerpos son pequeños y fijos.

token_id es un valor de 64 bits con signo derivado de un hash, así que puede ser negativo. Las monedas génesis son los ids 1 a 14; el propio ZBC es el id 0 y nunca aparece en TransferToken. Cada token tiene su propio decimals (0 a 8), que el dispositivo no puede verificar.

ApprovalEscrow cambió en v0.4.0. El cuerpo era approval más un id de 8 bytes (12 bytes); ahora es approval más el hash de 32 bytes de la transacción en depósito en garantía (36 bytes), y el analizador rechaza cualquier otra longitud. El motivo afecta directamente a las billeteras de hardware: un firmante que solo veía un id de 8 bytes no podía comprobar qué estaba liberando, y un id de 8 bytes se puede encontrar con una búsqueda de 2^64 contra un depósito en garantía falso mostrado al dispositivo. Con el hash completo, el dispositivo puede verificar lo que aprueba.

Lo que verifica el dispositivo

Lo que el usuario aprueba en pantalla

Por pantalla, en este orden, adaptado del firmante de referencia validado en la cadena.

No es necesario mostrar las marcas de tiempo. No son significativas para el usuario y el nodo impone la ventana.

Protocolo entre host y dispositivo

El transporte es la propia capa USB/HID del fabricante, con su fragmentación existente. Lo que importa es el contenido.

genesis_hash es esencial, no una indicación de visualización. En el borrador 1, el parámetro de red podía ser un enum, porque solo elegía una etiqueta. Ahora está dentro del digest, así que deben ser los 32 bytes reales, y un valor incorrecto produce una firma que ninguna cadena aceptará.

La regla de la firma en bruto. Un comando de firma en bruto nunca debe firmar una entrada de exactamente 32 bytes, y solo debería firmar entradas que pueda mostrar como texto. Una entrada en bruto de 32 bytes podría ser el digest SHA3 de una transacción que el usuario nunca vio, lo que convierte el comando de mensajes en una firma de transacciones a ciegas. Rechazar la longitud 32 cierra ese agujero sin ningún cambio en la cadena.

La secuencia completa

Website (page)         Companion / host           device                    Gateway / node
   |-- connect ---------->|                            |                          |
   |                      |-- GET_PUBLIC_KEY(0) ----->|  (shows ZBC_... address) |
   |<-- address ----------|<-- pubkey, address -------|                          |
   |-- GET /api/v1/node/info  (genesis_hash, signing_version, height) ---------->|
   |-- GET /api/v1/accounts/<addr>  (balances) --------------------------------->|
   |-- GET /api/v1/accounts/<addr>/tokens, /api/v1/tokens/<id> (decimals) ------>|
   |   user fills the form                             |                          |
   |-- GET /api/v1/blockchain/estimate-fee?type=1&body_length=8 ---------------->|
   |<-- {minimum_fee, timestamp} ------------------------------------------------|
   |-- fields {type, recipient, body, fee, message} -->|                          |
   |                      |  serialize the 11 fields   |                          |
   |                      |-- SIGN_TX(0, genesis, -->|  parse, verify, display,  |
   |                      |            bytes)         |  user approves            |
   |                      |<-- signature, tx_hash ---|                          |
   |<-- signature --------|                            |                          |
   |-- POST /api/v1/transactions {JSON} ---------------------------------------->|
   |<-- 202 {status:"success", transaction_hash} --------------------------------|
   |-- GET /api/v1/transactions/<hash>/status  (staging, mempool, confirmed) --->|

El host compara el transaction_hash del nodo con el tx_hash del dispositivo. Deben ser idénticos; de lo contrario, el host alteró los bytes después de la firma.

Lee genesis_hash y signing_version del endpoint al que vayas a difundir, ya que esa es la cadena que juzga la firma.

Identidad de la cadena

El único identificador de red que tiene ZooBC es el hash del bloque génesis. Los nodos lo comparan antes de conectarse como pares; no hay ningún byte de id de red. GET /api/v1/node/info lo devuelve junto con dos campos nuevos en v0.4.0:

"genesis_hash": "090ab3c7...", "signing_version": 2, "signing_tag": "ZBC-TX"

signing_version ausente significa que el nodo es anterior a v0.4.0 y aplica el digest heredado no vinculado. Un host que solo admite cadenas actuales puede tratar su ausencia como "no firmes aquí". Un nodo imprime el hex en minúsculas y la API de archivo en mayúsculas, así que decodifica sin distinguir mayúsculas de minúsculas y elimina un 0x inicial si lo hay. Los bytes son los mismos en ambos casos.

De dónde leerlo. Una pasarela responde a /api/v1/node/info desde el servicio de archivo y no desde un nodo. El servicio de archivo transmite los dos campos de firma del nodo que replica, emitiéndolos exactamente cuando el nodo los informa, a partir de la compilación 7ad161a4. Lee signing_version de un endpoint de nodo, o de una pasarela con esa compilación o una posterior, y trata su ausencia como "pregunta a un nodo" y no como una respuesta.

Difusión

POST /api/v1/transactions. Sin cambios en v0.4.0, ningún campo nuevo. transaction_body_bytes es solo el cuerpo: el nodo reconstruye el sobre a partir de los campos con nombre, antepone su propio hash génesis y la etiqueta, y recalcula el digest, así que cada campo debe ser igual a lo que se firmó.

{
  "version": 1,
  "timestamp": 1700000000,
  "transaction_type": 1,
  "fee": 5000000,
  "sender_account_address":    "00000000 5e8eb28d ... 2152",
  "recipient_account_address": "00000000 5e8eb28d ... 2152",
  "transaction_body_bytes": "00e1f50500000000",
  "signature": "9a3b044d ... 03bb07",
  "message_hex": "...optional...",
  "escrow": { "approver_address": "...", "commission": 0, "timeout": 1700003600 }
}

El éxito es HTTP 202 con {"status":"success","duplicate":false,"transaction_hash":"..."}. duplicate:true significa que el nodo ya la tiene, así que no la reenvíes. Trata también 200 como éxito. El fallo es 400 con un cuerpo de error, o 503 bajo carga.

Una prueba de integración útil: el pool de preparación comprueba primero la firma, así que una transacción que llega a un error posterior como "Sender account does not exist" ya ha superado la verificación de firma. Puedes validar tu ruta de firma con una clave sin fondos.

Cuando se rechaza una firma

Hoy, una discrepancia de cadena no se distingue de ningún otro fallo de firma. Un digest heredado y un digest de la cadena equivocada devuelven exactamente el mismo cuerpo:

{"success":false,"error":"Transaction validation failed: ValidationError: Invalid transaction signature","code":400}

Así que revisa las causas en este orden, de la más probable a la menos probable:

Endpoints para tu integración

Dirige las lecturas primero al nodo de archivo, luego a la pasarela y luego al nodo. Difunde a una pasarela o a un nodo, nunca a un endpoint de archivo.

Lee el hash de génesis en tiempo de ejecución; no lo escribas fijo en el código. El de la devnet cambia en cada relanzamiento. La tabla de hashes del firmware existe solo para mostrar un nombre en la pantalla, así que una entrada obsoleta se degrada a "UNKNOWN CHAIN" en lugar de romper la firma. Cuando el hash de la devnet cambia, todas las firmas hechas antes quedan anuladas, y eso es la función haciendo su trabajo.