apow-cli 0.1.3 → 0.2.0

package/.env.example

@@ -19,6 +19,10 @@ LLM_API_KEY=
 # Ollama (only if LLM_PROVIDER=ollama)
 # OLLAMA_URL=http://127.0.0.1:11434
 
+# Solana bridging (only needed for `apow fund --solana`)
+# SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+# SQUID_INTEGRATOR_ID=
+
 # Contract addresses (defaults built-in, override only if needed)
 # MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 # AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3

package/README.md

@@ -34,8 +34,9 @@ LLM_MODEL=gpt-4o-mini
 LLM_API_KEY=<your key>
 EOF
 
-# 3. Ask your user to fund the wallet with ≥0.005 ETH on Base
-#    This is the ONLY step that requires human action
+# 3. Fund the wallet (bridge from Solana or send ETH on Base)
+npx apow-cli fund --solana            # bridge SOL → ETH on Base
+# Or ask your user to send ≥0.005 ETH on Base directly
 
 # 4. Mint a mining rig NFT (solves SMHL challenge via LLM)
 npx apow-cli mint
@@ -66,7 +67,8 @@ If you prefer to do it yourself:
 # 1. Interactive setup — wallet, RPC, LLM config
 npx apow-cli setup
 
-# 2. Fund your wallet with ETH on Base (≥0.005 ETH)
+# 2. Fund your wallet (bridge from Solana or send ETH directly)
+npx apow-cli fund
 
 # 3. Mint a mining rig NFT
 npx apow-cli mint
@@ -80,6 +82,7 @@ npx apow-cli mine
 | Command | Description |
 |---------|-------------|
 | `apow setup` | Interactive setup wizard — configure wallet, RPC, and LLM |
+| `apow fund` | Fund your wallet — bridge SOL → ETH on Base, or show deposit address |
 | `apow wallet new` | Generate a new mining wallet |
 | `apow wallet show` | Show configured wallet address |
 | `apow wallet export` | Export your wallet's private key |
@@ -98,6 +101,9 @@ RPC_URL=https://mainnet.base.org
 LLM_PROVIDER=openai            # openai | anthropic | gemini | ollama | claude-code | codex
 LLM_MODEL=gpt-4o-mini
 LLM_API_KEY=sk-...
+# Solana bridging (only for `apow fund --solana`)
+# SOLANA_RPC_URL=https://api.mainnet-beta.solana.com
+# SQUID_INTEGRATOR_ID=          # free, get at squidrouter.com (deposit address flow only)
 # Contract addresses (defaults built-in, override only if needed)
 # MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 # AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3

package/dist/bridge/debridge.js

@@ -0,0 +1,128 @@
+"use strict";
+// deBridge DLN bridge — direct signing flow (Option A).
+// SOL → native ETH on Base in ~20 seconds via DLN market makers.
+// No API key needed.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.bridgeViaDeBridge = bridgeViaDeBridge;
+exports.pollOrderStatus = pollOrderStatus;
+const solana = __importStar(require("./solana"));
+const DLN_API = "https://dln.debridge.finance/v1.0";
+const SOLANA_CHAIN_ID = "7565164";
+const BASE_CHAIN_ID = "8453";
+const NATIVE_SOL = "11111111111111111111111111111111"; // System Program = native SOL
+const NATIVE_ETH = "0x0000000000000000000000000000000000000000";
+/**
+ * Create and submit a deBridge DLN order: SOL → ETH on Base.
+ * Returns after the Solana tx is confirmed. Call pollOrderStatus() to wait for fulfillment.
+ */
+async function bridgeViaDeBridge(solanaKeypair, baseAddress, solAmount) {
+    const startTime = Date.now();
+    const lamports = Math.floor(solAmount * 1e9);
+    const srcPublicKey = solanaKeypair.publicKey.toBase58();
+    // Step 1: Get serialized bridge transaction from DLN
+    const params = new URLSearchParams({
+        srcChainId: SOLANA_CHAIN_ID,
+        srcChainTokenIn: NATIVE_SOL,
+        srcChainTokenInAmount: lamports.toString(),
+        dstChainId: BASE_CHAIN_ID,
+        dstChainTokenOut: NATIVE_ETH,
+        dstChainTokenOutRecipient: baseAddress,
+        senderAddress: srcPublicKey,
+        srcChainOrderAuthorityAddress: srcPublicKey,
+        dstChainOrderAuthorityAddress: baseAddress,
+    });
+    const response = await fetch(`${DLN_API}/dln/order/create-tx?${params}`);
+    if (!response.ok) {
+        const body = await response.text();
+        throw new Error(`deBridge API error (${response.status}): ${body}`);
+    }
+    const data = await response.json();
+    if (data.errorCode || data.error) {
+        throw new Error(`deBridge error: ${data.error || data.message || JSON.stringify(data)}`);
+    }
+    const orderId = data.orderId;
+    const txData = data.tx?.data;
+    if (!txData) {
+        throw new Error("deBridge API returned no transaction data");
+    }
+    // Step 2: Sign and submit on Solana
+    const txSignature = await solana.signAndSendTransaction(txData, solanaKeypair);
+    return {
+        orderId,
+        txSignature,
+        status: "submitted",
+        timeMs: Date.now() - startTime,
+    };
+}
+/**
+ * Poll deBridge order status until fulfilled, cancelled, or timeout.
+ * Default timeout: 5 minutes.
+ */
+async function pollOrderStatus(orderId, onUpdate, timeoutMs = 300_000) {
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const response = await fetch(`${DLN_API}/dln/order/${orderId}/status`);
+            if (response.ok) {
+                const data = await response.json();
+                const status = data.status || data.orderStatus || "unknown";
+                if (onUpdate)
+                    onUpdate(status);
+                if (status === "Fulfilled" ||
+                    status === "ClaimedUnlock" ||
+                    status === "SentUnlock") {
+                    return {
+                        status: "fulfilled",
+                        ethReceived: data.fulfilledDstAmount
+                            ? (Number(data.fulfilledDstAmount) / 1e18).toFixed(6)
+                            : undefined,
+                    };
+                }
+                if (status === "Cancelled" || status === "CancelledByMaker") {
+                    throw new Error(`Bridge order was cancelled: ${status}`);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error && err.message.includes("cancelled"))
+                throw err;
+            // Transient fetch error — keep polling
+        }
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    throw new Error("Bridge order timed out after 5 minutes. Check deBridge explorer for order: " +
+        orderId);
+}

package/dist/bridge/solana.js

@@ -0,0 +1,129 @@
+"use strict";
+// Solana wallet utilities — key parsing, balance checks, transaction signing.
+// Uses dynamic import() for @solana/web3.js to avoid bloating startup.
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getSolanaRpcUrl = getSolanaRpcUrl;
+exports.parseSolanaKey = parseSolanaKey;
+exports.getSolanaBalance = getSolanaBalance;
+exports.getAddressBalance = getAddressBalance;
+exports.signAndSendTransaction = signAndSendTransaction;
+const DEFAULT_SOLANA_RPC = "https://api.mainnet-beta.solana.com";
+const BASE58_ALPHABET = "123456789ABCDEFGHJKLMNPQRSTUVWXYZabcdefghijkmnopqrstuvwxyz";
+function base58Decode(str) {
+    const bytes = [];
+    for (const char of str) {
+        const idx = BASE58_ALPHABET.indexOf(char);
+        if (idx === -1)
+            throw new Error(`Invalid base58 character: ${char}`);
+        let carry = idx;
+        for (let j = 0; j < bytes.length; j++) {
+            carry += bytes[j] * 58;
+            bytes[j] = carry & 0xff;
+            carry >>= 8;
+        }
+        while (carry > 0) {
+            bytes.push(carry & 0xff);
+            carry >>= 8;
+        }
+    }
+    // Preserve leading zeros
+    for (const char of str) {
+        if (char !== "1")
+            break;
+        bytes.push(0);
+    }
+    return new Uint8Array(bytes.reverse());
+}
+function getSolanaRpcUrl() {
+    return process.env.SOLANA_RPC_URL || DEFAULT_SOLANA_RPC;
+}
+/** Parse a base58-encoded Solana secret key (64 bytes) or seed (32 bytes). */
+async function parseSolanaKey(input) {
+    const { Keypair } = await Promise.resolve().then(() => __importStar(require("@solana/web3.js")));
+    const trimmed = input.trim();
+    // Try JSON array format first (Solana CLI keygen output)
+    if (trimmed.startsWith("[")) {
+        try {
+            const arr = JSON.parse(trimmed);
+            const keypair = Keypair.fromSecretKey(new Uint8Array(arr));
+            return { keypair, publicKey: keypair.publicKey.toBase58() };
+        }
+        catch {
+            throw new Error("Invalid Solana key: looks like JSON but could not parse.");
+        }
+    }
+    // Base58 secret key (Phantom, Backpack export format)
+    const decoded = base58Decode(trimmed);
+    if (decoded.length === 64) {
+        const keypair = Keypair.fromSecretKey(decoded);
+        return { keypair, publicKey: keypair.publicKey.toBase58() };
+    }
+    if (decoded.length === 32) {
+        // 32-byte seed
+        const keypair = Keypair.fromSeed(decoded);
+        return { keypair, publicKey: keypair.publicKey.toBase58() };
+    }
+    throw new Error(`Invalid Solana key: expected 64 bytes (secret key) or 32 bytes (seed), got ${decoded.length}. Provide the full base58-encoded secret key from your wallet.`);
+}
+/** Get SOL balance for a public key (in SOL, not lamports). */
+async function getSolanaBalance(publicKeyBase58) {
+    const { Connection, PublicKey } = await Promise.resolve().then(() => __importStar(require("@solana/web3.js")));
+    const connection = new Connection(getSolanaRpcUrl(), "confirmed");
+    const lamports = await connection.getBalance(new PublicKey(publicKeyBase58));
+    return lamports / 1e9;
+}
+/** Get SOL balance for any address (used to detect deposits). */
+async function getAddressBalance(address) {
+    const { Connection, PublicKey } = await Promise.resolve().then(() => __importStar(require("@solana/web3.js")));
+    const connection = new Connection(getSolanaRpcUrl(), "confirmed");
+    const lamports = await connection.getBalance(new PublicKey(address));
+    return lamports / 1e9;
+}
+/** Deserialize, sign, and submit a base64-encoded Solana transaction. */
+async function signAndSendTransaction(serializedTxBase64, keypair) {
+    const { Connection, VersionedTransaction } = await Promise.resolve().then(() => __importStar(require("@solana/web3.js")));
+    const connection = new Connection(getSolanaRpcUrl(), "confirmed");
+    const txBuffer = Buffer.from(serializedTxBase64, "base64");
+    const tx = VersionedTransaction.deserialize(txBuffer);
+    tx.sign([keypair]);
+    const signature = await connection.sendTransaction(tx, {
+        skipPreflight: false,
+        preflightCommitment: "confirmed",
+    });
+    const { blockhash, lastValidBlockHeight } = await connection.getLatestBlockhash("confirmed");
+    await connection.confirmTransaction({ signature, blockhash, lastValidBlockHeight }, "confirmed");
+    return signature;
+}

package/dist/bridge/squid.js

@@ -0,0 +1,128 @@
+"use strict";
+// Squid Router bridge — deposit address flow (Options B+C).
+// SOL → ETH on Base via Chainflip multi-hop (~1-3 minutes).
+// Requires SQUID_INTEGRATOR_ID (free, apply at squidrouter.com).
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.getDepositAddress = getDepositAddress;
+exports.pollBridgeStatus = pollBridgeStatus;
+const SQUID_API = "https://v2.api.squidrouter.com/v2";
+const SOLANA_CHAIN_ID = "solana";
+const BASE_CHAIN_ID = "8453";
+const NATIVE_SOL_ADDRESS = "So11111111111111111111111111111111111111112"; // Wrapped SOL mint
+const NATIVE_ETH_ADDRESS = "0xEeeeeEeeeEeEeeEeEeEeeEEEeeeeEeeeeeeeEEeE";
+function getIntegratorId() {
+    const id = process.env.SQUID_INTEGRATOR_ID;
+    if (!id) {
+        throw new Error("SQUID_INTEGRATOR_ID is required for the deposit address flow.\n" +
+            "Get one free at https://app.squidrouter.com/\n" +
+            "Or use direct signing instead: apow fund --solana --key <base58>");
+    }
+    return id;
+}
+/**
+ * Get a Squid deposit address for SOL → ETH on Base bridging.
+ * User sends SOL to this address from any wallet; Squid handles the rest.
+ */
+async function getDepositAddress(baseAddress, solAmount) {
+    const integratorId = getIntegratorId();
+    const lamports = Math.floor(solAmount * 1e9).toString();
+    // Step 1: Get route quote
+    const routeResponse = await fetch(`${SQUID_API}/route`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-integrator-id": integratorId,
+        },
+        body: JSON.stringify({
+            fromChain: SOLANA_CHAIN_ID,
+            toChain: BASE_CHAIN_ID,
+            fromToken: NATIVE_SOL_ADDRESS,
+            toToken: NATIVE_ETH_ADDRESS,
+            fromAmount: lamports,
+            toAddress: baseAddress,
+            quoteOnly: false,
+            enableBoost: true,
+            prefer: ["CHAINFLIP_DEPOSIT_ADDRESS"],
+        }),
+    });
+    if (!routeResponse.ok) {
+        const body = await routeResponse.text();
+        throw new Error(`Squid route API error (${routeResponse.status}): ${body}`);
+    }
+    const routeData = (await routeResponse.json());
+    if (routeData.error) {
+        throw new Error(`Squid route error: ${routeData.error.message || JSON.stringify(routeData.error)}`);
+    }
+    // Step 2: Request deposit address from route
+    const depositResponse = await fetch(`${SQUID_API}/deposit-address`, {
+        method: "POST",
+        headers: {
+            "Content-Type": "application/json",
+            "x-integrator-id": integratorId,
+        },
+        body: JSON.stringify({
+            routeData: routeData.route,
+        }),
+    });
+    if (!depositResponse.ok) {
+        const body = await depositResponse.text();
+        throw new Error(`Squid deposit-address API error (${depositResponse.status}): ${body}`);
+    }
+    const depositData = (await depositResponse.json());
+    const estimatedReceive = routeData.route?.estimate?.toAmount
+        ? (Number(routeData.route.estimate.toAmount) / 1e18).toFixed(6)
+        : "unknown";
+    return {
+        depositAddress: depositData.depositAddress,
+        requestId: depositData.requestId || routeData.requestId,
+        expectedReceive: estimatedReceive,
+        expiresAt: depositData.expiresAt,
+    };
+}
+/**
+ * Poll Squid bridge status until complete, failed, or timeout.
+ * Default timeout: 10 minutes (Chainflip can be slow).
+ */
+async function pollBridgeStatus(requestId, onUpdate, timeoutMs = 600_000) {
+    const integratorId = getIntegratorId();
+    const deadline = Date.now() + timeoutMs;
+    while (Date.now() < deadline) {
+        try {
+            const params = new URLSearchParams({
+                requestId,
+                bridgeType: "chainflipmultihop",
+            });
+            const response = await fetch(`${SQUID_API}/status?${params}`, {
+                headers: { "x-integrator-id": integratorId },
+            });
+            if (response.ok) {
+                const data = (await response.json());
+                const status = data.squidTransactionStatus || data.status || "unknown";
+                if (onUpdate)
+                    onUpdate(status);
+                if (status === "success" ||
+                    status === "completed" ||
+                    status === "destination_executed") {
+                    return {
+                        status: "fulfilled",
+                        ethReceived: data.toChain?.amount
+                            ? (Number(data.toChain.amount) / 1e18).toFixed(6)
+                            : undefined,
+                    };
+                }
+                if (status === "failed" || status === "refunded") {
+                    throw new Error(`Bridge failed with status: ${status}`);
+                }
+            }
+        }
+        catch (err) {
+            if (err instanceof Error &&
+                (err.message.includes("failed") || err.message.includes("refunded"))) {
+                throw err;
+            }
+            // Transient fetch error — keep polling
+        }
+        await new Promise((r) => setTimeout(r, 5000));
+    }
+    throw new Error("Bridge timed out after 10 minutes. Check Squid explorer: https://axelarscan.io/");
+}

package/dist/fund.js

@@ -0,0 +1,313 @@
+"use strict";
+// Fund command — bridge SOL → ETH on Base so Solana users can start mining.
+// Three paths:
+//   Option A: Direct Solana signing via deBridge DLN (~20s)
+//   Option B: Deposit address + QR via Squid Router (~1-3 min)
+//   Option C: Manual send (just show Base address)
+var __createBinding = (this && this.__createBinding) || (Object.create ? (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    var desc = Object.getOwnPropertyDescriptor(m, k);
+    if (!desc || ("get" in desc ? !m.__esModule : desc.writable || desc.configurable)) {
+      desc = { enumerable: true, get: function() { return m[k]; } };
+    }
+    Object.defineProperty(o, k2, desc);
+}) : (function(o, m, k, k2) {
+    if (k2 === undefined) k2 = k;
+    o[k2] = m[k];
+}));
+var __setModuleDefault = (this && this.__setModuleDefault) || (Object.create ? (function(o, v) {
+    Object.defineProperty(o, "default", { enumerable: true, value: v });
+}) : function(o, v) {
+    o["default"] = v;
+});
+var __importStar = (this && this.__importStar) || (function () {
+    var ownKeys = function(o) {
+        ownKeys = Object.getOwnPropertyNames || function (o) {
+            var ar = [];
+            for (var k in o) if (Object.prototype.hasOwnProperty.call(o, k)) ar[ar.length] = k;
+            return ar;
+        };
+        return ownKeys(o);
+    };
+    return function (mod) {
+        if (mod && mod.__esModule) return mod;
+        var result = {};
+        if (mod != null) for (var k = ownKeys(mod), i = 0; i < k.length; i++) if (k[i] !== "default") __createBinding(result, mod, k[i]);
+        __setModuleDefault(result, mod);
+        return result;
+    };
+})();
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.runFundFlow = runFundFlow;
+const viem_1 = require("viem");
+const wallet_1 = require("./wallet");
+const ui = __importStar(require("./ui"));
+async function fetchPrices() {
+    const res = await fetch("https://api.coingecko.com/api/v3/simple/price?ids=solana,ethereum&vs_currencies=usd");
+    if (!res.ok)
+        throw new Error("Failed to fetch prices from CoinGecko");
+    const data = (await res.json());
+    const ethUsd = data.ethereum.usd;
+    const solUsd = data.solana.usd;
+    return { solPerEth: ethUsd / solUsd, ethPriceUsd: ethUsd, solPriceUsd: solUsd };
+}
+/** SOL needed for target ETH, with 10% buffer for bridge fees + slippage. */
+function solNeededForEth(targetEth, solPerEth) {
+    return targetEth * solPerEth * 1.1;
+}
+// ---------------------------------------------------------------------------
+// QR code helper
+// ---------------------------------------------------------------------------
+async function showQrCode(text) {
+    try {
+        const mod = await Promise.resolve().then(() => __importStar(require("qrcode-terminal")));
+        const qrcode = mod.default || mod;
+        await new Promise((resolve) => {
+            qrcode.generate(text, { small: true }, (qr) => {
+                for (const line of qr.split("\n")) {
+                    if (line)
+                        console.log(`    ${line}`);
+                }
+                resolve();
+            });
+        });
+    }
+    catch {
+        // QR is nice-to-have, not critical
+    }
+}
+// ---------------------------------------------------------------------------
+// Option A — Direct signing via deBridge
+// ---------------------------------------------------------------------------
+async function runDirectBridge(solanaKeyInput, baseAddress, targetEth) {
+    const solanaSpinner = ui.spinner("Checking Solana balance...");
+    const solana = await Promise.resolve().then(() => __importStar(require("./bridge/solana")));
+    const debridge = await Promise.resolve().then(() => __importStar(require("./bridge/debridge")));
+    let kp;
+    try {
+        kp = await solana.parseSolanaKey(solanaKeyInput);
+    }
+    catch (err) {
+        solanaSpinner.fail("Invalid Solana key");
+        throw err;
+    }
+    const balance = await solana.getSolanaBalance(kp.publicKey);
+    solanaSpinner.stop(`Solana balance: ${balance.toFixed(4)} SOL`);
+    // Prices
+    const priceSpinner = ui.spinner("Fetching prices...");
+    const prices = await fetchPrices();
+    const solAmount = solNeededForEth(targetEth, prices.solPerEth);
+    priceSpinner.stop(`SOL/ETH rate: ${prices.solPerEth.toFixed(1)} SOL = 1 ETH`);
+    if (balance < solAmount) {
+        ui.error(`Insufficient SOL. Need ~${solAmount.toFixed(4)} SOL, have ${balance.toFixed(4)} SOL.`);
+        return;
+    }
+    console.log("");
+    ui.table([
+        ["Bridging", `${solAmount.toFixed(4)} SOL → ~${targetEth.toFixed(4)} ETH on Base`],
+        ["Via", "deBridge DLN (~20 seconds)"],
+        [
+            "From",
+            `${kp.publicKey.slice(0, 4)}...${kp.publicKey.slice(-4)}`,
+        ],
+        ["To", `${baseAddress.slice(0, 6)}...${baseAddress.slice(-4)}`],
+    ]);
+    console.log("");
+    const proceed = await ui.confirm("Confirm bridge?");
+    if (!proceed) {
+        console.log("  Cancelled.");
+        return;
+    }
+    const bridgeSpinner = ui.spinner("Signing bridge transaction...");
+    const result = await debridge.bridgeViaDeBridge(kp.keypair, baseAddress, solAmount);
+    bridgeSpinner.stop(`Submitted! Order: ${result.orderId.slice(0, 12)}...`);
+    const pollSpinner = ui.spinner("Waiting for bridge fulfillment... (~20s)");
+    const fulfillment = await debridge.pollOrderStatus(result.orderId, (status) => pollSpinner.update(`Bridge status: ${status}`));
+    const received = fulfillment.ethReceived || `~${targetEth.toFixed(4)}`;
+    pollSpinner.stop(`Bridge complete! ${received} ETH arrived on Base`);
+    console.log("");
+    console.log(`  ${ui.green("Your wallet is funded!")} Next: ${ui.cyan("apow mint")}`);
+    console.log("");
+}
+// ---------------------------------------------------------------------------
+// Options B+C — Deposit address via Squid
+// ---------------------------------------------------------------------------
+async function runDepositBridge(baseAddress, targetEth) {
+    const priceSpinner = ui.spinner("Fetching prices...");
+    const prices = await fetchPrices();
+    const solAmount = solNeededForEth(targetEth, prices.solPerEth);
+    priceSpinner.stop(`SOL/ETH rate: ${prices.solPerEth.toFixed(1)} SOL = 1 ETH`);
+    const addrSpinner = ui.spinner("Generating deposit address...");
+    const squid = await Promise.resolve().then(() => __importStar(require("./bridge/squid")));
+    const solana = await Promise.resolve().then(() => __importStar(require("./bridge/solana")));
+    let deposit;
+    try {
+        deposit = await squid.getDepositAddress(baseAddress, solAmount);
+    }
+    catch (err) {
+        addrSpinner.fail("Failed to get deposit address");
+        throw err;
+    }
+    addrSpinner.stop("Deposit address ready");
+    // Display deposit info
+    console.log("");
+    console.log(`  ${ui.bold("Send SOL to this address:")}`);
+    console.log("");
+    console.log(`  ${ui.cyan(deposit.depositAddress)}`);
+    console.log("");
+    await showQrCode(deposit.depositAddress);
+    console.log("");
+    ui.table([
+        [
+            "Amount",
+            `~${solAmount.toFixed(4)} SOL (~$${(solAmount * prices.solPriceUsd).toFixed(2)})`,
+        ],
+        ["You'll receive", `~${deposit.expectedReceive} ETH on Base`],
+        ["Bridge", "Squid Router (Chainflip)"],
+        ["Time", "~1-3 minutes"],
+    ]);
+    console.log("");
+    if (deposit.expiresAt) {
+        ui.warn(`Deposit address expires: ${deposit.expiresAt}`);
+        console.log("");
+    }
+    // Poll for SOL deposit
+    const depositSpinner = ui.spinner("Waiting for SOL deposit... (Ctrl+C to cancel)");
+    const initialBalance = await solana.getAddressBalance(deposit.depositAddress);
+    let depositDetected = false;
+    const depositDeadline = Date.now() + 600_000; // 10 min
+    while (!depositDetected && Date.now() < depositDeadline) {
+        await new Promise((r) => setTimeout(r, 3000));
+        try {
+            const currentBalance = await solana.getAddressBalance(deposit.depositAddress);
+            if (currentBalance > initialBalance + 0.001) {
+                depositDetected = true;
+                depositSpinner.stop(`Deposit received! ${(currentBalance - initialBalance).toFixed(4)} SOL`);
+            }
+        }
+        catch {
+            // Transient RPC error — keep polling
+        }
+    }
+    if (!depositDetected) {
+        depositSpinner.fail("No deposit detected after 10 minutes");
+        ui.hint("If you sent SOL, check: https://explorer.squidrouter.com");
+        return;
+    }
+    // Poll for bridge completion
+    const bridgeSpinner = ui.spinner("Bridging SOL → ETH on Base... (~1-3 min)");
+    const result = await squid.pollBridgeStatus(deposit.requestId, (status) => bridgeSpinner.update(`Bridge status: ${status}`));
+    const received = result.ethReceived || deposit.expectedReceive;
+    bridgeSpinner.stop(`Bridge complete! ${received} ETH arrived`);
+    console.log("");
+    console.log(`  ${ui.green("Your wallet is funded!")} Next: ${ui.cyan("apow mint")}`);
+    console.log("");
+}
+// ---------------------------------------------------------------------------
+// Option C — Manual Base address
+// ---------------------------------------------------------------------------
+async function runManualFund(baseAddress) {
+    console.log("");
+    console.log(`  ${ui.bold("Send ETH on Base to this address:")}`);
+    console.log("");
+    console.log(`  ${ui.cyan(baseAddress)}`);
+    console.log("");
+    await showQrCode(baseAddress);
+    console.log("");
+    console.log(`  ${ui.dim("Send from any wallet — Coinbase, MetaMask, Phantom, etc.")}`);
+    console.log(`  ${ui.dim("Need ~0.005 ETH to start mining.")}`);
+    console.log(`  ${ui.dim("After sending, run:")} ${ui.cyan("apow mint")}`);
+    console.log("");
+}
+// ---------------------------------------------------------------------------
+// Main entry point
+// ---------------------------------------------------------------------------
+async function runFundFlow(options) {
+    if (!wallet_1.account) {
+        ui.error("No wallet configured. Run `apow setup` first.");
+        process.exit(1);
+    }
+    const baseAddress = wallet_1.account.address;
+    const balance = await (0, wallet_1.getEthBalance)();
+    const ethBalance = Number((0, viem_1.formatEther)(balance));
+    console.log("");
+    ui.banner(["Fund Your Mining Wallet"]);
+    console.log("");
+    ui.table([
+        [
+            "Your Base wallet",
+            `${baseAddress.slice(0, 6)}...${baseAddress.slice(-4)}`,
+        ],
+        [
+            "Balance",
+            `${ethBalance.toFixed(6)} ETH${ethBalance < 0.005 ? " (need ~0.005 ETH to start)" : ""}`,
+        ],
+    ]);
+    console.log("");
+    // Parse target ETH
+    const targetEth = options.amount ? parseFloat(options.amount) : 0.005;
+    if (isNaN(targetEth) || targetEth <= 0) {
+        ui.error("Invalid amount. Specify ETH target (e.g., --amount 0.005).");
+        return;
+    }
+    // --key flag: direct bridge immediately
+    if (options.key) {
+        await runDirectBridge(options.key, baseAddress, targetEth);
+        return;
+    }
+    // --solana flag: ask about key, then bridge
+    if (options.solana) {
+        const hasKey = await ui.confirm("Do you have your Solana private key?");
+        if (hasKey) {
+            const key = await ui.promptSecret("Solana private key (base58)");
+            if (!key) {
+                ui.error("No key provided.");
+                return;
+            }
+            await runDirectBridge(key, baseAddress, targetEth);
+        }
+        else {
+            await runDepositBridge(baseAddress, targetEth);
+        }
+        return;
+    }
+    // Interactive menu
+    console.log("  How do you want to fund?");
+    console.log(`    ${ui.cyan("1.")} Bridge from Solana (SOL → ETH on Base)`);
+    console.log(`    ${ui.cyan("2.")} Send ETH on Base directly (from another wallet)`);
+    console.log(`    ${ui.cyan("3.")} Copy address and fund manually`);
+    console.log("");
+    const choice = await ui.prompt("Choice", "1");
+    switch (choice) {
+        case "1": {
+            const hasKey = await ui.confirm("Do you have your Solana private key?");
+            if (hasKey) {
+                const key = await ui.promptSecret("Solana private key (base58)");
+                if (!key) {
+                    ui.error("No key provided.");
+                    return;
+                }
+                await runDirectBridge(key, baseAddress, targetEth);
+            }
+            else {
+                await runDepositBridge(baseAddress, targetEth);
+            }
+            break;
+        }
+        case "2": {
+            console.log("");
+            console.log(`  ${ui.bold("Send ETH on Base to:")}`);
+            console.log(`  ${ui.cyan(baseAddress)}`);
+            console.log("");
+            console.log(`  ${ui.dim("Need ~0.005 ETH to start mining.")}`);
+            console.log(`  ${ui.dim("After sending, run:")} ${ui.cyan("apow mint")}`);
+            console.log("");
+            break;
+        }
+        case "3":
+        default: {
+            await runManualFund(baseAddress);
+            break;
+        }
+    }
+}

package/dist/index.js

@@ -45,6 +45,7 @@ const MiningAgent_json_1 = __importDefault(require("./abi/MiningAgent.json"));
 const config_1 = require("./config");
 const detect_1 = require("./detect");
 const explorer_1 = require("./explorer");
+const fund_1 = require("./fund");
 const mint_1 = require("./mint");
 const miner_1 = require("./miner");
 const preflight_1 = require("./preflight");
@@ -271,6 +272,18 @@ async function main() {
         .action(async () => {
         await setupWizard();
     });
+    program
+        .command("fund")
+        .description("Fund your wallet — bridge SOL → ETH on Base, or show deposit address")
+        .option("--solana", "Bridge from Solana")
+        .option("--key <base58>", "Solana private key for direct signing")
+        .option("--amount <eth>", "Target ETH amount (default: 0.005)")
+        .hook("preAction", async () => {
+        await (0, preflight_1.runPreflight)("readonly");
+    })
+        .action(async (opts) => {
+        await (0, fund_1.runFundFlow)(opts);
+    });
     program
         .command("mint")
         .description("Mint a new miner NFT")

package/dist/miner.js

@@ -265,21 +265,19 @@ async function startMining(tokenId) {
                 throw new Error("Mine transaction reverted on-chain");
             }
             txSpinner.stop("Submitting transaction... confirmed");
-            // Fetch post-mine stats
-            const [tokenMineCount, earnings] = await Promise.all([
-                wallet_1.publicClient.readContract({
-                    address: config_1.config.agentCoinAddress,
-                    abi: agentCoinAbi,
-                    functionName: "tokenMineCount",
-                    args: [tokenId],
-                }),
-                wallet_1.publicClient.readContract({
+            // Fetch post-mine earnings with retry (public RPC may lag)
+            let earnings = runningTotal;
+            for (let retry = 0; retry < 5; retry++) {
+                earnings = (await wallet_1.publicClient.readContract({
                     address: config_1.config.agentCoinAddress,
                     abi: agentCoinAbi,
                     functionName: "tokenEarnings",
                     args: [tokenId],
-                }),
-            ]);
+                }));
+                if (earnings > runningTotal)
+                    break;
+                await new Promise((r) => setTimeout(r, 2000));
+            }
             const delta = earnings - runningTotal;
             runningTotal = earnings;
             console.log(`  ${ui.green("+")} ${(0, viem_1.formatEther)(delta)} AGENT | Total: ${(0, viem_1.formatEther)(earnings)} AGENT | Tx: ${ui.dim((0, explorer_1.txUrl)(txHash))}`);

package/dist/mint.js

@@ -72,33 +72,6 @@ function deriveChallengeFromSeed(seed) {
         totalLength,
     ]);
 }
-async function findMintedTokenId(startTokenId, endTokenIdExclusive, owner, blockNumber) {
-    for (let tokenId = startTokenId; tokenId < endTokenIdExclusive; tokenId += 1n) {
-        try {
-            const [tokenOwner, mintBlock] = await Promise.all([
-                wallet_1.publicClient.readContract({
-                    address: config_1.config.miningAgentAddress,
-                    abi: miningAgentAbi,
-                    functionName: "ownerOf",
-                    args: [tokenId],
-                }),
-                wallet_1.publicClient.readContract({
-                    address: config_1.config.miningAgentAddress,
-                    abi: miningAgentAbi,
-                    functionName: "mintBlock",
-                    args: [tokenId],
-                }),
-            ]);
-            if (tokenOwner.toLowerCase() === owner.toLowerCase() && mintBlock === blockNumber) {
-                return tokenId;
-            }
-        }
-        catch {
-            // Ignore missing token ids while scanning the minted window.
-        }
-    }
-    throw new Error("Unable to determine minted token ID from post-mint contract state.");
-}
 async function runMintFlow() {
     const { account, walletClient } = (0, wallet_1.requireWallet)();
     console.log("");
@@ -184,14 +157,21 @@ async function runMintFlow() {
         throw new Error("Challenge request reverted on-chain");
     }
     challengeSpinner.stop("Requesting challenge... done");
-    const challengeSeed = (await wallet_1.publicClient.readContract({
-        address: config_1.config.miningAgentAddress,
-        abi: miningAgentAbi,
-        functionName: "challengeSeeds",
-        args: [account.address],
-    }));
+    // Read challenge seed with retry (public RPC may lag behind tx confirmation)
+    let challengeSeed = ZERO_SEED;
+    for (let retry = 0; retry < 5; retry++) {
+        challengeSeed = (await wallet_1.publicClient.readContract({
+            address: config_1.config.miningAgentAddress,
+            abi: miningAgentAbi,
+            functionName: "challengeSeeds",
+            args: [account.address],
+        }));
+        if (challengeSeed.toLowerCase() !== ZERO_SEED.toLowerCase())
+            break;
+        await new Promise((r) => setTimeout(r, 2000));
+    }
     if (challengeSeed.toLowerCase() === ZERO_SEED.toLowerCase()) {
-        throw new Error("Challenge seed was not stored on-chain.");
+        throw new Error("Challenge seed not found after 5 retries. The RPC may be lagging — try again.");
     }
     // Solve SMHL
     const challenge = deriveChallengeFromSeed(challengeSeed);
@@ -200,11 +180,6 @@ async function runMintFlow() {
         smhlSpinner.update(`Solving SMHL... attempt ${attempt}/5`);
     });
     smhlSpinner.stop("Solving SMHL... done");
-    const nextTokenIdBefore = (await wallet_1.publicClient.readContract({
-        address: config_1.config.miningAgentAddress,
-        abi: miningAgentAbi,
-        functionName: "nextTokenId",
-    }));
     // Mint
     const mintSpinner = ui.spinner("Minting...");
     const mintTx = await walletClient.writeContract({
@@ -221,12 +196,15 @@ async function runMintFlow() {
         throw new Error("Mint transaction reverted on-chain");
     }
     mintSpinner.stop("Minting... confirmed");
-    const nextTokenIdAfter = (await wallet_1.publicClient.readContract({
-        address: config_1.config.miningAgentAddress,
-        abi: miningAgentAbi,
-        functionName: "nextTokenId",
-    }));
-    const tokenId = await findMintedTokenId(nextTokenIdBefore, nextTokenIdAfter, account.address, receipt.blockNumber);
+    // Parse token ID from Transfer event in receipt (avoids stale RPC reads)
+    const TRANSFER_TOPIC = "0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef";
+    const mintLog = receipt.logs.find((log) => log.address.toLowerCase() === config_1.config.miningAgentAddress.toLowerCase() &&
+        log.topics[0] === TRANSFER_TOPIC &&
+        log.topics[1] === "0x0000000000000000000000000000000000000000000000000000000000000000");
+    if (!mintLog || !mintLog.topics[3]) {
+        throw new Error("Mint tx confirmed but Transfer event not found in logs. Check tx on Basescan.");
+    }
+    const tokenId = BigInt(mintLog.topics[3]);
     const [rarityRaw, hashpowerRaw] = await Promise.all([
         wallet_1.publicClient.readContract({
             address: config_1.config.miningAgentAddress,

package/dist/smhl.js

@@ -59,8 +59,8 @@ function validateSmhlSolution(solution, challenge) {
         return issues;
     }
     const len = Buffer.byteLength(solution, "utf8");
-    if (Math.abs(len - challenge.totalLength) > 5) {
-        issues.push(`length ${len} not within ±5 of ${challenge.totalLength}`);
+    if (Math.abs(len - challenge.totalLength) > 4) {
+        issues.push(`length ${len} not within ±4 of ${challenge.totalLength}`);
     }
     if (!/^[\x20-\x7E]+$/.test(solution)) {
         issues.push("solution must use printable ASCII only");
@@ -82,8 +82,8 @@ function validateSmhlSolution(solution, challenge) {
  */
 function adjustSolution(raw, challenge) {
     const requiredChar = String.fromCharCode(challenge.charValue);
-    const minLen = challenge.totalLength - 5;
-    const maxLen = challenge.totalLength + 5;
+    const minLen = challenge.totalLength - 4;
+    const maxLen = challenge.totalLength + 4;
     const maxWords = challenge.wordCount + 2;
     // Clean: lowercase, letters and spaces only, collapse whitespace
     let words = raw
@@ -234,7 +234,7 @@ async function requestGeminiSolution(prompt) {
                 parts: [{ text: "You generate short lowercase word sequences that match exact constraints. Return only the words separated by spaces. Nothing else." }],
             },
             contents: [{ parts: [{ text: prompt }] }],
-            generationConfig: { temperature: 0.7 },
+            generationConfig: { temperature: 0.7, thinkingConfig: { thinkingBudget: 0 } },
         }),
     });
     if (response.status === 429) {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "apow-cli",
-  "version": "0.1.3",
+  "version": "0.2.0",
   "description": "Mine AGENT tokens on Base L2 with AI-powered proof of work",
   "keywords": [
     "apow",
@@ -39,9 +39,11 @@
     "prepublishOnly": "npm run build"
   },
   "dependencies": {
+    "@solana/web3.js": "^1.98.0",
     "commander": "^14.0.0",
     "dotenv": "^17.2.3",
     "openai": "^6.6.0",
+    "qrcode-terminal": "^0.12.0",
     "viem": "^2.38.2"
   },
   "devDependencies": {

package/skill.md

@@ -30,6 +30,7 @@ with ETH on Base. Everything else you handle yourself.
 **Via npm (recommended):**
 ```bash
 npx apow-cli setup     # interactive wizard — wallet, RPC, LLM config
+npx apow-cli fund      # fund wallet — bridge from Solana or show deposit address
 npx apow-cli mint      # mint a mining rig NFT
 npx apow-cli mine      # start mining (auto-detects your best rig)
 ```
@@ -65,8 +66,10 @@ MINING_AGENT_ADDRESS=0xB7caD3ca5F2BD8aEC2Eb67d6E8D448099B3bC03D
 AGENT_COIN_ADDRESS=0x12577CF0D8a07363224D6909c54C056A183e13b3
 EOF
 
-# 3. Ask your user to fund the wallet with ≥0.005 ETH on Base
-#    This is the ONLY step that requires human action
+# 3. Fund the wallet (bridge from Solana or send ETH on Base)
+npx apow-cli fund --solana            # interactive bridge SOL → ETH on Base
+# Or: npx apow-cli fund --solana --key <base58>  # direct signing (~20s)
+# Or: ask your user to send ≥0.005 ETH on Base directly
 
 # 4. Mint + mine (fully autonomous from here)
 npx apow-cli mint
@@ -138,9 +141,34 @@ This prompts for confirmation, then displays your address and private key. It al
 Your mining wallet needs ETH on Base for gas and the mint fee.
 **Minimum:** 0.005 ETH (~$15) covers minting + several mining cycles.
 
-Ask your user how they want to fund their wallet, then give them the appropriate instructions:
+### Built-in Bridge: `apow fund` (Recommended)
 
-### From Solana (Phantom Wallet)
+The CLI has a built-in cross-chain bridge for Solana users:
+
+```bash
+npx apow-cli fund                           # Interactive: choose funding method
+npx apow-cli fund --solana                  # Deposit address + QR code
+npx apow-cli fund --solana --key <base58>   # Direct Solana signing (~20s)
+npx apow-cli fund --solana --amount 0.01    # Custom ETH target
+```
+
+**Three funding paths:**
+
+| Path | How it works | Speed | Requires Solana key? |
+|------|-------------|-------|---------------------|
+| Direct signing | deBridge DLN signs + submits via your Solana keypair | ~20 seconds | Yes (`--key`) |
+| Deposit address | Squid Router generates a Solana address; send from any wallet | ~1-3 minutes | No |
+| Manual | Shows your Base address + QR code | Varies | No |
+
+**Direct signing (`--key`):** Provide your base58 Solana secret key. The CLI calls deBridge DLN to create a bridge order, signs the Solana transaction locally, submits it, and polls until ETH arrives on Base. No API key needed.
+
+**Deposit address (`--solana` without `--key`):** Requires `SQUID_INTEGRATOR_ID` in `.env` (free, apply at [squidrouter.com](https://app.squidrouter.com/)). Generates a one-time Solana deposit address with a QR code. Send SOL from any wallet (Phantom, Backpack, etc.) and the bridge handles the rest.
+
+### Manual Funding Options
+
+If you prefer not to use the built-in bridge:
+
+#### From Solana (Phantom Wallet)
 Phantom natively supports Base. Tell your user:
 1. Open Phantom → tap the **Swap** icon
 2. Set **From:** SOL (Solana) → **To:** ETH (Base)
@@ -149,19 +177,17 @@ Phantom natively supports Base. Tell your user:
 5. Once ETH arrives on Base, tap **Send** → paste the mining wallet address
 6. Confirm the transfer
 
-Alternatively, use [relay.link/bridge/solana](https://relay.link/bridge/solana) to bridge SOL → ETH on Base directly to the mining wallet address.
-
-### From an Exchange (Coinbase, Binance, etc.)
+#### From an Exchange (Coinbase, Binance, etc.)
 1. Buy ETH on Base (Coinbase supports Base withdrawals natively)
 2. Withdraw to the mining wallet address
 3. Select **Base** as the network — do NOT send on Ethereum mainnet
 
-### From Ethereum Mainnet
+#### From Ethereum Mainnet
 Bridge ETH to Base via [bridge.base.org](https://bridge.base.org):
 1. Connect source wallet → enter mining wallet address as recipient
 2. Bridge ≥0.005 ETH → arrives on Base in ~10 minutes
 
-### From Another Base Wallet
+#### From Another Base Wallet
 Send ETH directly to the mining wallet address on Base.
 
 ### Verifying Funds
@@ -236,6 +262,8 @@ CHAIN=base
 | `LLM_MODEL` | No | `gpt-4o-mini` | Model identifier passed to the provider |
 | `RPC_URL` | No | `https://mainnet.base.org` | Base JSON-RPC endpoint |
 | `CHAIN` | No | `base` | Network selector; auto-detects `baseSepolia` if RPC URL contains "sepolia" |
+| `SOLANA_RPC_URL` | No | `https://api.mainnet-beta.solana.com` | Solana RPC endpoint (only for `apow fund --solana`) |
+| `SQUID_INTEGRATOR_ID` | No | -- | Squid Router integrator ID for deposit address flow (free at [squidrouter.com](https://app.squidrouter.com/)) |
 
 ### LLM Provider Recommendations
 
@@ -253,10 +281,54 @@ CHAIN=base
 
 ### RPC Recommendations
 
-The default `https://mainnet.base.org` is rate-limited. For production mining, use a dedicated RPC:
-- [Alchemy](https://www.alchemy.com/) -- `https://base-mainnet.g.alchemy.com/v2/YOUR_KEY`
-- [Infura](https://infura.io/) -- `https://base-mainnet.infura.io/v3/YOUR_KEY`
-- [QuickNode](https://www.quicknode.com/) -- custom endpoint
+The default `https://mainnet.base.org` is a public RPC with aggressive rate limits. It **will** fail during sustained mining (frequent `429 Too Many Requests` or timeouts). You need a dedicated RPC endpoint. All providers below offer a **free tier** that is more than sufficient for mining.
+
+#### Option 1: Alchemy (Recommended)
+
+1. Go to [alchemy.com](https://www.alchemy.com/) and sign up (free, no credit card)
+2. Click **Create new app** → Name: `apow-miner` → Chain: **Base** → Network: **Base Mainnet**
+3. On the app dashboard, copy the **HTTPS** URL. It looks like:
+   ```
+   https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
+   ```
+4. Set in your `.env`:
+   ```
+   RPC_URL=https://base-mainnet.g.alchemy.com/v2/YOUR_API_KEY
+   ```
+
+**Free tier:** 300M compute units/month (~millions of RPC calls). More than enough for mining.
+
+#### Option 2: QuickNode
+
+1. Go to [quicknode.com](https://www.quicknode.com/) and sign up (free, no credit card)
+2. Click **Create Endpoint** → Chain: **Base** → Network: **Mainnet**
+3. Copy the **HTTP Provider** URL. It looks like:
+   ```
+   https://something-something.base-mainnet.quiknode.pro/YOUR_TOKEN/
+   ```
+4. Set in your `.env`:
+   ```
+   RPC_URL=https://something-something.base-mainnet.quiknode.pro/YOUR_TOKEN/
+   ```
+
+**Free tier:** 10M API credits/month. Sufficient for a few miners.
+
+#### Option 3: Other Free RPCs
+
+| Provider | Free Tier | URL Pattern |
+|---|---|---|
+| [Infura](https://infura.io/) | 100K req/day | `https://base-mainnet.infura.io/v3/KEY` |
+| [Ankr](https://www.ankr.com/) | 30 req/s | `https://rpc.ankr.com/base` (no key needed) |
+| [Blast](https://blastapi.io/) | 40 req/s | `https://base-mainnet.blastapi.io/KEY` |
+
+#### Troubleshooting RPC Issues
+
+| Symptom | Cause | Fix |
+|---|---|---|
+| `429 Too Many Requests` | Public RPC rate limit | Switch to a dedicated RPC (Alchemy/QuickNode) |
+| `Timed out waiting for next block (60s)` | RPC not responding | Check endpoint URL; try a different provider |
+| `fetch failed` / `ECONNREFUSED` | RPC URL is wrong or down | Verify URL; test with `curl YOUR_RPC_URL -X POST -H "Content-Type: application/json" -d '{"jsonrpc":"2.0","method":"eth_blockNumber","params":[],"id":1}'` |
+| Stale data / missed mines | RPC caching or slow sync | Alchemy and QuickNode are fastest; avoid free community RPCs |
 
 ---
 
@@ -565,12 +637,17 @@ The CLI contains no analytics, no error reporting, and no phone-home behavior of
 - No error reporting services (no Sentry, no Bugsnag)
 - No tracking pixels, no usage metrics, no telemetry endpoints
 
-The CLI makes exactly two types of network calls:
+The CLI makes only these network calls:
 
 1. **Blockchain RPC** (to user-configured RPC URL, default: `mainnet.base.org`) -- standard `eth_call`, `eth_sendRawTransaction`, etc.
 2. **LLM API** (to user-configured provider) -- sends only word-puzzle prompts for SMHL solving, never wallet data
+3. **Bridge APIs** (only when using `apow fund --solana`):
+   - **CoinGecko** (`api.coingecko.com`) -- SOL/ETH price quotes
+   - **deBridge DLN** (`dln.debridge.finance`) -- bridge order creation and status (direct signing flow)
+   - **Squid Router** (`v2.api.squidrouter.com`) -- deposit address generation (deposit address flow)
+   - **Solana RPC** (`api.mainnet-beta.solana.com` or custom) -- balance checks and tx submission
 
-Nothing else. No other outbound connections.
+No private keys are transmitted to bridge providers. deBridge returns a serialized Solana transaction that is signed locally. Squid generates a deposit address -- the user sends SOL themselves.
 
 ### LLM Calls Are Data-Isolated
 
@@ -601,7 +678,7 @@ The SMHL solver sends only generic word-generation prompts to the LLM (e.g., "Wr
    cd apow-cli && npm install && npm run build
    node dist/index.js setup
    ```
-5. **Review dependencies.** The dependency tree is minimal and standard: `viem` (Ethereum library), `commander` (CLI framework), `dotenv` (env loading), `chalk`/`ora` (terminal UI), and an LLM client. No exotic or suspicious packages.
+5. **Review dependencies.** The dependency tree is minimal and standard: `viem` (Ethereum library), `commander` (CLI framework), `dotenv` (env loading), `@solana/web3.js` (Solana signing, lazy-loaded only for bridging), `qrcode-terminal` (QR codes for fund command), and an LLM client. No exotic or suspicious packages.
 
 ### How to Verify These Claims Yourself