Recording

This is the contract between the four parts of Polestar's recording program, and the public statement of what it collects. Everything here is open source in this repository.

What is never collected#

Character names, realm names, account names, chat, whispers, guild, friends, other players' names, mail, auction or trade data, the player's typed text other than /psrec mark notes and /psrec trail labels, and anything from outside the game folder. Quest and gossip text has the player's name replaced with $N (and race and class with $R, $C) in the addon, and again in Polestar Client.

SavedVariables (PolestarRecorderDB, per account)#

PolestarRecorderDB = {
	schema = 2,
	enabled = true,            -- recording on (/psrec on, or Polestar Client's share flag); nothing is written while false
	optout = true,             -- only after /psrec off: the client's share flag does not turn recording on; /psrec on clears it
	install = "k3j9x0q2m7ab",  -- 12 random base-36 characters, made once per WoW account folder
	seq = 41,                  -- last chunk number used
	acked = 37,                -- highest chunk Polestar Client confirmed (from Ack.lua), kept for display
	chunks = { [38] = "...", [39] = "...", [40] = "...", [41] = "..." },
	maps = { [1429] = "1429\t3\t1415\t0\t-7939.6\t1535.4\t-10135.2\t-2141.6", ... }, -- see `map` record
}

Per character (PolestarRecorderCharDB, SavedVariablesPerCharacter): { id = "<10 random base-36 characters>", textSeen = { [questID] = true } }. The character id lets records from one character be followed across sessions without its name.

Chunks#

• A chunk is one Lua string: records separated by \n. A record is fields separated by \t. The first field is the record kind, the second dt.
• The first record of every chunk is chunk, which sets the clock: chunk <dt=0> <seq> <serverEpoch> <charId>. Every later dt is tenths of a second since that epoch (integer).
• A chunk closes after 5 minutes or 16 KiB, at logout, and on a character change. It is written into chunks[seq] when it closes and refreshed every 60 seconds out of combat (so a /reload or crash loses at most a minute). The open chunk is always the highest seq.
• The addon keeps at most 4 MiB of chunks; the oldest unacknowledged ones go first and a dropped record counts them.
• At login the addon deletes every chunk with seq <= PolestarRecorderAck[PolestarRecorderDB.install].

Ack file (written by Polestar Client)#

Interface/AddOns/Polestar_Recorder/Ack.lua, loaded first by the TOC. One entry per install, because several WoW accounts share one AddOns folder, then whether the player shares:

PolestarRecorderAck = { ["k3j9x0q2m7ab"] = 37 }
PolestarRecorderShare = true

The release zip ships it as PolestarRecorderAck = nil with no share flag; Polestar Client merges its entry into whatever the file holds. A lost ack only means a chunk is uploaded twice; the server ignores a repeated (install, seq).

PolestarRecorderShare is written only once the player has turned sharing on in Polestar Client at least once (before that the file has no flag, so a /psrec on of someone who never opted in is left alone). From then on it is true while sharing is on and uploads are not paused, false otherwise; the client writes it whenever that changes and with every ack. At login the Recorder reads it: true turns recording on (saying so once in chat) unless optout is set, false turns it off (without setting optout), and no flag leaves enabled as the player set it. So one opt-in, Start sharing in the client, is enough; /psrec off stays the player's last word until /psrec on.

Field encoding#

• Integers in decimal. Empty field = unknown or not applicable.
• P = three fields map x y: C_Map uiMapID and the player's position in hundredths of a percent (integers 0–10000, about 0.3 yd on a zone). Empty when the client gives no position (instances).
• Lists inside a field: items separated by ;, parts of an item by : (12345:2;6789:1).
• Text fields (titles, names, objective text, notes) have \t, \n, ; and : replaced with spaces only where the field is a list; free text fields only lose \t and \n. Text is in the client's language (session.locale). At most 4,000 bytes per text field, and no control characters. Quest titles (text), objectives (objectives) and zone names (zone) also have no | (the game's escape character) and at most 255 characters (100 for zone names); a record that breaks this makes its chunk invalid.
• npcKind: c creature, o game object, i item, p player (never stored beyond the kind), empty unknown.
• Unknown record kinds are skipped by readers (forward compatible). A known kind with a malformed or extra field makes the whole chunk invalid; missing trailing optional fields read as empty (the addon always writes them all).

Record kinds#

Context

Upload API (https://data.polestar.guide/v1)#

The server is reachable only through a Cloudflare Tunnel: it opens no ports and its address never appears in DNS.

Polestar Client registers once: it asks for a challenge, spends a few seconds of CPU on a proof of work, and receives a token, which it keeps on the PC. The server stores only the token's SHA-256, and calls it the contributor. Each network (an IPv4 address or an IPv6 /48) can register at most 3 times a UTC day (and one IPv6 /32 at most 20 times), and every registration from one network on one day shares a random cohort id. The server keeps only a keyed hash of the network, with a salt made for that day, and deletes both when the day ends.

Trust#

Everything here is open source and anyone can edit their own file or write their own client, so nothing trusts a single upload.