BalanceDelta

BalanceDelta is a fundamental data structure in Uniswap v4 that encapsulates the net token balance changes resulting from any pool operation. Rather than executing transfers after each individual action, the Pool Manager tracks cumulative deltas throughout a transaction sequence, settling only the final net amounts—a key component of v4's flash accounting system.

Structure and representation

The BalanceDelta struct contains two signed integers representing the balance changes for each token in a pool:

1struct BalanceDelta {
2    int256 amount0;
3    int256 amount1;
4}

The sign convention follows a consistent pattern from the pool's perspective:

• Negative values indicate tokens leaving the pool (the user is selling/withdrawing)
• Positive values indicate tokens entering the pool (the user is buying/depositing)

This representation provides a complete "receipt" of any pool operation, enabling developers to understand exactly what was exchanged without tracking intermediate states.

Role in flash accounting

BalanceDelta is central to Uniswap v4's gas optimization strategy. Under flash accounting, the protocol defers actual token transfers until all operations within an unlock scope complete. During execution:

1. Each pool action (swap, add liquidity, remove liquidity) returns a BalanceDelta
2. The Pool Manager accumulates these deltas internally
3. Only when all operations complete does the final netted delta trigger actual token transfers

This approach eliminates intermediate ERC-20 transfers that would otherwise occur in multi-hop swaps or complex DeFi strategies, providing significant gas savings for sophisticated users.

Interpreting swap results

For swap operations, BalanceDelta interpretation depends on the swap direction:

zeroToOne swap (selling Token0 for Token1):

• amount0 is negative (Token0 leaves the pool → user spent it)
• amount1 is positive (Token1 enters the pool → user received it)

oneToZero swap (selling Token1 for Token0):

• amount0 is positive (Token0 enters the pool → user received it)
• amount1 is negative (Token1 leaves the pool → user spent it)

Understanding this convention is essential for correctly processing swap outcomes and implementing proper accounting in integrating protocols.

Security considerations

Validation requirements

Protocols integrating with Uniswap v4 must validate BalanceDelta values against expectations:

1BalanceDelta delta = poolManager.swap(key, params, hookData);
2
3// Validate minimum output for exactInputForOutput swap
4require(
5    delta.amount1() >= minAmountOut,
6    "Insufficient output amount"
7);

Failing to validate deltas can expose users to sandwich attacks or other MEV extraction where the actual execution differs significantly from expectations.

Decimal handling

When processing BalanceDelta values, developers must account for differing token decimals. A delta of 1e18 means vastly different amounts depending on whether the token uses 6 or 18 decimal places. Always normalize or convert values appropriately before displaying to users or making comparisons.

Hook interactions

Hooks with delta-modifying permissions can alter the BalanceDelta returned by operations. Protocols must understand which hooks are attached to pools they interact with and how those hooks might affect the expected deltas. A hook could legitimately modify deltas for features like dynamic fees or could maliciously extract value if not properly audited.

Practical usage patterns

Multi-hop swap aggregation

For trades routing through multiple pools (A → B → C), BalanceDeltas can be aggregated to determine the net result:

1BalanceDelta totalDelta;
2totalDelta = totalDelta + poolManager.swap(poolAB, paramsAB, "");
3totalDelta = totalDelta + poolManager.swap(poolBC, paramsBC, "");
4// totalDelta now contains net change across both swaps

This pattern enables complex routing strategies while maintaining clear accounting.

Liquidity operations

BalanceDelta also represents the results of liquidity modifications, showing how much of each token was added or removed from a position. This unified representation simplifies protocol development by providing consistent semantics across all pool operations.

Comparison to previous versions

In Uniswap v2 and v3, swap results were typically represented by actual token transfers or output amounts rather than a unified delta structure. The introduction of BalanceDelta in v4 reflects the protocol's shift toward deferred settlement and more efficient batch operations, enabling gas optimizations that weren't possible with immediate transfer semantics.