@spec anchor_commitment(record_b64 :: String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

The fixed-size commitment over the record's checkpoint head — the value an operator publishes to (and re-fetches from) the external medium.

Medium- and locator-independent: the same head yields the same commitment regardless of where it is anchored. Returns {:ok, commitment_b64} or {:error, reason}. Runs on a dirty CPU scheduler.

@spec parse_record(record_b64 :: String.t()) ::
  {:ok, anchor_record()} | {:error, String.t()}

Parse a canonical anchor record into a anchor_record/0 map. Validates the layout, format version, algorithm tag, medium grammar, and non-empty origin/locator. Returns {:ok, record} or {:error, reason}.

@spec record_canonical_bytes(
  origin :: String.t(),
  size :: non_neg_integer(),
  root_b64 :: String.t(),
  medium :: String.t(),
  locator_b64 :: String.t(),
  commitment_alg :: String.t()
) :: {:ok, String.t()} | {:error, String.t()}

Build the canonical bytes of an anchor attestation record from an explicit checkpoint head.

medium is a printable-ASCII identifier (no whitespace/control bytes, / allowed for hierarchy, e.g. "ethereum/mainnet"); locator_b64 is the opaque external-commitment handle (tx id, block height, receipt, object key); commitment_alg is a safe-menu tag ("sha3_512", the v0.1 default and only entry). Returns {:ok, record_b64} or {:error, reason}.

@spec rfc6962_leaf_hash(record_b64 :: String.t()) ::
  {:ok, String.t()} | {:error, String.t()}

The RFC 6962 Merkle leaf hash of the record's canonical bytes, so an operator may also log its attestations as Layer-0 leaves. Returns {:ok, hash_b64} or {:error, reason}. Dirty CPU.

@spec verify_anchored(
  note_text :: String.t(),
  vkeys :: [String.t()],
  record_b64 :: String.t(),
  opts :: keyword()
) :: :ok | {:error, String.t()}

Verify an anchored checkpoint.

Checks that record_b64 binds the checkpoint carried by note_text (verified against the trusted vkeys), and — when a previous anchored checkpoint is supplied — that the newer checkpoint is an append-only extension of it.

This is the log-side audit of "the operator never equivocated between anchored heads": it trusts neither the operator nor the medium. Pair it with verify_commitment/2 (the medium-side check) for the full guarantee. Runs on a dirty CPU scheduler.

Options

• :prev_note — a previously-anchored checkpoint signed note. When given, consistency from it to note_text is verified.
• :consistency_proof — a list of base64 RFC 9162 consistency-proof hashes from :prev_note to note_text (each 32 bytes). Required (and only used) when :prev_note is set.

With no :prev_note, only the attestation-binds-checkpoint check runs.

Returns :ok on success or {:error, reason} (a failed binding/consistency check or malformed input).

Examples

# binding-only
:ok = MetamorphicLog.Anchor.verify_anchored(note, [vkey], record)

# binding + consistency from a previous anchored head
:ok =
  MetamorphicLog.Anchor.verify_anchored(newer_note, [vkey], record,
    prev_note: older_note,
    consistency_proof: proof_b64
  )

@spec verify_commitment(
  record_b64 :: String.t(),
  fetched_commitment_b64 :: String.t()
) ::
  :ok | {:error, :commitment_mismatch | String.t()}

Medium-side check: the bytes fetched_commitment_b64 retrieved from the external medium equal the commitment recomputed from record_b64's checkpoint head.

On :ok the medium genuinely attests to this checkpoint head. This is the counterpart to verify_anchored/4: together they prove the head was anchored and the operator never equivocated between anchored heads. The fetch itself is your operator's job (this library performs no I/O).

Returns :ok, {:error, :commitment_mismatch}, or {:error, reason} if the record is malformed.