Attested incentive allocator — specification

Report date and source-read date: 2026-10-05 UTC.

Recommendation

Launch an immutable, quote-token-funded trading-reward allocator for one Uniswap v4 pool, with a small authenticated swap gateway and an observation hook that logs the gateway's actual calling account. Buy one chain-evidence ranking and one independently bound sum for each winner per epoch; store the signed list on chain and pay capped pro-rata rewards through permissionless claims to those exact accounts. Start with ten winners and nominal weekly epochs. This removes the distributor's discretion over recipients, amounts and question selection, but still trusts the oracle service key and its re-execution process; it does not prove that wallets represent distinct people or that trades are organic. Use three new contracts, or four including an optional launch token. Refused or incomplete attestations release no rewards. Economic protection is conditional on an independently defensible lower bound on unrecoverable trading costs; absent that bound, use a zero reward rate rather than claiming a positive budget is wash-proof.

Decisions table

Question	Choice	Figure	Main reason
1. Attribution	Hook event keyed by caller of immutable gateway	ParticipantVolume(poolId, participant, quoteVolume); two hook flags	Authentic account authorization; arbitrary router labels are spoofable
2. Payout	Stored top-ten list plus sums; capped pro rata	11 requests: 5.5 IMD/epoch; approximately $46.75 only at the brief's assumed exchange value	Order alone cannot establish reward-per-volume bounds
3. Washing/sybils	Same quote denomination for volume and rewards; conservative per-volume cap	Illustrative 3000 fee tier, 50% fee recapture: choose 7.5 bp rate; $750 maximum on $1m selected volume	Fees paid to attacker-controlled LPs are not an attacker expense
4. Timing	Fixed contiguous block windows, sequential closure	50,400 blocks; nominal seven days at 12 seconds/block; seven-day response grace	Avoid discretionary endpoint selection and partial payout
5. Comparators	Separate distribution integrity from retention and identity	2025 Uniswap proposal: $24m v4 and $21m initial Unichain requests; 2024/25 LTIPP evaluation: 95.95m ARB claimed across three programmes	Reproducibility does not turn subsidized activity into durable demand

Evidence legend. FACT means directly supported by a cited primary document or a pinned input read in this assignment. DESIGN means a proposed rule, not observed production behavior. INFERENCE means reasoning from those facts. UNKNOWN means evidence was unavailable or insufficient. Every IdentityMD-plane assertion below is explicitly an ASSUMPTION supplied by the brief, unless identified as a directly inspected pinned-test fact. No live oracle request, signature, deployed consumer, price feed or mainnet transaction was independently exercised. Source pages were read on the date above; historical dates are identified separately. Comparator amounts are not live prices or audited effectiveness estimates.

1. Attribution: what the ranking reads

FACT: PoolManager Swap and ModifyLiquidity identify the account calling the manager, not necessarily the beneficial trader or LP. Ranking this field can reward a router or position manager. The ABI documents the sender fields and signed swap deltas. Uniswap PoolManager interface

Candidate	Honest meaning	Spoofing/measurement failure	Decision
PoolManager event sender	Immediate manager caller	Common routers aggregate many users	Reject as participant key
Any router's msgSender()	Whatever that router reports	A malicious router can implement the same selector and return anyone	Accept only reviewed immutable integrations
Address in hookData	Caller-supplied label	Anyone can name a victim, distributor or fresh sybil	Never authenticate this alone
ERC-20 Transfer recipient	Token recipient	Transfers, self-transfers, routers, fee settlements and gifts are not unique pool trades	Reject as trade metric
Position NFT owner	Owner at a particular moment	Transfers, operators, mint timing and tokenId-to-position linkage matter	Suitable only for a separate carefully defined LP scheme
Immutable gateway caller	Account authorizing this gateway execution	Contract accounts and sybils remain possible	Selected trading metric

FACT: Universal Router's Lock exposes msgSender() using its active locker. This is a useful convention, not an authentication standard applicable to every contract. Universal Router Lock source

DESIGN: Gateway swap accepts no participant argument. It locks against reentry, records msg.sender, calls PoolManager through its unlock callback, settles the trade and clears the account before returning. Hook afterSwap requires PoolManager as its own caller. If the hook's sender is the gateway, it reads the gateway's active account and emits exactly one event for a nonzero quote-side delta. If the sender is another router, the pool trade still succeeds but earns no reward and emits no qualifying event. Unknown integrations therefore cannot forge rewarded identities or halt ordinary routing. tx.origin is never used. A Safe or other account contract earns as that contract; an aggregator earns as the aggregator unless a future separately reviewed integration preserves authenticated user authorization.

event ParticipantVolume(
    bytes32 indexed poolId,
    address indexed participant,
    uint256 quoteVolume
);

quoteVolume is the absolute executed quote-currency balance delta, in the quote token's native integer units, obtained from the callback's final swap delta. It is not the requested input, a dollar estimate or the sum of both token legs. Both directions count the quote leg once. The specification excludes zero-volume events and any other pool. The gateway permits one swap per invocation, exact-input or exact-output with bounded input/output and a deadline; partial execution counts the actual result. Failed settlement reverts the entire transaction and its logs. No extra accounting delta or hook fee is introduced. Quote delta may include input fee effects; the economic lower bound must use this exact measured-volume denominator rather than an approximate gross-volume dashboard definition.

ASSUMPTION (IdentityMD): log-rank can group this event by participant, sum quoteVolume, apply topN, and return an ordered address[] without sums. Each subsequent log-sum filters the same pool and one participant over the exact same inclusive block window. Required rank semantics are descending aggregate sum, then ascending numeric address for ties, exclusion of zero totals, and fewer than N results when fewer participants exist. These are proposed definitions; actual tie and filter support require developer confirmation. Refusal is preferable to a service silently implementing different semantics.

LP incentives are deliberately a different metric. FACT: PositionManager contains NFT position operations, liquidity modifications and ownership checks; its internal call sequencing must be examined before attempting to recover owners in callbacks. PositionManager source

INFERENCE: summing liquidity additions rewards repeated deposit/withdrawal rather than sustained useful liquidity. An honest LP product needs position identity, historical ownership including transfers, in-range liquidity and time integration. An owner lookup at epoch close retroactively assigns earlier activity to buyers. A hook cannot assume every position manager exposes a callback-safe tokenId or that a minted NFT already exists when the callback runs. The supported recipe list supplied here does not establish an exact ownership-aware liquidity-time integral. Do not relabel deposit sums as liquidity mining; ship trading rewards first and commission an LP metric separately.

The hook is one of the contract count, using BaseHook behavior with beforeInitialize and afterSwap only, mask 0x2040 (8256). All other twelve flags, including every ReturnDelta flag, are false. FACT: v4 encodes permissions in the low fourteen address bits. Hooks library The pinned Hook protected test independently requires an initialization callback, matching flags, restricted callers, runtime size at most 24,576 bytes and no executable SELFDESTRUCT, DELEGATECALL or CALLCODE. It does not run a pool lifecycle; that omission must never be reported as a lifecycle pass.

2. Payout shape and cost

ASSUMPTION (IdentityMD): a request costs 0.5 IMD, approximately $4.25 at the brief's reference value, and rank results contain order but no amounts. USD conversions below use that assumed value only; no current IMD market price was verified.

Shape	Requests for N winners	Payout rule	Principal limitation
Fixed rank tiers	1	N=10: 30%, 20%, 15%, 10%, 7%, 5%, 4%, 3%, 3%, 3% = 100%	Economically unsafe without volume floors; compare only
Pro rata among ranked winners	N+1	B * V_i / sum(V_j)	Extra cost, partial-answer liveness and fee recapture
Selected capped pro rata	N+1	min(B * V_i / S, r * V_i)	Can leave much of budget undistributed; still has a top-N boundary

Tiers for N=50/100 would need separate immutable vectors. If fewer winners exist, selected pro rata uses those actual winners; fixed tiers should leave missing positions unspent rather than renormalizing upward. Avoid winner-takes-all lottery semantics.

topN	Rank tiers	Rank plus N sums	Assumed USD tiers / pro rata
10	0.5 IMD	5.5 IMD	$4.25 / $46.75
50	0.5 IMD	25.5 IMD	$4.25 / $216.75
100	0.5 IMD	50.5 IMD	$4.25 / $429.25

Those are successful first-attempt request costs, excluding gas, operator work, funding and any retry charges. For k<N actual winners the selected design needs k+1 requests. An aggregate sum over all participants would add another 0.5 IMD and change the denominator; it is not silently included here.

DESIGN: Store ranked[epoch], verified volume per index, a received-sums bitmap/count and claim status. Let S=sum(V_i) with every V positive. Use full-precision multiplication/division and round both bounds down. Rate is a rational integer ratePpm/1_000_000, expressed in quote reward units per quote-volume unit. Finalize only after all actual winners' sums arrive; freeze each entitlement then. Empty ranking finalizes with zero rewards. Sum of claims is at most B and at most the sum of individual caps. Rounding dust and unused ceiling remain unallocated.

Commitment	Verification required	Scale	Trust
Stored list, selected	Check signature, canonical answer bytes and per-winner sums	O(N) writes; claims O(1)	No discretionary distributor
Merkle root derived on chain	Same checks, then deterministic leaf/root construction	O(N) input/hash work; O(log N) proofs	Equivalent integrity if all leaves are derived
Root submitted off chain	Proof that root equals full signed list and amounts	Cheap root storage but proof machinery required	Without that proof restores distributor discretion

A signed list does not sign an arbitrary distributor root. Any root variant needs leaves binding consumer chain, allocator, epoch, index, account and amount, plus unambiguous tree ordering and odd-node rules. For ten winners, storage is simpler. Publish the verified list in an event; membership also remains claim-accessible in storage. ASSUMPTION (IdentityMD): job delivery has no consumer-verifiable signature and cannot replace an oracle attestation.

3. Wash trading, sybils and budget

Define W as counted quote volume over all wash legs, f_eff as fees per measured quote volume irreversibly paid outside the attacker, I(W) as net price-impact/arbitrage loss, and G as gas/financing cost. For a round trip, both legs enter W, so do not multiply fW by two again. A simple attacker-profit model is:

profit(W) = incremental_rewards(W) - f_eff * W - I(W) - G.

The requested no-wash condition is incremental_rewards(W)/W < f_eff + I(W)/W + G/W. For an unconditional per-unit sufficient bound, use conservative lower bounds, not optimistic expected impact. With attacker LP share alpha and fee rebates d, an approximate model is f_eff = f*(1-alpha)-d; the implementation's denominator and trade direction require refining this approximation. Small repeated round trips can make net impact approach zero. A concentrated-liquidity attacker can capture most fees. Thus the advertised pool fee alone is not an expense floor.

DESIGN: Select B ceiling and r before activity starts; spend B_spend <= min(B, r*S), with each entitlement min(floor(B*V_i/S), floor(ratePpm*V_i/1e6)). Same quote token for rewards and volume avoids needing a manipulable token-price oracle. Paying launch tokens instead requires an independently bounded conversion to quote value; a thin-pool spot is unsuitable. Assets are quote reserves; liabilities are unpaid entitlements. Sponsors bear emissions costs and unused locked funding.

Illustrative case, not observed pool data	Conservative cost floor	Suggested r	Budget consequence
3000 tier, no recapture/rebate; zero impact floor	About 30 bp	15 bp	$1,500 per $1m selected volume
3000 tier, alpha at most 50%; zero impact floor	About 15 bp	7.5 bp	$750 per $1m selected volume
500 tier, no recapture/rebate	About 5 bp	2.5 bp	$250 per $1m selected volume
Unbounded LP recapture or external rebate	Zero can be possible	Zero	No positive provably wash-proof spend

DESIGN example: B=$1,000 quote units, r=750 ppm, S=$1m gives at most $750; S=$100,000 gives at most $75; S=$2m permits the full $1,000. Examples assume a dollar quote. In code they are raw quote units, with decimals accounted for. Actual fee-denominator effects need a safety margin in the reviewed r. Oracle expense is additional: the top-ten assumed $46.75 service cost is substantial beside a $75 payout.

INFERENCE: splitting a fixed volume does not increase its sum. It can nevertheless change selected-set membership and redistribute pro-rata rewards; top-N is not mathematically sybil-neutral. Fee recapture, per-address floors and rank tiers make the issue worse. The selected design has no equal-wallet bonus, new-user multiplier or per-wallet cap that invites splitting. Its aggregate cap limits rewards to r times selected volume, but it does not prove negative marginal profit near the cutoff. A wallet with pre-existing organic volume can wash a small amount to enter top N and unlock rewards for that earlier volume. Avoid claiming the total-volume bound proves the incremental condition.

Therefore positive rates are a monitored, conditional incentive experiment, not a universal prevention theorem. Publish rank-boundary sensitivity, organic retention and fee-recipient concentration, and stop funding future epochs if assumptions fail. Changing rules requires a new deployment; nobody can blacklist signed winners midway. A strict anti-wash requirement would need a different mechanism, such as rewarding all authenticated participants at a linear fee-linked rate, or an additional verified cost metric. Neither is delivered by a ranking-only answer. Human identity or graph-based exclusions introduce separate evidence and appeal requirements; they must not be hidden in chain rankings.

4. Epochs, requests and attestation acceptance

DESIGN: This deployment observes its local Sepolia pool. Data chain equals consumer chain for the first version; cross-chain observations are explicitly unsupported rather than implicitly checked against the wrong chain. Define H as hook initialization block and L=50,400. Epoch e has inclusive bounds [H+1+eL, H+(e+1)L]. These are block epochs, nominal weekly at twelve seconds/block, not guaranteed seven-day UTC intervals. Initialization cannot occur twice. beforeInitialize validates immutable currencies, hook address, static fee 500/3000/10000 and tick spacing, then records H; a reverted initialization rolls that write back. No activity in block H is rewarded.

Anyone may fund an epoch before its starting block, up to immutable B. Anyone may prepare its fixed window after closing and a 128-block settlement delay. The delay is a chosen buffer, not a proof of consensus finality. Confirm finalized status before buying requests. Windows close sequentially; either finalize or expire the pending epoch before accepting the next ranking. Sums belong to the pending rank window and therefore reuse its closing block rather than advancing separately. A refusal must not permanently block later epochs: after seven days from preparation, anyone can expire it, advance the processed cursor and release its reservation. Existing finalized claims remain valid indefinitely.

ASSUMPTION (IdentityMD): answers take minutes; mainnet IMD funds requests, launches currently target Sepolia, schedules cost 0.5 IMD per run, recurring oracle requests are at least ten minutes apart, and recurring jobs are at least thirty minutes apart. These operational properties were supplied, not verified. A sponsor buys the rank after the window is finalized, then sums after winners are known. Other users may buy exactly equivalent questions with the allocator as consumer and relay valid answers. No mainnet IMD transfer is attempted by the Sepolia allocator and there is no invented bridge or keeper reimbursement. Off-chain request provisioning occurs after launch; the contracts are already fully linked without it.

ASSUMPTION (IdentityMD): service signer is 0x5598aa9146215bc13eb26f2c692ad1461fd32982; EIP-712 domain is name IdentityMD Oracle, version 2, consumer chainId and allocator verifyingContract. Signed fields are requestId, chainId, questionHash, answerType, answer, figure, fromBlock, toBlock, blockHash, panelJobId, panelSize, quorum, agreed, issuedAt, expiresAt. Their Solidity types, primary struct name, answer encoding and chainId semantics have not been established by a signed fixture. An interface envelope below is a consumer adapter design, not a claim about the existing wire ABI.

DESIGN: pin signer in source, with no setter, owner, rotation or upgrade. Reject wrong signer, malleable/high-s signatures and malformed bytes. Verify domain using block.chainid and address(this), then require the signed data chain field equals the deployment's data chain. Check exact answer type and canonical decoding, figure consistency for sum answers, window equality, expiry, issuedAt not in the future, issuance after window closing, maximum permitted signature age of 48 hours, nonzero closing block hash and matching hash across rank and sums. Require unique requestIds for accepted answers. Do not equate a closing block hash carried in a signature with independent on-chain finality: local blockhash only covers a limited recent range, and remote hashes are unavailable. ASSUMPTION (IdentityMD): old-window re-execution/finality relies on the service.

ASSUMPTION (IdentityMD): agreed is signed and live answers have agreed=quorum. DESIGN floors are panelSize>=5 and agreed>=3, subject to developer confirmation that these counts can be bought. Also check agreed<=panelSize, quorum<=panelSize, and agreed>=quorum. Never enforce an agreement ratio. A one-signature service is still one cryptographic trust boundary, even when five agents participated. ASSUMPTION (IdentityMD): supported chain recipes are log-sum, log-count, univ4-spot, call-compare, log-rank and v4-volume-rank; other evidence is panel-voted and not re-run. This allocator accepts only its pinned chain-evidence documents; a voted price, identity judgement or arbitrary ranking is ineligible.

ASSUMPTION (IdentityMD): questionHash hashes the sorted-key canonical document {v, question, chainId, window, answerType, head?, definitions?, evidence?}, including window and evidence class. DESIGN: build exact canonical bytes in a reviewed serializer with immutable templates and replace only decimal fromBlock/toBlock, and the sum template's fixed-format address selected from the already verified list. Pin version, hook address, event signature, poolId, grouping, sum argument, order/tie rules, topN, units and zero handling inside question/definitions. ASSUMPTION (IdentityMD): window object keys and recipe nesting remain unverified. Never hash an ad hoc abi.encode surrogate and never let the relayer supply definitions. Store golden documents and hashes once the developer provides the real schema. EIP-712 hashes dynamic fields according to their declared types; it does not provide application replay protection automatically. EIP-712 specification

A refused rank creates no claim. A rank with one missing sum creates no claim for anyone; retry within grace using the same question/window. ASSUMPTION (IdentityMD): retry billing/refunds are unknown. Expired reservations become unallocated reserves, eligible for a later fixed-ceiling epoch through a permissionless allocation function; they never create an enlarged jackpot or let a sponsor recover accepted liabilities. Unclaimed entitlements have no sweep path.

5. Comparator evidence and failures

The freshness window is 2024-10-05 through 2026-10-05. Figures below are from documents within that period, or currently served technical parameters. Where a programme ended earlier, a later evaluation is identified as such. Historical airdrop policy is discussed for methodology without passing its old launch figures off as recent performance.

System	Dated evidence and figure, read 2026-10-05	What went wrong or remains unproven	Design consequence
Merkl	Technical documentation served at read date: approximately two-hour computation, eight-hour average root updates (4–12 hour range), 1–2 hour dispute period	Documentation acknowledges data-feed/invariant delays; engine and root publication remain separate trust surfaces. Archived docs may lag deployed settings	Store actual verified lists; do not promise immediate claims
Uniswap incentives	February/March 2025 governance proposal: $24m v4 six-month budget, $21m initial Unichain request, two-week tranches	These are proposed budgets/goals, not realized organic growth. Subsequent attribution research shows retention weaknesses	Separate distribution correctness from growth measurement
Uniswap retention	Forse's 2025 research update: 27.8% of incentivized LPs subsequently used Aerodrome; 84.5% of that subset fully left Uniswap	Cohort observation, not causal proof that incentives made LPs leave	Measure continued activity after rewards end
Arbitrum LTIPP and related programmes	PYOR November 2024 evaluation: 101.86m ARB proposed and 95.95m claimed across STIP, Backfund and LTIPP; 88 LTIPP grantees	Initial report explicitly lacked sufficient post-LTIPP data; December 2024 Foundation note reports fund misuse and recovery	A signed activity metric cannot prove correct grant operations or sustainable returns
Optimism airdrops	Airdrop 5 rules read live: >=20 distinct contracts and >=10% contracts/transactions during March–September 2024; August 2026 budget reports 10,368,678 OP circulated in Year 3 and zero in Year 4	Eligibility disputes exist; no verified recent false-positive or sybil-leakage rate found	Publish exact windows and explain exclusions; never invent accuracy figures
Arbitrum airdrop filtering	Currently served historical policy: 48-hour activity concentration and low-balance/low-diversity penalties, plus Hop sybil exclusions	Original distribution is outside the comparison period; no current efficacy estimate established	Behavioral heuristics can be reproduced without proving personhood
Blur points	Season 4 rules, ending June 2025: 500m BLAST allocation; top-100 rolling 24-hour boosts up to 2.5x; mythical packages worth 100x uncommon	Documented user complaints about inaccessible holder views in November 2024; rules expose concentration and loyalty incentives. No verified recent wash-share figure	Avoid discretionary boosts and probabilistic payout conversion

Merkl's technical source describes published reward files, delayed availability and claims against roots. Its 1–2 hour dispute description is a documented parameter, not a live contract read; actual chain configuration should be read before integration. Merkl technical overview The open dispute bot describes halting updates when data is wrong or insufficient and DAO resolution. No recent exploit or loss amount was independently established here. Merkl dispute reference

Uniswap's budgets and tranche arrangements come from the proposer's governance document, not a third-party estimate. Treat them as that dated plan. Uniswap Unleashed proposal Forse's directly authored update supplies the retention percentages; the denominator of 84.5% is the Aerodrome-moving subset, not every incentivized LP. Forse programme update

PYOR's programme totals are grantee claims, not verified end-user receipts. Its January 2025 follow-up announces a final analysis; this report does not claim to reproduce that linked PDF's results. PYOR preliminary evaluation and follow-up The Foundation says it identified misuse and retrieved nearly all funds, without a loss/recovery amount in the inspected passage. Foundation ARDC recommendations, December 2024

Optimism's activity criteria are direct programme rules, not a published identity classifier. Airdrop 5 criteria The more recent budget distinguishes circulating tokens from newly committed spending; its Year 3 airdrop figure should not be interpreted as Year 4 emissions. Optimism August 2026 budget update A dated eligibility complaint is evidence of a disputed experience, not proof of an erroneous exclusion. Optimism October 2024 discussion

Arbitrum's served policy documents transaction-window and balance heuristics plus imported sybil flags. No such filter is included in this allocator. Arbitrum eligibility methodology Recent primary research demonstrates why accuracy claims need labelled datasets: a May 2025 paper evaluates 193,701 addresses including 23,240 labelled sybils and reports metrics above 0.9, which are dataset results, not production Arbitrum or Optimism accuracy. Sybil detection research

Blur's rules describe bidding/listing/lending rather than simply rewarding executed trade volume, so comparing all its points to a v4 volume ranking would be misleading. Blur Season 4 rules A November 2024 participant reports missing stake visibility despite network/cache changes; this is an unresolved report, not a verified stolen-funds finding. Blur holder discussion INFERENCE: rank boosts and loyalty rewards can encourage optimization for score rather than beneficial liquidity. UNKNOWN: no primary recent wash-trading percentage or proved protocol loss was verified; old sensational figures are excluded rather than recycled as current facts.

6. Contracts and constructor-only deployment

These are Solidity interfaces and behavioral specifications, not implementations. No proxies, administrative recovery, blacklist, upgrade, pause or signer setter exists. All public operational actions are permissionless with state checks. The only fixed externally privileged identity is the assumed oracle signer, written as the literal source constant above. PoolManager and token constructor inputs are infrastructural references, not configurable administrators. Gateway and allocator links refer to newly created contracts fixed during construction, never arbitrary operator addresses.

Contract	Purpose and constructor	Storage	External access, events and invariants
EpochAllocator	Parent and oracle consumer. constructor(IPoolManager manager, address launchToken, address quoteToken, uint24 fee, int24 tickSpacing, uint256 budgetRaw, uint32 ratePpm, bytes32 hookSalt); creates gateway, then CREATE2 hook	Immutable manager, currencies, key, N=10, ceilings, templates, signer; epoch state, reservations, lists, sums, request-use flags, liabilities, claims	Anyone funds/allocates reserves before start, prepares, submits, finalizes, expires or claims. Events Funded, EpochPrepared, RankAccepted, SumAccepted, EpochFinalized, EpochExpired, Claimed. Immutable recipient/formula; reserves cover liabilities
ParticipantGateway	Authenticated execution. constructor(IPoolManager manager, IEpochAllocator allocator) called by parent	Immutable links; execution lock and active account	Anyone swaps as self. Only manager enters unlockCallback. Public msgSender view. SwapExecuted event. Never arbitrary calls, participants or pools; settlement ends with zero manager debt
ParticipantHook	Observation. constructor(IPoolManager manager, address gateway, address launchToken, address quoteToken, uint24 fee, int24 tickSpacing)	Immutable links/config; initializedPoolId and H	Only manager callbacks; public configuration views. PoolBound and ParticipantVolume. Correct selectors; afterSwap zero hook delta; unknown routers produce no reward log
Optional LaunchToken	Standard immutable fixed-supply launch ERC-20. constructor(string name, string symbol, uint256 supplyRaw)	Balances, allowances, supply; decimals fixed in source	Standard ERC-20 methods; Transfer/Approval. Entire exact policy supply minted to deployer; no later mint, transfer tax, rebasing or upgrade

Deploy launch token first if needed; otherwise use an existing reviewed token and deploy only three contracts. Deploy allocator with token and manager references. Allocator creates gateway with address(this); gateway queries the parent's immutable pool key only during later trades, never during parent construction. Parent creates hook referencing that gateway and assigns its hook/key immutables. Thus no circular initializer or setter is needed. Mine hookSalt against the actual parent's CREATE2 address and exact creation code before deployment; allocator constructor checks the resulting flags and reverts on mismatch. Optional launch token funding is a later user/sponsor action, not a link required to complete deployment. ASSUMPTION (IdentityMD): outer launcher supports parent-created children within its four-contract count and supplies $poolManager/$token; confirm this before implementation. No helper verifier/factory is separately deployed.

// Imports refer to pinned, vendored v4 types in the eventual implementation.
interface IParticipantGateway {
    function msgSender() external view returns (address);
    function swap(bool zeroForOne, int256 amountSpecified,
        uint160 sqrtPriceLimitX96, uint256 maxInput,
        uint256 minOutput, uint256 deadline) external returns (BalanceDelta);
    function unlockCallback(bytes calldata data) external returns (bytes memory);
}
interface IParticipantHook {
    function getHookPermissions() external pure returns (Hooks.Permissions memory);
    function initializedBlock() external view returns (uint256);
    function beforeInitialize(address sender, PoolKey calldata key,
        uint160 sqrtPriceX96) external returns (bytes4);
    function afterSwap(address sender, PoolKey calldata key,
        SwapParams calldata params, BalanceDelta delta,
        bytes calldata hookData) external returns (bytes4, int128);
}
interface IEpochAllocator {
    // Adapter bytes await a real signed ABI fixture; never guess wire types.
    function poolKey() external view returns (PoolKey memory);
    function fund(uint256 epoch, uint256 amount) external;
    function allocateReserve(uint256 epoch, uint256 amount) external;
    function prepare(uint256 epoch) external;
    function expectedQuestionHash(uint256 epoch, bool isRank,
        uint256 index) external view returns (bytes32);
    function submitRank(uint256 epoch, bytes calldata signedAttestation,
        bytes calldata signature) external;
    function submitSum(uint256 epoch, uint256 index,
        bytes calldata signedAttestation, bytes calldata signature) external;
    function finalize(uint256 epoch) external;
    function expire(uint256 epoch) external;
    function claim(uint256 epoch, uint256 index) external;
    function entitlement(uint256 epoch, uint256 index)
        external view returns (address participant, uint256 amount, bool claimed);
}
interface ILaunchToken {
    function totalSupply() external view returns (uint256);
    function decimals() external view returns (uint8);
    function balanceOf(address who) external view returns (uint256);
    function allowance(address owner, address spender) external view returns (uint256);
    function approve(address spender, uint256 amount) external returns (bool);
    function transfer(address to, uint256 amount) external returns (bool);
    function transferFrom(address from, address to, uint256 amount) external returns (bool);
}

Claims always pay the stored participant, even when a third party submits them; no redirect argument exists. Apply checks-effects-interactions and a reentrancy guard before token transfer. Gateway uses exact bounded approvals/transfers and manager settlement, and refunds only its current trader's unused funds. The hook never takes or mints manager assets. Reject fee-on-transfer/rebasing quote tokens at configuration/review; funding measures received balances, and invariants assume the approved token remains non-rebasing. A blocklisted beneficiary may be unable to claim without affecting other claims. There is no arbitrary-token rescue function. Principal risks from the pinned security reference incorporated here are signature replay, decimal errors, rounding, token quirks, reentry and discretionary authority; its illustrative spot-price and approval snippets are not imported blindly.

7. Foundry test plan

The eventual suite uses local real PoolManager deployments and vendored dependencies, never a network-dependent test prerequisite. Pin solc and v4 versions compatible with the target chain; v4's transient-storage requirements mean a blanket Paris EVM target is inappropriate without checking the actual core version. This report specifies tests; none of these behavioral tests ran, since no implementation is requested.

Named test	Required assertion/adversary
test_ConstructorLinksAllChildren	Deploy parent once; all references agree; no post-deploy initializer; optional token keeps total at four
test_HookFlagsAndSelectors	Address mask 0x2040 equals reported permissions; initialization and swap selectors match
test_EveryEnabledCallbackRejectsNonManager	Direct attacker calls to beforeInitialize and afterSwap revert, including authentic-looking sender/key
test_InitRejectsWrongKeyAndSecondPool	Wrong currencies, fees, spacing or second binding rejected; failed manager init rolls H back
test_LifecycleWithRealManager	Initialize, seed, buy/sell, partial fill, remove liquidity; no fabricated manager-code relocation
test_FreshManagerTokenOnlySeed	Ordinary valid funded swaps work without hook fee transfer or claim balance dependence
test_UnknownRouterTradesWithoutRewards	Pool remains usable; arbitrary msgSender convention produces no qualifying event
test_HookDataCannotSpoofVictim	Gateway hookData addresses do not alter recorded trader; direct fake hook calls fail
test_GatewayContextAndSettlement	Authentic caller recorded, both directions and exact modes bounded; failed settlement emits no surviving log
test_GatewayReentryAndForgedUnlock	Token callback reentry, direct unlock and nested execution fail; account context never leaks
test_QuoteUnitsAndNoDoubleCounting	Six/eighteen-decimal quote fixtures; only quote leg counted; zero and signed-min absolute conversion handled
test_CanonicalGoldenQuestionHashes	Real service golden JSON bytes/hash match Solidity serializer across decimal window/address boundaries
test_SignatureWireGoldenVectors	Real signed fixtures recover assumed service key; all dynamic fields encoded per actual schema
test_RejectWrongQuestionAndEvidence	Different event/pool/N/filter/window/evidence, bought for same consumer, cannot pass
test_RejectWrongDomainAndChain	Foreign consumer, domain name/version, consumer chain and data chain rejected
test_RejectTamperedEverySignedField	Mutate every field independently; invalid signatures cannot create claims
test_PanelAbsoluteFloors	5/3 passes; 4/3 and 5/2 fail; 100/3 is not rejected merely for its ratio; invalid counts fail
test_ExpiryAndWindowAdvancement	Future issue, old/expired signatures, overlap, gap, repeated closing block and wrong epoch fail
test_SumsReuseRankWindow	Same closing block for distinct sums allowed; different participant/filter/hash rejected
test_ListValidationAndTies	Empty/short list supported; duplicate/zero accounts, oversize list, malformed/trailing answer bytes rejected
test_VerifiedSumsCheckRankOrder	Positive verified sums must be descending; equal sums require numeric address tie order; rank inconsistency fails finalization
test_RequestAndClaimReplay	Reused accepted request, repeated sum/index, second finalization and double claim fail
test_RefusalMissingSumAndExpiry	No partial payouts; grace expiry unreserves without harming old claims; next epoch proceeds
test_FundingCannotChangeActiveBudget	Late funding rejected; exact reserve ceilings; direct token donations do not change entitlements
test_ClaimPaysOnlyStoredAccount	Relayer cannot redirect; token failure preserves entitlement; one bad recipient cannot block others
testFuzz_PayoutConservation	Bound positive volumes/budgets; total payouts <=B and each <=rV; dust never increases liabilities
invariant_ReservesCoverLiabilities	Across funding, finalization, expiry and claims, quote balance covers reservations plus unpaid claims
test_AdversarialSybilCutoffExample	Demonstrate membership/pro-rata redistribution under splitting; do not assert nonexistent sybil neutrality
test_AdversarialWashFeeRecapture	Simulate LP-owned fees and near-zero impact; demonstrate why gross fee is not a guaranteed cost floor
test_TokenProtectedFloor	If token included, exact policy supply/decimals, exact transfers, no mint even by deployer, no forbidden runtime escape opcodes

Offline implementation validation should include build, tests, format check and dry-run deployment without keys. Re-run meaningful fuzz invariants with a second seed and greater run count; do not assert exact gas or precomputed CREATE addresses. Retain the supplied protected floor tests unchanged in the independent verifier. Generate no fake signature fixtures signed by test keys and label them service interoperability evidence: mock-key tests prove only consumer logic. Static analysis and independent review remain future checks, not claimed completed work.

8. Risks ranked by severity

Severity	Risk	Who bears it / mitigation / residual
Critical	Service-key compromise, dishonest re-execution or wrong question serialization	Winners/sponsors; immutable template and floors reduce unrelated-answer attacks, but cannot cryptographically verify logs or agent independence
Critical	Attribution forgery or unsafe gateway settlement	Traders/sponsors; manager-only callbacks, fixed gateway and no arbitrary execution; full local lifecycle review required
High	Wash farming, fee recapture, sybil cutoff manipulation	Sponsor; caps and no wallet bonuses bound spend; positive reward remains economically conditional
High	Unknown real attestation types and canonical schema	Everyone; implementation blocked until actual golden fixtures and recipe grammar exist
High	Oracle refusal/censorship, sequential-window delay	Winners; permissionless submissions and expiry restore progress, not the expired rewards
Medium	Reorg/finality mismatch and stale archived documentation	Sponsor/winners; finalized request practice and exact windows; service-signed hash alone does not prove finality
Medium	Quote token blocks, rebases or malformed transfer behavior	Sponsor/recipient; restrict assets, SafeERC20, balance checks; external token governance may remain
Medium	Locked unspent reserves and sponsor operations	Sponsor; document absence of recovery; future capped allocation is possible, withdrawal is not
Medium	Subsidy mistaken for retention	Sponsor/community; report fees, persistent accounts and post-incentive activity separately from gross volume
Low	Rounding dust, storage/gas and source drift	Sponsor; bounded N, down-rounding and pinned implementation revisions; no gas figures invented

“No distributor can tamper” is an implementation invariant about fixed signed inputs and immutable formulas. “Nobody can tamper” is stronger than the evidence permits: the signing service and chain consensus remain trust boundaries. The design must advertise the former and disclose the latter.

9. Open questions for the IdentityMD developer

1. Can you provide the exact EIP-712 primary type string, every field type, answerType enum, dynamic answer encoding and real signed rank and sum fixtures addressed to a Sepolia consumer?
2. Does the signed chainId mean the data chain or consumer chain, and how does the service bind both when they differ?
3. Can you provide canonical question JSON and hash vectors, including window keys, evidence encoding, recipe placement, event filters and address formatting?
4. Does log-rank support poolId filtering, deterministic numeric-address tie-breaking, zero-total exclusion and short or empty results with the semantics specified here?
5. Can the service supply panelSize at least five and agreed at least three using absolute counts, and what are their run cost and availability guarantees?
6. What closing-block finality checks does the signer re-run, and can rank and sum requests require the same closing block hash?
7. How are refused, retried, duplicate and expired requests billed or refunded, and can a schedule generate participant-dependent sum requests after ranking?
8. Does the launch count include parent-created children, and can it mine a hook CREATE2 salt against the allocator's actual address and creation code?
9. How does the launch seed the allocator's quote-token reserve without post-deployment operator calls, if funding must be part of launch rather than later permissionless sponsorship?
10. Which quote token and actual pool fee will be used, and what defensible lower bound exists on attacker fee recapture and rebates before choosing a positive rate?
11. Is conditional economic protection acceptable, or must the top-N product be replaced by a mechanism that avoids ranking cliffs and verifies unrecoverable participant costs?
12. Is a trading-only first version acceptable, or will the service implement a re-runnable historical ownership-aware in-range liquidity-time recipe for LP rewards?