CowSettlementHelpers

Git Source

Inherits: Assertion

Title: CowSettlementHelpers

Author: Phylax Systems

Fork-aware, log-aware helpers for the CoW Protocol (GPv2) settlement assertions.

The assertion adopter is the GPv2Settlement contract. These helpers wire up the bundle’s immutable configuration and provide the two observations the invariants need:

• the solver that authored a settlement call (the call’s caller), and
• the value the settlement contract moves out to a given recipient (via Transfer logs and ERC20 balance deltas). All reads go through snapshot forks / call-scoped logs; the bundle keeps no assertion-owned state of its own.

Constants

ERC20_TRANSFER_TOPIC

keccak256(“Transfer(address,address,uint256)”) — standard ERC20 Transfer topic0.

bytes32 internal constant ERC20_TRANSFER_TOPIC = keccak256("Transfer(address,address,uint256)")

GPV2_TRADE_TOPIC

keccak256(“Trade(address,address,address,uint256,uint256,uint256,bytes)”) from GPv2Settlement.

bytes32 internal constant GPV2_TRADE_TOPIC =
    keccak256("Trade(address,address,address,uint256,uint256,uint256,bytes)")

BPS

Basis-points denominator.

uint256 internal constant BPS = 10_000

SETTLEMENT

The GPv2 settlement contract this bundle protects (the assertion adopter).

address internal immutable SETTLEMENT

SWEEP_RECIPIENT

The single authorized destination for buffer outflows (the CoW DAO reward/sweep Safe). Net reductions of the settlement’s buffer are only allowed when they land here.

address internal immutable SWEEP_RECIPIENT

BUFFER_TOLERANCE_BPS

Dust tolerance, in basis points of the pre-transaction buffer balance, allowed when reconciling a buffer reduction against authorized sweeps. Absorbs rounding / fee dust.

uint256 internal immutable BUFFER_TOLERANCE_BPS

State Variables

bufferTokens

The buffer tokens whose settlement-held balances are protected (e.g. fee tokens that accumulate between DAO sweeps, such as the DAI buffer drained in the 2023 incident).

address[] internal bufferTokens

Functions

constructor

Configuration is passed in explicitly; the constructor never reads adopter state, since the assertion-deploy runtime is isolated from the calling state.

constructor(
    address settlement_,
    address sweepRecipient_,
    address[] memory bufferTokens_,
    uint256 bufferToleranceBps_
) ;

_requireSettlementIsAdopter

Reverts unless the configured settlement is the adopter for the current transaction.

function _requireSettlementIsAdopter() internal view;

_solver

Returns the solver that authored the settlement call.

GPv2’s onlySolver authenticates msg.sender, not tx.origin, so the protected counterparty is the immediate caller of the triggered settlement entry point.

function _solver(bytes4 selector, uint256 callId) internal view returns (address);

_valueFromSettlementTo

Sums the value of every ERC20 Transfer emitted inside callId that moves tokens from the settlement contract to recipient, across all tokens.

Scans standard 3-topic ERC20 Transfer events in the call frame (including nested calls, so value routed out through a solver interaction is still observed).

function _valueFromSettlementTo(uint256 callId, address recipient) internal view returns (uint256 total);

_reportedTradeVolume

Returns token volume that GPv2 itself reported as executed for the watched token.

Sums both sell and buy legs from GPv2 Trade events so normal settlement inventory movements do not trip the buffer assertion. The event does not identify the receiver, so this is a volume allowance rather than recipient-level authorization.

function _reportedTradeVolume(address token) internal view returns (uint256 volume);

_transferredValueFrom

Returns total standard ERC20 outflow from from for one token over the transaction.

function _transferredValueFrom(address token, address from) internal view returns (uint256 value);

_saturatingAdd

Saturating sum for small allowance sets used in reconciliation.

function _saturatingAdd(uint256 a, uint256 b) internal pure returns (uint256);