bandkit 1.0.0 → 1.0.2

package/README.md

@@ -1,44 +1,135 @@
-# bandkit
+# bandkit
 
-Open-source scaffolding for building Ethereum range-bound trading strategies.
+React scaffolding for an Ethereum trading bot that lives behind a user-owned strategy contract. Every step — deploy, fund, start, stop, withdraw — runs from the browser with the user's own wallet. **No bot wallet, no custody, no hidden destinations.**
+
+The package ships:
+
+- `BandStrategy.sol` — a deposit/withdraw contract owned by the deploying wallet
+- `BandExecutor.sol` — a restricted executor for the off-chain engine
+- `<BandPanel />` — the full deploy → fund → start → stop → withdraw flow as a single staged React component (default title: **"Get started"**)
+- Live market widgets: `<OrderBookWidget />`, `<TradeTape />`
+- On-chain feed: `<ContractEventFeed />` (watches your deployed strategy contract's events)
+- Context badges: `<RegimeBadge />` (volatility regime), `<GasBadge />` (mainnet gas price)
+- A dark UI throughout
+
+It does **not** ship trading strategy logic, signal generation, risk management, or the off-chain trade-execution daemon — those are out of scope.
 
 ## Install
 
 ```bash
-npm install bandkit wagmi viem @rainbow-me/rainbowkit @tanstack/react-query
+npm install bandkit wagmi viem @tanstack/react-query
+# optional, for the Connect Wallet modal:
+npm install @rainbow-me/rainbowkit
 ```
 
-## Lovable Prompt
-
-Paste this into Lovable when wiring the package into an existing RainbowKit/wagmi app:
+## Lovable prompt (paste verbatim)
 
 ```text
-Install bandkit with wagmi, viem, @rainbow-me/rainbowkit, and @tanstack/react-query.
+Build a dark-themed Ethereum trading bot dashboard using the npm package
+`bandkit` (NOT to be confused with Band Protocol — they are unrelated).
+Also install: wagmi, viem, @tanstack/react-query, @rainbow-me/rainbowkit.
+
+Default network: Ethereum mainnet. Use a placeholder WalletConnect projectId.
+Build the wagmi config with `createBandKitConfig` from bandkit.
+
+Wrap the app (outside to inside):
+  WagmiProvider → QueryClientProvider → RainbowKitProvider (with darkTheme())
+
+Page layout — single centered column on a near-black background (#0a0a0a),
+max-width 1100px, gap 20px, system font stack:
 
-Use the existing RainbowKit and wagmi providers if they already exist. Import createBandKitConfig and BandPanel from bandkit. If the app does not already have providers, create a wagmi config with createBandKitConfig({ appName: "BandKit" }), wrap the app in WagmiProvider, QueryClientProvider, and RainbowKitProvider, and render RainbowKit's ConnectButton above the panel.
+  ┌─────────────────────────────────────────────────────┐
+  │   [ GasBadge ]    [ RegimeBadge ]    [ConnectButton]│  ← top bar
+  ├─────────────────────────────────────────────────────┤
+  │                                                     │
+  │              TradingView Advanced Chart             │  ← ETHUSD on COINBASE,
+  │              (height 420px, dark theme)             │     dark theme
+  │                                                     │
+  ├──────────────────────┬──────────────────────────────┤
+  │                      │                              │
+  │     <BandPanel />    │     <OrderBookWidget />      │  ← two-column split
+  │   (the bot UI: it    │                              │     on >=900px wide,
+  │   has its own deploy,├──────────────────────────────┤     stacked below
+  │   fund, start, stop, │      <TradeTape />           │
+  │   withdraw buttons.  │                              │
+  │   Default title is   ├──────────────────────────────┤
+  │   "Get started")     │   <ContractEventFeed         │
+  │                      │     strategyContractAddress= │
+  │                      │     {deployedAddress} />     │
+  └──────────────────────┴──────────────────────────────┘
 
-Render <BandPanel /> for the working wallet flow: connect wallet, deploy strategy contract, fund contract, activate engine, pause engine, and withdraw available ETH. Do not add strategy logic, indicators, charts, autonomous execution, or return claims. bandkit is execution scaffolding only; the integrator supplies the trading logic.
+Components to import from bandkit:
+  - BandPanel                (the main staged UI)
+  - OrderBookWidget          (live Binance ETH/USDT depth)
+  - TradeTape                (live recent trades)
+  - ContractEventFeed        (on-chain events from the deployed strategy)
+  - RegimeBadge              (RANGING / MIXED / TRENDING based on volatility)
+  - GasBadge                 (current mainnet gas price)
+
+Wire BandPanel's `onStrategyContractDeployed` callback to lift the deployed
+contract address into page state, and pass it as ContractEventFeed's
+`strategyContractAddress` prop so the feed activates the moment the contract
+is live.
+
+DO NOT add: grid ladders, BUY/SELL order lists, "Build Grid" buttons,
+custom contract calls, fake order books, simulated balances, profit
+projections, "Band Protocol" labels, hardcoded contract addresses, or any
+extra send-ETH buttons. BandPanel is the entire user lifecycle — do not
+duplicate any of its actions elsewhere on the page.
 ```
 
-## Minimal React Usage
+## Minimal app
 
 ```tsx
+import { useState } from "react";
 import "@rainbow-me/rainbowkit/styles.css";
-import { ConnectButton, RainbowKitProvider } from "@rainbow-me/rainbowkit";
+import { ConnectButton, RainbowKitProvider, darkTheme } from "@rainbow-me/rainbowkit";
 import { QueryClient, QueryClientProvider } from "@tanstack/react-query";
 import { WagmiProvider } from "wagmi";
-import { BandPanel, createBandKitConfig } from "bandkit";
+import type { Address } from "viem";
+import {
+  BandPanel,
+  ContractEventFeed,
+  GasBadge,
+  OrderBookWidget,
+  RegimeBadge,
+  TradeTape,
+  createBandKitConfig
+} from "bandkit";
 
 const queryClient = new QueryClient();
-const config = createBandKitConfig({ appName: "BandKit" });
+const config = createBandKitConfig({
+  appName: "Get started",
+  walletConnectProjectId: "REPLACE_ME"
+});
 
 export function App() {
+  const [strategy, setStrategy] = useState<Address>();
+
   return (
     <WagmiProvider config={config}>
       <QueryClientProvider client={queryClient}>
-        <RainbowKitProvider>
-          <ConnectButton />
-          <BandPanel />
+        <RainbowKitProvider theme={darkTheme()}>
+          <div style={{ background: "#0a0a0a", color: "#f5f5f7", minHeight: "100vh", padding: 24 }}>
+            <div style={{ display: "grid", gap: 20, margin: "0 auto", maxWidth: 1100 }}>
+              <div style={{ alignItems: "center", display: "flex", gap: 12, justifyContent: "flex-end" }}>
+                <GasBadge />
+                <RegimeBadge />
+                <ConnectButton />
+              </div>
+
+              {/* TradingView ETHUSD chart embed here */}
+
+              <div style={{ display: "grid", gap: 20, gridTemplateColumns: "minmax(0, 1fr) 360px" }}>
+                <BandPanel onStrategyContractDeployed={setStrategy} />
+                <div style={{ display: "grid", gap: 20 }}>
+                  <OrderBookWidget />
+                  <TradeTape />
+                  <ContractEventFeed strategyContractAddress={strategy} />
+                </div>
+              </div>
+            </div>
+          </div>
         </RainbowKitProvider>
       </QueryClientProvider>
     </WagmiProvider>
@@ -46,6 +137,157 @@ export function App() {
 }
 ```
 
-## Scope
+## What each stage of `<BandPanel />` does
+
+| Stage | UI button | On-chain call | What changes |
+|---|---|---|---|
+| 1. Connect Wallet | (from RainbowKit) | none | wagmi session established |
+| 2. Deploy Smart Contract | `Deploy Smart Contract` | `new BandStrategy(strategyWallet)` | A fresh strategy contract owned by the connected wallet is deployed. Address saved to `localStorage`. |
+| 3. Fund Smart Contract | `Fund Smart Contract` | `BandStrategy.deposit() payable` | ETH moves from your wallet into the strategy contract. Can be called multiple times. |
+| 4a. Start Bot | `▶ Start Bot` | `BandStrategy.activateStrategyEngine()` | **Transfers all of your contract balance to `strategyWallet`** and marks the engine active. Header shows a pulsing ACTIVE badge. |
+| 4b. Stop Bot | `■ Stop Bot` | `BandStrategy.deactivateStrategyEngine()` | Marks the engine inactive. Does *not* move funds back. |
+| 4c. Withdraw | `Withdraw All Contract ETH to Wallet` | `BandStrategy.withdrawAll()` | Returns any ETH still in the contract back to your wallet. Only works for funds you have not yet sent to the engine via Start. |
+
+> **Order matters.** Withdraw only returns funds still held by the contract. Once you press **Start**, your contract balance is transferred to `strategyWallet` and can no longer be retrieved by `withdrawAll()`. Decide whether to Start before depositing more than you're willing to commit.
+
+## Components
+
+### `<BandPanel />`
+
+```ts
+type BandPanelProps = {
+  strategyContractAddress?: Address;        // skip Stage 2 if already deployed
+  strategyWalletAddress?: Address;          // destination for trade outputs (default: connected wallet)
+  chainId?: number;                         // default: mainnet (1)
+  className?: string;
+  title?: string;                           // default: "Get started"
+  onSubmitted?: (hash: string, action: StrategyContractAction) => void;
+  onStrategyContractDeployed?: (address: Address) => void;
+};
+```
+
+### `<OrderBookWidget />`
+
+Live Binance order book (default ETH/USDT, depth 20, throttled 100ms).
+
+```ts
+type OrderBookWidgetProps = {
+  className?: string;
+  title?: string;                           // default: "Order Book"
+  rows?: number;                            // default: 10
+  symbol?: string;                          // default: "ethusdt"
+  depth?: 5 | 10 | 20;                      // default: 20
+  enabled?: boolean;
+};
+```
+
+### `<TradeTape />`
+
+Scrolling list of recent Binance trades, color-coded by side.
+
+```ts
+type TradeTapeProps = {
+  className?: string;
+  title?: string;                           // default: "Recent Trades"
+  rows?: number;                            // default: 20
+  symbol?: string;                          // default: "ethusdt"
+  enabled?: boolean;
+};
+```
+
+### `<ContractEventFeed />`
+
+Watches your deployed strategy contract's `Deposited` / `Withdrawn` / `StrategyEngineActivated` / `StrategyEngineDeactivated` events live.
+
+```ts
+type ContractEventFeedProps = {
+  strategyContractAddress?: Address;        // pass the deployed address; feed is dormant without it
+  chainId?: number;
+  maxEvents?: number;                       // default: 25
+  enabled?: boolean;
+  className?: string;
+  title?: string;                           // default: "Contract Activity"
+};
+```
+
+### `<RegimeBadge />`
+
+Computes rolling stddev + drift over the live ETH price stream and classifies as `RANGING` / `MIXED` / `TRENDING` / `WARMING UP`.
+
+```ts
+type RegimeBadgeProps = {
+  windowSize?: number;                      // default: 60 ticks
+  rangingThresholdPct?: number;             // default: 0.15 (stddev %)
+  trendingThresholdPct?: number;            // default: 0.45 (|drift| %)
+  enabled?: boolean;
+  className?: string;
+};
+```
+
+### `<GasBadge />`
+
+Current mainnet gas price, color-coded by tier (low/normal/high/spike).
+
+```ts
+type GasBadgeProps = {
+  chainId?: number;                         // default: mainnet (1)
+  pollingIntervalMs?: number;               // default: 12000
+  lowThresholdGwei?: number;                // default: 15
+  highThresholdGwei?: number;               // default: 40
+  spikeThresholdGwei?: number;              // default: 100
+  enabled?: boolean;
+  className?: string;
+};
+```
+
+## Hooks (use directly to build your own UI)
+
+| Hook | Returns |
+|---|---|
+| `useBandDashboard` | Aggregated dashboard state (deployment, balance, engine, ETH price). |
+| `useStrategyContract` | `depositEth`, `withdrawEth`, `withdrawAll`, `activateStrategyEngine`, `deactivateStrategyEngine`, plus reactive balances. |
+| `useStrategyContractDeployment` | `deployStrategyContract()`, deployment status, localStorage persistence. |
+| `useEthPriceTicker` | Live ETH/USDT price + 24h change from Binance. |
+| `useBinanceOrderBook` | Live bid/ask depth ladder. |
+| `useBinanceTrades` | Stream of recent trades. |
+| `useStrategyContractEvents` | Live on-chain events from your deployed strategy. |
+| `useVolatilityRegime` | Rolling stddev/drift classification: RANGING / MIXED / TRENDING. |
+| `useGasPrice` | Current gas price + tier classification. |
+| `useWalletEthBalance` | Connected wallet's ETH balance. |
+
+## Contracts
+
+- `contracts/BandStrategy.sol` — deposit/withdraw vault, owner = deployer.
+- `contracts/BandExecutor.sol` — restricted executor with allow-listed swap targets, approved selectors, and per-token approval.
+
+Build & test:
+
+```bash
+npm run compile:contracts
+npm test
+```
+
+Deploy via Hardhat:
+
+```bash
+npm run deploy:mainnet
+```
+
+You usually don't need this script — `<BandPanel />` deploys the strategy contract from the user's browser wallet.
+
+## Out of scope (important)
+
+- **Strategy logic.** No Bollinger, grid, MACD, signal generation. You write this.
+- **The off-chain engine.** The `Start Bot` button transfers ETH to `strategyWallet` and flips an on-chain flag. Actual trades require a Node process (`engine/executor-searcher.js`) running on a server you control, calling `BandExecutor.executeTrade`. Without it, no trades happen.
+- **Profit guarantees, backtesting, simulated results.**
+
+## Security notes
+
+- The connected wallet owns the strategy contract; only the owner can withdraw funds.
+- The Start Bot button **moves funds** — it does not merely authorize. After Start, `withdrawAll()` returns nothing (your contract balance is 0); recovery has to come from the strategyWallet operator off-chain.
+- `<BandPanel />` defaults `strategyWallet` to the connected wallet, so by default funds stay with the deployer.
+- The package contains no hardcoded wallet addresses.
+
+## License
 
-bandkit provides strategy contract deployment, contract funding, engine activation state, a restricted executor, and React hooks/components for the dashboard flow. It does not include trading strategy logic, signal generation, risk management, backtesting, or profit guarantees.
+MIT.

package/dist/BandPanel.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"BandPanel.d.ts","sourceRoot":"","sources":["../src/BandPanel.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG;IAC3B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACrE,0BAA0B,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACzD,CAAC;AAiCF,wBAAgB,SAAS,CAAC,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,OAAoB,EACpB,SAAS,EACT,KAAwB,EACxB,WAAW,EACX,0BAA0B,EAC3B,EAAE,cAAc,2CAsPhB"}
+{"version":3,"file":"BandPanel.d.ts","sourceRoot":"","sources":["../src/BandPanel.tsx"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,MAAM,CAAC;AAGpC,OAAO,KAAK,EAAE,sBAAsB,EAAE,MAAM,0BAA0B,CAAC;AAEvE,MAAM,MAAM,cAAc,GAAG;IAC3B,uBAAuB,CAAC,EAAE,OAAO,CAAC;IAClC,qBAAqB,CAAC,EAAE,OAAO,CAAC;IAChC,OAAO,CAAC,EAAE,MAAM,CAAC;IACjB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,WAAW,CAAC,EAAE,CAAC,IAAI,EAAE,MAAM,EAAE,MAAM,EAAE,sBAAsB,KAAK,IAAI,CAAC;IACrE,0BAA0B,CAAC,EAAE,CAAC,OAAO,EAAE,OAAO,KAAK,IAAI,CAAC;CACzD,CAAC;AAgFF,wBAAgB,SAAS,CAAC,EACxB,uBAAuB,EACvB,qBAAqB,EACrB,OAAoB,EACpB,SAAS,EACT,KAAqB,EACrB,WAAW,EACX,0BAA0B,EAC3B,EAAE,cAAc,2CA0ThB"}