Contract

Contract wb1!

Law for addon Lua and web D1. Any field change bumps version and requires web importer update same day.

Format

wb1! + base64url( raw-deflate( json ) )

No newline, single line. WoW EditBox is large but avoids whitespace.

• wb0! Camp DNA share URL, existing
• wb1! Inventory and lockouts, this repo v1
• wb2! Reserved

One envelope for 1 and 20 characters so decoder has no branch.

Envelope v1

{
  "v":1,
  "addon":"1.0.0",
  "exportedAt":1724001234,
  "gameVersion":"12.1.0",
  "interface":120100,
  "bundle":{"count":3,"freshestSeenAt":1724001200,"oldestSeenAt":1723980000},
  "characters":[ ... ]
}

Character fields: guid, name, realm slug, faction, class, level, gold, bags[], bank[], reagentBank, Warband bank root, mail, auctions, currencies[], professions[], cooldowns[], instances[], bosses killed boolean in encounter order plus name, world bosses[], keystone{}, runs[], score, weekly Vault map, consumables rolled up phial/potion/food/rune, seenAt stamps.

All _at times are Unix seconds UTC from time(), not milliseconds. Null if never seen. Web converts.

• Bank never opened: free=null, items=[] -> unknown versus empty. UI prints "Not opened" not "0 free".
• Warband bank seenByGuid -> web "by Vocnar" credit line. Payload root plus own D1 table avoids repeating 5 tabs across 6 characters (about 22 KB saved, deflate 32 KB window cannot fold copies).
• currencies.maxQuantity 0 = no cap, weeklyMax 0 = not weekly-capped.
• Consumables derived cache for Tonight Plan speed. Absent = unknown not zero (prevents hard block on 0 Phials when we did not look).
• Items inventory only, no equips (API has it). Link optional.

Implementation Gotchas Fixed In Code

1. Not LibDeflate:EncodeForPrint. That uses own 6-bit alphabet neither Base64 nor Base64url, swap +/ for -_ cannot make it atob readable. Addon carries real RFC 4648 Section 5 encoder.
2. Raw deflate not zlib. CompressDeflate emits bare stream no header, DecompressionStream('deflate') rejects. Must use 'deflate-raw' or pako.inflateRaw.

Caps

• 20 characters (DoS protection)
• 1 MB decoded not 25 KB. Measured: 1 full 39 KB JSON 8.6 KB wire, 6 154 KB / 26 KB, 20 474 KB / 73 KB. Enforced chunk-by-chunk during inflate not after (bomb mitigation).
• Validated v==1, array 1..20, each guid + name + seenAt.lastSeen.

Wire: LibDeflate level 9 -> base64url strip = -> prefix.

Absent Versus Empty

• Section absent -> never seen -> unknown -> grey, not delete
• Character missing from bundle -> not gone -> old snapshot aging red
• Consumables absent until ID table filled -> absent not zero

Vectors

• docs/contract/vectors/v1-min.json
• v1-min.wb1
• Planned v1-full.json, v1-6.json plus CI check-contract-vectors

Warbank Split

Root plus warband_bank_cache one row per user. Each character seenAt.warbank for dots. seenByName credit line.

Versioning

Single wb1! version strict. Any field change bumps prefix and breaks paste if sides disagree. Web checks prefix first.

Spec lives in addon repo, enforced in app warband-import.ts.