Build with Signal

v4 events and accounting

One trade on a Signal v4 pool emits logs from several contracts. They describe the same trade from different sides. Adding them up double-counts it.

The logs of one swap

event FeeTaken(bytes32 indexed id, bool buy, uint256 fee, uint256 tax, uint256 sniperSurplus);
// topic 0: 0xcb06e9b550297e242ebbed1ca909965e3afe67f426041dd9785b3db02f2320ad

sniperSurplus is everything above the base rate: the opening fee's part above the base, plus the size and deviation extras. fee − sniperSurplus is the base fee, of which tax is the buy or sell tax's part.

What the trader paid and received

A price computed from Swap alone is the pool's price. It is the right price for a chart of the pool. It is the wrong figure for what a user paid during a 90% opening, when the pool's side of a buy is a tenth of what left the wallet. Pair each Swap with the FeeTaken of the same pool in the same transaction.

A pair asset that taxes its own transfers. The table holds when the pair asset moves the amount it is sent. On an asset that keeps a cut of its own transfers (PSTR), Swap and FeeTaken are amounts at the PoolManager: a buyer's wallet sent more and a seller's wallet received less, by that asset's cut, and a trade in native HYPE passed through that asset's own market first. Use the wallet's own Transfer logs and native value for what the trader paid and received.

A swap whose fee is zero emits no FeeTaken: every swap of a feeless pool, and on other pools a side with a zero rate or a dust trade. Match a FeeTaken to its Swap by its buy flag; a Swap without one paid no hook fee.

Not every PoolManager swap is a trade. The hook's own buyback swaps the pool too, inside a flush. It is paid from collected fees and pays no fee. Recognise it by BoughtBack in the same transaction and by Swap.sender being the hook, and count it as a burn, not as volume.

Use (chainId, transactionHash, logIndex) as an event identity. Keep block number and hash, handle removed logs, and replay overlapping ranges safely. Keep raw amounts when a dollar price is not available; unpriced is not zero.

Payout events

All emitted from the hook's address. Flushed, LegPaid, VestReleased, BoughtBack and BidAdded are declared in the flush library the hook runs; their ABI is SignalV4FlushEvents. PotWon, PayoutOwed and OwedPaid are in the hook ABI.

event Flushed(bytes32 indexed id, uint256 protocol, uint256 creator, uint256 holders,
              uint256 burn, uint256 liquidity, uint256 floor);
event LegPaid(bytes32 indexed id, address indexed to, uint256 amount);
event PotWon(bytes32 indexed id, address indexed winner, uint256 amount, uint32 buyIndex);
event VestReleased(bytes32 indexed id, uint256 amount);
event BoughtBack(bytes32 indexed id, uint256 quoteSpent, uint256 tokensBurned);
event BidAdded(bytes32 indexed id, bytes32 indexed kind, int24 tpLo, int24 tpHi,
               uint256 quoteSpent, uint128 liquidity);
event PayoutOwed(address indexed recipient, address indexed quote, uint256 amount);
event OwedPaid(address indexed recipient, address indexed quote, uint256 amount);

Reading them:

• Flushed reports what one flush sent or set aside, in the pair asset. creator is only what went to creatorPayout in this flush: the pot's slice, the co-recipients (LegPaid) and anything placed in a vest (VestReleased, later) are not in it, so its fields do not sum to the fees taken on a pool with a pot, co-recipients or a vest. burn and liquidity are amounts set aside for the buyback and the bid, spent in the same flush or a later one (BoughtBack a slice at a time, BidAdded).
• A divided amount is not always a delivered amount. A payout the asset refuses becomes PayoutOwed and stays in the hook until OwedPaid. For "what reached a wallet", follow the pair asset's Transfer logs from the PoolManager, or pair Flushed with the absence of PayoutOwed for that recipient.
• PotWon fires inside a buy, not inside a flush: the pot is paid to the buy's recipient in the same transaction.

A holders token's events

A holders token receives its share at a flush and pays it out itself:

event DividendFundsQueued(uint256 amount, uint256 burnedOwnTokens);
event DividendStreamStarted(uint256 amount, uint256 start, uint256 finish);   // five minutes
event DividendClaimed(address indexed holder, uint256 amount);
event DividendPushed(address indexed holder, uint256 amount);

Money queued or streaming is owed, not paid. Count DividendClaimed and DividendPushed as payments. withdrawableDividendOf(holder) is what a holder can claim now. The PoolManager, the hook, the dead address and the token itself earn nothing, and a stream starts only once at least 0.1% of the supply is in other hands.

Changes of destination and identity

Factory events worth watching

PausedSet(bool) closes or reopens a factory for new launches. QuoteSet(...) admits, updates or closes a pair asset for future launches. ProtocolBpsSet(uint16) changes Signal's share for future launches. None of them touches a launched pool.