nebula-ai-plugin-onchain 0.1.0

package/src/approval.ts

@@ -0,0 +1,99 @@
+/**
+ * Permission-gate bridge between the deterministic policy engine and the
+ * harness permission service.
+ *
+ * The CLI + gateway pre-tool-call hooks build a `PermissionRequest` for every
+ * value-moving tool call and ask the permission service to resolve it. That
+ * service is driven by the operator's session MODE (strict/prompt/off). On its
+ * own it has no notion of "how much" — so under YOLO it would let any in-cap
+ * spend through silently. This helper closes that gap: it runs the SAME
+ * `evaluatePolicy` the tool runs and, when the policy flags the action as
+ * material-risk (`requiresApproval`), the hook sets `force` on the request so
+ * approval is demanded beneath the session mode. Fund controls in code, not in
+ * the model (CLAUDE.md).
+ *
+ * Native amounts are parsed from the human MNT arg. Token amounts can't be
+ * sized without decimals at this layer, so token/swap escalation rides on the
+ * policy autonomy tier (which `evaluatePolicy` resolves without an amount); the
+ * tool itself still enforces per-token hard caps with real decimals.
+ */
+
+import { parseEther } from 'viem'
+import { type OnchainPolicy, type PolicyAction, evaluatePolicy } from './policy'
+import { isNativeToken } from './tokens'
+
+function parseMntToWei(v: unknown): bigint {
+  if (typeof v !== 'string' && typeof v !== 'number') return 0n
+  try {
+    return parseEther(String(v))
+  } catch {
+    return 0n
+  }
+}
+
+/** `chain.write` already carries `value` in wei (string/number/bigint). */
+function parseWeiLike(v: unknown): bigint {
+  if (typeof v === 'bigint') return v
+  if (typeof v === 'number' && Number.isFinite(v)) return BigInt(Math.trunc(v))
+  if (typeof v === 'string' && /^\d+$/.test(v.trim())) return BigInt(v.trim())
+  return 0n
+}
+
+/** Map a tool call (name + raw args) to a best-effort PolicyAction. */
+function actionForCall(name: string, a: Record<string, unknown>): PolicyAction | null {
+  switch (name) {
+    case 'chain.send': {
+      const token = typeof a.token === 'string' ? a.token : undefined
+      const native = isNativeToken(token)
+      return {
+        kind: 'transfer',
+        asset: native ? 'native' : (token as string),
+        amountRaw: native ? parseMntToWei(a.amount) : 0n,
+        to: typeof a.to === 'string' ? a.to : undefined,
+      }
+    }
+    case 'chain.wrap':
+    case 'chain.unwrap':
+      return { kind: 'transfer', asset: 'native', amountRaw: parseMntToWei(a.amount) }
+    case 'swap.execute':
+    case 'moe.swap':
+    case 'swap.best':
+      return {
+        kind: 'swap',
+        asset: typeof a.tokenIn === 'string' ? a.tokenIn : 'native',
+        amountRaw: 0n,
+        slippageBps: typeof a.slippageBps === 'number' ? a.slippageBps : undefined,
+      }
+    case 'aave.supply':
+    case 'aave.withdraw':
+    case 'aave.borrow':
+    case 'aave.repay':
+      // Token amount needs decimals we don't have here, so the floor rides the
+      // autonomy tier (confirm => approval); the tool re-checks with decimals.
+      return {
+        kind: 'transfer',
+        asset: typeof a.token === 'string' ? a.token : 'native',
+        amountRaw: 0n,
+      }
+    case 'chain.write':
+      return { kind: 'transfer', asset: 'native', amountRaw: parseWeiLike(a.value) }
+    default:
+      return null
+  }
+}
+
+/**
+ * True when the policy requires human approval for this tool call (the gate
+ * should force a prompt regardless of mode). Returns false when no policy is
+ * configured or the call is not value-moving.
+ */
+export function policyRequiresApprovalForCall(
+  name: string,
+  args: Record<string, unknown>,
+  policy: OnchainPolicy | undefined,
+): boolean {
+  if (!policy) return false
+  const action = actionForCall(name, args)
+  if (!action) return false
+  return evaluatePolicy(action, policy).requiresApproval
+}

package/src/balances.ts

@@ -0,0 +1,262 @@
+/**
+ * Balance discovery + multicall reads.
+ *
+ * The "no curated list" rule from `phase-10-design-locked.md` means
+ * `chain.balance` (no token arg) needs to find every ERC-20 the agent has
+ * ever held WITHOUT a hardcoded list. We do this by scanning ERC-20 Transfer
+ * events keyed on the agent's address as topic2 (recipient) since iNFT mint.
+ * The set of distinct contract emitters IS the agent's token universe.
+ *
+ * Multicall3 then batches `balanceOf` reads on every discovered contract
+ * plus a `getEthBalance` for native Mantle — single round-trip.
+ */
+
+import { existsSync, mkdirSync, readFileSync, writeFileSync } from 'node:fs'
+import { dirname, join } from 'node:path'
+import {
+  type Address,
+  type PublicClient,
+  decodeFunctionResult,
+  encodeFunctionData,
+  formatEther,
+  formatUnits,
+  getAddress,
+  pad,
+} from 'viem'
+import { ERC20_ABI, MULTICALL3_ABI } from './abis'
+import {
+  LOG_SCAN_CHUNK_BLOCKS,
+  LOG_SCAN_MAX_CHUNKS,
+  MULTICALL3,
+  TRANSFER_TOPIC0,
+} from './constants'
+import { rawGetLogs } from './raw-logs'
+import { fetchOnchainErc20Info, loadTokenCache, lookupFromList, rememberTokens } from './tokens'
+import type { BalanceSnapshot, TokenInfo } from './types'
+
+function lastScannedBlockPath(agentDir: string): string {
+  return join(agentDir, 'onchain', 'last-scanned-block.txt')
+}
+
+function readLastScannedBlock(agentDir: string): bigint | null {
+  const path = lastScannedBlockPath(agentDir)
+  if (!existsSync(path)) return null
+  try {
+    const raw = readFileSync(path, 'utf8').trim()
+    if (!raw) return null
+    return BigInt(raw)
+  } catch {
+    return null
+  }
+}
+
+function writeLastScannedBlock(agentDir: string, blockNumber: bigint): void {
+  const path = lastScannedBlockPath(agentDir)
+  mkdirSync(dirname(path), { recursive: true })
+  writeFileSync(path, blockNumber.toString())
+}
+
+/**
+ * Scan ERC-20 Transfer events where `to == address` for the given block range.
+ * Returns the unique set of token contract addresses (lowercase). Chunks to
+ * stay under the RPC's getLogs limits.
+ */
+export async function discoverTokensByTransfers(opts: {
+  client: PublicClient
+  address: Address
+  fromBlock: bigint
+  toBlock: bigint
+}): Promise<Address[]> {
+  const { client, address, fromBlock, toBlock } = opts
+  if (toBlock < fromBlock) return []
+  const padded = pad(address, { size: 32 })
+  const seen = new Set<string>()
+  let cursor = fromBlock
+  let chunks = 0
+  while (cursor <= toBlock && chunks < LOG_SCAN_MAX_CHUNKS) {
+    const chunkEnd = cursor + LOG_SCAN_CHUNK_BLOCKS - 1n
+    const end = chunkEnd > toBlock ? toBlock : chunkEnd
+    try {
+      const logs = await rawGetLogs({
+        client,
+        topics: [TRANSFER_TOPIC0, null, padded],
+        fromBlock: cursor,
+        toBlock: end,
+      })
+      for (const log of logs) {
+        seen.add(log.address.toLowerCase())
+      }
+    } catch {
+      // Some RPCs throttle on dense ranges; halve the chunk and continue
+      const half = (end - cursor + 1n) / 2n
+      if (half > 0n) {
+        try {
+          const logs = await rawGetLogs({
+            client,
+            topics: [TRANSFER_TOPIC0, null, padded],
+            fromBlock: cursor,
+            toBlock: cursor + half - 1n,
+          })
+          for (const log of logs) {
+            seen.add(log.address.toLowerCase())
+          }
+        } catch {
+          // give up on this chunk silently — won't miss balances since
+          // we'll still pick up via cache from a later run
+        }
+      }
+    }
+    cursor = end + 1n
+    chunks += 1
+  }
+  return Array.from(seen).map(a => getAddress(a) as Address)
+}
+
+/**
+ * Read native + ERC-20 balances for `address` via Multicall3 in one round-trip.
+ * Tokens with zero balance are still returned; caller filters.
+ */
+export async function readBalancesMulticall(opts: {
+  client: PublicClient
+  address: Address
+  tokens: TokenInfo[]
+}): Promise<{
+  blockNumber: number
+  native: bigint
+  perToken: Map<string, bigint>
+}> {
+  const { client, address, tokens } = opts
+  const calls: Array<{
+    target: Address
+    allowFailure: boolean
+    callData: `0x${string}`
+  }> = []
+  // [0] native via Multicall3.getEthBalance
+  calls.push({
+    target: MULTICALL3,
+    allowFailure: false,
+    callData: encodeFunctionData({
+      abi: MULTICALL3_ABI,
+      functionName: 'getEthBalance',
+      args: [address],
+    }),
+  })
+  // [1..n] ERC-20 balanceOf
+  for (const t of tokens) {
+    calls.push({
+      target: t.address,
+      allowFailure: true,
+      callData: encodeFunctionData({
+        abi: ERC20_ABI,
+        functionName: 'balanceOf',
+        args: [address],
+      }),
+    })
+  }
+  const blockNumber = await client.getBlockNumber()
+  const results = (await client.readContract({
+    address: MULTICALL3,
+    abi: MULTICALL3_ABI,
+    functionName: 'aggregate3',
+    args: [calls],
+  })) as ReadonlyArray<{ success: boolean; returnData: `0x${string}` }>
+  const native = decodeFunctionResult({
+    abi: MULTICALL3_ABI,
+    functionName: 'getEthBalance',
+    data: results[0]!.returnData,
+  }) as bigint
+  const perToken = new Map<string, bigint>()
+  for (let i = 0; i < tokens.length; i++) {
+    const r = results[i + 1]
+    if (!r?.success) continue
+    try {
+      const bal = decodeFunctionResult({
+        abi: ERC20_ABI,
+        functionName: 'balanceOf',
+        data: r.returnData,
+      }) as bigint
+      perToken.set(tokens[i]!.address.toLowerCase(), bal)
+    } catch {
+      // ignore unparseable
+    }
+  }
+  return { blockNumber: Number(blockNumber), native, perToken }
+}
+
+/**
+ * High-level: discover tokens via Transfer scan + cached set, then multicall
+ * balances. Persists cache + last-scanned block.
+ */
+export async function snapshotBalances(opts: {
+  client: PublicClient
+  agentDir: string
+  address: Address
+  mintBlock: bigint
+  includeZero?: boolean
+  refresh?: boolean
+}): Promise<BalanceSnapshot> {
+  const { client, agentDir, address, mintBlock, includeZero, refresh } = opts
+  const cache = loadTokenCache(agentDir)
+  const cachedTokens: TokenInfo[] = Object.values(cache.byAddress)
+  const head = await client.getBlockNumber()
+  const lastScanned = refresh ? null : readLastScannedBlock(agentDir)
+  const fromBlock = lastScanned !== null ? lastScanned + 1n : mintBlock
+  const newAddrs =
+    fromBlock <= head
+      ? await discoverTokensByTransfers({
+          client,
+          address,
+          fromBlock,
+          toBlock: head,
+        })
+      : []
+
+  // Resolve metadata for any new addresses not in cache/list. Metadata reads
+  // are independent — fan out so a 20-token discovery doesn't serialize 20
+  // round-trips. List hits skip the network entirely.
+  const cachedSet = new Set(cachedTokens.map(t => t.address.toLowerCase()))
+  const toResolve = newAddrs.filter(a => !cachedSet.has(a.toLowerCase()))
+  const resolvedRaw = await Promise.all(
+    toResolve.map(a => {
+      const fromList = lookupFromList(a, cache)
+      return fromList !== null ? Promise.resolve(fromList) : fetchOnchainErc20Info(client, a)
+    }),
+  )
+  const resolved = resolvedRaw.filter((t): t is TokenInfo => t !== null)
+  if (resolved.length > 0) rememberTokens(agentDir, resolved)
+  // Skip the file write when the cursor didn't advance (multiple
+  // chain.balance calls in the same chat turn end up on the same head).
+  if (lastScanned === null || head > lastScanned) {
+    writeLastScannedBlock(agentDir, head)
+  }
+
+  const allTokens = [...cachedTokens, ...resolved]
+  const { blockNumber, native, perToken } = await readBalancesMulticall({
+    client,
+    address,
+    tokens: allTokens,
+  })
+  const tokenBalances = allTokens
+    .map(t => {
+      const raw = perToken.get(t.address.toLowerCase()) ?? 0n
+      return {
+        ...t,
+        raw: raw.toString(),
+        formatted: formatUnits(raw, t.decimals),
+      }
+    })
+    .filter(b => includeZero || b.raw !== '0')
+    .sort((a, b) => {
+      const ar = BigInt(a.raw)
+      const br = BigInt(b.raw)
+      if (ar > br) return -1
+      if (ar < br) return 1
+      return a.symbol.localeCompare(b.symbol)
+    })
+  return {
+    address,
+    native: { raw: native.toString(), formatted: formatEther(native) },
+    tokens: tokenBalances,
+    blockNumber,
+  }
+}

package/src/bybit.ts

@@ -0,0 +1,118 @@
+/**
+ * Bybit V5 read-only client — account balance (portfolio view) only.
+ *
+ * DELIBERATELY READ-ONLY. CEX trading/transfers are out of scope: they execute
+ * off-chain and would bypass Nebula's on-chain policy -> simulate -> approval
+ * pipeline (the whole safety thesis). This only reads the Unified account
+ * balance so the agent can show a CEX + on-chain treasury picture.
+ *
+ * Auth: V5 HMAC-SHA256. Keys come from the ENVIRONMENT only
+ * (BYBIT_API_KEY / BYBIT_API_SECRET) — never committed.
+ */
+
+import { createHmac } from 'node:crypto'
+
+export const BYBIT_BASE = 'https://api.bybit.com'
+const RECV_WINDOW = '5000'
+
+/**
+ * V5 signature: HMAC_SHA256(timestamp + apiKey + recvWindow + payload, secret).
+ * For GET, payload is the (already-ordered) query string. Pure + unit-testable.
+ */
+export function bybitSign(opts: {
+  secret: string
+  timestamp: string
+  apiKey: string
+  recvWindow: string
+  payload: string
+}): string {
+  return createHmac('sha256', opts.secret)
+    .update(opts.timestamp + opts.apiKey + opts.recvWindow + opts.payload)
+    .digest('hex')
+}
+
+export interface BybitCoin {
+  coin: string
+  walletBalance: string
+  /** Bybit-reported USD value of the holding (exchange data, not Nebula pricing). */
+  usdValue: string
+}
+
+export interface BybitBalanceResult {
+  ok: boolean
+  error?: string
+  accountType?: string
+  /** Bybit-reported total equity in USD (exchange figure). */
+  totalEquityUsd?: string
+  coins: BybitCoin[]
+}
+
+/**
+ * Read the Unified Trading account balance. `now` is injectable for tests.
+ */
+export async function fetchBybitBalance(opts: {
+  apiKey: string
+  apiSecret: string
+  fetchImpl?: typeof fetch
+  now?: () => number
+}): Promise<BybitBalanceResult> {
+  const { apiKey, apiSecret, fetchImpl } = opts
+  const f = fetchImpl ?? fetch
+  const now = opts.now ?? (() => Date.now())
+  const timestamp = String(now())
+  const query = 'accountType=UNIFIED'
+  const sign = bybitSign({
+    secret: apiSecret,
+    timestamp,
+    apiKey,
+    recvWindow: RECV_WINDOW,
+    payload: query,
+  })
+
+  let res: Response
+  try {
+    res = await f(`${BYBIT_BASE}/v5/account/wallet-balance?${query}`, {
+      method: 'GET',
+      headers: {
+        'X-BAPI-API-KEY': apiKey,
+        'X-BAPI-TIMESTAMP': timestamp,
+        'X-BAPI-RECV-WINDOW': RECV_WINDOW,
+        'X-BAPI-SIGN': sign,
+      },
+    })
+  } catch (e) {
+    return {
+      ok: false,
+      error: `Bybit request failed: ${(e as Error).message.slice(0, 120)}`,
+      coins: [],
+    }
+  }
+  const j = (await res.json().catch(() => ({}))) as {
+    retCode?: number
+    retMsg?: string
+    result?: {
+      list?: Array<{
+        accountType?: string
+        totalEquity?: string
+        coin?: Array<{ coin?: string; walletBalance?: string; usdValue?: string }>
+      }>
+    }
+  }
+  if (j.retCode !== 0) {
+    return { ok: false, error: `Bybit: ${j.retMsg ?? `retCode ${j.retCode}`}`, coins: [] }
+  }
+  const acct = j.result?.list?.[0]
+  const coins = (acct?.coin ?? [])
+    .map(c => ({
+      coin: c.coin ?? '?',
+      walletBalance: c.walletBalance ?? '0',
+      usdValue: c.usdValue ?? '0',
+    }))
+    .filter(c => Number(c.walletBalance) > 0)
+  return {
+    ok: true,
+    accountType: acct?.accountType ?? 'UNIFIED',
+    totalEquityUsd: acct?.totalEquity ?? '0',
+    coins,
+  }
+}

package/src/constants.ts

@@ -0,0 +1,102 @@
+/**
+ * Mainnet-verified contract addresses for Mantle Aristotle (chain 5000).
+ * All four core protocols below were probed live on May 1 2026 with successful
+ * txs; see memory `phase-10-design-locked.md` for the cast verifications.
+ */
+
+import type { NebulaNetwork } from 'nebula-ai-core'
+import type { Address } from 'viem'
+
+/** Multicall3 universal address — same on every EVM chain that has it. */
+export const MULTICALL3: Address = '0xcA11bde05977b3631167028862bE2a173976CA11'
+
+/** AGNI protocol contracts (Uniswap V3 softfork on Mantle). */
+export interface AgniAddresses {
+  factory: Address
+  swapRouter: Address
+  quoter: Address
+  weth9: Address
+}
+
+export const AGNI_BY_NETWORK: Record<NebulaNetwork, AgniAddresses | null> = {
+  'mantle-mainnet': {
+    // Agni Finance (Uniswap V3 fork) on Mantle mainnet. Source: official
+    // agni-sdk HomeAddress.ts; factory + swapRouter cross-verified on-chain.
+    factory: '0x25780dc8Fc3cfBD75F33bFDAB65e969b603b2035',
+    swapRouter: '0x319B69888b0d11cEC22caA5034e25FfFBDc88421',
+    quoter: '0x9488C05a7b75a6FefdcAE4f11a33467bcBA60177', // QuoterV1 (5-arg quoteExactInputSingle)
+    weth9: '0x78c1b0C915c4FAA5FffA6CAbf0219DA63d7f4cb8', // WMNT
+  },
+  'mantle-testnet': null, // Agni not wired for Mantle Sepolia testnet.
+}
+
+/** Aave V3 Pool on Mantle. Verified live (getReservesList returns 10 markets). */
+export const AAVE_POOL_BY_NETWORK: Record<NebulaNetwork, Address | null> = {
+  'mantle-mainnet': '0x458F293454fE0d67EC0655f3672301301DD51422',
+  'mantle-testnet': null,
+}
+
+/** Merchant Moe Liquidity Book contracts (LFJ/Trader Joe LB fork on Mantle). */
+export interface MoeLbAddresses {
+  router: Address
+  quoter: Address
+  factory: Address
+}
+
+/**
+ * Merchant Moe LB on Mantle mainnet. Source: official docs
+ * (docs.merchantmoe.com/resources/contracts); all three cross-verified on-chain
+ * (deployed bytecode) + the quoter live-verified (1 WMNT -> 0.55 USDC).
+ */
+export const MOE_LB_BY_NETWORK: Record<NebulaNetwork, MoeLbAddresses | null> = {
+  'mantle-mainnet': {
+    router: '0x013e138EF6008ae5FDFDE29700e3f2Bc61d21E3a',
+    quoter: '0x501b8AFd35df20f531fF45F6f695793AC3316c85',
+    factory: '0xa6630671775c4EA2743840F9A5016dCf2A104054',
+  },
+  'mantle-testnet': null,
+}
+
+/** AGNI V3 fee tiers in increasing order (1 bp = 0.01%). */
+export const FEE_TIERS = [500, 3000, 10000] as const
+export type FeeTier = (typeof FEE_TIERS)[number]
+
+/** Default swap deadline: 10 minutes. */
+export const DEFAULT_DEADLINE_SECS = 600n
+
+/** Default slippage tolerance (50 bps = 0.5%). */
+export const DEFAULT_SLIPPAGE_BPS = 50
+
+/** Block-range chunk size for `eth_getLogs`. 50k chunks safe on Mantle mainnet RPC. */
+export const LOG_SCAN_CHUNK_BLOCKS = 50_000n
+
+/** keccak256("Transfer(address,address,uint256)") — ERC-20/721 Transfer topic0. */
+export const TRANSFER_TOPIC0 =
+  '0xddf252ad1be2c89b69c2b068fc378daa952ba7f163c4a11628f55a4df523b3ef' as const
+
+/** Max chunks per `chain.balance` discovery scan = 1.5M block ceiling. */
+export const LOG_SCAN_MAX_CHUNKS = 30
+
+/** EIP-1967 implementation slot for proxy detection. */
+export const EIP1967_IMPL_SLOT =
+  '0x360894a13ba1a3210667c828492db98dca3e2076cc3735a920a3ca505d382bbc' as const
+
+/** ERC-165 interface IDs nebula checks via `chain.contract`. */
+export const ERC165_INTERFACES = {
+  ERC721: '0x80ac58cd',
+  ERC1155: '0xd9b67a26',
+  ERC721Metadata: '0x5b5e139f',
+  ERC721Enumerable: '0x780e9d63',
+} as const
+
+/** Symbols the brain may say in lieu of "native" / address. MNT is Mantle's gas token. */
+export const NATIVE_ALIASES = new Set(['MNT', 'mnt', 'native', 'Mantle', 'mantle'])
+
+/** Convenience guard that throws if the network has no AGNI deployment. */
+export function requireMainnet(network: NebulaNetwork): asserts network is 'mantle-mainnet' {
+  if (network !== 'mantle-mainnet') {
+    throw new Error(
+      `plugin-onchain currently supports mantle-mainnet only (got ${network}). AGNI isn't deployed on testnet.`,
+    )
+  }
+}