A kolo-log log belongs to one owner, the key that writes it. Entries are only ever added at the end. Nobody, not even the owner, can change or reorder an entry without the change showing.
Signed and append-only
Appending an entry
Entries are not chained to each other by hashes. The Merkle tree links them, and each signed head covers every entry before it.
- Append makes a fresh 32-byte entry key. The value is padded and sealed with XChaCha20-Poly1305.
- The record holds the index, the size, a hash of the ciphertext and a commitment to the key. The owner signs it.
- The leaf is the BLAKE2b-256 hash of 0x00 and the signed record. It joins the tree on the right.
- Each node above is the hash of 0x01 and its two children, up to a new root.
- The owner signs a new head: the log, the size and the root. Entry, key and head are stored in one commit.
- Each entry gets a record signed by the owner. The leaves of a Merkle tree are the hashes of those signed records, as in RFC 9162 with BLAKE2b-256.
- The owner signs the tree head: the size of the log and the root hash.
- An inclusion proof shows that an entry is in a signed head. A consistency proof shows that a newer head only added entries to an older one.
A reader needs two things it already trusts: the owner's public key and the 32-byte log ID. Heads, records, proofs and entries can come from any peer, because the reader checks every one of them against those two values.
Encrypted entries
Each entry is encrypted with its own random key (XChaCha20-Poly1305). A peer that holds the record and the ciphertext but not the key can store the entry, serve it to others and check its proofs, without reading it. Who gets the keys is up to the application; kolo-sync asks it for each peer.
Delete markers
Deleting an entry
Deletion removes the content, not the entry: the record stays, so every head and proof still checks out.
- Entry 2 is stored as its signed record, its ciphertext and its entry key.
- Delete makes a delete marker: the log, the index and the leaf hash, signed by the owner.
- The ciphertext and the key are dropped; the record and the marker stay. The tree and the head do not change.
- A replica checks the marker, then drops its own copy of that ciphertext and key. Reading the entry gives ErrDeleted.
- A copy made before, or a key someone kept, is out of reach. Deletion is best effort.
The owner deletes an entry by destroying its key and signing a delete marker for it. The signed record stays, so every proof still holds, but nobody who follows the protocol can read the entry any more. Deletion explains what this promises and what it does not.
One writer
A log has exactly one writer. There is no shared, multi-writer log: an app with several devices or several people uses one log per device or person, and each peer keeps read-only copies of the others' logs, called replicas. kolo-kv builds a key-value store on one such log.
Where a log lives
A kololog.Log keeps only its tree hashes and a compact copy of each record
in memory. Its ciphertexts, keys and delete markers live in a Storage:
NewMemory keeps them in memory, and
kolo-store keeps them on disk, with each change
written as one atomic, synced batch. Every change is one commit to the
storage, made before the change is shown, and a failed commit leaves the log
exactly as it was. A storage belongs to one log.