Solver

The Solver is a test market maker that provides quotes for the RFQ (Request for Quote) system. It generates signed quotes for users and submits RFQ theses to Kaizen Core.

Running

# Dry run (quotes only, no transactions)
pnpm run --filter mock-solver start -- --dry-run
 
# Custom port and multiplier
pnpm run --filter mock-solver start -- --port 3000 --multiplier 1.5
 
# Full options
pnpm run --filter mock-solver start -- \
  --rpc-url http://localhost:8545 \
  --ws-url ws://localhost:8546 \
  --port 3000 \
  --multiplier 1.5

CLI Options

Option	Description	Default
`-d, --dry-run`	Run without submitting transactions	`false`
`-r, --rpc-url <url>`	Kaizen Core RPC URL	`http://localhost:8545`
`-w, --ws-url <url>`	Kaizen Core WebSocket URL	`ws://localhost:8546`
`-k, --private-key <key>`	Solver private key (0x-prefixed, 64 hex chars)	From env
`-p, --port <port>`	API server port	`3000`
`-m, --multiplier <ratio>`	Base payout multiplier (1.0 - 10.0)	`1.5`
`--max-risk <amount>`	Max risk per thesis (USDC, 6 decimals)	`10000000000`

Environment Variables

Variable	Description
`KAIZEN_RPC_URL`	Kaizen Core RPC URL
`KAIZEN_WS_URL`	Kaizen Core WebSocket URL
`SOLVER_PRIVATE_KEY`	Solver wallet private key (0x-prefixed)

Supported Pairs

The mock solver supports the following trading pairs:

Base Token	Quote Token	Base Address
BTC	USDT	`0x0000000000000000000000000000000000000001`
ETH	USDT	`0x0000000000000000000000000000000000000002`
SOL	USDT	`0x0000000000000000000000000000000000000003`

Quote token address (USDT): 0x0000000000000000000000000000000000000100

API Reference

The solver exposes an HTTP API for quoting and thesis execution.

`GET /health`

Health check endpoint.

Response

{
  "status": "ok",
  "solver": "0x...",
  "dryRun": false
}

`GET /info`

Get solver information and configuration.

Response

{
  "address": "0x...",
  "balance": "1000000000",
  "dryRun": false,
  "config": {
    "basePayoutMultiplier": 1.5,
    "maxPayoutRatio": 10,
    "minBetAmount": "1",
    "maxBetAmount": "1000000000000",
    "minDuration": 1000,
    "maxDuration": 86400000
  }
}

Field	Description
`address`	Solver's address
`balance`	Solver's balance in USDC (6 decimals)
`dryRun`	Whether solver is in dry-run mode
`config.basePayoutMultiplier`	Base multiplier for payout calculation
`config.maxPayoutRatio`	Maximum allowed payout ratio
`config.minBetAmount`	Minimum bet amount (USDC, 6 decimals)
`config.maxBetAmount`	Maximum bet amount (USDC, 6 decimals)
`config.minDuration`	Minimum thesis duration (ms)
`config.maxDuration`	Maximum thesis duration (ms)

`GET /pairs`

List supported trading pairs.

Response

{
  "pairs": [
    {
      "base": "0x0000000000000000000000000000000000000001",
      "quote": "0x0000000000000000000000000000000000000100"
    },
    {
      "base": "0x0000000000000000000000000000000000000002",
      "quote": "0x0000000000000000000000000000000000000100"
    }
  ]
}

`POST /quote`

Request a signed quote for a trade.

Request Body

{
  "user": "0x...",
  "thesisType": "box",
  "base": "0x0000000000000000000000000000000000000001",
  "quote": "0x0000000000000000000000000000000000000100",
  "lowerPrice": "95000000000",
  "upperPrice": "105000000000",
  "betAmount": "1000000000",
  "startTime": 1700000000000,
  "endTime": 1700003600000,
  "deadline": 1700000060000
}

Field	Type	Description
`user`	Address	User's address
`thesisType`	string	Thesis type (only `"box"` supported)
`base`	Address	Base token address
`quote`	Address	Quote token address
`lowerPrice`	string	Lower price bound (bigint as string)
`upperPrice`	string	Upper price bound (bigint as string)
`betAmount`	string	Bet amount in USDC (bigint as string)
`startTime`	number	Thesis start time (Unix timestamp in ms)
`endTime`	number	Thesis end time (Unix timestamp in ms)
`deadline`	number	Quote deadline (Unix timestamp in ms)

Response (Success)

{
  "success": true,
  "quote": {
    "user": "0x...",
    "thesisType": "box",
    "oraclePair": { "base": "0x...", "quote": "0x..." },
    "priceRange": { "lower": "95000000000", "upper": "105000000000" },
    "betAmount": "1000000000",
    "payout": "1050000000",
    "startTime": 1700000000000,
    "endTime": 1700003600000,
    "deadline": 1700000060000,
    "signature": "0x..."
  }
}

Response (Error)

{
  "success": false,
  "error": "UNSUPPORTED_PAIR: Pair 0x.../0x... is not supported"
}

Error Codes

Code	Description
`UNSUPPORTED_PAIR`	Trading pair is not supported
`BET_TOO_SMALL`	Bet amount below minimum
`BET_TOO_LARGE`	Bet amount above maximum
`DURATION_TOO_SHORT`	Thesis duration below minimum
`DURATION_TOO_LONG`	Thesis duration above maximum
`INVALID_PRICE_RANGE`	Lower price >= upper price

`POST /execute`

Execute an RFQ thesis. The user submits the quote and their signature, and the solver submits the transaction to Kaizen Core.

Note: This endpoint is not available in dry-run mode.

Request Body

{
  "quote": {
    "user": "0x...",
    "thesisType": "box",
    "oraclePair": { "base": "0x...", "quote": "0x..." },
    "priceRange": { "lower": "95000000000", "upper": "105000000000" },
    "betAmount": "1000000000",
    "payout": "1050000000",
    "startTime": 1700000000000,
    "endTime": 1700003600000,
    "deadline": 1700000060000,
    "signature": "0x..."
  },
  "userSignature": "0x..."
}

Field	Type	Description
`quote`	object	The solver quote (returned from `/quote`)
`userSignature`	Hex	User's signature over the quote hash (65 bytes)

Response (Success)

{
  "success": true,
  "result": {
    "txHash": "0x...",
    "status": "committed",
    "thesisId": 42
  }
}

Field	Type	Description
`result.txHash`	Hex	Transaction hash
`result.status`	string	Transaction status (`"committed"` or `"failed"`)
`result.thesisId`	number	Thesis ID assigned by Core (optional)

Response (Error)

{
  "success": false,
  "error": "Quote deadline has passed"
}

Flow:

User gets a quote via POST /quote
User signs the quote hash (using SDK's signQuote method)
User sends quote + signature to POST /execute
Solver performs risk checks and hedging (simulated delay in mock)
Solver signs and submits RfqSubmit transaction to Core
Core validates signatures and creates the thesis

`POST /estimate`

Estimate payout without generating a signature. Useful for UI previews.

Request Body

{
  "thesisType": "box",
  "base": "0x0000000000000000000000000000000000000001",
  "quote": "0x0000000000000000000000000000000000000100",
  "lowerPrice": "95000000000",
  "upperPrice": "105000000000",
  "betAmount": "1000000000",
  "startTime": 1700000000000,
  "endTime": 1700003600000
}

Field	Type	Required	Description
`thesisType`	string	No	Thesis type (default: `"box"`)
`base`	Address	No	Base token address (default: BTC)
`quote`	Address	No	Quote token address (default: USDT)
`lowerPrice`	string	Yes	Lower price bound (bigint as string)
`upperPrice`	string	Yes	Upper price bound (bigint as string)
`betAmount`	string	Yes	Bet amount (bigint as string)
`startTime`	number	Yes	Thesis start time (Unix timestamp in ms)
`endTime`	number	Yes	Thesis end time (Unix timestamp in ms)
`deadline`	number	No	Quote deadline (default: now + 60s)

Response

{
  "success": true,
  "estimate": {
    "betAmount": "1000000000",
    "payout": "1070000000",
    "multiplier": "1.0700",
    "solverCollateral": "70000000"
  }
}

Field	Description
`estimate.betAmount`	User's bet amount
`estimate.payout`	Total payout if user wins
`estimate.multiplier`	Payout multiplier (formatted to 4 decimals)
`estimate.solverCollateral`	Solver's collateral (payout - betAmount)

Thesis Execution Flow

Solver Execution Flow

Key Points:

The solver submits the transaction to Core (not the user)
Core validates that tx.sender == solver (recovered from quote signature)
Core validates the user signature over the quote hash
The solver can perform risk checks and hedging before submitting
Settlements are handled automatically by Core (no challenge monitoring needed)

Payout Calculation

The mock solver calculates payouts with a random multiplier between 1.05x and 1.10x of the bet amount:

payout = betAmount * (1.05 + random * 0.05)

This is intentionally simplified for testing. Production solvers would implement sophisticated pricing based on:

Oracle price volatility
Thesis duration
Price range width
Market conditions