bandkit 0.0.1 → 0.1.0

package/dist/useWalletEthBalance.js

@@ -0,0 +1,98 @@
+import { useCallback, useEffect, useState } from "react";
+import { formatEther } from "viem";
+import { useAccount } from "wagmi";
+import { mainnet } from "wagmi/chains";
+function getChromeWalletProvider() {
+    if (typeof window === "undefined")
+        return undefined;
+    return window.ethereum;
+}
+function chainIdToHex(chainId) {
+    return `0x${chainId.toString(16)}`;
+}
+function parseHexWei(value) {
+    return typeof value === "string" && value.startsWith("0x") ? BigInt(value) : 0n;
+}
+export function useWalletEthBalance(options = {}) {
+    const account = useAccount();
+    const address = options.address ?? account.address;
+    const chainId = options.chainId ?? mainnet.id;
+    const [balanceWei, setBalanceWei] = useState(0n);
+    const [isLoading, setIsLoading] = useState(false);
+    const [error, setError] = useState();
+    const refetch = useCallback(async () => {
+        if (!address) {
+            setBalanceWei(0n);
+            setError(undefined);
+            return;
+        }
+        const provider = getChromeWalletProvider();
+        if (!provider) {
+            setBalanceWei(0n);
+            setError(new Error("Chrome wallet provider is not available."));
+            return;
+        }
+        setIsLoading(true);
+        try {
+            const providerChainId = await provider.request({ method: "eth_chainId" });
+            if (providerChainId !== chainIdToHex(chainId)) {
+                setBalanceWei(0n);
+                setError(new Error("Switch your Chrome wallet to Ethereum mainnet."));
+                return;
+            }
+            const value = await provider.request({
+                method: "eth_getBalance",
+                params: [address, "latest"]
+            });
+            setBalanceWei(parseHexWei(value));
+            setError(undefined);
+        }
+        catch (caught) {
+            setBalanceWei(0n);
+            setError(caught instanceof Error ? caught : new Error(String(caught)));
+        }
+        finally {
+            setIsLoading(false);
+        }
+    }, [address, chainId]);
+    useEffect(() => {
+        void refetch();
+    }, [refetch]);
+    useEffect(() => {
+        if (!address)
+            return;
+        const intervalId = window.setInterval(() => {
+            void refetch();
+        }, 12_000);
+        return () => {
+            window.clearInterval(intervalId);
+        };
+    }, [address, refetch]);
+    useEffect(() => {
+        const provider = getChromeWalletProvider();
+        if (!provider?.on || !provider.removeListener)
+            return;
+        const refresh = () => {
+            void refetch();
+        };
+        provider.on("accountsChanged", refresh);
+        provider.on("chainChanged", refresh);
+        return () => {
+            provider.removeListener?.("accountsChanged", refresh);
+            provider.removeListener?.("chainChanged", refresh);
+        };
+    }, [refetch]);
+    return {
+        address,
+        balanceWei,
+        balanceEth: formatEther(balanceWei),
+        formatted: formatEther(balanceWei),
+        symbol: "ETH",
+        isLoading,
+        error,
+        refetch: () => {
+            void refetch();
+        }
+    };
+}
+//# sourceMappingURL=useWalletEthBalance.js.map

package/dist/useWalletEthBalance.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"useWalletEthBalance.js","sourceRoot":"","sources":["../src/useWalletEthBalance.ts"],"names":[],"mappings":"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"}

package/engine/browser-provider.js

@@ -0,0 +1,25 @@
+import { createPublicClient, createWalletClient, custom } from "viem";
+import { mainnet } from "viem/chains";
+
+export function getBrowserEthereumProvider() {
+  if (typeof window === "undefined" || !window.ethereum) {
+    throw new Error("No browser wallet provider found. Open this from a wallet-enabled browser or provide ENGINE_RPC_URL.");
+  }
+
+  return window.ethereum;
+}
+
+export function createBrowserPublicClient() {
+  return createPublicClient({
+    chain: mainnet,
+    transport: custom(getBrowserEthereumProvider())
+  });
+}
+
+export function createBrowserWalletClient(account) {
+  return createWalletClient({
+    account,
+    chain: mainnet,
+    transport: custom(getBrowserEthereumProvider())
+  });
+}

package/engine/executor-searcher.js

@@ -0,0 +1,138 @@
+#!/usr/bin/env node
+import {
+  formatEther,
+  isAddress,
+  parseAbi,
+  parseEther
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { createEnginePublicClient, createEngineWalletClient, providerMode } from "./provider.js";
+
+const executorAbi = parseAbi([
+  "function approvedSelectors(address target,bytes4 selector) view returns (bool)",
+  "function approvedTargets(address target) view returns (bool)",
+  "function engineWallet() view returns (address)",
+  "function executeTrade(address target,uint256 value,bytes data,uint256 minBalanceAfter) payable returns (bytes)",
+  "function paused() view returns (bool)"
+]);
+
+function requiredAddress(name) {
+  const value = process.env[name];
+  if (!value || !isAddress(value)) {
+    throw new Error(`${name} must be a valid Ethereum address.`);
+  }
+  return value;
+}
+
+function bigintEnv(name, fallback = 0n) {
+  const value = process.env[name];
+  if (!value) return fallback;
+  return BigInt(value);
+}
+
+function ethEnv(name, fallback = 0n) {
+  const value = process.env[name];
+  if (!value) return fallback;
+  return parseEther(value);
+}
+
+function hexEnv(name, fallback = "0x") {
+  const value = process.env[name] ?? fallback;
+  if (!/^0x([a-fA-F0-9]{2})*$/.test(value)) {
+    throw new Error(`${name} must be 0x-prefixed hex calldata.`);
+  }
+  return value;
+}
+
+const rpcUrl = process.env.ENGINE_RPC_URL;
+const executorAddress = requiredAddress("EXECUTOR_ADDRESS");
+const targetAddress = requiredAddress("TRADE_TARGET");
+const calldata = hexEnv("TRADE_CALLDATA");
+const calldataSelector = calldata.length >= 10 ? calldata.slice(0, 10) : undefined;
+const tradeValue = ethEnv("TRADE_VALUE_ETH", bigintEnv("TRADE_VALUE_WEI"));
+const minBalanceAfter = ethEnv("MIN_EXECUTOR_BALANCE_AFTER_ETH", bigintEnv("MIN_EXECUTOR_BALANCE_AFTER_WEI"));
+const shouldExecute = process.env.ENGINE_EXECUTE === "true";
+const dryRunAccount = process.env.ENGINE_ACCOUNT_ADDRESS;
+const privateKey = process.env.ENGINE_PRIVATE_KEY;
+
+const publicClient = createEnginePublicClient(rpcUrl);
+
+const account = privateKey
+  ? privateKeyToAccount(privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`)
+  : dryRunAccount && isAddress(dryRunAccount)
+    ? dryRunAccount
+    : undefined;
+
+if (!account) {
+  throw new Error("Set ENGINE_PRIVATE_KEY for execution or ENGINE_ACCOUNT_ADDRESS for dry-run simulation.");
+}
+if (!calldataSelector) {
+  throw new Error("TRADE_CALLDATA must include a 4-byte function selector.");
+}
+
+const [paused, engineWallet, targetApproved, selectorApproved, executorBalance] = await Promise.all([
+  publicClient.readContract({
+    address: executorAddress,
+    abi: executorAbi,
+    functionName: "paused"
+  }),
+  publicClient.readContract({
+    address: executorAddress,
+    abi: executorAbi,
+    functionName: "engineWallet"
+  }),
+  publicClient.readContract({
+    address: executorAddress,
+    abi: executorAbi,
+    functionName: "approvedTargets",
+    args: [targetAddress]
+  }),
+  publicClient.readContract({
+    address: executorAddress,
+    abi: executorAbi,
+    functionName: "approvedSelectors",
+    args: [targetAddress, calldataSelector]
+  }),
+  publicClient.getBalance({ address: executorAddress })
+]);
+
+console.log(`Executor: ${executorAddress}`);
+console.log(`Provider mode: ${providerMode(rpcUrl)}`);
+console.log(`Engine wallet: ${engineWallet}`);
+console.log(`Target: ${targetAddress}`);
+console.log(`Selector: ${calldataSelector}`);
+console.log(`Executor balance: ${formatEther(executorBalance)} ETH`);
+console.log(`Trade value: ${formatEther(tradeValue)} ETH`);
+console.log(`Minimum balance after: ${formatEther(minBalanceAfter)} ETH`);
+
+if (paused) throw new Error("Executor is paused.");
+if (!targetApproved) throw new Error("Trade target is not approved by the executor owner.");
+if (!selectorApproved) throw new Error("Trade selector is not approved for this target.");
+
+const simulation = await publicClient.simulateContract({
+  account,
+  address: executorAddress,
+  abi: executorAbi,
+  functionName: "executeTrade",
+  args: [targetAddress, tradeValue, calldata, minBalanceAfter],
+  value: tradeValue
+});
+
+console.log("Simulation passed.");
+
+if (!shouldExecute) {
+  console.log("Dry run only. Set ENGINE_EXECUTE=true and ENGINE_PRIVATE_KEY to send the transaction.");
+  process.exit(0);
+}
+
+if (!privateKey) {
+  throw new Error("ENGINE_PRIVATE_KEY is required when ENGINE_EXECUTE=true.");
+}
+
+const walletClient = createEngineWalletClient({
+  account,
+  rpcUrl
+});
+
+const hash = await walletClient.writeContract(simulation.request);
+console.log(`Submitted trade transaction: ${hash}`);

package/engine/provider.js

@@ -0,0 +1,32 @@
+import { createPublicClient, createWalletClient, custom, http } from "viem";
+import { mainnet } from "viem/chains";
+
+function getBrowserEthereumProvider() {
+  if (typeof window === "undefined" || !window.ethereum) return undefined;
+  return window.ethereum;
+}
+
+export function createEnginePublicClient(rpcUrl) {
+  const browserProvider = getBrowserEthereumProvider();
+
+  return createPublicClient({
+    chain: mainnet,
+    transport: rpcUrl ? http(rpcUrl) : browserProvider ? custom(browserProvider) : http("https://ethereum.publicnode.com")
+  });
+}
+
+export function createEngineWalletClient({ account, rpcUrl }) {
+  const browserProvider = getBrowserEthereumProvider();
+
+  return createWalletClient({
+    account,
+    chain: mainnet,
+    transport: rpcUrl ? http(rpcUrl) : browserProvider ? custom(browserProvider) : http("https://ethereum.publicnode.com")
+  });
+}
+
+export function providerMode(rpcUrl) {
+  if (rpcUrl) return "http-rpc";
+  if (getBrowserEthereumProvider()) return "browser-wallet";
+  return "public-rpc-fallback";
+}

package/engine/uniswap-v2-roundtrip.js

@@ -0,0 +1,215 @@
+#!/usr/bin/env node
+import {
+  encodeFunctionData,
+  formatEther,
+  isAddress,
+  maxUint256,
+  parseAbi,
+  parseEther
+} from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { createEnginePublicClient, createEngineWalletClient, providerMode } from "./provider.js";
+
+const UNISWAP_V2_ROUTER = "0x7a250d5630B4cF539739dF2C5dAcb4c659F2488D";
+const WETH = "0xC02aaA39b223FE8D0A0e5C4F27eAD9083C756Cc2";
+
+const executorAbi = parseAbi([
+  "function approvedSelectors(address target,bytes4 selector) view returns (bool)",
+  "function approvedTargets(address target) view returns (bool)",
+  "function approvedTokens(address token) view returns (bool)",
+  "function approveToken(address token,address spender,uint256 amount)",
+  "function engineWallet() view returns (address)",
+  "function executeBatch(address[] targets,uint256[] values,bytes[] payloads,uint256 minBalanceAfter) payable returns (bytes[])",
+  "function paused() view returns (bool)"
+]);
+
+const SWAP_EXACT_ETH_FOR_TOKENS_SELECTOR = "0x7ff36ab5";
+const SWAP_EXACT_TOKENS_FOR_ETH_SELECTOR = "0x18cbafe5";
+
+const erc20Abi = parseAbi([
+  "function allowance(address owner,address spender) view returns (uint256)"
+]);
+
+const routerAbi = parseAbi([
+  "function getAmountsOut(uint amountIn,address[] calldata path) view returns (uint[] memory amounts)",
+  "function swapExactETHForTokens(uint amountOutMin,address[] calldata path,address to,uint deadline) payable returns (uint[] memory amounts)",
+  "function swapExactTokensForETH(uint amountIn,uint amountOutMin,address[] calldata path,address to,uint deadline) returns (uint[] memory amounts)"
+]);
+
+function requiredAddress(name) {
+  const value = process.env[name];
+  if (!value || !isAddress(value)) throw new Error(`${name} must be a valid Ethereum address.`);
+  return value;
+}
+
+function optionalAddress(name, fallback) {
+  const value = process.env[name] ?? fallback;
+  if (!isAddress(value)) throw new Error(`${name} must be a valid Ethereum address.`);
+  return value;
+}
+
+function ethEnv(name, fallback) {
+  const value = process.env[name];
+  return value ? parseEther(value) : fallback;
+}
+
+function intEnv(name, fallback) {
+  const value = process.env[name];
+  return value ? Number.parseInt(value, 10) : fallback;
+}
+
+function applySlippage(value, slippageBps) {
+  return (value * BigInt(10_000 - slippageBps)) / 10_000n;
+}
+
+const rpcUrl = process.env.ENGINE_RPC_URL;
+const executorAddress = requiredAddress("EXECUTOR_ADDRESS");
+const tokenAddress = requiredAddress("TRADE_TOKEN");
+const routerAddress = optionalAddress("ROUTER_ADDRESS", UNISWAP_V2_ROUTER);
+const wethAddress = optionalAddress("WETH_ADDRESS", WETH);
+const tradeValue = ethEnv("TRADE_VALUE_ETH", parseEther("0.01"));
+const minProfit = ethEnv("MIN_PROFIT_ETH", 0n);
+const slippageBps = intEnv("SLIPPAGE_BPS", 50);
+const deadlineSeconds = intEnv("DEADLINE_SECONDS", 180);
+const shouldExecute = process.env.ENGINE_EXECUTE === "true";
+const privateKey = process.env.ENGINE_PRIVATE_KEY;
+const dryRunAccount = process.env.ENGINE_ACCOUNT_ADDRESS;
+
+if (slippageBps < 0 || slippageBps > 1_000) {
+  throw new Error("SLIPPAGE_BPS must be between 0 and 1000.");
+}
+
+const publicClient = createEnginePublicClient(rpcUrl);
+
+const account = privateKey
+  ? privateKeyToAccount(privateKey.startsWith("0x") ? privateKey : `0x${privateKey}`)
+  : dryRunAccount && isAddress(dryRunAccount)
+    ? dryRunAccount
+    : undefined;
+
+if (!account) throw new Error("Set ENGINE_PRIVATE_KEY for execution or ENGINE_ACCOUNT_ADDRESS for dry-run simulation.");
+
+const [paused, engineWallet, routerApproved, buySelectorApproved, sellSelectorApproved, tokenApproved, executorBalance] = await Promise.all([
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "paused" }),
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "engineWallet" }),
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "approvedTargets", args: [routerAddress] }),
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "approvedSelectors", args: [routerAddress, SWAP_EXACT_ETH_FOR_TOKENS_SELECTOR] }),
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "approvedSelectors", args: [routerAddress, SWAP_EXACT_TOKENS_FOR_ETH_SELECTOR] }),
+  publicClient.readContract({ address: executorAddress, abi: executorAbi, functionName: "approvedTokens", args: [tokenAddress] }),
+  publicClient.getBalance({ address: executorAddress })
+]);
+
+if (paused) throw new Error("Executor is paused.");
+if (!routerApproved) throw new Error("Router is not approved in BandExecutor.");
+if (!buySelectorApproved) throw new Error("Router buy selector is not approved in BandExecutor.");
+if (!sellSelectorApproved) throw new Error("Router sell selector is not approved in BandExecutor.");
+if (!tokenApproved) throw new Error("Trade token is not approved in BandExecutor.");
+if (executorBalance < tradeValue) throw new Error("Executor balance is lower than TRADE_VALUE_ETH.");
+
+const buyPath = [wethAddress, tokenAddress];
+const sellPath = [tokenAddress, wethAddress];
+const [buyQuote, sellQuote] = await Promise.all([
+  publicClient.readContract({ address: routerAddress, abi: routerAbi, functionName: "getAmountsOut", args: [tradeValue, buyPath] }),
+  publicClient.readContract({
+    address: routerAddress,
+    abi: routerAbi,
+    functionName: "getAmountsOut",
+    args: [
+      (await publicClient.readContract({
+        address: routerAddress,
+        abi: routerAbi,
+        functionName: "getAmountsOut",
+        args: [tradeValue, buyPath]
+      }))[1],
+      sellPath
+    ]
+  })
+]);
+
+const expectedTokenOut = buyQuote[1];
+const expectedEthOut = sellQuote[1];
+const expectedProfit = expectedEthOut - tradeValue;
+
+console.log(`Executor: ${executorAddress}`);
+console.log(`Provider mode: ${providerMode(rpcUrl)}`);
+console.log(`Engine wallet: ${engineWallet}`);
+console.log(`Router: ${routerAddress}`);
+console.log(`Token: ${tokenAddress}`);
+console.log(`Executor balance: ${formatEther(executorBalance)} ETH`);
+console.log(`Trade value: ${formatEther(tradeValue)} ETH`);
+console.log(`Expected token out: ${expectedTokenOut.toString()}`);
+console.log(`Expected ETH after round trip: ${formatEther(expectedEthOut)} ETH`);
+console.log(`Expected profit before gas: ${formatEther(expectedProfit)} ETH`);
+
+if (expectedProfit < minProfit) {
+  throw new Error(`Expected profit ${formatEther(expectedProfit)} ETH is below MIN_PROFIT_ETH ${formatEther(minProfit)} ETH.`);
+}
+
+const allowance = await publicClient.readContract({
+  address: tokenAddress,
+  abi: erc20Abi,
+  functionName: "allowance",
+  args: [executorAddress, routerAddress]
+});
+
+const walletClient = privateKey
+  ? createEngineWalletClient({ account, rpcUrl })
+  : undefined;
+
+if (allowance < expectedTokenOut) {
+  console.log("Executor token allowance is lower than expected token output.");
+
+  if (!shouldExecute || !walletClient) {
+    console.log("Dry run stopped before batch simulation. Run once with ENGINE_EXECUTE=true and ENGINE_PRIVATE_KEY to approve the router.");
+    process.exit(0);
+  }
+
+  const approvalHash = await walletClient.writeContract({
+    address: executorAddress,
+    abi: executorAbi,
+    functionName: "approveToken",
+    args: [tokenAddress, routerAddress, maxUint256]
+  });
+
+  console.log(`Submitted executor token approval: ${approvalHash}`);
+  await publicClient.waitForTransactionReceipt({ hash: approvalHash });
+  console.log("Executor token approval confirmed.");
+}
+
+const deadline = BigInt(Math.floor(Date.now() / 1000) + deadlineSeconds);
+const buyCalldata = encodeFunctionData({
+  abi: routerAbi,
+  functionName: "swapExactETHForTokens",
+  args: [applySlippage(expectedTokenOut, slippageBps), buyPath, executorAddress, deadline]
+});
+const sellCalldata = encodeFunctionData({
+  abi: routerAbi,
+  functionName: "swapExactTokensForETH",
+  args: [expectedTokenOut, applySlippage(expectedEthOut, slippageBps), sellPath, executorAddress, deadline]
+});
+const minBalanceAfter = executorBalance + minProfit;
+
+const simulation = await publicClient.simulateContract({
+  account,
+  address: executorAddress,
+  abi: executorAbi,
+  functionName: "executeBatch",
+  args: [
+    [routerAddress, routerAddress],
+    [tradeValue, 0n],
+    [buyCalldata, sellCalldata],
+    minBalanceAfter
+  ]
+});
+
+console.log(`Batch simulation passed. Minimum executor balance after: ${formatEther(minBalanceAfter)} ETH`);
+
+if (!shouldExecute) {
+  console.log("Dry run only. Set ENGINE_EXECUTE=true and ENGINE_PRIVATE_KEY to execute.");
+  process.exit(0);
+}
+
+if (!walletClient) throw new Error("ENGINE_PRIVATE_KEY is required when ENGINE_EXECUTE=true.");
+
+const hash = await walletClient.writeContract(simulation.request);
+console.log(`Submitted round-trip transaction: ${hash}`);

package/hardhat.config.cjs

@@ -0,0 +1,27 @@
+require("dotenv/config");
+require("@nomicfoundation/hardhat-ethers");
+
+const MAINNET_RPC_URL = process.env.MAINNET_RPC_URL ?? "";
+const DEPLOYER_PRIVATE_KEY = process.env.DEPLOYER_PRIVATE_KEY ?? "";
+
+const accounts = DEPLOYER_PRIVATE_KEY ? [DEPLOYER_PRIVATE_KEY] : [];
+
+/** @type {import("hardhat/config").HardhatUserConfig} */
+module.exports = {
+  solidity: {
+    version: "0.8.24",
+    settings: {
+      optimizer: {
+        enabled: true,
+        runs: 200
+      }
+    }
+  },
+  networks: {
+    mainnet: {
+      url: MAINNET_RPC_URL,
+      accounts,
+      chainId: 1
+    }
+  }
+};

package/package.json

@@ -1,27 +1,88 @@
-{
+{
   "name": "bandkit",
-  "version": "0.0.1",
-  "description": "Open-source scaffolding for Ethereum band-bound trading strategies. Placeholder release — full package coming soon.",
-  "main": "index.js",
-  "types": "index.d.ts",
+  "version": "0.1.0",
+  "description": "Open-source scaffolding for Ethereum range-bound trading strategies: strategy contract deployment, restricted executor, and React hooks. Strategy logic is not included.",
+  "license": "MIT",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "bin": {
+    "bandkit": "./bin/bandkit.js"
+  },
   "files": [
-    "index.js",
-    "index.d.ts",
+    "bin",
+    "engine",
+    "contracts",
+    "dist",
+    "scripts",
+    "hardhat.config.cjs",
+    ".env.example",
     "README.md",
     "LICENSE"
   ],
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "default": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "engine:execute": "node engine/executor-searcher.js",
+    "engine:simulate": "node engine/executor-searcher.js",
+    "engine:uniswap-v2": "node engine/uniswap-v2-roundtrip.js",
+    "bot:execute": "node -e \"console.warn('bot:execute is deprecated. Use engine:execute.'); import('./engine/executor-searcher.js')\"",
+    "bot:simulate": "node -e \"console.warn('bot:simulate is deprecated. Use engine:simulate.'); import('./engine/executor-searcher.js')\"",
+    "bot:uniswap-v2": "node -e \"console.warn('bot:uniswap-v2 is deprecated. Use engine:uniswap-v2.'); import('./engine/uniswap-v2-roundtrip.js')\"",
+    "build": "tsc -p tsconfig.build.json",
+    "clean": "rimraf dist artifacts cache typechain-types",
+    "compile:contracts": "hardhat compile",
+    "deploy:mainnet": "hardhat run scripts/deploy.cjs --network mainnet",
+    "test": "hardhat test",
+    "typecheck": "tsc --noEmit"
+  },
+  "peerDependencies": {
+    "@rainbow-me/rainbowkit": "^2.2.0",
+    "@tanstack/react-query": "^5.0.0",
+    "react": "^18.2.0 || ^19.0.0",
+    "viem": "^2.0.0",
+    "wagmi": "^2.0.0"
+  },
+  "peerDependenciesMeta": {
+    "@rainbow-me/rainbowkit": {
+      "optional": true
+    },
+    "@tanstack/react-query": {
+      "optional": true
+    }
+  },
+  "devDependencies": {
+    "@nomicfoundation/hardhat-ethers": "3.0.8",
+    "@rainbow-me/rainbowkit": "^2.2.0",
+    "@tanstack/react-query": "^5.0.0",
+    "@types/node": "^22.0.0",
+    "@types/react": "^19.0.0",
+    "chai": "^6.2.2",
+    "dotenv": "^16.4.7",
+    "fp-ts": "^2.16.11",
+    "hardhat": "2.22.19",
+    "react": "^18.3.1",
+    "react-dom": "^18.3.1",
+    "rimraf": "^6.0.1",
+    "ts-node": "^10.9.2",
+    "typescript": "^5.7.0",
+    "viem": "^2.0.0",
+    "wagmi": "^2.0.0"
+  },
   "keywords": [
     "ethereum",
-    "uniswap",
     "rainbowkit",
     "wagmi",
+    "uniswap",
     "range-trading",
+    "bollinger-bands",
     "defi",
     "open-source"
-  ],
-  "license": "MIT",
-  "author": "",
-  "engines": {
-    "node": ">=18"
-  }
+  ]
 }

package/scripts/deploy.cjs

@@ -0,0 +1,31 @@
+const hre = require("hardhat");
+
+const { ethers, network } = hre;
+
+async function main() {
+  if (network.name === "mainnet") {
+    console.log("Deploying BandStrategy to Ethereum mainnet.");
+  }
+
+  const [deployer] = await ethers.getSigners();
+  const BandExecutor = await ethers.getContractFactory("BandExecutor");
+  const executor = await BandExecutor.deploy(deployer.address);
+  await executor.waitForDeployment();
+
+  const executorAddress = await executor.getAddress();
+  const BandStrategy = await ethers.getContractFactory("BandStrategy");
+  const strategyContract = await BandStrategy.deploy(executorAddress);
+  await strategyContract.waitForDeployment();
+
+  const strategyContractAddress = await strategyContract.getAddress();
+  console.log(`Engine wallet/operator: ${deployer.address}`);
+  console.log(`BandExecutor deployed to: ${executorAddress}`);
+  console.log(`BandStrategy deployed to: ${strategyContractAddress}`);
+  console.log(`Strategy destination: ${await strategyContract.strategyWallet()}`);
+  console.log("Use the strategy contract address as VITE_BAND_STRATEGY_ADDRESS in your Lovable app.");
+}
+
+main().catch((error) => {
+  console.error(error);
+  process.exitCode = 1;
+});

package/index.d.ts

@@ -1,2 +0,0 @@
-// bandkit placeholder — full package coming soon.
-export {};