Allocated Balance Event Ledger

Overview

BalanceChangePartyA and BalanceChangePartyB now form a deterministic delta ledger for the core Diamond's allocated-balance mappings. Every non-zero PartyA or PartyB allocated-balance mutation goes through a LibAccount increase or decrease method. That method writes storage and emits the matching event with the caller's reason as one operation.

The ledger covers allocated balance only. It excludes free balance, reserved open fees, locked or pending collateral, deferred balance, reimbursement, and liquidation escrow. v0.8.6 keeps those movements observable without placing false entries in the allocated ledger.

Reconstruction contract

event BalanceChangePartyA(
    address indexed partyA,
    uint256 amount,
    BalanceChangeType _type
);

event BalanceChangePartyB(
    address indexed partyB,
    address indexed partyA,
    uint256 amount,
    BalanceChangeType _type
);

Despite its retained ABI name, BalanceChangePartyB.partyA is the exact second key of partyBAllocatedBalances. Treat it as allocationKey: it is the PartyA address for an isolated PartyB bucket and address(0) for the shared cross-margin bucket.

Mutation ownership

The storage write and its event cannot drift apart: all direct writes to the two allocated-balance mappings are confined to these four helpers, and every caller must supply the reason.

Each helper calculates the post-write value once, stores it, emits only when amount > 0, and returns that calculated value for action events that expose newAllocatedBalance.

amount is always an absolute, non-negative delta. Direction comes from _type. For one PartyA address or one PartyB allocation key, the reconstruction equation is:

allocatedAfter = allocatedBefore + sum(inbound amounts) - sum(outbound amounts)

• Process logs by blockNumber, transactionIndex, then logIndex.
• Use only logs from the intended core Diamond deployment and the ABI active at that block.
• Zero-value calls do not change storage and do not emit a balance-change event.
• Reverted transactions contribute neither state changes nor surviving logs.
• Several valid deltas may occur in one transaction. Apply all of them; do not net or deduplicate by transaction hash.

Balance-change types

Both existing event signatures remain unchanged. BalanceChangeType preserves ordinals 0 through 13 and appends six new reasons at 14 through 19. The table below is the v0.8.6 direction contract. "Inbound" adds amount. "Outbound" subtracts it.

An indexer should reject or quarantine an unknown ordinal instead of guessing its direction. Future releases may append new types, so direction belongs in versioned indexer configuration rather than a suffix-only parser.

PartyB allocation keys

For BalanceChangePartyB, the indexed field named partyA is the exact second key of partyBAllocatedBalances[partyB][allocationKey]. Treat the event's accounting key as:

partyBAllocationKey = (partyB, event.partyA)

Why unified cross settlement writes credits before debits

All PartyAs share one cross-mode PartyB bucket. The contract credits that bucket for every PartyA loss before applying any PartyA gain, so an offsetting batch cannot fail from a temporary underflow caused only by input order. For example, from a starting bucket of 100, Alice paying the solver 30 and the solver paying Bob 50 emits SETTLEMENT_PNL_IN 30, then SETTLEMENT_PNL_OUT 50, both against (solver, address(0)); the final bucket is 80. Apply both logs by logIndex. Use SettleUpnlUnified for the affected PartyAs and final balance checkpoints, not to replace the zero-address ledger key.

Reimbursement ledger

While PartyA is liquidating, Clearing House distributions and returned pending-open fees can enter partyAReimbursement. That bucket has a separate exact event because it is not allocated balance.

event PartyAReimbursementChange(
    address indexed partyA,
    uint256 amount,
    uint256 newBalance,
    ReimbursementChangeType _type
);

For every reimbursement event, verify previousBalance ± amount == newBalance. A normal liquidation or Clearing House takeover emits RELEASE_TO_ALLOCATED, then a separate BalanceChangePartyA(REIMBURSEMENT_IN). A late or overdue liquidation emits MOVE_TO_LIQUIDATION_ESCROW and LiquidationEscrowCreated, but no allocated credit.

Liquidation and CVA

PartyA liquidation settlement keeps the original event and emits an overloaded enrichment for the same call:

event SettlePartyALiquidation(
    address partyA,
    address[] partyBs,
    int256[] amounts,
    bytes liquidationId
);

event SettlePartyALiquidation(
    address partyA,
    address[] partyBs,
    address[] allocationKeys,
    int256[] amounts,
    uint256[] cvaAmounts,
    bytes liquidationId
);

• All arrays in the extended event have the same length and align by index.
• allocationKeys[i] is the exact PartyB storage key: PartyA in isolated mode or address(0) in cross mode.
• amounts[i] > 0 means PartyB paid PartyA; amounts[i] < 0 means PartyA paid PartyB.
• cvaAmounts[i] is the CVA returned to that PartyB bucket: full in normal liquidation, haircut in late liquidation, and zero in overdue liquidation.
• Paginated settlement emits one legacy event and one extended event for each processed batch.

Final PartyA settlement also replaces the pre-finalization allocation with the values that survive liquidation. The emitted breakdown debits the allocation-funded liquidation fee as LF_OUT, debits the remaining old allocation as REALIZED_PNL_OUT, then credits surviving deferred or normal reimbursement values. The signed sum equals the exact before/after PartyA allocated-balance delta.

v0.8.6 liquidation accounting

v0.8.6 exposes the exact amount on both sides whenever the protocol records CVA or LF as its own liquidation component. Keep economic attribution separate from allocated-balance replay: settlement events identify who paid and received, while BalanceChangePartyA and BalanceChangePartyB identify the storage delta that actually occurred.

PartyA liquidation

partyAPaidCva(liquidationId) = sum(all extended cvaAmounts)
partyBReceivedCva(liquidationId, partyB) = sum(cvaAmounts[i] where partyBs[i] == partyB)
// The final settlement receipt is the settlement call that also emits FullyLiquidatedPartyA.
// Read LF_OUT and REALIZED_PNL_OUT on partyA, and LF_IN on the starter, from that receipt.
// A component with no event is zero, not unknown.
totalLf(liquidationId)            = LF_IN credited to the liquidation starter
lfFromPartyAAllocation(partyA)    = LF_OUT debited from partyA          // clamped to the live allocation
lfCreditDebitGap(partyA)          = totalLf - lfFromPartyAAllocation    // >= 0, no allocated-balance event
partyAAllocationBeforeFinalize    = LF_OUT + REALIZED_PNL_OUT on partyA // the allocation liquidation consumed
clampFired(partyA)                = totalLf > lfFromPartyAAllocation

// Liquidation-start classification, before the per-position profit cap:
rawRemainingLf                    = lockedLf - availableBalanceShortfall
totalLf                           = min(rawRemainingLf, maxLiquidationProfitPerPosition * positionsCount)
insuranceVaultCredit              = rawRemainingLf - totalLf
// LF_OUT is only the slice of totalLf still present in PartyA allocation at finalization.
// The allocated-balance events do not encode lockedLf or availableBalanceShortfall.

A settlement call emits its balance changes before the legacy and extended SettlePartyALiquidation events. Buffer the complete receipt, process it in logIndex order, and then attach the later extended event's liquidationId, partyBs, and allocationKeys. Paginated settlement contributes one extended event per processed batch; aggregate all batches sharing the liquidation ID.

PartyB liquidation

Event field corrections

Two events carried a wrong or path-dependent value in a single field. Both are corrected in v0.8.6 without any signature change, so an indexer will keep decoding them while silently starting to read a different value.

SettleUpnl reported the caller instead of PartyA

event SettleUpnl(
    QuoteSettlementData[] settlementData,
    uint256[] updatedPrices,
    address partyA,
    uint256 newPartyAAllocatedBalance,
    uint256[] newPartyBsAllocatedBalances
);

ForceActionsFacet.settleAndForceClosePosition passed msg.sender into the parameter declared as partyA. On that path the field held the keeper or liquidator who submitted the force close, not the PartyA being settled. SettlementFacet always passed the real PartyA, so one event signature meant two different things depending on which facet emitted it. v0.8.6 passes the quote's PartyA on both paths.

Any index keyed on that field from the force-close path has been attributing settlements to submitters. History can be corrected by re-deriving the PartyA from the quote IDs in settlementData.

LiquidatePartyB reported a post-payout balance on the force-close path

event LiquidatePartyB(address liquidator, address partyB, address partyA, uint256 partyBAllocatedBalance, int256 upnl);

PartyBLiquidationFacet.liquidatePartyB emits before it starts the liquidation, so its partyBAllocatedBalance is the value immediately before liquidation touches it. The force-close paths read the same field after liquidation had already run. Starting a PartyB liquidation debits that bucket twice, once for the realized settlement transfer and once for the remaining liquidation fee. The field therefore reported a smaller, post-payout number on those paths.

v0.8.6 captures the balance before liquidation on the force-close paths as well, so both entry points now report the pre-liquidation balance.

Indexer changelog