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.
Codificación
Sección titulada «Codificación»| 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.
Evento firmado
Sección titulada «Evento firmado»{ "event": { … }, "sig": { "kind": "passkey" | "ed25519", … } }ed25519(de sistema a sistema):sig.signaturees la firma sobre los 32 bytes crudos del hash del evento.passkey(personas): una aserción WebAuthn (authenticatorData,clientDataJSON,signature) producida conchallenge = 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):
ides el id de la credencial WebAuthn (base64url);rpIdes OBLIGATORIO;alges-7(ES256) o-257(RS256). - Llaves Ed25519:
algDEBE ser-8;ides"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 últimoevent.tsque la llave puede firmar.- Roles:
adminyofficialson personas;systemes un proceso sin persona y DEBE llevarscope.types; las llavessessionsolo existen mediantesession.open. Las llavessystemysessionNO DEBEN firmarissuer.*,key.*nisession.open.
Tipos de evento de sistema reservados
Sección titulada «Tipos de evento de sistema reservados»| 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).
Registros de IA
Sección titulada «Registros de IA»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.
Documentos
Sección titulada «Documentos»commitment = SHA-256("hardstate/doc/v1" ‖ salt ‖ SHA-256(file)) salt: 32 random bytesPublicar 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.
Anclaje
Sección titulada «Anclaje»| 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.
API HTTP
Sección titulada «API HTTP»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ódigos de estado de POST /v1/events
Sección titulada «Códigos de estado de POST /v1/events»| 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.