Skip to content

Protocol

A protocol is a JSON object that states, before a run, what will be checked and when the result counts as a pass.

Protocolith requires only two keys:

Key Rule
protocol_id Letters, digits, ., _, -; starts with a letter or digit; at most 128 characters.
version Letters, digits, ., _, -, +; starts with a letter or digit; at most 64 characters.

Everything else is up to you: the question, the data source, the gate, the metric, how missing data is handled. Protocolith does not interpret those keys and does not judge whether the protocol is a good one. What it guarantees is that the protocol that was frozen cannot be changed without leaving a trace.

What belongs in a protocol

Things you would be tempted to adjust after seeing the result:

  • the source and the period or sample it covers;
  • the metric and the exact gate (threshold, comparison);
  • the baseline or control;
  • what counts as a blocked source or insufficient coverage;
  • the claim boundary you intend to publish.

Identity

A protocol is identified by protocol_sha256, the SHA-256 of its canonical JSON bytes. Two files that differ only in whitespace or key order have the same hash. A record names the protocol by this hash, not by protocol_id and version.

Versions

A protocol version is frozen once. To change a protocol, freeze a new version with --supersedes OLD_HASH; see freeze. Old records keep pointing at the hash they were run under.

Constraints on content

Values are objects, arrays, strings, booleans, null and integers within +/- (2^53 - 1). Floats are not accepted; write decimals as strings ("0.001"). Nesting depth is at most 64. A whole ledger line, including the protocol, is at most 1,048,576 bytes.