The Open Location Network
Kafumu's local messages are part of an open network anyone can read from, write to and run a node of. Here's how it works and how to connect.
What it is
The Open Location Network is a way to leave short public messages at a place without
accounts, servers you must trust, or location tracking. A message is plain text plus hashtags. The place is a
hashtag too: #geo followed by the first six characters of the area's
plus code (about 5 km across), e.g. #geo8ccgmw.
Anyone can store, index and pass these messages on; a node is just something that does that.
Instead of an account, every message carries a small proof of work: the sender's device tries numbers until the message's Argon2id hash starts with enough zero bits. Argon2id is memory-hard, so a graphics card gains little over a phone. One message costs a phone about a second; a thousand cost a spammer real time, and every one has to be aimed at a real place. More work buys a longer life: a message lives one hour at the required work and twice as long for every extra bit (up to a week). When an area gets busy, the required work goes up a little, so floods price themselves out.
The proof of concept
OLN started as eolnpoc, a small Go proof of concept from long before Kafumu, and Kafumu speaks its format exactly, so messages move between the two unchanged. Kafumu is one OLN node: its local messages, questions, answers and reactions are all OLN messages.
The message format
v2;nonce;YYYYMMDDhhmmss;base64url(text);#geo8ccgmw #langeng #coffee
- v2: the format version (v2 = Argon2id work).
- nonce: the number the sender searched for.
- date: when it was made, in UTC; nodes accept a ±10 minute clock difference.
- text: the message, UTF-8, base64url without padding.
- keywords: space-separated hashtags; one
#geo…cell. Kafumu also uses#lang<iso639-3>,#askfor questions and#re<10 hex>for answers and reactions (the first ten hex of the message id it answers). A reaction needs no place:#re…alone says what it's about. A line about a subject for everyone into it, wherever they are, needs none either:#esperantowithout a#geo.#feedwith a link in the text adds a news or calendar source to its area; this node only takes those posted under a name by an account with a passkey, at most 20 live each. A source doesn't expire like a message: each time this node reads its feed well it stays another 90 days, so a working source lasts; one that can't be read for 90 days goes (it is also kept another week when it is among the ten sources of its area people reacted to most that week, and posting it again renews it). This node also keeps a line while something live refers to it: a#reanswer that outlives it extends it, so a chain lives as long as its newest link (🔁 on a line does exactly that).#wd<16 hex>is a way to take a line back: the first 16 hex of SHA-256 of a secret only the sending device keeps; showing that secret (POST /api/oln/withdraw?id=…&secret=…) hides the line here.
The work is the number of leading zero bits of Argon2id(line) with salt OLN-v2-proofwork,
1 pass, 4 MiB of memory, 1 lane and a 32-byte output. Kafumu asks 4 bits at the base (16 tries) and a little more
when an area is busy. The message id is the hex SHA-1 of the line. What a node accepts, keeps or drops is up to
that node: OLN fixes the format, not the policy.
Reading: GET /oln.json
Live messages of a cell and its neighbours, in eolnpoc's olnjson format (server info, messages by id,
a tag index, and where to push):
curl 'https://kafumu.com/oln.json?cell=8ccgmw'
Answers and reactions to messages, wherever they were posted (up to 20 ids):
curl 'https://kafumu.com/api/oln/re?ids=54cecdf267'
Lines without a place about subjects (up to 8):
curl 'https://kafumu.com/api/oln/general?tags=esperanto'
Writing: POST /api/oln
First ask how much work the cell currently wants, then mine and post the raw line:
curl 'https://kafumu.com/api/oln/required?cell=8ccgmw' # {"bits": 12}
curl 'https://kafumu.com/api/oln/required?re=54cecdf267' # a reaction: priced by what it answers
curl -X POST --data-binary 'v2;nonce;20261004183000;SGVsbG8;#geo8ccgmw' https://kafumu.com/api/oln
Answers: 200 with the stored message (and its expiry), 402 when the work is too low
(mine more bits), 400 for a malformed line, a clock off by more than ten minutes, or no place and
nothing to be about (no #geo cell, no #re, no subject).
Mining in JavaScript with hash-wasm's Argon2id:
// Argon2id → leading zero bits; try nonces until there are enough.
const salt = new TextEncoder().encode("OLN-v2-proofwork");
async function mine(text, keywords, bits) {
const date = new Date().toISOString().replace(/[-:T]/g, "").slice(0, 14);
const b64 = btoa(String.fromCharCode(...new TextEncoder().encode(text)))
.replace(/\+/g, "-").replace(/\//g, "_").replace(/=+$/, "");
for (let n = 0; ; n++) {
const line = `v2;${n};${date};${b64};${keywords}`;
const h = await hashwasm.argon2id({ password: line, salt, parallelism: 1, iterations: 1,
memorySize: 4096, hashLength: 32, outputType: "binary" });
let z = 0; for (const b of h) { if (b === 0) { z += 8; continue; } z += Math.clz32(b) - 24; break; }
if (z >= bits) return line;
}
}
Questions by subject: GET /api/asks
Live questions (#ask) about any of the given subjects, from anywhere; filter by distance yourself:
curl 'https://kafumu.com/api/asks?tags=opensource,esperanto'
Run your own node
Store messages you receive, serve them as oln.json, accept posts with enough work, and pull from or
push to other nodes (Kafumu lists /api/oln as its push address). The source of Kafumu is
open, and so is eolnpoc.