ape-claw 0.1.0

package/src/lib/bridge-relay.mjs

@@ -0,0 +1,294 @@
+import { createWalletClient, defineChain, http, parseUnits } from "viem";
+import { privateKeyToAccount } from "viem/accounts";
+import { resolveRpcUrl } from "./rpc.mjs";
+
+const RELAY_API_BASE = process.env.RELAY_API_BASE || "https://api.relay.link";
+const NATIVE_ADDRESS = "0x0000000000000000000000000000000000000000";
+
+const CHAIN_ID_BY_NAME = {
+  ethereum: 1,
+  arbitrum: 42161,
+  base: 8453,
+  optimism: 10,
+  polygon: 137,
+  apechain: 33139,
+};
+
+function normalizeChainId(input) {
+  if (typeof input === "number") return input;
+  const s = String(input || "").toLowerCase().trim();
+  if (/^\d+$/.test(s)) return Number(s);
+  if (CHAIN_ID_BY_NAME[s]) return CHAIN_ID_BY_NAME[s];
+  throw new Error(`Unsupported chain: ${input}`);
+}
+
+function toHexPrivateKey(pk) {
+  const raw = String(pk || "").trim();
+  if (!raw) return "";
+  return raw.startsWith("0x") ? raw : `0x${raw}`;
+}
+
+function getAddressFromPrivateKey(privateKey) {
+  const hex = toHexPrivateKey(privateKey);
+  if (!hex) return "";
+  return privateKeyToAccount(hex).address;
+}
+
+function normalizeCurrencyAddress(value) {
+  if (!value) return NATIVE_ADDRESS;
+  const s = String(value).trim();
+  if (s.toUpperCase() === "NATIVE" || s.toUpperCase() === "ETH" || s.toUpperCase() === "APE") {
+    return NATIVE_ADDRESS;
+  }
+  if (/^0x[a-fA-F0-9]{40}$/.test(s)) return s;
+  throw new Error(`Invalid currency address: ${value}`);
+}
+
+function relayHeaders(apiKey) {
+  const headers = {
+    "content-type": "application/json",
+    accept: "application/json",
+  };
+  if (apiKey) headers["x-api-key"] = apiKey;
+  return headers;
+}
+
+async function fetchJson(url, init = {}) {
+  const res = await fetch(url, init);
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`Relay HTTP ${res.status}${body ? `: ${body.slice(0, 220)}` : ""}`);
+  }
+  return res.json();
+}
+
+function guessRequestId(quote) {
+  return (
+    quote?.requestId ||
+    quote?.steps?.[0]?.requestId ||
+    quote?.steps?.[0]?.items?.[0]?.check?.requestId ||
+    quote?.steps?.[0]?.items?.[0]?.metadata?.requestId ||
+    ""
+  );
+}
+
+function guessCheckEndpoint(quote) {
+  return quote?.steps?.[0]?.items?.[0]?.check?.endpoint || "";
+}
+
+function guessAmountOut(quote) {
+  const out = quote?.details?.currencyOut?.amount;
+  if (typeof out === "string" && /^\d+$/.test(out)) return out;
+  return null;
+}
+
+function computeFeeBps(quote) {
+  const input = Number(quote?.details?.currencyIn?.amount || 0);
+  if (!Number.isFinite(input) || input <= 0) return null;
+  const relayer = Number(quote?.fees?.relayer?.amount || 0);
+  const relayerGas = Number(quote?.fees?.relayerGas?.amount || 0);
+  const app = Number(quote?.fees?.app?.amount || 0);
+  const total = relayer + relayerGas + app;
+  if (!Number.isFinite(total) || total < 0) return null;
+  return Math.round((total / input) * 10000);
+}
+
+function findNumericByKeys(obj, keys) {
+  if (!obj || typeof obj !== "object") return null;
+  for (const [k, v] of Object.entries(obj)) {
+    const lk = k.toLowerCase();
+    if (keys.some((x) => lk.includes(x)) && Number.isFinite(Number(v))) {
+      return Number(v);
+    }
+    if (v && typeof v === "object") {
+      const nested = findNumericByKeys(v, keys);
+      if (nested !== null) return nested;
+    }
+  }
+  return null;
+}
+
+function nativeCurrencyForChain(chainId) {
+  const id = Number(chainId);
+  if (id === 33139) return { name: "ApeCoin", symbol: "APE", decimals: 18 };
+  if (id === 137) return { name: "MATIC", symbol: "MATIC", decimals: 18 };
+  return { name: "Ether", symbol: "ETH", decimals: 18 };
+}
+
+function makeChain(chainId, rpcUrl) {
+  return defineChain({
+    id: Number(chainId),
+    name: `chain-${chainId}`,
+    nativeCurrency: nativeCurrencyForChain(chainId),
+    rpcUrls: { default: { http: [rpcUrl] } },
+  });
+}
+
+function extractStatus(payload) {
+  if (!payload || typeof payload !== "object") return "unknown";
+  if (typeof payload.status === "string") return payload.status;
+  if (typeof payload?.result?.status === "string") return payload.result.status;
+  if (typeof payload?.data?.status === "string") return payload.data.status;
+  if (Array.isArray(payload?.intents) && payload.intents[0]?.status) return payload.intents[0].status;
+  if (Array.isArray(payload?.data) && payload.data[0]?.status) return payload.data[0].status;
+  return "unknown";
+}
+
+function extractDestinationTxHash(payload) {
+  return (
+    payload?.destinationTxHash ||
+    payload?.txHashes?.[0] ||
+    payload?.result?.destinationTxHash ||
+    payload?.result?.txHashes?.[0] ||
+    payload?.data?.destinationTxHash ||
+    payload?.data?.txHashes?.[0] ||
+    payload?.intents?.[0]?.destinationTxHash ||
+    payload?.intents?.[0]?.txHashes?.[0] ||
+    payload?.data?.[0]?.destinationTxHash ||
+    payload?.data?.[0]?.txHashes?.[0] ||
+    null
+  );
+}
+
+export function relayUserAddress({ args = {}, privateKey = "" }) {
+  const byArg = String(args.user || "").trim();
+  if (byArg) return byArg;
+  const fromPk = getAddressFromPrivateKey(privateKey);
+  if (fromPk) return fromPk;
+  throw new Error("Missing user address. Pass --user <0x...> or set APE_CLAW_PRIVATE_KEY.");
+}
+
+export async function quoteBridgeRelay({
+  from,
+  to,
+  token,
+  amount,
+  args = {},
+  apiKey = "",
+  privateKey = "",
+}) {
+  const originChainId = normalizeChainId(from);
+  const destinationChainId = normalizeChainId(to);
+  const user = relayUserAddress({ args, privateKey });
+  const decimals = Number(args.decimals || 18);
+  const amountBaseUnits = parseUnits(String(amount), decimals).toString();
+  const originCurrency = normalizeCurrencyAddress(args.originCurrency || token);
+  const destinationCurrency = normalizeCurrencyAddress(args.destinationCurrency || token);
+
+  const body = {
+    user,
+    originChainId,
+    destinationChainId,
+    originCurrency,
+    destinationCurrency,
+    amount: amountBaseUnits,
+    tradeType: "EXACT_INPUT",
+  };
+
+  const quote = await fetchJson(`${RELAY_API_BASE}/quote/v2`, {
+    method: "POST",
+    headers: relayHeaders(apiKey),
+    body: JSON.stringify(body),
+  });
+
+  const relayRequestId = guessRequestId(quote);
+  const checkEndpoint = guessCheckEndpoint(quote);
+  const quotedFeeBps = computeFeeBps(quote) ?? findNumericByKeys(quote, ["feebps", "fee_bps", "bps"]);
+
+  return {
+    requestId: relayRequestId || `relay_${Date.now()}`,
+    relayRequestId: relayRequestId || null,
+    relayCheckEndpoint: checkEndpoint || null,
+    from: String(from),
+    to: String(to),
+    token: String(token || "NATIVE"),
+    amount: Number(amount),
+    amountBaseUnits,
+    originChainId,
+    destinationChainId,
+    originCurrency,
+    destinationCurrency,
+    status: "quoted",
+    routeHash: relayRequestId || null,
+    minAmountOut: guessAmountOut(quote),
+    feeBps: Number.isFinite(quotedFeeBps) ? quotedFeeBps : null,
+    expiresAt: new Date(Date.now() + 4 * 60_000).toISOString(),
+    relayQuote: quote,
+  };
+}
+
+export async function executeBridgeRelay({
+  request,
+  privateKey = "",
+  policy = {},
+}) {
+  const hexPk = toHexPrivateKey(privateKey);
+  if (!hexPk) throw new Error("Missing APE_CLAW_PRIVATE_KEY for live bridge execute.");
+  const account = privateKeyToAccount(hexPk);
+  const quote = request?.relayQuote;
+  const steps = Array.isArray(quote?.steps) ? quote.steps : [];
+  if (steps.length === 0) throw new Error("Relay quote has no executable steps.");
+
+  const submittedTxs = [];
+  for (const step of steps) {
+    const item = step?.items?.[0];
+    const kind = String(step?.kind || item?.kind || "").toLowerCase();
+    if (!item) throw new Error("Relay step has no items.");
+    if (kind !== "transaction") {
+      throw new Error(`Unsupported relay step kind '${kind}'. Only transaction steps are supported.`);
+    }
+    const tx = item?.data || {};
+    const chainId = Number(tx.chainId || request.originChainId);
+    const rpcUrl = await resolveRpcUrl(chainId, policy);
+    const chain = makeChain(chainId, rpcUrl);
+    const client = createWalletClient({
+      account,
+      chain,
+      transport: http(rpcUrl),
+    });
+    const hash = await client.sendTransaction({
+      to: tx.to,
+      data: tx.data || "0x",
+      value: BigInt(tx.value || "0"),
+      chain,
+    });
+    submittedTxs.push({ chainId, hash });
+  }
+
+  return {
+    ...request,
+    status: "pending",
+    originTxHash: submittedTxs[0]?.hash || null,
+    submittedTxs,
+    submittedAt: new Date().toISOString(),
+  };
+}
+
+export async function getBridgeRelayStatus({ request, apiKey = "" }) {
+  const relayRequestId = request?.relayRequestId;
+  if (!relayRequestId) {
+    return { status: request?.status || "unknown", raw: null };
+  }
+  const check = String(request?.relayCheckEndpoint || "");
+  const url = check
+    ? (check.startsWith("http") ? check : `${RELAY_API_BASE}${check}`)
+    : `${RELAY_API_BASE}/intents/status/v3?requestId=${encodeURIComponent(relayRequestId)}`;
+  const raw = await fetchJson(url, {
+    method: "GET",
+    headers: relayHeaders(apiKey),
+  });
+  const relayStatus = extractStatus(raw);
+  const normalized =
+    relayStatus === "success"
+      ? "confirmed"
+      : relayStatus === "pending" || relayStatus === "waiting"
+        ? "pending"
+        : relayStatus;
+  return {
+    status: normalized,
+    relayStatus,
+    destinationTxHash: extractDestinationTxHash(raw),
+    raw,
+  };
+}
+

package/src/lib/clawbots.mjs

@@ -0,0 +1,94 @@
+import { createHash, randomUUID } from "node:crypto";
+import { readJson, writeJson } from "./io.mjs";
+import { CLAWBOTS_PATH } from "./paths.mjs";
+
+/**
+ * Clawbot verification system.
+ *
+ * Verified bots get access to the shared OpenSea API key so that bot
+ * operators do NOT need their own key. The shared key is read from the
+ * APE_CLAW_SHARED_OPENSEA_KEY env var (never stored in config files).
+ *
+ * Config format (config/clawbots.json):
+ * {
+ *   "agents": {
+ *     "the-clawllector": {
+ *       "name": "The Clawllector",
+ *       "tokenHash": "<sha256 of agent token>",
+ *       "createdAt": "...",
+ *       "enabled": true
+ *     }
+ *   }
+ * }
+ */
+
+function resolveSharedOpenseaKey() {
+  return String(process.env.APE_CLAW_SHARED_OPENSEA_KEY || "").trim();
+}
+
+function hashToken(token) {
+  return createHash("sha256").update(String(token)).digest("hex");
+}
+
+export function loadClawbotsConfig() {
+  return readJson(CLAWBOTS_PATH, null);
+}
+
+export function generateAgentToken() {
+  return `claw_${randomUUID().replace(/-/g, "")}`;
+}
+
+/**
+ * Register a new clawbot agent. Returns the agent token (shown once).
+ */
+export function registerClawbot({ agentId, displayName }) {
+  const config = loadClawbotsConfig() || { agents: {} };
+  if (!config.agents) config.agents = {};
+  if (config.agents[agentId]) {
+    throw new Error(`Agent "${agentId}" already registered. Use a different --agent-id.`);
+  }
+  const token = generateAgentToken();
+  config.agents[agentId] = {
+    name: displayName || agentId,
+    tokenHash: hashToken(token),
+    createdAt: new Date().toISOString(),
+    enabled: true,
+  };
+  writeJson(CLAWBOTS_PATH, config);
+  return { agentId, token, displayName: config.agents[agentId].name };
+}
+
+/**
+ * Verify a clawbot's credentials.
+ * Returns { verified, agent, sharedOpenseaApiKey } or { verified: false }.
+ */
+export function verifyClawbot({ agentId, agentToken }) {
+  if (!agentId || !agentToken) return { verified: false, reason: "missing credentials" };
+  const config = loadClawbotsConfig();
+  if (!config || !config.agents) return { verified: false, reason: "no clawbots config" };
+  const agent = config.agents[agentId];
+  if (!agent) return { verified: false, reason: `agent "${agentId}" not registered` };
+  if (!agent.enabled) return { verified: false, reason: `agent "${agentId}" is disabled` };
+  const expectedHash = agent.tokenHash;
+  const gotHash = hashToken(agentToken);
+  if (gotHash !== expectedHash) return { verified: false, reason: "invalid token" };
+  return {
+    verified: true,
+    agent: { id: agentId, name: agent.name },
+    sharedOpenseaApiKey: resolveSharedOpenseaKey(),
+  };
+}
+
+/**
+ * List all registered clawbots (no secrets).
+ */
+export function listClawbots() {
+  const config = loadClawbotsConfig();
+  if (!config || !config.agents) return [];
+  return Object.entries(config.agents).map(([id, a]) => ({
+    agentId: id,
+    name: a.name,
+    enabled: a.enabled,
+    createdAt: a.createdAt,
+  }));
+}

package/src/lib/io.mjs

@@ -0,0 +1,36 @@
+import fs from "node:fs";
+import path from "node:path";
+import { randomUUID } from "node:crypto";
+
+export function ensureDir(dirPath) {
+  fs.mkdirSync(dirPath, { recursive: true });
+}
+
+export function readJson(filePath, fallback = null) {
+  try {
+    const raw = fs.readFileSync(filePath, "utf8");
+    return JSON.parse(raw);
+  } catch {
+    return fallback;
+  }
+}
+
+export function writeJson(filePath, data) {
+  ensureDir(path.dirname(filePath));
+  fs.writeFileSync(filePath, JSON.stringify(data, null, 2));
+}
+
+export function appendJsonl(filePath, payload) {
+  ensureDir(path.dirname(filePath));
+  fs.appendFileSync(filePath, `${JSON.stringify(payload)}\n`);
+}
+
+export function nowIso() {
+  return new Date().toISOString();
+}
+
+export function randomId(prefix = "id") {
+  const body = randomUUID().replace(/-/g, "").slice(0, 12);
+  return `${prefix}_${body}`;
+}
+

package/src/lib/market.mjs

@@ -0,0 +1,233 @@
+function toSlug(input) {
+  return String(input || "")
+    .toLowerCase()
+    .trim()
+    .replace(/®/g, "")
+    .replace(/[^a-z0-9]+/g, "-")
+    .replace(/^-+|-+$/g, "");
+}
+
+function unique(items) {
+  return [...new Set(items.filter(Boolean))];
+}
+
+async function fetchJson(url, headers = {}) {
+  const res = await fetch(url, { headers });
+  if (!res.ok) {
+    const body = await res.text().catch(() => "");
+    throw new Error(`HTTP ${res.status} for ${url}${body ? `: ${body.slice(0, 180)}` : ""}`);
+  }
+  return res.json();
+}
+
+function extractContractAddress(collectionPayload) {
+  const contracts = collectionPayload?.contracts;
+  if (Array.isArray(contracts) && contracts.length > 0) {
+    const ape = contracts.find((c) => String(c?.chain || "").toLowerCase() === "apechain");
+    return (ape?.address || contracts[0]?.address || null);
+  }
+  const fallback = collectionPayload?.contract || collectionPayload?.primary_contract;
+  if (fallback && typeof fallback === "object") return fallback.address || null;
+  return null;
+}
+
+function extractContractFromNftPayload(nftPayload) {
+  const nfts = nftPayload?.nfts || [];
+  if (!Array.isArray(nfts) || nfts.length === 0) return null;
+  const first = nfts[0] || {};
+  const c = first?.contract;
+  if (c && typeof c === "object") return c.address || null;
+  const contracts = first?.contracts;
+  if (Array.isArray(contracts) && contracts.length > 0) return contracts[0]?.address || null;
+  return null;
+}
+
+function buildSlugCandidates(item, overrides = {}) {
+  const raw = String(item.name || "");
+  const base = toSlug(raw);
+  const fromOverride = overrides[raw] || overrides[base] || [];
+  const variants = [
+    item.slug,
+    base,
+    base.replace(/-on-apechain$/, ""),
+    base.replace(/-on-ape$/, ""),
+    base.replace(/-the-level-up$/, ""),
+    base.replace(/-/g, ""),
+    toSlug(raw.replace(/_/g, " ")),
+    toSlug(raw.replace(/:/g, " ")),
+    ...(Array.isArray(fromOverride) ? fromOverride : [fromOverride]),
+  ];
+  return unique(variants);
+}
+
+async function resolveOpenSeaCollection(item, headers, overrides = {}) {
+  const candidates = buildSlugCandidates(item, overrides);
+  const notes = [];
+  for (const slug of candidates) {
+    // 1) Try collection metadata endpoint
+    try {
+      const data = await fetchJson(
+        `https://api.opensea.io/api/v2/collections/${encodeURIComponent(slug)}`,
+        headers,
+      );
+      const collection = data?.collection || data;
+      const ca = extractContractAddress(collection);
+      if (ca) return { slug, contractAddress: ca, notes: [`resolved via get_collection slug=${slug}`] };
+      notes.push(`slug ${slug}: collection found but no contract field`);
+    } catch (err) {
+      notes.push(`slug ${slug}: get_collection failed (${err.message})`);
+    }
+
+    // 2) Fallback: try NFTs-by-collection and derive contract from first NFT
+    try {
+      const nftsData = await fetchJson(
+        `https://api.opensea.io/api/v2/collection/${encodeURIComponent(slug)}/nfts?limit=1`,
+        headers,
+      );
+      const ca = extractContractFromNftPayload(nftsData);
+      if (ca) return { slug, contractAddress: ca, notes: [`resolved via get_nfts_by_collection slug=${slug}`] };
+      notes.push(`slug ${slug}: nfts endpoint returned no contract`);
+    } catch (err) {
+      notes.push(`slug ${slug}: get_nfts_by_collection failed (${err.message})`);
+    }
+  }
+  return { slug: item.slug || toSlug(item.name), contractAddress: null, notes };
+}
+
+export async function enrichAllowlistWithOpenSea(allowlist, apiKey, overrides = {}) {
+  if (!apiKey) return { allowlist, notes: ["OpenSea key not provided; skipped enrichment."] };
+  const headers = { "x-api-key": apiKey, accept: "application/json" };
+  const notes = [];
+  const out = [];
+  for (const item of allowlist) {
+    if (item.contractAddress) {
+      out.push(item);
+      continue;
+    }
+    try {
+      const resolved = await resolveOpenSeaCollection(item, headers, overrides);
+      const ca = resolved.contractAddress;
+      if (ca) {
+        out.push({ ...item, slug: resolved.slug, contractAddress: ca });
+        notes.push(`resolved ${item.name} -> ${ca} (slug=${resolved.slug})`);
+      } else {
+        out.push(item);
+        notes.push(`no CA found for ${item.name}`);
+        notes.push(...resolved.notes.map((n) => `  ${n}`));
+      }
+    } catch (err) {
+      out.push(item);
+      notes.push(`OpenSea lookup failed for ${item.name}: ${err.message}`);
+    }
+  }
+  return { allowlist: out, notes };
+}
+
+export async function getListings({
+  collection,
+  tokenId,
+  maxPrice,
+  dataSource,
+  apiKey,
+  slugOverrides = {},
+}) {
+  const source = String(dataSource || "reservoir").toLowerCase();
+  if (source !== "opensea") {
+    throw new Error(
+      `Unsupported market data source '${source}' for live mode. Set market.dataSource to 'opensea'.`,
+    );
+  }
+
+  if (!apiKey) {
+    throw new Error("OpenSea data source selected but OPENSEA_API_KEY is missing.");
+  }
+
+  const candidates = buildSlugCandidates({ name: collection, slug: toSlug(collection) }, slugOverrides);
+  let slug = candidates[0];
+  const headers = { "x-api-key": apiKey, accept: "application/json" };
+
+  let data = null;
+  let endpoint = "";
+  for (const s of candidates) {
+    try {
+      const urls = tokenId
+        ? [
+            `https://api.opensea.io/api/v2/listings/collection/${encodeURIComponent(s)}/nfts/${encodeURIComponent(String(tokenId))}/all?limit=20`,
+            `https://api.opensea.io/api/v2/listings/collection/${encodeURIComponent(s)}/all?limit=50`,
+          ]
+        : [`https://api.opensea.io/api/v2/listings/collection/${encodeURIComponent(s)}/all?limit=20`];
+      for (const listingsUrl of urls) {
+        try {
+          data = await fetchJson(listingsUrl, headers);
+          slug = s;
+          endpoint = listingsUrl;
+          break;
+        } catch {
+          // try next endpoint variant
+        }
+      }
+      if (data) break;
+    } catch {
+      // try next candidate slug
+    }
+  }
+  if (!data) {
+    throw new Error(`OpenSea collection not found for any slug candidate: ${candidates.join(", ")}`);
+  }
+  const rawListings = data?.listings || data?.orders || [];
+  const listings = rawListings.map((l, idx) => {
+    const wei =
+      l?.price?.current?.value ||
+      l?.current_price ||
+      l?.price?.value ||
+      l?.protocol_data?.parameters?.consideration?.[0]?.startAmount ||
+      "0";
+    const priceApe = Number((Number(wei) / 1e18).toFixed(6));
+    const tid = String(
+      l?.protocol_data?.parameters?.offer?.[0]?.identifierOrCriteria ||
+      l?.protocol_data?.parameters?.consideration?.[0]?.identifierOrCriteria ||
+      l?.asset?.token_id ||
+      tokenId ||
+      idx + 1,
+    );
+    return {
+      listingId: String(l?.order_hash || l?.id || `os_${idx}`),
+      orderHash: String(l?.order_hash || l?.id || `os_${idx}`),
+      collection: slug,
+      tokenId: tid,
+      priceApe,
+      currency: "APE",
+      source: "opensea",
+      protocolAddress: String(
+        l?.protocol_address ||
+          l?.protocolData?.protocol_address ||
+          "0x0000000000000068f116a894984e2db1123eb395",
+      ),
+      assetContractAddress: String(
+        l?.protocol_data?.parameters?.offer?.[0]?.token ||
+          l?.asset?.asset_contract?.address ||
+          "",
+      ),
+      chainSlug: "ape_chain",
+      expiresAt: l?.expiration_time
+        ? new Date(Number(l.expiration_time) * 1000).toISOString()
+        : null,
+      protocolData: l?.protocol_data || null,
+    };
+  });
+
+  const filteredByToken = tokenId
+    ? listings.filter((l) => String(l.tokenId) === String(tokenId))
+    : listings;
+
+  return {
+    source: "opensea",
+    listings: filteredByToken.filter((l) => Number(l.priceApe) <= Number(maxPrice)),
+    notes: [
+      "Listings fetched from OpenSea live listings endpoint.",
+      `Resolved slug: ${slug}`,
+      `Endpoint: ${endpoint}`,
+    ],
+  };
+}
+