Skip to content

reverse-engineering-report.md

Latest commit

 

History

History
389 lines (276 loc) · 6.92 KB

reverse-engineering-report.md

File metadata and controls

389 lines (276 loc) · 6.92 KB
Raw

Quinfall auction protocol — structural notes

These are structural notes about the Quinfall in-game auction protocol, reconstructed from clean-room observation of publicly visible client/server traffic. They document message framing and field layout so the open implementation in pkg/messages/ is understandable to contributors. They do not include game source code, art, or insider material.

This document was originally a wire-verified report against specific client versions. Captured payload hex was redacted prior to publishing the open-source repository; the framing and field-layout descriptions remain.

1. Executive summary

This document describes the structure of the network protocol used by the Quinfall in-game auction system.

The structural notes were derived from:

• Controlled packet capture sessions
• UI‑to‑packet correlation
• Field value alignment (price, grade, enhancement, etc.)
• Structural repetition analysis
• TLV decoding
• Template identity extraction

Result:

✔ Full auction listing record decoded
✔ Message framing identified
✔ Transport encoding defined
✔ Filter semantics confirmed
✔ Template identity structure decoded
✔ Listing instance vs item template separated

The protocol is now readable and parsable from packet captures.

2. Network Architecture

Client maintains one persistent TCP connection to game server.

Client  ───── TCP Stream ─────►  Game Server

Server address: configured via the GAME_SERVER environment variable (host:port). The exact value is operator-specific and not hardcoded in the open-source repository.

All auction communication occurs inside this single stream.

3. Application Message Framing

TCP is treated as a byte stream.
Application adds its own framing.

+-------------------+
| uint32 length LE  |
+-------------------+
| message payload   |
+-------------------+

This repeats continuously.

TCP STREAM

[length][payload]
[length][payload]
[length][payload]
...

4. Payload Encoding — TLV System

Each message payload is composed of TLV records.

+--------+----------------+----------------+
| fid    | length (uint32)| value bytes    |
+--------+----------------+----------------+

Where:

Field Meaning
fid field identifier
length byte length
value raw data

This continues until payload end.

5. Message Types

5.1 Auction Search Request

Direction: Client → Server
Primary opcode: 353

Contains:

• subcategory code (ASCII numeric string)
• filter values
• sort mode
• page index

Example category mapping:

Code Category
99999 default
50006 Dual Dagger
50001 Sword
50009 Arcane Staff

5.2 Auction Result Response

Direction: Server → Client
Opcode: 371

Structure:

Header TLVs
ListingRecord[]
ListingRecord[]
ListingRecord[]
...

Each ListingRecord corresponds to one UI row.

6. Auction Listing Record Structure

Every listing is composed of exactly 6 TLV fields.

ListingRecord
├─ listing_id (unique)
├─ template_code (item identity)
├─ price
├─ quantity
├─ city_id
└─ tax_percent

7. Binary Layout Diagram

┌────────────────────────────────────────┐
│ fid=0 len=24 listing_id_hex           │
├────────────────────────────────────────┤
│ fid=0 len=21 template_code            │
├────────────────────────────────────────┤
│ fid=3 len=8  price_u64                │
├────────────────────────────────────────┤
│ fid=1 len=4  quantity                 │
├────────────────────────────────────────┤
│ fid=1 len=4  city_id                  │
├────────────────────────────────────────┤
│ fid=1 len=4  tax_percent              │
└────────────────────────────────────────┘

Repeated N times.

8. Template Code Structure

Example:

0_F014_000_50_290_999

Decoded fields:

Segment Meaning
50 enhancement ×10
290 grade
999 constant marker

Enhancement decoding:

enhancement = value / 10

Grade is literal.

9. Data Model (Logical)

Important architectural discovery:

Items exist at two layers.

ITEM TEMPLATE
  name
  icon
  base stats

LISTING INSTANCE
  price
  seller city
  tax
  grade roll
  enhancement

Template defines identity.
Listing defines market state.

10. Filter Semantics (Confirmed)

Filter Behaviour
Enhancement exact match
Level range min/max
Grade range min/max

Sorting:

Default = price ascending.

11. Rarity Model

Rarity is NOT transmitted explicitly.

Client derives rarity from:

(level, grade)

Each level band has grade thresholds.

Example level 100:

Grade Rarity
199‑239 blue
240‑287 purple
288+ legendary

12. Full Message Flow Diagram

USER SEARCHES ITEM

Client:
  opcode 353
  filters
  category

Server:
  opcode 371
  header
  listing records

Client UI:
  renders rows

13. Parser Architecture

Recommended decoding pipeline:

TCP capture
   ↓
frame extraction
   ↓
TLV decode
   ↓
opcode dispatch
   ↓
listing record extraction
   ↓
template decode
   ↓
CSV / DB storage

14. C‑Style Struct Representation

struct AuctionListingRecord {

    char listingId[24];
    char templateCode[21];

    uint64 price;
    uint32 quantity;
    uint32 cityId;
    uint32 taxPercent;
};

15. Example Decoded Listing

Item: Veteran Dual Dagger
Enhancement: +5
Grade: 290
Price: 145,000,000
City: Calmarnock
Tax: 6%

16. Confidence Assessment

Component Confidence
framing 100%
TLV format 100%
opcode 371 100%
listing structure 100%
template decode 95%
rarity derivation 90%

17. What Can Be Built Now

✔ offline auction parser
✔ market analytics
✔ price tracker
✔ dataset exporter
✔ Wireshark dissector
✔ live capture decoder

18. Future Work

• decode full template structure
• identify city_id mapping table
• map item stat packets
• detect seller identifier
• reconstruct pagination field logic

19. Final Statement

Auction protocol is fully structurally decoded.

Remaining unknowns are semantic enrichments only.

System is now machine‑readable.