Ir al contenido

Referencia del protocolo

Esta página es una referencia rápida para integrarse. Cómo se verifica un comprobante lo define el abierto HardState Receipt Format, y el contrato de la API legible por máquina es openapi.yaml (ambos en inglés), con cada endpoint en la referencia HTTP.

Qué Regla
Hashes SHA-256, escritos en hexadecimal en minúsculas (64 caracteres).
Binario en JSON base64url, sin relleno (firmas, llaves, datos de WebAuthn).
JSON canónico RFC 8785 (JCS). canonical(x) son los bytes UTF-8 de la serialización JCS.
Horas Cadenas RFC 3339 en UTC, p. ej. 2026-10-20T15:18:38.955Z.
{
"hss": 1,
"issuer": "esperanza-demo",
"seq": 5,
"prev": "09f54f6f…69b9ab",
"type": "case.inspect",
"case": "BP-2026-4077",
"ts": "2026-10-20T15:18:39.120Z",
"public": { "result": "pass", "inspector": "Unit 3" },
"docs": [{ "label": "Inspection report", "commitment": "…", "mime": "application/pdf", "size": 812 }],
"actor": "ed25519:4be1…"
}
Campo Regla
hss DEBE ser 1.
issuer Slug en minúsculas ^[a-z0-9][a-z0-9-]{1,62}[a-z0-9]$. Estable durante toda la vida de la bitácora.
seq 0 para el primer evento; después, exactamente el seq anterior + 1.
prev null en seq 0; si no, el hash del evento seq - 1.
type ^[a-z][a-z0-9_]*(\.[a-z][a-z0-9_]*)+$. Los tipos de abajo están reservados.
case OPCIONAL, hasta 128 caracteres. Agrupa los eventos de un trámite.
ts Cuándo afirma la institución que ocurrió el acto. No es de confianza; el ancla de Bitcoin lo acota por arriba.
public Objeto JSON, publicado tal cual. Nunca ponga datos personales aquí.
docs Arreglo de referencias a documentos (puede estar vacío).
actor Id de la llave que firma.

El hash del evento es SHA-256(canonical(event)); la firma no forma parte del evento. Un evento serializado NO DEBE superar 64 KiB, y con hss: 1 se rechazan los campos de primer nivel desconocidos.

{ "event": { … }, "sig": { "kind": "passkey" | "ed25519", … } }
  • ed25519 (de sistema a sistema): sig.signature es la firma sobre los 32 bytes crudos del hash del evento.
  • passkey (personas): una aserción WebAuthn (authenticatorData, clientDataJSON, signature) producida con challenge = event_hash, verificada como lo describe el Receipt Format.

Las llaves viven en la propia bitácora de la institución; no hay un registro de llaves aparte.

{ "id": "…", "kind": "passkey" | "ed25519", "alg": -7 | -257 | -8,
"publicKey": "<SPKI DER, base64url>",
"role": "admin" | "official" | "system" | "session",
"label": "Ana López — Building inspector",
"rpId": "app.hardstate.net",
"scope": { "types": ["case.*", "fee.paid"], "expires": "2026-10-20T20:00:00Z" } }
  • Llaves de acceso (passkeys): id es el id de la credencial WebAuthn (base64url); rpId es OBLIGATORIO; alg es -7 (ES256) o -257 (RS256).
  • Llaves Ed25519: alg DEBE ser -8; id es "ed25519:" + hex(SHA-256(spki))[0:32].
  • scope.types: tipos exactos o un comodín al final ("case.*"); NO DEBE otorgar tipos de sistema. scope.expires: el último event.ts que la llave puede firmar.
  • Roles: admin y official son personas; system es un proceso sin persona y DEBE llevar scope.types; las llaves session solo existen mediante session.open. Las llaves system y session NO DEBEN firmar issuer.*, key.* ni session.open.
Tipo Qué hace Lo firma
issuer.create seq 0. Declara public.name, opcionalmente jurisdiction / location / website, y public.key (la llave del administrador fundador). la llave que declara
key.add Agrega una llave en public.key. un admin activo
key.revoke Revoca public.keyId. NO DEBE revocarse al último administrador activo. un admin activo
issuer.update Incorpora cambios al perfil de la institución. un admin activo
session.open Declara una llave de sesión en public.key; scope.expires ≤ 30 días. un admin u official activo
session.close Cierra la sesión indicada en public.keyId. quien la abrió, la propia sesión o un admin

Cualquier otro tipo de evento es vocabulario propio de la institución (domain.action).

Un vocabulario recomendado, no un cambio de protocolo: ai es un dominio de la institución como cualquier otro. El sistema de IA firma con una llave system con alcance ai.decision, ai.run y ai.heartbeat; una persona firma la revisión (nunca la llave del sistema). El contenido solo aparece como compromisos con sal en docs.

Tipo Lo firma public
ai.decision el sistema de IA system, model, version, config?, outcome, oversight (required | none), score?, explanation?
ai.run el sistema de IA system, model, version, steps, root (un solo sello sobre los pasos de la ejecución), outcome?
ai.review una persona decision (hash del evento), action (confirm | override | reject), outcome?
ai.heartbeat el sistema de IA every (segundos), decisions, runs, failures, since (seq del latido anterior), instance, digest

Vea Decisiones de IA para registrarlas por HTTP y para qué sirve cada campo.

commitment = SHA-256("hardstate/doc/v1" ‖ salt ‖ SHA-256(file)) salt: 32 random bytes

Publicar un documento revela su salt y su SHA-256(file) y deja disponibles los bytes. Los comprobantes llevan las sales en el fragmento de la URL (/r/<event_hash>#k=<commitment[0:16]>.<salt>,…), que los navegadores nunca envían a un servidor.

Capa Dato
Lotes Árbol de Merkle RFC 9162 (CT v2); datos de hoja 0x01 ‖ event_hash (eventos) o 0x02 ‖ digest (sellos), intervalo de referencia de 10 minutos.
OpenTimestamps Cada raíz de lote → ≥ 2 calendarios públicos; un .ots separado estándar (ots verify -d <root> <file>.ots).
HardState Anchor OP_RETURN PUSH36("HSS" ‖ 0x01 ‖ root), script 6a 24 48 53 53 01 <32 bytes>. Los datos de hoja del árbol del ancla son 0x03 ‖ batch_root.

Las anclas en signet se identifican como de prueba y nunca cuentan como prueba en Bitcoin.

URL base https://api.hardstate.net (http://localhost:8787 en local). Las lecturas son abiertas y sin llave. Escribir no requiere API key: un evento solo se acepta si extiende la bitácora de su institución y lo firma una llave autorizada.

Cada endpoint, con sus parámetros, respuestas y ejemplos de código, está en la referencia de la API HTTP (en inglés), generada a partir del contrato OpenAPI que sigue la propia API.

Código Significado
201 Agregado: { hash, issuer, seq, status: "queued", proof, receipt }.
404 La institución no existe y el evento no es issuer.create.
409 La cabeza de la bitácora se movió: { error, head }. Rehágalo sobre la cabeza que devuelve y vuelva a firmar.
422 Falló la comprobación de forma, cadena, autorización o firma.
429 Límite de peticiones excedido.

HardState es una empresa de Zevlat Intelligence. © 2026 Zevlat Intelligence.