Sign in

Developers / Record format

Record format, version 1

An osmarks record says: these two parties each counted this, on their own side, and confirmed it on this date. This page describes how that statement is built, so anyone can check it, and anyone can build a compatible tool.

1. What a record is

A record covers one period (usually a month) of one engagement between a provider (the agency or freelancer doing the work) and a client. It holds the counts each side reported for each agreed measure, for example meetings held or qualified leads, and which side confirmed.

2. Counting without sharing contacts

Each side turns every counted item (a prospect's work email, a company domain) into a fingerprint: HMAC-SHA-256 with a key only the two parties hold, over a normalised identifier. osmarks receives fingerprints and counts, never the identifiers, and can't reverse them because it never has the key. Matching the two sides' fingerprints shows how many items both counted. Normalisation rules and code: fingerprint rules, fp.mjs.

3. Confirming

When a side confirms, the period's payload (a JSON string: engagement, period, measures, counts, matched counts, who confirmed) is hashed with SHA-256. That hash is appended to the public log with the previous entry's hash and the time, and the three are signed with the osmarks Ed25519 key. A month confirmed by one side only is still recorded, and says which side did not take part.

signed_message = mark_hash + "|" + prev_hash + "|" + log_time_ms
signature      = Ed25519(osmarks key, signed_message)   // base64url
mark_hash      = SHA-256(payload)                       // hex

4. Verifying

See check a record yourself. The log is copied daily to the Internet Archive, so a later change to any entry, by anyone including us, would be visible.

5. What a record never contains

  • Names, emails, phone numbers or meeting details of anyone contacted.
  • A score, rating or verdict.
  • The name of a party who hasn't chosen to be named.

6. Versioning

This is version 1. Changes that would break a verifier get a new version, and old records stay verifiable under the version they were signed with.