# DaWabLauncher Searcher Kit

Open-source integration infrastructure for three WABIT market surfaces:

- Robinhood Chain `WABIT/RHC-WETH`
- Ethereum `WABIT/WETH`
- Ethereum `WABIT/USDT`

The public **DaWabit API** is the canonical external integration surface. The
browser/module kit also preserves direct-RPC methods so searchers can
independently verify RHC execution state and Ethereum pool state before
trading.

The browser/module kit supplies **no trading capital**, stores **no private
keys**, and broadcasts **no transactions**. The open-source reference searcher
uses operator-supplied inventory, RPC infrastructure and signing credentials
when explicitly configured for live execution.

## Public API

Base URL: `https://api.dawabit.tech`

Key routes:

- `GET /v1/health`
- `GET /v1/markets`
- `GET /v1/markets/WABIT`
- `GET /v1/markets/WABIT/activity`
- `GET /v1/ethereum/markets`
- `POST /v1/quote`
- `POST /v1/execution/prepare`
- `GET /v1/stream`

`/v1/ethereum/markets` returns both canonical Ethereum WABIT pools from one
Ethereum block together with independent Chainlink USD references used for
cross-quote normalization.

## Install

```bash
npm install viem
```

## API-first example

```js
import { parseUnits } from 'viem';
import { DaWabSearcherKit } from './dawab-searcher-kit.mjs';

const kit = new DaWabSearcherKit();

const rhc = await kit.apiMarket('WABIT');
const eth = await kit.apiEthereumMarkets();
const buy = await kit.apiQuoteBuy(parseUnits('0.01', 18));

console.log({ rhc, eth, buy });
```

## User-signed execution preparation

```js
const prepared = await kit.prepareBuyExecution({
  amountWethIn: parseUnits('0.01', 18),
  sender: '0xYOUR_ADDRESS',
  slippageBps: 50,
  ttlSeconds: 120
});

console.log(prepared.execution.transaction);
```

The API prepares approval/swap calldata but does not sign or broadcast.
Execution remains user-signed and non-custodial.

## Direct-RPC verification

The direct-RPC methods remain available:

```js
const kit = new DaWabSearcherKit({
  rhcRpcUrl: process.env.RHC_RPC_URL,
  ethereumRpcUrl: process.env.ETHEREUM_RPC_URL
});

const state = await kit.curveState();
const buy = await kit.quoteBuy(parseUnits('0.01', 18));
const sell = await kit.quoteSell(parseUnits('100000000000', 18));
const l1 = await kit.l1ReferencePrices();
```

This split is intentional:

- **Public API:** canonical integration/discovery surface
- **Direct RPC:** independent execution preflight and verification
- **Substreams:** indexed market activity and provenance
- **Beacon/state.json:** advisory market-dislocation signal and discovery feed
- **Reference searcher:** route modeling, fork validation and protected
  autonomous execution

## Three-market arbitrage topology

```text
RHC WABIT/RHC-WETH
        ↕
ETH WABIT/WETH ↔ ETH WABIT/USDT
```

The production reference searcher models six explicit routes:

```text
ETH_WETH_TO_RHC
RHC_TO_ETH_WETH
ETH_USDT_TO_RHC
RHC_TO_ETH_USDT
ETH_WETH_TO_ETH_USDT
ETH_USDT_TO_ETH_WETH
```

Cross-chain routes assume **pre-positioned inventory**. Bridging is not part of
the atomic arbitrage path.

The API and browser Searcher Kit expose the market inputs; they do not promise
profitability. The reference searcher evaluates executable route economics and
can normalize WETH- and USDT-denominated legs with independent Chainlink
`ETH/USD` and `USDT/USD` references.

## Six-route fork validation

All six routes have been executed against pinned fork state at the reference
`0.01 WETH`-equivalent notional:

```text
Ethereum legs → Anvil mainnet forks
RHC legs      → Forge mainnet forks
broadcast     → NONE
```

The second leg consumes the **actual first-leg output**. Ethereum-only routes
execute both swaps sequentially on the same fork so the second leg observes the
first leg's state changes.

The validated snapshot produced `0.0000 bps` modeled-vs-executed output drift
for all six routes.

## Fork-calibrated route gas

Current reference gas-unit profiles:

```text
Route                         Ethereum   RHC
ETH_WETH_TO_RHC                 135232   259939
RHC_TO_ETH_WETH                 162565   731265
ETH_USDT_TO_RHC                 147591   259948
RHC_TO_ETH_USDT                 175568   731265
ETH_WETH_TO_ETH_USDT            305988        0
ETH_USDT_TO_ETH_WETH            305356        0
```

These are reference measurements, not immutable constants. Current RHC gas
profiles were measured while the WABIT market routes through the
**BondingCurve** venue and must be recalibrated after graduation to the AMM.

Route economics separate gas units from gas price:

```text
fork-calibrated route gas units
× live chain gas price
= modeled current route gas cost
```

The gas-adjusted model subtracts route gas from gross executable venue edge.
It still excludes bridge/rebalance cost, latency, MEV and execution
competition.

## Production live execution boundary

The six-route engine is fork-proven, but autonomous live execution remains
deliberately narrower.

The currently proven production route is economically:

```text
BUY Ethereum WETH → WABIT
SELL RHC WABIT → WETH
```

For execution safety, the production executor sends the capacity-sensitive RHC
sell first and then performs the mandatory Ethereum inventory hedge.

Reverse-direction, USDT and Ethereum-only routes are **not silently enabled for
autonomous live execution** merely because their fork simulations are proven.
Each production path still requires deliberate wallet, protection and
failure-recovery enablement.

## Machine discovery

- `https://dawabit.tech/.well-known/dawablauncher.json`
- `https://dawabit.tech/searcher/manifest.json`
- `https://dawabit.tech/searcher/state.json`
- `https://api.dawabit.tech`

The v1.3.0 discovery manifest advertises:

- RHC Substreams: `dawabit_substreams@v0.2.2` / `map_market_activity`
- Ethereum Substreams: `dawabit-eth-substreams@v0.1.0` /
  `map_eth_market_activity`
- RHC RPC + Ethereum RPC as current-state authorities
- the Ethereum markets API route
- three-market / six-route reference-searcher topology
- fork-validated route simulation
- route-specific gas calibration
- the current autonomous live-route boundary

## Beacon v0.5.0 market signal

Beacon v0.5.0 consumes the six-route `arbitrageEngine` from
`/searcher/state.json` and selects the **highest positive eligible
`netEdgePct`** at the `0.01 WETH`-equivalent reference notional.

The v0.5.0 publication signal therefore includes executable gross route edge,
fork-calibrated route-specific gas units, live Ethereum/RHC gas prices, and
modeled net-after-gas edge.

Cross-chain routes continue to assume pre-positioned inventory. Beacon does
**not** subtract bridge/rebalance cost and does not model latency, MEV or
execution competition.

The legacy `marketSignal.sameNotionalBuy.priceSpreadPct` surface is preserved
for backward compatibility, but it is no longer Beacon's primary trigger.

Manual Worker controls are authenticated in v0.5.0:

- `GET /run` — authenticated diagnostic dry-run; does not mutate KV.
- `POST /run?post=true` — authenticated manual publication path.
- Both require `Authorization: Bearer <BEACON_CONTROL_TOKEN>`.

## Autonomous reference searcher

Repository: `https://github.com/bizznezz89/dawab-searcher`

The executable reference searcher remains separate from the hosted browser
module. It supports paper/live modes, direct-RPC verification, three-market
route modeling, pinned-fork simulation, live gas normalization, protected
execution, persistent journaling and a durable circuit breaker using
operator-supplied infrastructure and credentials.

## RPC note

Public RPCs and public API feeds are useful for discovery and integration.
Latency-sensitive or capital-at-risk execution should independently verify
state using production-grade infrastructure.
