cocoa-butter/cca-bid-planner

What it does

Uniswap Continuous Clearing Auctions (CCA) run a uniform-price auction in continuous time, so a single bid at your maximum price fills at whatever the market clears at and gives you no view of how much budget returns as a refund. This project is a read-only planner for CCA auctions: given an auction, a budget and an assumption about external demand, it produces a bid schedule and simulates expected fill, average price, refund exposure and whether the auction graduates under several demand scenarios.

It never holds keys and never signs. The calldata command encodes submitBid arguments (with prevTickPrice hints and Permit2 or msg.value notes) for you to review and send with your own wallet. Outputs are labelled [obs] (read from chain), [der] (computed with protocol math) and [asm] (depends on your assumption).

The simulator is a bigint port of the contract's checkpoint, clearing-price and fill accounting, and is checked with a differential test that replays random auctions on the real ContinuousClearingAuction v2.1.0 with Foundry; the README reports equality to the wei across 300 auctions and 2,405 bids (math details).

Quick start

Requirements: Node 22 or later. viem is the only runtime dependency, and the package is not on the npm registry, so installing from GitHub builds it on install.

Run without installing:

npx github:cocoa-butter/cca-bid-planner --help

Or install the command globally:

npm install -g github:cocoa-butter/cca-bid-planner
cca-bid-planner --help

Then inspect an auction on a supported chain (robinhood, ethereum, base, unichain, arbitrum) and plan against it:

cca-bid-planner inspect --chain robinhood --auction 0x... --save slop.json
cca-bid-planner plan --snapshot slop.json --budget 25000 --max-price 0.02196

plan prints an ordered ladder with prices and amounts, plus a scenario table with external demand, tokens received, spent, average price, refund, final clearing price and graduation status. Options include --levels (default 5), --weighting flat|top|bottom|auto, --demand, --demand-ceiling and --arrival early|flat|late. plan --json output feeds into simulate --schedule and calldata --schedule, and calldata produces submitBid calldata you send yourself:

cca-bid-planner calldata --snapshot slop.json --schedule plan.json --owner 0xYourAddress

Browser and library use

The web app runs the same planner in the browser, reading an auction directly from a public RPC so nothing passes through a server; you can also paste a snapshot from inspect --save. Inputs live in the query string, so a plan can be shared as a link. For programmatic use, plan, readSnapshot, clientFor, toPriceQ96 and toRaw are exported, and the pure core is available as cca-bid-planner/core.

Constraints

• Every fill and price is conditional on the demand forecast, which is an assumption, not a price oracle.
• Auctions can fail to graduate: if currencyRaised never reaches requiredCurrencyRaised, all bids are refunded in full. Exits are restricted before graduation, and filled or at-clearing bids can only exit after the end block.
• Clearing can move before your transaction lands; a bid at or below the clearing price at inclusion reverts.
• The tool cannot check honeypot or fee-on-transfer tokens, the liquidity-launcher positionRecipient, or whether the floor price is fair.
• Out of scope: signing, key management, transaction submission, price prediction, non-CCA auctions, fee-on-transfer tokens, tokens with fewer than 6 decimals, and portfolios spanning several auctions.
• MIT licensed; the protocol contracts, ABI and constants come from Uniswap Labs and the project is not affiliated with Uniswap Labs.

HotRepo's take

The project appeared briefly on HotRepo's new-project list on 2026-11-05, recording 107 stars gained over a roughly 5.7-hour observation window with no forks; no all-language daily rank is recorded. That is a small sample, so it says little about sustained interest. The more concrete signal is the engineering effort described in the materials: a bigint port of the CCA accounting validated by a differential test against the pinned contract version, plus explicit labelling of what is observed, derived or assumed. For a niche DeFi planning tool, that specificity and the clear separation between simulation and signing are the parts worth evaluating.