DeltaSync — Efficient Data Sync Library for WoW Addons

For addon developers. DeltaSync is a LibStub library that handles the hard parts of keeping guild-member data in sync — version comparison, delta compression, peer-to-peer catch-up, and message integrity — so you can focus on your addon's actual features instead of writing another sync engine from scratch.

It's the same sync stack that powers TOGBankClassic and TOGProfessionMaster, extracted into a reusable library you can embed in a few lines.

Why Use This

If your addon shares data across guild members — inventories, crafting recipes, raid rosters, settings — you've probably run into some combination of:

Full re-sends every time anything changes, hammering the guild channel
CRC errors under load when several addons compete for chat throttle slots
New members joining and having no idea who to ask for a data catch-up
Home-rolled hashing that disagrees on tables because Lua iteration order is unstable
One slow peer freezing everyone else because there's no timeout on expected data

DeltaSync solves all of these. Drop it in, wire up a handful of callbacks, and you get battle-tested sync behavior that's been running in production on live Classic Era guilds.

What You Get

Bandwidth-efficient sync

Instead of re-sending everything whenever something changes, DeltaSync computes and transmits only the differences between states. In practice this cuts sync traffic by 90-99% for incremental updates. Full sync is always available as a fallback for new members or major changes.

Peer-to-peer catch-up

When a player logs in missing data, DeltaSync broadcasts a summary of what they have and lets any peer with fresher data step up. No single "banker" bottleneck, no manual request dance. If the first peer is busy, it politely declines and the next best peer takes over automatically.

Message integrity you can trust

Every structured message is wrapped with a checksum and a stop-marker. On the receive side, truncation and corruption are detected separately — so if a message got mangled mid-flight, you find out instead of silently applying garbage. Corrupt messages are logged with diagnostic info, not quietly dropped.

A fair share of your addon-message budget

WoW caps each addon at 16 communication prefixes. DeltaSync uses 7 of yours (one per channel type), leaving 9 for your own use. Prefixes are auto-derived from your addon's name so you don't have to pick unique strings yourself.

Guild roster tracking as a companion library

DeltaSync ships with GuildCache-1.0, a small companion library that tracks who's in your guild and who's online. It's a separate LibStub library (so other addons can use it without pulling in the full sync stack) embedded under Libs/GuildCache-1.0/. DeltaSync uses it to avoid whispering offline members and to default its peer-eligibility check — but it's a soft dependency, so if you don't need it you can drop it and DeltaSync falls back to reasonable defaults.

Dependencies

Ace3 (required) — provides LibStub, AceComm, AceSerializer
AceCommQueue-1.0 (required) — serializes outgoing messages so chunked payloads don't interleave and corrupt each other. Your host addon embeds this alongside Ace3.

Both are declared as hard Dependencies: in the TOC, so WoW loads them before DeltaSync.

Quick Start

Basic setup

-- In your addon's OnInitialize:
local AceAddon     = LibStub("AceAddon-3.0")
local AceCommQueue = LibStub("AceCommQueue-1.0")
local DeltaSync    = LibStub("DeltaSync-1.0")

-- 1. Make sure your AceAddon instance has AceComm and AceCommQueue
local MyAddon = AceAddon:NewAddon("MyAddon", "AceComm-3.0")
AceCommQueue:Embed(MyAddon)

-- 2. Hand your AceAddon handle to DeltaSync
DeltaSync:Initialize({
    namespace = "MyAddon",
    aceAddon  = MyAddon,   -- REQUIRED — DeltaSync sends through your addon
    onDataReceived = function(sender, data)
        -- apply received data or delta
    end,
    onDataRequest = function(sender, baseline)
        -- peer asked for data; call DeltaSync:SendData(sender, myData)
    end,
})

Sending and receiving

-- Announce your current state to the guild
DeltaSync:BroadcastVersion(myVersion, myHash)

-- Respond to a data request
DeltaSync:SendData(sender, myData,  false)   -- full sync
DeltaSync:SendData(sender, myDelta, true)    -- delta sync

Peer-to-peer catch-up

DeltaSync:InitP2P({
    getMyHashes     = function()        return myItemHashes           end,
    hasContent      = function(key)     return myData[key] ~= nil     end,
    hasMissingItems = function()        return nextMissingItem ~= nil end,
    onSyncAccepted  = function(key, sender)
        DeltaSync:RequestData(sender, myBaseline)
    end,
})

DeltaSync:BroadcastItemHashes(myItemHashes)

Who Should Use This

Addons that sync structured data (inventories, rosters, recipes, settings) across guild members
Addons where incremental updates are common and full re-syncs are wasteful
Addons that want new members to catch up from any peer, not just a single broadcaster
Addons that want CRC-level message integrity without writing it themselves

What You Don't Have to Write

AceComm prefix registration and routing
A wire format that survives partial delivery and chat-throttle chunk interleaving
A P2P collect/offer/dispatch pipeline with timeouts and busy fallback
Stable content hashing for Lua tables (iteration order is not your friend)
An online-member cache that handles connected-realm name suffixes correctly

Recent Updates

v2.0.0 (Current) — Major release folding in the matured sync engine from TOGProfessionMaster and splitting the guild-roster cache into its own companion library.

GuildCache extracted into GuildCache-1.0 — Roster and name-normalization methods moved from the DeltaSync handle to their own LibStub library at Libs/GuildCache-1.0/. Other addons can now embed just GuildCache without the full sync stack. This is a breaking change: calls like DeltaSync:NormalizeName(x) become LibStub("GuildCache-1.0"):NormalizeName(x).
aceAddon is now a required Initialize() config key — DeltaSync routes sends through your AceAddon's SendCommMessage instead of embedding AceComm into itself. This keeps throttling and CRC protection wrapping the correct send path. Existing consumers need a one-line addition: pass your AceAddon:NewAddon(...) handle as config.aceAddon.
AceCommQueue moved from library-side to host-side — Your addon embeds AceCommQueue into its own AceAddon handle now. One line: LibStub("AceCommQueue-1.0"):Embed(MyAddon).
Cross-realm name normalization fixed — Connected-realm peers whose name arrives with a foreign realm suffix are no longer silently rewritten to the local realm. Their per-realm data stays separate where it should.
New debug APIs — lib:DebugStatus() prints a diagnostic block showing namespace, library revision, registered prefixes, and wiring state. Useful when sends are silently dropping and you need to confirm which config key is missing.

v1.0.0 — First stable release. P2P session hardening, integrity checks on every channel, and a whisper-online guard so offline members stop eating send slots.

DELIVERY_TIMEOUT added so a peer that accepts a sync-request and then goes silent no longer pins an inbound session slot forever
All seven channel types (not just DATA) now use the CRC + stop-marker wire format
Whisper sends now skip guild members the roster knows are offline
Several P2P state-machine edge cases fixed where late messages could mutate unrelated sessions

v0.0.3-alpha — GuildCache's first appearance as a module inside DeltaSync (later promoted to its own library in v2.0.0), plus a custom peer-eligibility callback.

v0.0.2-alpha — Switched to AceSerializer-3.0, added the OFFER and HANDSHAKE channels that make peer-to-peer catch-up work, and introduced the checksum wire format.

v0.0.1-alpha — Initial extraction from TOGBankClassic.

Bug Reports & Feedback

Found a bug or have a suggestion? Reach out on Discord.

Credits

Pimptasty — Author

Special Thanks:

The Old Gods guild community for real-world testing via TOGBankClassic and TOGProfessionMaster
Ace3 library maintainers for the excellent framework
AceCommQueue-1.0 for solving the chunk-interleave CRC problem

License

DeltaSync is open-source software. See the LICENSE file for details.