14 Protocol API Specification

14 — Protocol / API Specification

Content type: interface design, pre-implementation. Illustrative shapes, not a frozen contract — field names and error codes will change during actual implementation.

14.1 Endpoints (registry node, illustrative)

POST /v1/commitments
  body: CommitmentRecord (signed)
  201 -> { commitment_id, public_url }
  400 -> { error: "invalid_signature" | "malformed_record" }

POST /v1/commitments/{id}/proof-of-life
  body: { signature, timestamp }
  200 -> { state: "ACTIVE", next_deadline_reminder: <timestamp> }
  409 -> { error: "already_triggered" }

POST /v1/commitments/{id}/extend
  body: { new_deadline, justification?, signature }
  200 -> { state: "EXTENDED", new_deadline }
  400 -> { error: "deadline_not_monotonic" }

POST /v1/commitments/{id}/fulfill
  body: { publication_ref, signature }
  200 -> { state: "FULFILLED" }

GET /v1/commitments/{id}
  200 -> CommitmentRecord + current state + full public event log

POST /v1/commitments/{id}/deposit
  body: { encrypted_payload_share, signature }
  # deposits/updates the researcher's own share of release_payload
  200 -> { accepted: true }

14.2 Node-to-node coordination (illustrative, unresolved per Page 10.5)

POST /v1/internal/trigger-proposal
  body: { commitment_id, proposing_node, evaluated_deadline, node_signature }
  # nodes exchange these to reach quorum on whether a deadline has passed

POST /v1/internal/reconstruction-contribution
  body: { commitment_id, node_id, share, node_signature }
  # exchanged only after quorum agreement on trigger

14.3 Error handling philosophy

Consistent with the "fail toward disclosure, not secrecy" principle (Page 05.2): ambiguous or malformed requests should fail loudly and publicly (logged to the public commitment log as a rejected/malformed event) rather than silently. A researcher should never be able to claim "I tried to send a proof-of-life and it silently failed" without that attempt being independently verifiable in the public record, one way or the other.

14.4 Versioning note

No implementation exists yet. This specification should be treated as version 0.0.1-draft and revised heavily once the federation model (Page 12) and trigger-consensus mechanism (Page 10.5) are actually resolved — those decisions will change several of the shapes above, particularly the internal node-coordination endpoints.