nebula-ai-plugin-onchain 0.1.0

package/src/tools/blockchain.ts

@@ -0,0 +1,95 @@
+/**
+ * `chain.block` + `chain.gas` — passive RPC introspection.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { getGasPriceWithFloor } from 'nebula-ai-core'
+import { formatEther, formatGwei } from 'viem'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+/** Representative gas units per operation (Mantle), for cost estimates in MNT. */
+const TYPICAL_GAS: ReadonlyArray<readonly [string, bigint]> = [
+  ['nativeTransfer', 21_000n],
+  ['erc20Transfer', 52_000n],
+  ['swap', 180_000n],
+  ['aaveSupply', 250_000n],
+]
+
+const BlockSchema = z.object({
+  tag: z
+    .union([
+      z.enum(['latest', 'finalized', 'safe', 'earliest', 'pending']),
+      z.number().int().nonnegative(),
+    ])
+    .optional()
+    .describe('Block tag or number (default: "latest").'),
+})
+type BlockArgs = z.infer<typeof BlockSchema>
+
+export function makeChainBlock(ctx: OnchainRuntimeContext): ToolDef<BlockArgs> {
+  return {
+    name: 'chain.block',
+    description:
+      'Read a Mantle block summary (number, hash, timestamp, txCount, gasUsed). Default: latest.',
+    searchHint: 'block number height timestamp head',
+    schema: BlockSchema,
+    handler: async args => {
+      try {
+        const tag = args.tag ?? 'latest'
+        const block =
+          typeof tag === 'number'
+            ? await ctx.publicClient.getBlock({ blockNumber: BigInt(tag) })
+            : await ctx.publicClient.getBlock({ blockTag: tag })
+        return {
+          ok: true,
+          data: {
+            number: Number(block.number ?? 0n),
+            hash: block.hash,
+            parentHash: block.parentHash,
+            timestamp: Number(block.timestamp),
+            txCount: block.transactions.length,
+            gasUsed: block.gasUsed.toString(),
+            gasLimit: block.gasLimit.toString(),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+const GasSchema = z.object({})
+type GasArgs = z.infer<typeof GasSchema>
+
+export function makeChainGas(ctx: OnchainRuntimeContext): ToolDef<GasArgs> {
+  return {
+    name: 'chain.gas',
+    description:
+      'Current Mantle gas price (network 4 gwei floor applied) plus estimated MNT cost of common operations (native/ERC-20 transfer, swap, Aave supply). Use to estimate cost or detect spikes. Costs are in MNT, not USD.',
+    searchHint: 'gas price gwei fee estimate cost mnt how much transfer swap',
+    schema: GasSchema,
+    handler: async () => {
+      try {
+        const wei = await getGasPriceWithFloor(ctx.publicClient)
+        const estimatedCostMnt = Object.fromEntries(
+          TYPICAL_GAS.map(([op, units]) => [
+            op,
+            { gasUnits: Number(units), costMnt: formatEther(wei * units) },
+          ]),
+        )
+        return {
+          ok: true,
+          data: {
+            gasPriceWei: wei.toString(),
+            gasPriceGwei: formatGwei(wei),
+            estimatedCostMnt,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/cex.ts

@@ -0,0 +1,54 @@
+/**
+ * `cex.balance` — read-only Bybit Unified account balance (portfolio view).
+ *
+ * READ-ONLY by design: no CEX trading/transfers (they'd bypass the on-chain
+ * safety pipeline). Keys come from BYBIT_API_KEY / BYBIT_API_SECRET in the env,
+ * never committed. Degrades gracefully when keys are unset.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+import { fetchBybitBalance } from '../bybit'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({})
+type Args = z.infer<typeof Schema>
+
+export function makeCexBalance(_ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'cex.balance',
+    description:
+      'Read-only Bybit Unified account balance (CEX portfolio: per-coin balances + exchange-reported total equity). Lets you show a combined CEX + on-chain treasury picture. Needs BYBIT_API_KEY + BYBIT_API_SECRET in the env. Read-only — this agent never trades or transfers on the CEX (that would bypass the on-chain safety controls).',
+    searchHint: 'cex bybit exchange balance portfolio account holdings off-chain unified',
+    schema: Schema,
+    handler: async () => {
+      try {
+        const apiKey = process.env.BYBIT_API_KEY
+        const apiSecret = process.env.BYBIT_API_SECRET
+        if (!apiKey || !apiSecret) {
+          return {
+            ok: true,
+            data: {
+              configured: false,
+              note: 'BYBIT_API_KEY / BYBIT_API_SECRET not set — CEX balance unavailable. Set them in the env (never commit them); use a READ-ONLY key.',
+            },
+          }
+        }
+        const r = await fetchBybitBalance({ apiKey, apiSecret })
+        if (!r.ok) return { ok: true, data: { venue: 'Bybit', available: false, note: r.error } }
+        return {
+          ok: true,
+          data: {
+            venue: 'Bybit (Unified, read-only)',
+            accountType: r.accountType,
+            totalEquityUsd: r.totalEquityUsd,
+            coins: r.coins,
+            note: 'Exchange-reported figures; this agent does not trade or transfer on the CEX.',
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/defillama.ts

@@ -0,0 +1,83 @@
+/**
+ * `defi.yields` — discover Mantle yield opportunities via DeFiLlama (analytics
+ * + discovery only; never execution, per CLAUDE.md). Read-only: no signer, no
+ * policy/simulation gate. Restricted products (USDY/MI4/mUSD) are surfaced but
+ * flagged so the brain proposes them only with eligibility confirmation.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { z } from 'zod'
+import { fetchMantleYields } from '../defillama'
+import type { OnchainRuntimeContext } from '../types'
+
+const Schema = z.object({
+  minTvlUsd: z
+    .number()
+    .optional()
+    .describe('Minimum pool TVL in USD (filters illiquid pools). Default 50000.'),
+  stableOnly: z
+    .boolean()
+    .optional()
+    .describe('Only stablecoin pools — lower-risk treasury parking. Default false.'),
+  noIlRisk: z
+    .boolean()
+    .optional()
+    .describe('Exclude pools flagged with impermanent-loss risk. Default false.'),
+  project: z
+    .string()
+    .optional()
+    .describe('Filter to a protocol slug substring, e.g. "aave", "agni", "merchant-moe".'),
+  sortBy: z.enum(['apy', 'tvl']).optional().describe('Rank by APY (default) or TVL.'),
+  limit: z.number().optional().describe('Max rows (1-50). Default 10.'),
+})
+type Args = z.infer<typeof Schema>
+
+export function makeDefiYields(_ctx: OnchainRuntimeContext): ToolDef<Args> {
+  return {
+    name: 'defi.yields',
+    description:
+      'Discover Mantle yield opportunities (lending + LP pools) ranked by APY or TVL, via DeFiLlama. Each row carries risk signals: stablecoin, impermanent-loss risk, single/multi exposure, 7d APY trend, and a `restricted` flag for products that need eligibility confirmation (USDY/MI4/mUSD). Analytics + discovery ONLY — does not execute anything. Use for "best yields on Mantle", "where can I park USDC", "safe stablecoin yield".',
+    searchHint:
+      'defi yield apy pool discover farm lend stablecoin tvl mantle defillama best return',
+    schema: Schema,
+    handler: async (args: Args) => {
+      try {
+        const pools = await fetchMantleYields({
+          minTvlUsd: args.minTvlUsd,
+          stableOnly: args.stableOnly,
+          noIlRisk: args.noIlRisk,
+          project: args.project,
+          sortBy: args.sortBy,
+          limit: args.limit,
+        })
+        return {
+          ok: true,
+          data: {
+            chain: 'Mantle',
+            source: 'DeFiLlama (analytics/discovery only — not executable)',
+            count: pools.length,
+            restrictedNote:
+              pools.some(p => p.restricted) === true
+                ? 'Some results are RESTRICTED products (USDY/MI4/mUSD); confirm eligibility before proposing entry.'
+                : undefined,
+            pools: pools.map(p => ({
+              project: p.project,
+              symbol: p.symbol,
+              apy: Number(p.apy.toFixed(2)),
+              apyBase: p.apyBase === null ? null : Number(p.apyBase.toFixed(2)),
+              apyReward: p.apyReward === null ? null : Number(p.apyReward.toFixed(2)),
+              apy7dTrend: p.apyPct7D === null ? null : Number(p.apyPct7D.toFixed(2)),
+              tvlUsd: Math.round(p.tvlUsd),
+              stablecoin: p.stablecoin,
+              ilRisk: p.ilRisk,
+              exposure: p.exposure,
+              restricted: p.restricted,
+            })),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/generic.ts

@@ -0,0 +1,213 @@
+/**
+ * `chain.read` + `chain.write` — generic ABI-call escape hatch for contracts
+ * not covered by the curated tools.
+ *
+ * Argument format mirrors `cast`:
+ *   - `signature: 'balanceOf(address)'`
+ *   - `args: ['0xabc...']`
+ * Decimal numbers are auto-converted to bigint (zod number → BigInt) to keep
+ * the interface friendly for the LLM. Hex strings stay as-is.
+ */
+
+import type { ToolDef } from 'nebula-ai-core'
+import { getGasPriceWithFloor } from 'nebula-ai-core'
+import {
+  type Address,
+  decodeAbiParameters,
+  encodeFunctionData,
+  getAddress,
+  parseAbiItem,
+  parseAbiParameters,
+  parseEther,
+} from 'viem'
+import { z } from 'zod'
+import { evaluatePolicy } from '../policy'
+import { simulateRawTx } from '../simulate'
+import type { OnchainRuntimeContext } from '../types'
+import { waitForReceipt } from '../wait-receipt'
+
+const ReadSchema = z.object({
+  to: z.string().min(42).describe('0x contract address.'),
+  signature: z
+    .string()
+    .min(1)
+    .describe('Function signature, e.g. "balanceOf(address)" or "totalSupply()".'),
+  args: z.array(z.unknown()).optional().describe('Encoded args matching signature.'),
+  returnTypes: z
+    .array(z.string())
+    .optional()
+    .describe('Optional explicit return types for decoding (e.g. ["uint256"]).'),
+})
+type ReadArgs = z.infer<typeof ReadSchema>
+
+export function coerceArg(raw: unknown): unknown {
+  if (typeof raw === 'string') {
+    if (/^-?\d+$/.test(raw) && !raw.startsWith('0x')) {
+      try {
+        return BigInt(raw)
+      } catch {
+        return raw
+      }
+    }
+    return raw
+  }
+  if (typeof raw === 'number') {
+    return BigInt(raw)
+  }
+  if (Array.isArray(raw)) return raw.map(coerceArg)
+  return raw
+}
+
+export function buildAbiFunction(signature: string): import('viem').AbiFunction {
+  const trimmed = signature.trim()
+  const text = trimmed.startsWith('function ') ? trimmed : `function ${trimmed}`
+  const item = parseAbiItem(text)
+  if (typeof item !== 'object' || item.type !== 'function') {
+    throw new Error(`could not parse function signature: ${signature}`)
+  }
+  return item as import('viem').AbiFunction
+}
+
+export function makeChainRead(ctx: OnchainRuntimeContext): ToolDef<ReadArgs> {
+  return {
+    name: 'chain.read',
+    description:
+      'Generic eth_call. Pass `signature` (e.g. "balanceOf(address)") + `args`. Returns hex `data` plus a decoded version when `returnTypes` provided OR the signature itself includes returns.',
+    searchHint: 'read view eth_call generic abi cast',
+    schema: ReadSchema,
+    handler: async args => {
+      try {
+        const fn = buildAbiFunction(args.signature)
+        const coerced = (args.args ?? []).map(coerceArg)
+        const data = encodeFunctionData({
+          abi: [fn] as readonly [import('viem').AbiFunction],
+          args: coerced,
+        })
+        const result = await ctx.publicClient.call({
+          to: getAddress(args.to) as Address,
+          data,
+        })
+        const raw = result.data ?? '0x'
+        let decoded: unknown[] | null = null
+        if (args.returnTypes && args.returnTypes.length > 0) {
+          try {
+            const params = parseAbiParameters(args.returnTypes.join(', '))
+            decoded = [...decodeAbiParameters(params, raw)]
+          } catch {
+            decoded = null
+          }
+        } else if (fn.outputs && fn.outputs.length > 0) {
+          try {
+            decoded = [...decodeAbiParameters(fn.outputs as never, raw)]
+          } catch {
+            decoded = null
+          }
+        }
+        return {
+          ok: true,
+          data: {
+            to: getAddress(args.to),
+            signature: args.signature,
+            raw,
+            decoded:
+              decoded === null
+                ? null
+                : decoded.map(d => (typeof d === 'bigint' ? d.toString() : d)),
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}
+
+const WriteSchema = z.object({
+  to: z.string().min(42),
+  signature: z.string().min(1),
+  args: z.array(z.unknown()).optional(),
+  value: z
+    .string()
+    .optional()
+    .describe(
+      'Native value to send. Accepts decimal Mantle ("0.0001") OR wei integer ("100000000000000").',
+    ),
+})
+type WriteArgs = z.infer<typeof WriteSchema>
+
+export function parseChainWriteValue(raw: string): bigint {
+  const trimmed = raw.trim()
+  if (trimmed.includes('.')) {
+    return parseEther(trimmed as `${number}`)
+  }
+  return BigInt(trimmed)
+}
+
+export function makeChainWrite(ctx: OnchainRuntimeContext): ToolDef<WriteArgs> {
+  return {
+    name: 'chain.write',
+    description:
+      'Generic state-changing call. Pass `signature` + `args` (+ optional `value`). Policy-checked (native value), dry-run simulated, and approval-gated before broadcast like every other write.',
+    searchHint: 'write contract send call generic state-change',
+    schema: WriteSchema,
+    handler: async args => {
+      try {
+        const account = ctx.walletClient.account
+        if (!account) return { ok: false, error: 'walletClient has no account; cannot write' }
+        const fn = buildAbiFunction(args.signature)
+        const coerced = (args.args ?? []).map(coerceArg)
+        const data = encodeFunctionData({
+          abi: [fn] as readonly [import('viem').AbiFunction],
+          args: coerced,
+        })
+        const value = args.value ? parseChainWriteValue(args.value) : 0n
+        const to = getAddress(args.to) as Address
+        // Policy caps the NATIVE value moved by an arbitrary call (it can't see
+        // token semantics — the harness approval gate covers the rest).
+        if (ctx.policy && value > 0n) {
+          const verdict = evaluatePolicy(
+            { kind: 'transfer', asset: 'native', amountRaw: value, to },
+            ctx.policy,
+          )
+          if (!verdict.allowed) {
+            return { ok: false, error: `policy blocked: ${verdict.violations.join('; ')}` }
+          }
+        }
+        // Simulate before broadcasting: a doomed arbitrary call aborts here.
+        const sim = await simulateRawTx(ctx.publicClient, {
+          account: account.address,
+          to,
+          data,
+          value,
+        })
+        if (!sim.ok) return { ok: false, error: `pre-flight simulation reverted: ${sim.reason}` }
+        const gasPrice = await getGasPriceWithFloor(ctx.publicClient)
+        const txHash = await ctx.walletClient.sendTransaction({
+          to,
+          data,
+          value,
+          chain: ctx.walletClient.chain,
+          account,
+          gasPrice,
+        })
+        const receipt = await waitForReceipt(ctx.publicClient, txHash)
+        return {
+          ok: true,
+          data: {
+            txHash,
+            blockNumber: Number(receipt.blockNumber),
+            gasUsed: receipt.gasUsed.toString(),
+            status: receipt.status === 'success' ? 'success' : 'reverted',
+            to: getAddress(args.to),
+            value: value.toString(),
+            signature: args.signature,
+            simGasEstimate: sim.gas.toString(),
+            policyEnforced: ctx.policy != null,
+          },
+        }
+      } catch (e) {
+        return { ok: false, error: (e as Error).message.slice(0, 240) }
+      }
+    },
+  }
+}

package/src/tools/identity.ts

@@ -0,0 +1,139 @@
+/**
+ * `identity.resolve` / `identity.register` — ERC-8004 ("Trustless Agents")
+ * on-chain agent identity on Mantle. Lets the agent discover any agent's
+ * identity card and register/publish its own.
+ */
+import {
+  type ToolDef,
+  agentIdByAddress,
+  buildAgentCard,
+  cardToDataUri,
+  registerAgent,
+  resolveAgentById,
+  resolveRegistryAddress,
+} from 'nebula-ai-core'
+import { z } from 'zod'
+import type { OnchainRuntimeContext } from '../types'
+
+const ResolveSchema = z.object({
+  agentId: z
+    .string()
+    .optional()
+    .describe('Agent id to resolve. Omit (and omit address) to resolve THIS agent by its EOA.'),
+  address: z.string().optional().describe('Resolve the agent registered to this EOA (0x...).'),
+})
+type ResolveArgs = z.infer<typeof ResolveSchema>
+
+export function makeIdentityResolve(ctx: OnchainRuntimeContext): ToolDef<ResolveArgs> {
+  return {
+    name: 'identity.resolve',
+    description:
+      'Resolve an ERC-8004 (Trustless Agents) on-chain agent identity on Mantle to its owner, operational address, and agent-card URI. Resolve by agentId, by an EOA via `address`, or (no args) this agent itself. Read-only — call it to discover who/what an agent is before trusting it.',
+    searchHint:
+      'erc-8004 erc8004 identity registry agent card resolve trustless agent reputation discover who is',
+    schema: ResolveSchema,
+    handler: async (args: ResolveArgs) => {
+      const registry = resolveRegistryAddress(ctx.network)
+      if (!registry) {
+        return {
+          ok: false as const,
+          error: `No ERC-8004 Identity Registry deployed for ${ctx.network}. Set NEBULA_IDENTITY_REGISTRY.`,
+        }
+      }
+      try {
+        let id: bigint
+        if (args.agentId) {
+          id = BigInt(args.agentId)
+        } else {
+          const addr = (args.address ?? ctx.agentEoa) as `0x${string}`
+          id = await agentIdByAddress({
+            publicClient: ctx.publicClient,
+            registry,
+            agentAddress: addr,
+          })
+          if (id === 0n) {
+            return { ok: true as const, data: { registered: false, address: addr, registry } }
+          }
+        }
+        const r = await resolveAgentById({ publicClient: ctx.publicClient, registry, agentId: id })
+        return {
+          ok: true as const,
+          data: {
+            registered: true,
+            agentId: r.agentId.toString(),
+            owner: r.owner,
+            agentAddress: r.agentAddress,
+            cardURI: r.cardURI,
+            registry,
+            network: ctx.network,
+          },
+        }
+      } catch (e) {
+        return { ok: false as const, error: (e as Error).message }
+      }
+    },
+  }
+}
+
+const RegisterSchema = z.object({
+  name: z
+    .string()
+    .optional()
+    .describe('Display name for the agent card. Defaults to a nebula-<hex> slug.'),
+})
+type RegisterArgs = z.infer<typeof RegisterSchema>
+
+export function makeIdentityRegister(ctx: OnchainRuntimeContext): ToolDef<RegisterArgs> {
+  return {
+    name: 'identity.register',
+    description:
+      "Register THIS agent's own ERC-8004 (Trustless Agents) identity on Mantle: mints a transferable identity NFT to the agent and publishes its agent card (name, endpoints, agent address, skills) as the on-chain tokenURI. One-time; idempotent (no-op if already registered). Costs a little gas. Resolve afterwards with identity.resolve.",
+    searchHint:
+      'erc-8004 erc8004 register identity mint agent card publish trustless on-chain identity self',
+    schema: RegisterSchema,
+    handler: async (args: RegisterArgs) => {
+      const registry = resolveRegistryAddress(ctx.network)
+      if (!registry) {
+        return {
+          ok: false as const,
+          error: `No ERC-8004 Identity Registry deployed for ${ctx.network}. Set NEBULA_IDENTITY_REGISTRY.`,
+        }
+      }
+      if (!ctx.walletClient?.account) {
+        return { ok: false as const, error: 'no signer available to register identity' }
+      }
+      try {
+        const agentAddress = ctx.agentEoa
+        const existing = await agentIdByAddress({
+          publicClient: ctx.publicClient,
+          registry,
+          agentAddress,
+        })
+        if (existing !== 0n) {
+          return {
+            ok: true as const,
+            data: { alreadyRegistered: true, agentId: existing.toString(), registry },
+          }
+        }
+        const card = buildAgentCard({
+          name: args.name ?? `nebula-${agentAddress.slice(2, 8)}`,
+          agentAddress,
+          network: ctx.network,
+        })
+        const { agentId, txHash } = await registerAgent({
+          walletClient: ctx.walletClient,
+          publicClient: ctx.publicClient,
+          registry,
+          cardURI: cardToDataUri(card),
+          agentAddress,
+        })
+        return {
+          ok: true as const,
+          data: { agentId: agentId.toString(), txHash, registry, network: ctx.network },
+        }
+      } catch (e) {
+        return { ok: false as const, error: (e as Error).message }
+      }
+    },
+  }
+}