acdream/docs/research/2026-08-14-trade-laneB-wire.md

Secure-trade wire protocol (Lane B research)

2026-08-14. Sources: ACE (references/ACE/Source/ACE.Server/, authoritative for what our local server accepts/sends), retail decomp (docs/research/named-retail/acclient_2013_pseudo_c.txt, CM_Trade / ClientTradeSystem / Trade), holtburger Rust client protocol (references/holtburger/crates/holtburger-protocol/src/messages/trade/). All three agree byte-for-byte on every field ACE actually implements; no disagreements found. holtburger implements the FULL retail set (including OpenTrade/RemoveFromTrade, which ACE never sends) — its structs are cited as the independent cross-check.

Frame headers (GameActionPacket.cs:9-17, GameEventMessage.cs:14-26):

• C→S action frame: opcode 0xF7B1 (GameAction) → [sequence u32][GameActionType u32][action-specific fields].
• S→C event frame: opcode 0xF7B0 (GameEvent) → [PlayerGuid u32][GameEventSequence u32][GameEventType u32][event-specific fields].

All guids below are u32 (ObjectGuid/Guid, little-endian).

Table 1 — client→server actions (GameActionType)

Opcode	Name	Payload fields (order, type)	ACE file:line	Retail sender (address)
0x01F6	OpenTradeNegotiations	tradePartnerGuid: u32	GameActionOpenTradeNegotiations.cs:10	CM_Trade::Event_OpenTradeNegotiations @ 0x0056d300
0x01F7	CloseTradeNegotiations	(none)	GameActionCloseTradeNegotiations.cs:8	CM_Trade::Event_CloseTradeNegotiations @ 0x0056d1e0
0x01F8	AddToTrade	itemGuid: u32, tradeSlot: u32	GameActionAddToTrade.cs:9-10	CM_Trade::Event_AddToTrade @ 0x0056d0d0
0x01F9	(unassigned — reserved for RemoveFromTrade)	n/a	not in GameActionType.cs	retail has no Event_RemoveFromTrade C→S sender either — removal is client-local-only (see quirks)
0x01FA	AcceptTrade	partnerGuid: u32, tradeStamp: f64, tradeStatus: u32, initiatorGuid: u32, initiatorAccepts: u32(bool), partnerAccepts: u32(bool), (then self_list/partner_list, variable-length PackableList<ContentProfile>, ACE never reads these — see quirks)	GameActionAcceptTrade.cs:11-16	CM_Trade::Event_AcceptTrade @ 0x0056ad010, packing Trade::Pack @ 0x005b9ff0
0x01FB	DeclineTrade	(none)	GameActionDeclineTrade.cs:8	CM_Trade::Event_DeclineTrade @ 0x0056d270
0x0204	ResetTrade	(none)	GameActionResetTrade.cs:8	CM_Trade::Event_ResetTrade @ 0x0056d3d0

The 6 fixed AcceptTrade fields are exactly Trade::Pack's first 6 members (_partner, _stamp, _status, _initiator, _accepted, _p_accepted — acclient_2013_pseudo_c.txt:457619-457648); holtburger's AcceptTradeActionData (holtburger-protocol/src/messages/trade/actions.rs:159-205, test fixture at :265-280) reproduces the identical 24-byte-after-guid layout independently, confirming the read order.

Table 2 — server→client events (GameEventType)

Opcode	Name	Payload fields (order, type)	ACE file:line	Retail parser (address)
0x01FD	RegisterTrade	initiator: u32(guid), partner: u32(guid), stamp: u64 (ACE always writes 0L)	GameEventRegisterTrade.cs:10-12	ClientTradeSystem::Handle_Trade__Recv_RegisterTrade(this, initiator, partner, double stamp) @ 0x0056e050, dispatched via DispatchUI_Recv_RegisterTrade @ 0x006acf20 (type check == 0x1fd)
0x01FE	OpenTrade	partnerGuid: u32	not implemented by ACE — no C# class emits GameEventType.OpenTrade	ClientTradeSystem::Handle_Trade__Recv_OpenTrade @ 0x0056d930, dispatch @ 0x006acef0 (== 0x1fe)
0x01FF	CloseTrade	endTradeReason: u32 (EndTradeReason: Normal=1, EnteredCombat=2, Canceled=0x51)	GameEventCloseTrade.cs:10	Handle_Trade__Recv_CloseTrade (calls SendNotice_CloseTrade), dispatch @ 0x006ace90 (== 0x1ff)
0x0200	AddToTrade	objectGuid: u32, tradeSide: u32 (Self=1, Partner=2), slot: u32 (ACE always writes 0)	GameEventAddToTrade.cs:10-12	dispatch @ 0x006ace20 (== 0x200), reads 3 dwords at +4/+8/+0xc
0x0201	RemoveFromTrade	objectGuid: u32, mode: u32 (1 = remove one, 2 = remove all matching qty — Trade::RemoveItem)	not implemented by ACE — no C# class emits GameEventType.RemoveFromTrade	Handle_Trade__Recv_RemoveFromTrade @ 0x0056dc00, dispatch @ 0x006acf80 (== 0x201)
0x0202	AcceptTrade	whoAccepted: u32(guid)	GameEventAcceptTrade.cs:10	Handle_Trade__Recv_AcceptTrade @ 0x0056dc40, dispatch @ 0x006acdf0 (== 0x202) — client compares arg2 against its own SmartBox::player_id to know self-vs-partner
0x0203	DeclineTrade	whoDeclined: u32(guid)	GameEventDeclineTrade.cs:10	dispatch @ 0x006acec0 (== 0x203)
0x0205	ResetTrade	whoReset: u32(guid)	GameEventResetTrade.cs:10	Handle_Trade__Recv_ResetTrade (calls Trade::Reset), dispatch @ 0x006acfb0 (== 0x205)
0x0207	TradeFailure	objectGuid: u32, reason: u32 (WeenieError)	GameEventTradeFailure.cs:10-11	Handle_Trade__Recv_TradeFailure @ 0x0056d990 (calls Trade::RemoveItem(objectGuid, 1) before UI notice), dispatch @ 0x006acfe0 (== 0x207)
0x0208	ClearTradeAcceptance	(none)	GameEventClearTradeAcceptance.cs (no extra fields)	dispatch @ 0x006ace60 (== 0x208)

holtburger's events.rs independently reproduces every field above, including the "always 0 in ACE" comments on RegisterTradeEventData.unknown (:29) and AddToTradeEventData.slot (:83) — these comments were written from observing ACE traffic, corroborating the ACE source read.

SendNotice_* retail functions (e.g. SendNotice_AcceptTrade @ 0x0056ad460) are not wire sends — they walk gmGlobalEventHandler's registered UI notice-handler list to update the local trade window after a Recv_* dispatch. Do not confuse with Event_* (the only C→S wire builders, via Proto_UI::SendToWeenie).

Sequencing narrative

Happy path: A initiates trade with B, both add items, both accept

1. A → S: OpenTradeNegotiations(0x01F6) targeting B's guid (Player_Trade.cs:30-100).
2. Server-side checks in order (HandleActionOpenTradeNegotiations, initiator=true branch, :32-83): A not Olthoi → B online → B not Olthoi → B not IgnoreAllTradeRequests → neither already IsTrading → neither in combat mode → A moves/rotates to B via CreateMoveToChain (this is the "if in range" distance gate — failure sends WeenieError.TradeMaxDistanceExceeded, no trade starts).
3. On successful approach, S → A: RegisterTrade(0x01FD) with (initiator=B.Guid, partner=B.Guid, 0L) — note ACE passes tradePartner.Guid for BOTH fields here (Player_Trade.cs:80), not (A.Guid, B.Guid); this looks like an ACE bug relative to retail's _partner/_initiator semantics, but it is what ships (flagged again in Quirks below).
4. Internally A calls tradePartner.HandleActionOpenTradeNegotiations(A.Guid, initiator:false) (:82) — this is a same-process direct call into B's Player object, not a wire message. B's non-initiator branch (:85-99) sets IsTrading=true on both, clears both ItemsInTradeWindow, sets TradePartner cross-links, then:
5. S → B: RegisterTrade(0x01FD) with (initiator=B.Guid, partner=B.Guid, 0L) (:98 — same "wrong" both-fields-partner value, since this runs as B's own Session).
6. A → S: AddToTrade(0x01F8) with (itemGuid, tradeSlot) for each item A drags into the window. Server (HandleActionAddToTrade, :116-175): rejects if TradeTransferInProgress; clears both sides' TradeAccepted; resolves the item from A's inventory or equipped slot; refuses attuned/pet-bound items and uncarryable-uniques (see Quirks); adds to A.ItemsInTradeWindow; S → A: AddToTrade(0x0200) (itemGuid, TradeSide.Self=1, 0) immediately; then after a 0.001s ActionChain delay, S → B: AddToTrade(0x0200) (itemGuid, TradeSide.Partner=2, 0). Same flow mirrored when B adds items (roles of Self/Partner flip per session).
7. A → S: AcceptTrade(0x01FA) (full Trade::Pack payload, but ACE only parses the header — no fields are used). Server (HandleActionAcceptTrade, :196-216): sets A.TradeAccepted=true; S → A: AcceptTrade(0x0202) (whoAccepted=A.Guid) + CommunicationTransientString("You have accepted the offer"); S → B: AcceptTrade(0x0202) (whoAccepted=A.Guid) + CommunicationTransientString("{A.Name} has accepted the offer"). If B.TradeAccepted is already true, FinalizeTrade(B) runs now; otherwise nothing further happens until B also sends AcceptTrade (repeats this step for B, and then it's B's HandleActionAcceptTrade that finds target.TradeAccepted==true and calls FinalizeTrade).
8. FinalizeTrade (:218-283), runs on whichever side's accept was second:
   • VerifyTrade_BusyState — if either player IsBusy, abort: both get a CommunicationTransientString explaining who's busy, and ClearTradeAcceptance fires on both (S → both: ClearTradeAcceptance(0x0208), no fields — see step "Failure: busy / inventory" below).
   • VerifyTrade_Inventory — re-resolves both ItemsInTradeWindow sets by guid (if any item vanished, HandleActionDeclineTrade fires for that side instead); then checks CanAddToInventory (burden + free-slot capacity) for the INCOMING items on both sides. Failure → per-side CommunicationTransientString (encumbered vs. no-free-slots wording)
     • ClearTradeAcceptance on both, trade stays open with items still in the window.
   • On success: IsBusy=true on both, TradeTransferInProgress=true on both; S → A and S → B: CommunicationTransientString("The items are being traded").
   • Escrow: for every guid in A.ItemsInTradeWindow, TryRemoveFromInventoryWithNetworking(..., RemoveFromInventoryAction.TradeItem) or TryDequipObjectWithNetworking(..., DequipObjectAction.TradeItem) — this emits the ordinary inventory wire family, not trade-specific opcodes: from a pack slot → GameMessagePublicUpdateInstanceID(Container→Invalid) + GameMessagePrivateUpdatePropertyInt(EncumbranceVal) + GameMessageDeleteObject(item) (Player_Inventory.cs:217-247); from an equipped slot → GameMessagePublicUpdateInstanceID(Wielder→Invalid) + GameMessagePublicUpdatePropertyInt(CurrentWieldedLocation=0) + GameMessagePickupEvent(item) + GameMessageSound(UnwieldObject) + GameMessageDeleteObject(item) (Player_Inventory.cs:396-421). Mirror for B's items.
   • After a 0.5s ActionChain delay: deliver each escrowed item to its new owner via TryCreateInInventoryWithNetworking — emits GameMessageCreateObject(item) (+ GameEventViewContents and child GameMessageCreateObjects if the item is itself a container) + GameEventItemServerSaysContainId(item, container) + GameMessagePrivateUpdatePropertyInt(EncumbranceVal) (Player_Inventory.cs:90-114).
   • S → A and S → B: WeenieError.TradeComplete (0x0529) via GameEventWeenieError.
   • TradeTransferInProgress=false, IsBusy=false on both; SaveBiotasInParallel persists the moved items; then HandleActionResetTrade runs for both sides (S → A, S → B: ResetTrade(0x0205) (whoReset=own guid)) — this clears ItemsInTradeWindow/TradeAccepted but leaves IsTrading/TradePartner intact, so the window stays open, empty, for another round.

Decline path

Either side → S: DeclineTrade(0x01FB) (no fields). HandleActionDeclineTrade (:307-323): if TradeTransferInProgress, no-op (mid-swap declines are ignored); else clears the sender's TradeAccepted; S → sender: DeclineTrade(0x0203) (whoDeclined=sender.Guid) + CommunicationTransientString("Trade confirmation failed..."); S → partner: identical pair. The window stays open with items still present — decline only clears acceptance, it does not reset or close.

Reset path (client-initiated "clear my offered items")

A → S: ResetTrade(0x0204) (no fields). GameActionResetTrade.Handle resolves target = PlayerManager.GetOnlinePlayer(A.TradePartner); if found, calls A.HandleActionResetTrade(A.Guid) and target.HandleActionResetTrade(A.Guid) (GameActionResetTrade.cs:14-19). Both calls run the same body (Player_Trade.cs:177-186): no-op if TradeTransferInProgress; else clears ItemsInTradeWindow and TradeAccepted for whichever player's session the call executes under, then S → that session: ResetTrade(0x0205) (whoReset=A.Guid). Net effect: A's own window is cleared and A gets ResetTrade; B's window is also cleared (same whoReset=A.Guid payload) and B gets ResetTrade too — i.e. one player resetting clears both sides' offered-item lists, not just their own. (Confirmed by reading the two-call site directly; this is easy to misread as "reset only mine.")

Close path

A → S: CloseTradeNegotiations(0x01F7) (no fields). GameActionCloseTradeNegotiations.Handle resolves B via A.TradePartner, then calls A.HandleActionCloseTradeNegotiations() and B.HandleActionCloseTradeNegotiations() (:12-17). HandleActionCloseTradeNegotiations(endTradeReason=Normal) (Player_Trade.cs:102-114): no-op if TradeTransferInProgress (can't close mid-swap); else IsTrading=false, TradeAccepted=false, TradeTransferInProgress=false, ItemsInTradeWindow.Clear(), TradePartner=Invalid; S → that session: CloseTrade(0x01FF) (reason) + WeenieError.TradeClosed (0x0451). Runs for both A and B, each getting their own CloseTrade+TradeClosed pair. Items still sitting in the window at close time are simply left in the owner's inventory/equipped slot — closing never moves anything (only FinalizeTrade's accept-accept path does).

There is also a forced-close path: HandleActionTradeSwitchToCombatMode (:325-340) — if a trading player enters combat mode, both sides get WeenieError.TradeNonCombatMode (0x0455) then HandleActionCloseTradeNegotiations(EndTradeReason.EnteredCombat). Not triggered by a dedicated action opcode; it's called from wherever ACE's combat-mode-change action handler lives (not opened in this pass — grep GameActionChangeCombatMode.cs if wiring this).

Failure paths

• Distance: WeenieError.TradeMaxDistanceExceeded (0x044E) — initiator's CreateMoveToChain callback failed (target moved away / unreachable) before any RegisterTrade is sent. No trade session created.
• Already trading: WeenieError.TradeAlreadyTrading (0x044F) — either side already IsTrading.
• Non-combat required: WeenieError.TradeNonCombatMode (0x0455) — either side in combat mode at open time, or entering combat mid-trade (above).
• Ignoring requests: WeenieError.TradeIgnoringRequests (0x044C) — target has CharacterOption.IgnoreAllTradeRequests set.
• Attuned/pet item: AddToTrade refused — GameEventCommunicationTransientString("You cannot trade that!") (or the pet-specific string) + TradeFailure(0x0207) with reason=WeenieError.AttunedItem. Item never enters ItemsInTradeWindow.
• Unique-item cap: AddToTrade refused when wo.IsUniqueOrContainsUnique && !target.CheckUniques(...) — TradeFailure(0x0207) with reason=WeenieError.None (ACE leaves a // TODO comment at Player_Trade.cs:156 questioning whether this should be TooManyUniqueItems or a WeenieErrorWithString — as shipped it's the generic None reason, i.e. the client gets a failure with no readable cause).
• Busy at finalize: VerifyTrade_BusyState fails — CommunicationTransientString (busy-side/other-side wording) on both + ClearTradeAcceptance(0x0208) on both. Window stays open with items in place; nothing moves.
• Inventory can't accept at finalize: VerifyTrade_Inventory fails (encumbrance or free-slot check via CanAddToInventory) — CommunicationTransientString (encumbered/pack-space wording, correctly attributed to whichever side is the actual blocker) on both + ClearTradeAcceptance(0x0208) on both. Window stays open, items in place.
• Item vanished before finalize (e.g. someone else picked it up / it was consumed by another concurrent action): GetItemsInTradeWindow returns false for that side inside VerifyTrade_Inventory, which routes into HandleActionDeclineTrade for the affected side — same wire as the manual decline path (DeclineTrade(0x0203) + transient string to both).

ACE quirks / landmines vs. retail

1. RegisterTrade sends the wrong initiator guid. Both S→A and S→B RegisterTrade events carry (initiator=tradePartner.Guid, partner=tradePartner.Guid) — i.e. the non-initiator's guid in both slots, always (Player_Trade.cs:80, :98). Retail's Trade::Register(partnerGuid, stamp) (decomp 0x005b9ef0) only takes a single partner argument and separately tracks _initiator elsewhere in the Trade object, so the client is presumably reading initiator/partner fields that ACE fills identically and incorrectly. Whether any retail client logic actually branches on RegisterTrade's initiator field (vs. deriving initiator status locally) is unverified in this pass — flag before relying on that field client-side.
2. OpenTrade (0x01FE) is never sent. Retail's dispatcher and Handle_Trade__Recv_OpenTrade exist and are wired (DispatchUI_Recv_OpenTrade @ 0x006acef0), but no ACE GameEvent* class emits GameEventType.OpenTrade. RegisterTrade is what actually establishes the session; whatever retail UI behavior was gated on the separate OpenTrade notice (a partnerGuid-only payload) never fires against ACE.
3. RemoveFromTrade (0x0201) is never sent. Retail supports removing a single item from the trade window without clearing the whole thing (Handle_Trade__Recv_RemoveFromTrade, mode 1 = remove one, mode 2 = remove matching quantity, calling Trade::RemoveItem). ACE has no server-side action to remove a single item either — there is no GameActionType between AddToTrade (0x1F8) and AcceptTrade (0x1FA) reserved for it beyond the opcode gap at 0x1F9. The only way to change an offer on ACE is ResetTrade (0x0204), which clears the entire window on both sides (see Reset path above), not per-item removal. Any acdream UI that lets a player "un-drag" a single item from the trade window has nothing to send — either fake it client-side (visually pull the item back, no wire message, and let the player re-add the rest) or accept it maps to a full reset.
4. AcceptTrade's client-echoed state is entirely ignored server-side. The client packs its full local Trade snapshot — partner guid, a double timestamp, status, initiator guid, both accept flags, AND the two variable-length item lists it believes are in play — but GameActionAcceptTrade.Handle (:11-18) reads all six fixed fields into locals and then calls session.Player.HandleActionAcceptTrade() with zero arguments; none of the parsed values are used. ACE derives accept state purely from its own TradeAccepted bool and the two ItemsInTradeWindow sets. This means a desynced client (stale local Trade object) cannot corrupt the server's view, but also means ACE does zero cross-validation against what the client thinks is in the trade — divergence would only surface as a visual mismatch on the client, not a security issue.
5. RegisterTrade's stamp and AddToTrade's slot are hardcoded zero. ACE always writes 0L for the trade timestamp (GameEventRegisterTrade.cs:12) and 0 for the trade-window slot index (GameEventAddToTrade.cs:12). If retail client UI ever used the slot field to place an item visually at a specific grid position rather than append-ordering, that positioning info is lost against ACE — items would need to rely on arrival order instead.
6. Distance/approach gate only applies to the initiator. CreateMoveToChain (auto-walk-to-target) only runs in the initiator=true branch (Player_Trade.cs:70-84); the responding player's side (initiator=false, :85-99) never re-checks distance and starts the session unconditionally once the initiator's chain succeeds. There is no second distance check at AddToTrade or AcceptTrade time — a trade session, once open, has no live proximity requirement to keep offering or accepting items even if the players walk apart afterward.
7. ClearTradeAcceptance (0x0208) carries no identifying field. Unlike every other trade event, it has no guid/payload at all (GameEventClearTradeAcceptance.cs) — the client must infer "this applies to my own trade window" purely from receiving it on its own session, since there's nothing to disambiguate self vs. partner (not needed: it's always sent to the session whose acceptance was cleared).
8. Attuned/unique-item refusals leave the item untouched, no RemoveFromTrade needed — since the item is refused before ever being added to ItemsInTradeWindow, there is nothing to roll back client-side beyond the TradeFailure notice.