The module interface

A module is a contract with one view function. It receives the context of a fee and returns five weights in basis points that say how the 40% mechanic share is split across the dispatcher's sinks.

Interface

interface IHibouModule {
    function split(SwapContext calldata ctx) external view returns (uint16[5] memory weightsBps);
}
// weights, in order: BURN, STAKERS, LP_DONATE, TOP_BUYER, SWAPPER_REBATE
// they must sum to 10,000

BURN 5,000

STAKERS 3,000

REBATE 2,000

Example: half the mechanic share burns, 30% to stakers, 20% back to the swapper.

SwapContext

Field	Meaning
`sqrtPriceX96`	Pool price after the swap (0 for a harvest)
`hibouBought`	True when the swap bought $HIBOU with ETH
`ethAmount`, `hibouAmount`	The two sides of the swap
`fee`	The ETH fee being split
`timestamp`, `blockNumber`, `prevBlockHash`	Block data
`swapper`	Who gets a SWAPPER_REBATE (zero for a harvest, which sends the rebate to stakers)
`harvest`	True when the fee is a harvest of the Pons creator fees

A module may read other contracts with view calls: the RHNVDA/USD feed (0x379EC4f7C378F34a1B47E4F3cbeBCbAC3E8E9F15), RHTSLA/USD (0x4A1166a659A55625345e9515b32adECea5547C38), pool state on the PoolManager.

A full module

contract TopBuyer is IHibouModule {
    function split(SwapContext calldata) external pure returns (uint16[5] memory w) {
        w[3] = 10_000; // all of the mechanic share to the day's top buyer pot
    }
}

The default split

When there is no live module, when it is paused, or when it reverts, runs past 40,000 gas, returns the wrong length or weights that do not sum to 10,000, the dispatcher uses the default split: the whole mechanic share goes to STAKERS. A swap never fails because of a module.