Queueball — A hook-gated launch round machine

drop in. wait for the gate. everyone in the same round clears together.

Abstract

Queueball is a Uniswap V4 launch token whose canonical pool hook rejects direct launch-window buys and routes buy intent into numbered escrow rounds. the problem is not price discovery itself; the problem is the private first fill, where the fastest path through the AMM can drain early liquidity before normal buyers arrive. Queueball replaces that sprint with visible cohort settlement: input is escrowed, each buyer receives a ball number, and each eligible round clears against hook-held $QBALL inventory using one clearing calculation. the design has no admin winner selection, no upgrade path, and no team withdrawal path for used launch input. buyers benefit by receiving a public ticket and a shared round price; the protocol benefits by turning launch fairness into the contract's actual state machine rather than a social promise.

1. Motivation

Uniswap V2 and V3 pools execute swaps continuously. that is the right primitive for liquid markets, but the first minutes of a token launch are not an ordinary market. a contract address becomes a starting gun, routing quality and block position dominate, and ordinary users often discover after the fact that the first fill was sold to speed rather than demand. batch auctions and sale contracts can address parts of this, but they often sit beside the AMM instead of binding the launch path to the pool itself.

Uniswap V4 changes the design space because hooks can enforce pool-local behavior. Queueball uses that property narrowly. during the launch window, the canonical $QBALL/input pool does not accept a normal direct buy path; the hook rejects it and requires queue entry through the pool-gated queue function. this keeps the fairness object attached to the same pool key buyers care about, rather than a separate sale page with a later migration.

The cultural reason matters too. launch buyers need a simple social object. “i got ball 42 in round 7” is easier to verify, post, and understand than “i hope the anti-snipe worked.” Queueball makes the launch moment visible without requiring a central operator to decide who gets filled.

2. Mechanic Specification

The hook stores an immutable launch `poolId`, validates that the supplied pool key names this hook, and maintains rounds, tickets, escrowed input, allocated $QBALL, claimed $QBALL, refundable input, and input locked forever. a ticket records its buyer, round id, ball number, input amount, filled $QBALL, refundable input, and claim state. a round records its ball count, input escrowed, inventory limit, input used, settlement status, and clearing rate.

The lifecycle begins at `beforeSwap`. while the launch window is open, a buy against the canonical launch pool reverts with `LaunchSwapMustQueue(poolId)`. the accepted path is `queueBuy(poolKey, buyer, inputAmount)`, callable through the pool manager path and checked against the same pool key. that function pulls input from the buyer into hook escrow and creates a ticket in the current round.

Settlement is public. when the round reaches its ball threshold or block clock, anyone can call `settleCurrentRound()`. the round computes the maximum $QBALL that can be allocated from its configured inventory and the hook's unallocated $QBALL balance. in plain notation:

`clearingRate = qballAllocatedToRound / inputUsedByRound`

and at ticket level:

`ticketFill = ticketInputUsed * clearingRate`

If demand exceeds the available round allocation, each ticket receives a pro-rata fill and the unused input becomes `inputRefund`. if demand is below the allocation, the round uses only the needed inventory and leaves the remainder unallocated for later rounds. claims transfer hook-held $QBALL to the buyer and release any refund.

Core invariants are simple. allocated-but-unclaimed $QBALL can never be allocated a second time. used input has no team withdrawal path and increments `totalInputLockedForever`. refundable input remains ticket-scoped until claim. after a ticket claims, it cannot claim again.

3. Worked Scenarios

**Scenario 1 — balanced round.** suppose a round has 3 buyers, 10 input total, and 10,000 $QBALL inventory available. settlement uses all 10 input and allocates 10,000 $QBALL. the clearing rate is 1,000 $QBALL per input. a 1 input ticket receives 1,000 $QBALL; a 4 input ticket receives 4,000 $QBALL.

**Scenario 2 — oversubscribed round.** suppose a round receives 20 input but only 10,000 $QBALL can be allocated. if settlement uses 10 input to clear the allocation, the clearing rate is still 1,000 $QBALL per used input, but each ticket uses only half its input. a buyer who queued 4 input receives 2,000 $QBALL and gets 2 input back in the refund tray.

**Scenario 3 — inventory protection.** suppose the hook has previously allocated 630,000,000 $QBALL and 5,000,000 remains unallocated from launch inventory. even if a later round's nominal setting is higher, settlement can allocate only from the unallocated hook balance. the machine cannot promise tokens already reserved for earlier tickets.

4. Security Model

Queueball defends specifically against private launch-window AMM fills on the canonical pool. it does not promise a fixed final market price, guaranteed allocation, or protection against changing demand across rounds. buyers in later rounds may clear at different rates than earlier rounds because they are different cohorts with different input and inventory conditions.

The largest integration risk is routing. the pool-manager path must use the queue entrypoint during launch; a normal direct buy against the canonical pool is expected to fail. this is intentional, but front ends and routers must surface it cleanly. state safety rests on ordinary escrow and claim correctness: no double claim, no double allocation, no allocation beyond hook-held inventory, and correct refund accounting.

There is no admin pause, upgrade, signer approval, or operator close. that removes discretionary abuse, but it also means parameter mistakes at deployment cannot be patched by governance. the design should be treated as an immutable machine: useful if built correctly, unforgiving if configured incorrectly.

5. Parameters & Deployment

  • Token: $QBALL
  • Total supply: 1,000,000,000 $QBALL
  • Launch inventory: 640,000,000 $QBALL staged into the hook
  • Post-launch liquidity vault: 260,000,000 $QBALL
  • Lab-board reserve: 100,000,000 $QBALL
  • AMM: Uniswap V4
  • Launch enforcement: `beforeSwap` rejects direct launch buys for the canonical pool
  • Queue route: `queueBuy(poolKey, buyer, inputAmount)`
  • Settlement: public `settleCurrentRound()` after round eligibility
  • Claim route: ticket-level `claim(ticketId)`
  • Hook contract: pending
  • Token contract: pending

6. Limitations & Future Work

Queueball is a launch-path mechanism, not a full market-making strategy. it makes the early buy path visible and cohort-based, but it cannot make demand uniform across time or guarantee that every queued buyer receives the desired amount. oversubscribed rounds produce refunds by design.

Future versions could add richer read-only round displays, route standards for wallets, and formal verification of allocation/refund invariants. those additions should not add admin discretion; the point of the machine is that the gate behaves the same for everyone in the round.

7. References

  • [Uniswap V4 Documentation](https://docs.uniswap.org/contracts/v4/overview) — overview of the V4 architecture and hooks.
  • [Uniswap V4 Hooks](https://docs.uniswap.org/contracts/v4/concepts/hooks) — hook lifecycle concepts relevant to launch enforcement.
  • [Uniswap V4 Core](https://github.com/Uniswap/v4-core) — reference implementation for V4 pool and hook interfaces.
  • [Batch Auctions](https://en.wikipedia.org/wiki/Call_market) — prior market structure for cohort-based clearing.
  • [ERC-20 Token Standard](https://eips.ethereum.org/EIPS/eip-20) — token interface baseline.

the fair launch is not a promise shouted over the rail. it is the gate.