@elizaos/autonomous 2.0.0-alpha.10

package/src/api/merkle-tree.ts

@@ -0,0 +1,239 @@
+/**
+ * Merkle tree service for whitelist proof generation.
+ *
+ * Builds a Merkle tree from verified addresses in whitelist.json and
+ * generates proofs that can be submitted to the smart contract's
+ * `mintWhitelist(name, endpoint, capHash, proof[])` function.
+ *
+ * This is the missing bridge between:
+ *   whitelist.json  →  Merkle tree  →  on-chain mintWhitelist()
+ *
+ * The contract stores a `merkleRoot()` and verifies each mint against
+ * a proof derived from the caller's address.
+ *
+ * Standard: leaves = keccak256(abi.encodePacked(address))
+ *           sorted pairs to ensure deterministic tree construction.
+ *
+ * @see drop-service.ts  — mintWithWhitelist() consumer
+ * @see twitter-verify.ts — one source of whitelist addresses
+ * @see nft-verify.ts     — another source of whitelist addresses
+ */
+
+import { logger } from "@elizaos/core";
+import { ethers } from "ethers";
+import { getVerifiedAddresses } from "./twitter-verify";
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface MerkleProofResult {
+  /** The proof array (bytes32[]) to submit to mintWhitelist(). */
+  proof: string[];
+  /** The leaf hash for this address. */
+  leaf: string;
+  /** The root of the current tree. */
+  root: string;
+  /** Whether this address is in the tree. */
+  isWhitelisted: boolean;
+}
+
+export interface MerkleTreeInfo {
+  /** The root hash of the current tree. */
+  root: string;
+  /** Total number of addresses in the tree. */
+  addressCount: number;
+  /** All leaf hashes (sorted). */
+  leaves: string[];
+}
+
+// ── Leaf hashing ─────────────────────────────────────────────────────────
+
+/**
+ * Hash an address into a Merkle leaf.
+ *
+ * Uses `keccak256(abi.encodePacked(address))` — the standard Solidity
+ * pattern for OpenZeppelin MerkleProof verification.
+ */
+export function hashLeaf(address: string): string {
+  return ethers.solidityPackedKeccak256(
+    ["address"],
+    [ethers.getAddress(address)], // checksummed
+  );
+}
+
+// ── Merkle tree construction ─────────────────────────────────────────────
+
+/**
+ * Sort a pair of hashes for deterministic tree construction.
+ * This ensures the tree is the same regardless of insertion order.
+ */
+function sortPair(a: string, b: string): [string, string] {
+  return a.toLowerCase() < b.toLowerCase() ? [a, b] : [b, a];
+}
+
+/**
+ * Hash two nodes together (internal node).
+ */
+function hashPair(a: string, b: string): string {
+  const [left, right] = sortPair(a, b);
+  return ethers.solidityPackedKeccak256(["bytes32", "bytes32"], [left, right]);
+}
+
+/**
+ * Build a Merkle tree from an array of leaf hashes.
+ *
+ * Returns the tree as a 2D array where:
+ *   tree[0] = leaves (sorted)
+ *   tree[1] = first level of internal nodes
+ *   ...
+ *   tree[tree.length - 1] = [root]
+ *
+ * Leaves are sorted before building to ensure determinism.
+ */
+export function buildTree(leaves: string[]): string[][] {
+  if (leaves.length === 0) {
+    return [[`0x${"0".repeat(64)}`]]; // empty tree → zero root
+  }
+
+  // Sort leaves for deterministic construction
+  const sorted = [...leaves].sort((a, b) =>
+    a.toLowerCase().localeCompare(b.toLowerCase()),
+  );
+
+  const tree: string[][] = [sorted];
+  let currentLevel = sorted;
+
+  while (currentLevel.length > 1) {
+    const nextLevel: string[] = [];
+    for (let i = 0; i < currentLevel.length; i += 2) {
+      if (i + 1 < currentLevel.length) {
+        nextLevel.push(hashPair(currentLevel[i], currentLevel[i + 1]));
+      } else {
+        // Odd node: promote to next level (no sibling)
+        nextLevel.push(currentLevel[i]);
+      }
+    }
+    tree.push(nextLevel);
+    currentLevel = nextLevel;
+  }
+
+  return tree;
+}
+
+/**
+ * Get the proof (sibling path) for a leaf in the tree.
+ */
+export function getProof(tree: string[][], leaf: string): string[] {
+  const proof: string[] = [];
+  let index = tree[0].indexOf(leaf);
+
+  if (index === -1) return []; // leaf not in tree
+
+  for (let level = 0; level < tree.length - 1; level++) {
+    const currentLevel = tree[level];
+    const isRightNode = index % 2 === 1;
+    const siblingIndex = isRightNode ? index - 1 : index + 1;
+
+    if (siblingIndex < currentLevel.length) {
+      proof.push(currentLevel[siblingIndex]);
+    }
+
+    index = Math.floor(index / 2);
+  }
+
+  return proof;
+}
+
+/**
+ * Get the root of the tree.
+ */
+export function getRoot(tree: string[][]): string {
+  return tree[tree.length - 1][0];
+}
+
+/**
+ * Verify a proof against a root.
+ *
+ * Recomputes the root from the leaf + proof path and checks
+ * if it matches the expected root.
+ */
+export function verifyProof(
+  leaf: string,
+  proof: string[],
+  expectedRoot: string,
+): boolean {
+  let computed = leaf;
+  for (const sibling of proof) {
+    computed = hashPair(computed, sibling);
+  }
+  return computed.toLowerCase() === expectedRoot.toLowerCase();
+}
+
+// ── High-level API ───────────────────────────────────────────────────────
+
+/**
+ * Build a Merkle tree from the current whitelist.
+ *
+ * Reads all verified addresses from whitelist.json, hashes them into
+ * leaves, and builds the tree.
+ */
+export function buildWhitelistTree(): {
+  tree: string[][];
+  info: MerkleTreeInfo;
+} {
+  const addresses = getVerifiedAddresses();
+  const leaves = addresses.map((addr) => hashLeaf(addr));
+
+  const tree = buildTree(leaves);
+  const root = getRoot(tree);
+
+  logger.info(
+    `[merkle] Built whitelist tree with ${addresses.length} addresses (root: ${root.slice(0, 10)}...)`,
+  );
+
+  return {
+    tree,
+    info: {
+      root,
+      addressCount: addresses.length,
+      leaves: tree[0],
+    },
+  };
+}
+
+/**
+ * Generate a Merkle proof for a specific address.
+ *
+ * Returns the proof, leaf, root, and whether the address is whitelisted.
+ * The proof can be passed directly to `mintWhitelist()` on the contract.
+ */
+export function generateProof(walletAddress: string): MerkleProofResult {
+  const { tree, info } = buildWhitelistTree();
+
+  let leaf: string;
+  try {
+    leaf = hashLeaf(walletAddress);
+  } catch {
+    return {
+      proof: [],
+      leaf: `0x${"0".repeat(64)}`,
+      root: info.root,
+      isWhitelisted: false,
+    };
+  }
+
+  const proof = getProof(tree, leaf);
+  const isWhitelisted =
+    proof.length > 0 || (info.addressCount === 1 && tree[0][0] === leaf);
+
+  if (isWhitelisted) {
+    const valid = verifyProof(leaf, proof, info.root);
+    if (!valid) {
+      logger.warn(
+        `[merkle] Proof verification failed for ${walletAddress} — tree may be corrupted`,
+      );
+      return { proof: [], leaf, root: info.root, isWhitelisted: false };
+    }
+  }
+
+  return { proof, leaf, root: info.root, isWhitelisted };
+}

package/src/api/models-routes.ts

@@ -0,0 +1,72 @@
+import type { RouteHelpers, RouteRequestMeta } from "./route-helpers";
+
+export interface ModelsRouteContext
+  extends RouteRequestMeta,
+    Pick<RouteHelpers, "json"> {
+  url: URL;
+  providerCachePath: (provider: string) => string;
+  getOrFetchProvider: (provider: string, force: boolean) => Promise<unknown[]>;
+  getOrFetchAllProviders: (
+    force: boolean,
+  ) => Promise<Record<string, unknown[]>>;
+  resolveModelsCacheDir: () => string;
+  pathExists: (targetPath: string) => boolean;
+  readDir: (targetPath: string) => string[];
+  unlinkFile: (targetPath: string) => void;
+  joinPath: (left: string, right: string) => string;
+}
+
+export async function handleModelsRoutes(
+  ctx: ModelsRouteContext,
+): Promise<boolean> {
+  const {
+    res,
+    method,
+    pathname,
+    url,
+    json,
+    providerCachePath,
+    getOrFetchProvider,
+    getOrFetchAllProviders,
+    resolveModelsCacheDir,
+    pathExists,
+    readDir,
+    unlinkFile,
+    joinPath,
+  } = ctx;
+
+  if (method !== "GET" || pathname !== "/api/models") return false;
+
+  const force = url.searchParams.get("refresh") === "true";
+  const specificProvider = url.searchParams.get("provider");
+
+  if (specificProvider) {
+    if (force) {
+      try {
+        unlinkFile(providerCachePath(specificProvider));
+      } catch {
+        // Ignore cache-bust errors and continue with a fresh fetch.
+      }
+    }
+    const models = await getOrFetchProvider(specificProvider, force);
+    json(res, { provider: specificProvider, models });
+    return true;
+  }
+
+  if (force) {
+    try {
+      const dir = resolveModelsCacheDir();
+      if (pathExists(dir)) {
+        for (const file of readDir(dir)) {
+          if (file.endsWith(".json")) unlinkFile(joinPath(dir, file));
+        }
+      }
+    } catch {
+      // Ignore cache-bust errors and continue with a fresh fetch.
+    }
+  }
+
+  const all = await getOrFetchAllProviders(force);
+  json(res, { providers: all });
+  return true;
+}

package/src/api/nfa-routes.ts

@@ -0,0 +1,169 @@
+import { createHash } from "node:crypto";
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import type { RouteHelpers, RouteRequestMeta } from "./route-helpers";
+
+function emptyMerkleRoot(): string {
+  return createHash("sha256").update("", "utf8").digest("hex");
+}
+
+type NfaPlugin = {
+  buildMerkleRoot: (leafHashes: string[]) => string;
+  parseLearnings: (markdown: string) => Array<{ hash: string }>;
+  sha256: (data: string) => string;
+};
+
+let nfaPlugin: NfaPlugin | null | undefined;
+
+async function getNfaPlugin(): Promise<NfaPlugin | null> {
+  if (nfaPlugin !== undefined) return nfaPlugin;
+  try {
+    const pkgName = "@elizaos/plugin-bnb-identity";
+    const mod = await import(/* @vite-ignore */ pkgName);
+    nfaPlugin =
+      typeof mod?.buildMerkleRoot === "function" &&
+      typeof mod?.parseLearnings === "function" &&
+      typeof mod?.sha256 === "function"
+        ? {
+            buildMerkleRoot: mod.buildMerkleRoot,
+            parseLearnings: mod.parseLearnings,
+            sha256: mod.sha256,
+          }
+        : null;
+  } catch {
+    nfaPlugin = null;
+  }
+  return nfaPlugin;
+}
+
+export interface NfaRouteContext
+  extends RouteRequestMeta,
+    Pick<RouteHelpers, "json" | "error"> {}
+
+interface NfaRecord {
+  tokenId: string;
+  contractAddress: string;
+  network: string;
+  ownerAddress: string;
+  mintTxHash: string;
+  merkleRoot: string;
+  mintedAt: string;
+  lastUpdatedAt: string;
+}
+
+interface IdentityRecord {
+  agentId: string;
+  network: string;
+  txHash: string;
+  ownerAddress: string;
+  agentURI: string;
+  registeredAt: string;
+  lastUpdatedAt: string;
+}
+
+async function readJsonFile<T>(filePath: string): Promise<T | null> {
+  try {
+    const raw = await readFile(filePath, "utf8");
+    return JSON.parse(raw) as T;
+  } catch {
+    return null;
+  }
+}
+
+export async function handleNfaRoutes(ctx: NfaRouteContext): Promise<boolean> {
+  const { res, method, pathname, json } = ctx;
+
+  if (method === "GET" && pathname === "/api/nfa/status") {
+    const miladyDir = join(homedir(), ".milady");
+    const [nfaRecord, identityRecord] = await Promise.all([
+      readJsonFile<NfaRecord>(join(miladyDir, "bap578-nfa.json")),
+      readJsonFile<IdentityRecord>(join(miladyDir, "bnb-identity.json")),
+    ]);
+
+    const bscscanBase =
+      (nfaRecord?.network ?? identityRecord?.network ?? "bsc-testnet") === "bsc"
+        ? "https://bscscan.com"
+        : "https://testnet.bscscan.com";
+
+    json(res, {
+      nfa: nfaRecord
+        ? {
+            tokenId: nfaRecord.tokenId,
+            contractAddress: nfaRecord.contractAddress,
+            network: nfaRecord.network,
+            ownerAddress: nfaRecord.ownerAddress,
+            merkleRoot: nfaRecord.merkleRoot,
+            mintTxHash: nfaRecord.mintTxHash,
+            mintedAt: nfaRecord.mintedAt,
+            lastUpdatedAt: nfaRecord.lastUpdatedAt,
+            bscscanUrl: `${bscscanBase}/tx/${nfaRecord.mintTxHash}`,
+          }
+        : null,
+      identity: identityRecord
+        ? {
+            agentId: identityRecord.agentId,
+            network: identityRecord.network,
+            ownerAddress: identityRecord.ownerAddress,
+            agentURI: identityRecord.agentURI,
+            registeredAt: identityRecord.registeredAt,
+            scanUrl: `https://${identityRecord.network === "bsc" ? "www" : "testnet"}.8004scan.io/agent/${identityRecord.agentId}`,
+          }
+        : null,
+      configured: !!(nfaRecord || identityRecord),
+    });
+    return true;
+  }
+
+  if (method === "GET" && pathname === "/api/nfa/learnings") {
+    const learningsPaths = [
+      join(homedir(), ".milady", "LEARNINGS.md"),
+      join(process.cwd(), "LEARNINGS.md"),
+    ];
+
+    let markdown: string | null = null;
+    let resolvedSource: string | null = null;
+    for (const path of learningsPaths) {
+      try {
+        markdown = await readFile(path, "utf8");
+        resolvedSource = path;
+        break;
+      } catch {}
+    }
+
+    if (!markdown) {
+      json(res, {
+        entries: [],
+        merkleRoot: emptyMerkleRoot(),
+        totalEntries: 0,
+        source: null,
+      });
+      return true;
+    }
+
+    const plugin = await getNfaPlugin();
+    if (!plugin) {
+      json(res, {
+        entries: [],
+        merkleRoot: emptyMerkleRoot(),
+        totalEntries: 0,
+        source: null,
+      });
+      return true;
+    }
+
+    const entries = plugin.parseLearnings(markdown);
+    const leafHashes = entries.map((entry) => entry.hash);
+    const merkleRoot = plugin.buildMerkleRoot(leafHashes);
+
+    json(res, {
+      entries,
+      merkleRoot,
+      totalEntries: entries.length,
+      source: resolvedSource,
+    });
+    return true;
+  }
+
+  return false;
+}

package/src/api/nft-verify.ts

@@ -0,0 +1,188 @@
+/**
+ * NFT holder verification for whitelist eligibility.
+ *
+ * Checks on-chain Milady NFT ownership (ERC-721 balanceOf) to determine
+ * whitelist eligibility. Verified addresses are stored in the same
+ * whitelist.json used by twitter-verify.ts, so both paths feed the
+ * same Merkle tree for on-chain whitelist proofs.
+ *
+ * OG Milady Maker: 0x5Af0D9827E0c53E4799BB226655A1de152A425a5 (Ethereum mainnet)
+ *
+ * @see twitter-verify.ts — parallel verificatio path via Twitter
+ * @see drop-service.ts  — mintWithWhitelist() consumer
+ */
+
+import { logger } from "@elizaos/core";
+import { ethers } from "ethers";
+import { isAddressWhitelisted, markAddressVerified } from "./twitter-verify";
+
+// ── Constants ────────────────────────────────────────────────────────────
+
+/** OG Milady Maker contract on Ethereum mainnet. */
+const MILADY_CONTRACT = "0x5Af0D9827E0c53E4799BB226655A1de152A425a5";
+
+/** Minimal ERC-721 ABI — only what we need. */
+const ERC721_BALANCE_ABI = [
+  "function balanceOf(address owner) view returns (uint256)",
+] as const;
+
+/** Default public Ethereum RPC endpoints (fallback chain). */
+const DEFAULT_RPC_ENDPOINTS = [
+  "https://cloudflare-eth.com",
+  "https://eth.llamarpc.com",
+  "https://rpc.ankr.com/eth",
+];
+
+/** Timeout for RPC calls (ms). */
+const RPC_TIMEOUT_MS = 15_000;
+
+// ── Types ────────────────────────────────────────────────────────────────
+
+export interface NftVerificationResult {
+  verified: boolean;
+  balance: number;
+  contractAddress: string;
+  error: string | null;
+}
+
+// ── Provider ─────────────────────────────────────────────────────────────
+
+/**
+ * Get an Ethereum JSON-RPC provider.
+ * Prefers ETHEREUM_RPC_URL env var, falls back to public endpoints.
+ */
+function getProvider(): ethers.JsonRpcProvider {
+  const customRpc = process.env.ETHEREUM_RPC_URL?.trim();
+  const rpcUrl = customRpc || DEFAULT_RPC_ENDPOINTS[0];
+
+  return new ethers.JsonRpcProvider(rpcUrl, 1, {
+    staticNetwork: true,
+  });
+}
+
+// ── Core Verification ────────────────────────────────────────────────────
+
+/**
+ * Check if a wallet address holds at least one Milady NFT.
+ *
+ * Makes a single `balanceOf()` call to the Milady contract on Ethereum
+ * mainnet. This is a read-only view call — no gas, no signing required.
+ */
+export async function verifyMiladyHolder(
+  walletAddress: string,
+): Promise<NftVerificationResult> {
+  const contractAddress =
+    process.env.MILADY_NFT_CONTRACT?.trim() || MILADY_CONTRACT;
+
+  // ── Input validation ───────────────────────────────────────────────
+  if (!walletAddress || typeof walletAddress !== "string") {
+    return {
+      verified: false,
+      balance: 0,
+      contractAddress,
+      error: "Wallet address is required.",
+    };
+  }
+
+  if (!ethers.isAddress(walletAddress)) {
+    return {
+      verified: false,
+      balance: 0,
+      contractAddress,
+      error: "Invalid Ethereum address format.",
+    };
+  }
+
+  // ── On-chain balance check ─────────────────────────────────────────
+  const provider = getProvider();
+
+  try {
+    const contract = new ethers.Contract(
+      contractAddress,
+      ERC721_BALANCE_ABI,
+      provider,
+    );
+
+    const balanceBN = (await Promise.race([
+      contract.balanceOf(walletAddress),
+      new Promise((_, reject) =>
+        setTimeout(
+          () => reject(new Error("RPC request timed out")),
+          RPC_TIMEOUT_MS,
+        ),
+      ),
+    ])) as bigint;
+
+    const balance = Number(balanceBN);
+
+    if (balance > 0) {
+      logger.info(
+        `[nft-verify] Address ${walletAddress} holds ${balance} Milady NFT(s) — verified ✓`,
+      );
+      return { verified: true, balance, contractAddress, error: null };
+    }
+
+    logger.info(
+      `[nft-verify] Address ${walletAddress} holds 0 Milady NFTs — not eligible`,
+    );
+    return {
+      verified: false,
+      balance: 0,
+      contractAddress,
+      error: "Wallet does not hold any Milady NFTs.",
+    };
+  } catch (err) {
+    const message = err instanceof Error ? err.message : "Unknown RPC error";
+    logger.warn(`[nft-verify] Balance check failed: ${message}`);
+    return {
+      verified: false,
+      balance: 0,
+      contractAddress,
+      error: `NFT verification failed: ${message}`,
+    };
+  } finally {
+    provider.destroy();
+  }
+}
+
+// ── Whitelist Integration ────────────────────────────────────────────────
+
+/**
+ * Verify NFT ownership and add to whitelist if eligible.
+ *
+ * This is the main entry point called by the API route. It performs the
+ * on-chain check and, if successful, writes the address into whitelist.json
+ * alongside any Twitter-verified addresses.
+ */
+export async function verifyAndWhitelistHolder(
+  walletAddress: string,
+): Promise<NftVerificationResult> {
+  // Skip the on-chain call if already whitelisted
+  if (isAddressWhitelisted(walletAddress)) {
+    logger.info(
+      `[nft-verify] Address ${walletAddress} already whitelisted — skipping RPC call`,
+    );
+    return {
+      verified: true,
+      balance: -1, // -1 indicates "already verified, balance not re-checked"
+      contractAddress:
+        process.env.MILADY_NFT_CONTRACT?.trim() || MILADY_CONTRACT,
+      error: null,
+    };
+  }
+
+  const result = await verifyMiladyHolder(walletAddress);
+
+  if (result.verified) {
+    markAddressVerified(
+      walletAddress,
+      `nft:milady:${result.contractAddress}`,
+      `milady-holder:${result.balance}`,
+    );
+    logger.info(
+      `[nft-verify] Address ${walletAddress} added to whitelist via NFT verification`,
+    );
+  }
+
+  return result;
+}