TECHNICAL REFERENCE / PRE-LAUNCH
This is an implementation reference for the contracts and keeper in this repository—not a yield page. It distinguishes deployed behavior from pending launch work and names the operational trust assumptions.
System overview
Basket has one intended ETH/BASKET Uniswap v4 market. Its hook collects a 3% native-ETH fee on both directions of trade and forwards it to DividendVault. The vault accounts for 10% of each allocation as protocol revenue and makes the remaining 90% available for B20 stock purchases.
| Destination | Rate | How it is accounted for |
|---|---|---|
| LP fee | 1.00% | Pool configuration; separate from the hook. |
| Hook fee | 3.00% | Collected in native ETH by BasketFeeHook. |
| B20 purchase budget | 2.70% | 90% of the hook allocation, split by active basket weights. |
| Protocol revenue | 0.30% | 10% of the hook allocation, tracked as platformClaimable. |
Important: the hook itself only collects the 3% fee. It does not initialize a pool, choose a price or provide liquidity.
Contract reference
These are the source modules that define the protocol today. There are no production Basket contract addresses yet.
src/BasketToken.solFixed-supply BASKET ERC-20. Maintains the enumerable holder registry used by the vault; it does not ask an indexer or explorer for recipients.
src/BasketFeeHook.solThe Uniswap v4 hook attached to the intended ETH/BASKET pool. It takes 300 bps in native ETH and settles it directly to the vault.
src/DividendVault.solHolds hook ETH and acquired B20 balances, tracks protocol revenue, snapshots eligible holders and pushes dividends in batches.
keeper/src/keeper.tsOff-chain executor for quotes, buy transactions and payout batches. It reads the recipient set from contracts; it never uploads a holder list.
The pool must place native ETH in currency0. The hook collects before the swap when ETH is specified, and after the swap when it is not. It uses Uniswap v4 return deltas to settle exactly 300 bps to the vault.
Distribution cycle
The keeper discovers B20 swap routes off-chain, but it does not build a Merkle tree or submit an address list. Recipient enumeration, captured balances and payout accounting live in the token and vault contracts.
buyStocks(minOuts, routerCalldatas)KeeperUses available native ETH, retains 10% in platformClaimable and divides the other 90% over the current active basket by weight. Every configured stock must have a complete route or the supplied keeper skips the buy.
snapshotHolders(count)KeeperReads BasketToken.holderAt(i) in pages, excludes infrastructure and reward-excluded accounts, records balance plus address in one word, and accumulates eligibleSupply.
startCycle()KeeperRequires a complete snapshot (or creates a one-transaction snapshot for a small registry), freezes each distributable B20 pot and sets nextDistribution to now + 1 hour.
distributeBatch(count)KeeperPushes every frozen B20 asset to the next page of recipients. A failed B20 receiver-policy check records an unpaid entitlement instead of reverting the whole batch.
flushUnpaidDividend(holder, stock)AnyoneRetries a recorded failed payment to its original holder. It cannot redirect that entitlement or redivide it across other accounts.
stock pot × min(snapshot balance, live balance) ÷ eligibleSupplyTiming: nextDistribution is set when startCycle() begins, so a new cycle cannot start for one hour. Stock purchases are keeper-driven and are not independently rate-limited by this interval.
Eligibility & accounting
BasketToken maintains an array of eligible accounts every time a balance changes. Accounts qualify at the current threshold, initially 100,000 BASKET; governance can only set it between 10,000 and 100,000 BASKET.
The vault calls holderCount() and holderAt(i). Its keeper can therefore distribute without Blockscout, Etherscan or an off-chain holder database.
At payment, the snapshot amount is capped to the holder's current balance. A balance returned after capture cannot receive the full historic weight.
If a B20 receiver policy rejects a transfer, the amount is recorded as unpaid for that holder and can be retried with flushUnpaidDividend.
Roles & controls
Can change policy and use the ERC-20 emergency path. This is a material trust role and should be a multisig at deployment.
Can buy stocks and advance snapshots and payouts, but cannot change thresholds, basket weights, recipients or ownership.
Can claim platformClaimable. The owner can rotate this recipient; it has no direct access to the stock budget.
Can call flushUnpaidDividend, but tokens can only be sent to the recorded rightful holder.
| Token eligibility | setMinShareBalance(10k–100k) and setRewardsExcluded. |
|---|---|
| Basket policy | setBasket(stocks, weights) between cycles only; weights must total 10,000 bps. |
| Operators | setKeeper, setPlatformRecipient and setMaxGrossSpendPerCycle. |
| Infrastructure | setExcluded accepts contract addresses only, protecting ordinary wallet holders from this vault-level control. |
| Emergency path | emergencyWithdrawERC20 can recover every ERC-20 in custody, including B20 stocks; it intentionally has no matching native-ETH path. |
buyStocks forwards keeper-supplied router calldata and keeper-supplied minimum outputs. The configured cap applies per buyStocks call, not to a calendar-hour total. Separately, abortCycle() clears a partial cycle without recording which holders were already paid; it should not be used after any payout batch. These are current implementation constraints, not guarantees removed by the UI.Trading & liquidity
Basket is designed around one ETH/BASKET Uniswap v4 pool. Liquidity providers set the initial price and add liquidity in a separate pool-initialization transaction; the hook does neither. Until that happens, BASKET has no live market or price.
The intended pool uses a 1% LP fee plus Basket's 3% native-ETH hook fee on buys and sells. The hook fee is forwarded to the dividend vault.
Dividends are paid in the B20 assets acquired by the vault. B20 assets can apply their own sender and receiver transfer policies.
The keeper buys the active basket only when every configured stock has a complete route. If one is unavailable, hook ETH remains in the vault for a later attempt.
Pre-launch: the deployment script deliberately leaves the pool uninitialized. Pool price, liquidity and the first public BASKET route are launch decisions, not protocol constants.
Deployment status
| Base chain | 8453 | Target network |
|---|---|---|
| v4 PoolManager | 0x498581fF718922c3f8e6A244956aF099B2652b2b | Uniswap deployment reference ↗ |
| Universal Router | 0x6fF5693b99212Da76ad316178A184AB56D299b43 | Immutable vault dependency |
| BASKET / vault / hook | Not deployed | Publish verified addresses here after deployment |
Deploy the token, vault and CREATE2-mined hook; set the multisig owner, platform recipient, keeper and a reviewed spend cap.
Decide the initial ETH/BASKET price and liquidity separately. The deployment script deliberately does not initialize a v4 pool.
Confirm each active B20 route and receiver policy. The supplied keeper skips a full buy when any active stock has no complete route.
Publish verified addresses, multisig and keeper policy, monitoring, and the first distribution transaction data before calling the market live.
RELATED
Until the protocol is live, the dashboard intentionally shows no estimated APY or simulated payout history.
Distribution desk →