configurator

What this skill does

# CCA Configuration

Configure Continuous Clearing Auction (CCA) smart contract parameters for fair and transparent token distribution.

> **Runtime Compatibility:** This skill uses `AskUserQuestion` for interactive prompts. If `AskUserQuestion` is not available in your runtime, collect the same parameters through natural language conversation instead.

## Instructions for Claude Code

When the user invokes this skill, guide them through a **bulk interactive form configuration flow** using AskUserQuestion. Collect parameters in batches to minimize user interaction rounds.

### Bulk Interactive Form Rules

1. **Batch questions** - Ask up to 4 questions at once using a single AskUserQuestion call
2. **Allow direct input** - For fields requiring custom values (addresses, numbers):
   - Provide a "Not available yet" or "Skip for now" option
   - The "Other" option (automatically provided) allows direct custom input
   - **NEVER** ask "Do you have X?" as a separate question
3. **Store answers** - Keep track of all collected values in a configuration object
4. **Validate after collection** - After each batch, validate all inputs before proceeding
5. **Show progress** - After each batch, show which parameters are collected and which remain

### Configuration Flow

Collect parameters in these batches:

#### Batch 1: Task Selection (1 question)

**Question 1: Task Type**

- Prompt: "What would you like to do with CCA?"
- Options: "Configure auction parameters", "Generate supply schedule only", "Review existing config", "Deploy existing config"

**After collection:** If not "Configure auction parameters", skip to appropriate section.

---

#### Batch 2: Basic Configuration (4 questions)

**Question 1: Network**

- Prompt: "Which network to deploy on?"
- Options: "Ethereum Mainnet", "Unichain (Mainnet)", "Unichain Sepolia (Testnet)", "Base", "Arbitrum", "Sepolia"
- Store: `chainId`, `blockTime`, `rpcUrl`, `currencyDecimals` (for selected currency)

**Question 2: Token Address**

- Prompt: "Token to be auctioned?"
- Options: "Token not deployed yet" (placeholder), Custom address (via "Other")
- Validation: Must be 42 chars starting with 0x
- Store: `token`

**Question 3: Total Supply**

- Prompt: "How many tokens to auction?"
- Options: "100 million tokens (18 decimals)", "1 billion tokens (18 decimals)", "10 billion tokens (18 decimals)", Custom (via "Other")
- Validation: Must be <= 1e30 wei
- Store: `totalSupply`

**Question 4: Currency**

- Prompt: "What currency should bidders use?"
- Options: "ETH (Native)", "USDC on [network]", "USDT on [network]", Custom ERC20 (via "Other")
- Validation: Must be 42 chars starting with 0x or address(0)
- Store: `currency`

**After collection:** Validate all inputs, show summary of basic configuration.

---

#### Batch 3: Timing & Pricing (4 questions)

**Question 1: Auction Duration**

- Prompt: "How long should the auction run?"
- Options: "1 day", "2 days", "3 days", "7 days", Custom blocks (via "Other")
- Calculate blocks based on network block time
- Store: `auctionBlocks`

**Question 2: Prebid Period**

- Prompt: "Include a prebid period? (time when no tokens are sold)"
- Options: "No prebid period (0 blocks)", "12 hours", "1 day", Custom blocks (via "Other")
- Calculate blocks based on network block time
- Store: `prebidBlocks`

**Question 3: Floor Price**

- Prompt: "Starting floor price? (ratio of currency per token)"
- Options: "0.10x (10% of 1:1 ratio)", "0.01x (1% of 1:1 ratio)", "0.001x (0.1% of 1:1 ratio)", Custom ratio (via "Other")
- Calculate Q96 value accounting for decimal differences: `Q96 * ratio / 10^(tokenDecimals - currencyDecimals)`
- For USDC (6 decimals) and 18-decimal token: `Q96 * ratio / 10^12`
- For native ETH (18 decimals) and 18-decimal token: `Q96 * ratio / 10^0 = Q96 * ratio`
- Store: `floorPriceRatio`, `floorPrice` (Q96), `tokenDecimals`, `currencyDecimals`

**Question 4: Tick Spacing**

- Prompt: "Tick spacing as percentage of floor price?"
- Options: "1% of floor price (Recommended)", "10% of floor price", "0.1% of floor price", Custom percentage (via "Other")
- Calculate: `tickSpacing = int(floorPrice * percentage)`
- **CRITICAL**: Round floor price DOWN to be evenly divisible by tick spacing:
  - `roundedFloorPrice = (floorPrice // tickSpacing) * tickSpacing`
  - Verify: `roundedFloorPrice % tickSpacing == 0` must be true
- Validate: Tick spacing must be >= 1 basis point of floor price
- Store: `tickSpacingPercentage`, `tickSpacing` (Q96), `roundedFloorPrice`

**After collection:** Validate inputs, verify floor price divisibility, calculate and display Q96 values, show timing summary.

---

#### Batch 4: Recipients & Launch (4 questions)

**Question 1: Tokens Recipient**

- Prompt: "Where should unsold tokens be sent?"
- Options: "Same as funds recipient", Custom address (via "Other")
- Validation: Must be 42 chars starting with 0x
- Store: `tokensRecipient`

**Question 2: Funds Recipient**

- Prompt: "Where should raised funds be sent?"
- Options: "Same as tokens recipient", Custom address (via "Other")
- Validation: Must be 42 chars starting with 0x
- Store: `fundsRecipient`

**Question 3: Start Time**

- Prompt: "When should the auction start?"
- Options: "In 1 hour", "In 6 hours", "In 24 hours", Custom block number (via "Other")
- Fetch current block number from RPC and calculate
- Store: `startBlock`
- Calculate: `endBlock = startBlock + prebidBlocks + auctionBlocks`, `claimBlock = endBlock`

**Question 4: Minimum Funds Required**

- Prompt: "Require minimum currency raised for graduation?"
- Options: "No minimum (0)", "100 ETH", "1000 ETH", Custom amount in wei (via "Other")
- Store: `requiredCurrencyRaised`

**After collection:** Validate addresses, fetch current block from RPC, calculate full block timeline.

---

#### Batch 5: Optional Hook (1 question)

**Question 1: Validation Hook**

- Prompt: "Use a validation hook contract?"
- Options: "No validation hook", Custom hook address (via "Other")
- Validation: Must be 42 chars starting with 0x (if provided)
- Store: `validationHook`

**After collection:** Validate hook address if provided.

---

#### Step 6: Generate Supply Schedule

**If MCP server is not running**, provide instructions to start it:

```bash
# Navigate to MCP server directory
cd packages/plugins/uniswap-cca/mcp-server/supply-schedule

# Run setup script (first time only)
chmod +x setup.sh
./setup.sh

# Start the MCP server
python3 server.py
```

Once the MCP server is running, call the `cca-supply-schedule__generate_supply_schedule` MCP tool with the collected parameters. The tool expects a JSON object:

```json
{
  "auction_blocks": 86400,
  "prebid_blocks": 0
}
```

Replace the values with the actual `auctionBlocks` and `prebidBlocks` collected from the user.

If the MCP tool is unavailable, use the fallback Python algorithm directly (see Supply Schedule Configuration section).

Store: `supplySchedule`

#### Step 7: Generate and Display Configuration

After collecting all parameters and generating the supply schedule, display the complete JSON configuration in the CLI output:

```json
{
  "[chainId]": {
    "token": "...",
    "totalSupply": ...,
    "currency": "...",
    "tokensRecipient": "...",
    "fundsRecipient": "...",
    "startBlock": ...,
    "endBlock": ...,
    "claimBlock": ...,
    "tickSpacing": ...,
    "validationHook": "...",
    "floorPrice": ...,
    "requiredCurrencyRaised": ...,
    "supplySchedule": [...]
  }
}
```

**Do NOT automatically create a file.** Let the user copy the JSON or specify a filepath to save it.

#### Step 8: Display Summary

Show the user a comprehensive formatted summary including:

- Network and chain ID
- Token and currency details
- Block timeline (start, end, claim) with human-readable times
- Pricing (floor price, tick spacing) in both Q96 and ratio formats
- Recipients (tokens, funds)
- Supply schedule summary (total phases, final block percentage)
- Validation checklist (all validation rules passed/fa