Solver quickstart

Run the reference solver

The repository ships a continuously polling worker with real X Layer Aave V3 and Curve lanes plus registered RWA acquisition through exact Ethereum calls. It creates evidence on a disposable pinned Anvil fork, then submits the signed decision to the same public API used by every community solver.

cp examples/open-solver/.env.example examples/open-solver/.env
# Add a dedicated REFERENCE_SOLVER_PRIVATE_KEY.
docker compose -f examples/open-solver/compose.yaml up -d --build

The solver key identifies and receives rewards for the solver. It cannot sign for a user and is never sent to Cobia. Keep the state volume: it prevents the worker from repeating a decision after a restart.

1. Register and observe

Fetch the signed policy and current verifier-owned competition state. Do not infer authority from display text. Recompute the policy commitment before work.

Register a canonical solver profile by signing its short-lived claim locally, then pass only the claim and signature to client.registerSolver. The SDK and exchange never receive the operator's private key or wallet session.

GET /api/intents returns the wallet-signed V3 policy, its verifier-captured block anchors, both commitments, and the decision endpoint. The SDK rejects a policy signature, snapshot hash, or policy commitment that does not match.

2. Decide or abstain

If the requested chain, asset, merchant, protocol identity, or outcome cannot be verified, submit a signed abstention. Never fabricate a route to satisfy availability. POST /api/intents/{intentId}/decisions accepts short-lived, operator-signed abstentions and immutable proposal revisions until close.

3. Build inside an isolated harness

Use read-only RPC, provider tools, local TypeScript, and tracing tools. A disposable pinned fork can reproduce state diffs when RPC simulation is not complete enough; it is verifier evidence, never a production execution fallback.

4. Emit artifacts

Write a decision, unsigned transaction program, provider artifacts, evidence, and run manifest. Every provider payload and generated file is hash committed.

5. Sign and submit

Commit the complete decision, bind it to the published snapshot hash, then sign the short-lived decision claim with the registered operator key. Submit claim, signature, and decision through client.submitDecision. Revisions are sequential and immutable; a newer revision does not erase history.

There are two proposal lanes:

• capability-v2 uses Cobia's pinned Aave, Curve, or Uniswap adapters and gets adapter-level semantic verification on X Layer.
• transaction-program accepts evm.raw@1 exact wallet calls and is open to other protocols and registered issuer-backed assets. Every target, calldata byte, approval, balance outcome, deployment identity, event set, and state delta must reproduce independently.

Paid x402 resources use the same bounded-program principle but currently have a separate commerce proposal and receipt-verification API. A supported listing pins the exact merchant resource, product description, price, payment asset, payee, and delivery commitment before the wallet signs. External catalog entries remain discovery-only.

Winning execution carries a capped 0.10 USDt0 success fee: 0.09 USDt0 to the selected solver identity and 0.01 USDt0 to Cobia. The wallet authorizes it when reviewing the winning program; settlement is deferred until Cobia confirms the exact execution receipt. Ambiguous settlement is never retried automatically.