@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/node-agent-tool/src/ledgers.ts

@@ -0,0 +1,62 @@
+// Scenario 3, many ledgers, one interface: every ICRC-1 ledger speaks the
+// same `.did`, so one generated module (src/canisters/icrc1.ts, from
+// icrc1.did) and one `Actor` type serve them all. Each ledger is
+// `client.canister<Actor>(actor, { id })` on the same client; the client keeps
+// one object per (service, target), so asking again costs nothing.
+//
+// `--ledger icp|ckbtc|cketh|<canister id>`; the ids are the mainnet ledgers'.
+import { isPrincipal } from "@meantjs/schema"
+import type { Canister, Client } from "@ic-reactor/core"
+import { actor, type Actor } from "./canisters/icrc1.ts"
+import { UsageError } from "./input.ts"
+
+/** Mainnet ICRC-1 ledgers by name. */
+export const LEDGERS = {
+  icp: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+  ckbtc: "mxzaz-hqaaa-aaaar-qaada-cai",
+  cketh: "ss2fx-dyaaa-aaaar-qacoq-cai",
+} as const
+
+export type LedgerName = keyof typeof LEDGERS
+
+/** A ledger, chosen on the command line. */
+export interface LedgerChoice {
+  /** The canister id. */
+  readonly id: string
+  /** Its name in {@link LEDGERS}, or `null` for an id given as is. */
+  readonly name: LedgerName | null
+  /** The flags that pick this ledger again, for a command printed to re-run. */
+  readonly flags: readonly string[]
+}
+
+const isLedgerName = (text: string): text is LedgerName =>
+  Object.hasOwn(LEDGERS, text)
+
+/**
+ * The ledger `--ledger` names: a name from {@link LEDGERS} or a canister id;
+ * the ICP ledger when it is not given.
+ *
+ * @throws UsageError for anything else.
+ */
+export function ledgerFrom(flag: string | undefined): LedgerChoice {
+  const text = flag ?? "icp"
+  if (isLedgerName(text)) {
+    return { id: LEDGERS[text], name: text, flags: ["--ledger", text] }
+  }
+  if (isPrincipal(text))
+    return { id: text, name: null, flags: ["--ledger", text] }
+  throw new UsageError(
+    `--ledger ${JSON.stringify(text)} is not ${Object.keys(LEDGERS).join(", ")} or a canister id`
+  )
+}
+
+/**
+ * The ledger `id` on `client`. With `certified`, a second canister object for
+ * the same id whose query methods go out as replicated calls, so their
+ * replies are certified, and whose cache keys end in "certified".
+ */
+export const ledgerOn = (
+  client: Client,
+  id: string,
+  certified = false
+): Canister<Actor> => client.canister<Actor>(actor, { id, certified })

package/examples/node-agent-tool/src/mock-ledger.ts

@@ -0,0 +1,211 @@
+// An ICRC-1 ledger written as plain functions (`TestHandlers<Actor>`), for the
+// in-memory replica of `createTestClient()` from @ic-reactor/core/testing. The
+// `demo` command and the tests run the CLI against it: it keeps a balance per
+// account, takes the fee, deduplicates by `created_at_time`, and answers
+// `icrc1_transfer` with the standard's `Err` arms. Nothing here is ic-reactor
+// API; the client that calls it is the real one.
+import type { Principal } from "@meantjs/schema"
+import type { createTestClient, TestHandlers } from "@ic-reactor/core/testing"
+import {
+  actor,
+  type Account,
+  type Actor,
+  type TransferArg,
+  type TransferError,
+  type TransferResult,
+} from "./canisters/icrc1.ts"
+import { toHex } from "./input.ts"
+import { DEDUP_WINDOW_NS } from "./commands/transfer.ts"
+
+type TestClient = ReturnType<typeof createTestClient>
+
+/** How far a `created_at_time` may be ahead of the ledger's clock: 2 minutes. */
+const PERMITTED_DRIFT_NS = 2n * 60n * 1_000_000_000n
+
+export interface MockLedgerOptions {
+  /** The canister id it answers at. */
+  readonly id: string
+  /** What each principal's default account holds at first, in base units. */
+  readonly balances?: ReadonlyArray<readonly [Principal, bigint]>
+  readonly name?: string
+  readonly symbol?: string
+  readonly decimals?: number
+  readonly fee?: bigint
+  /** The ledger's clock, in nanoseconds since the epoch. */
+  readonly now?: () => bigint
+}
+
+export interface MockLedger {
+  readonly id: string
+  readonly decimals: number
+  readonly fee: bigint
+  /**
+   * Runs the ledger on a test client's replica. Its accounts live here, not
+   * on the replica, so a new client (one per run of the CLI) sees the same
+   * ledger. `overrides` replace some of its methods.
+   */
+  mountOn(test: TestClient, overrides?: TestHandlers<Actor>): void
+  /** What an account holds, in base units. */
+  balanceOf(account: Account): bigint
+  /** Adds to an account, as a transfer from elsewhere would. */
+  credit(account: Account, units: bigint): void
+  /**
+   * Makes the next transfer reject with `code` before it changes anything:
+   * `4` or `5` from the canister, `3` as from the system before it ran.
+   */
+  rejectNextTransfer(code: 3 | 4 | 5): void
+  /**
+   * Makes the next transfer answer `Err(err)` and move nothing, before the
+   * ledger looks for a duplicate, as a real ledger does when it is paused
+   * (`TemporarilyUnavailable`) or its fee has changed (`BadFee`).
+   */
+  answerNextTransfer(err: TransferError): void
+  /**
+   * Has the replica of the test client the ledger was last mounted on answer
+   * the next `times` sends of `icrc1_transfer` to this ledger with HTTP 429,
+   * as a boundary node that throttles. The reads `transfer` makes before its
+   * call are answered.
+   */
+  throttleNextTransfer(times?: number): void
+  /** Every transfer argument the ledger was sent, with the caller the replica verified. */
+  readonly received: ReadonlyArray<{
+    readonly arg: TransferArg
+    readonly caller: Principal
+  }>
+}
+
+/** One key per account; no subaccount and 32 zero bytes are the same account. */
+const keyOf = ({ owner, subaccount }: Account): string =>
+  subaccount === null || subaccount.every((byte) => byte === 0)
+    ? owner
+    : `${owner}.${toHex(subaccount)}`
+
+export function createMockLedger(options: MockLedgerOptions): MockLedger {
+  const {
+    id,
+    name = "Internet Computer (mock)",
+    symbol = "ICP",
+    decimals = 8,
+    fee = 10_000n,
+    now = () => BigInt(Date.now()) * 1_000_000n,
+  } = options
+  const accounts = new Map<string, bigint>(
+    (options.balances ?? []).map(([owner, units]) => [
+      keyOf({ owner, subaccount: null }),
+      units,
+    ])
+  )
+  const seen = new Map<string, bigint>()
+  const received: { arg: TransferArg; caller: Principal }[] = []
+  let blocks = 0n
+  let rejectNext: 3 | 4 | 5 | undefined
+  let answerNext: TransferError | undefined
+  let mounted: TestClient | undefined
+
+  const balanceOf = (account: Account) => accounts.get(keyOf(account)) ?? 0n
+  const refuse = (value: TransferError): TransferResult => ({
+    tag: "Err",
+    value,
+  })
+
+  function transfer(arg: TransferArg, caller: Principal): TransferResult {
+    const from: Account = { owner: caller, subaccount: arg.from_subaccount }
+    const time = now()
+    // The same sender and the same argument is the same transfer.
+    const txKey = [
+      keyOf(from),
+      keyOf(arg.to),
+      arg.amount,
+      arg.fee ?? "default",
+      arg.memo === null ? "" : toHex(arg.memo),
+      arg.created_at_time,
+    ].join("|")
+    if (arg.created_at_time !== null) {
+      if (arg.created_at_time < time - DEDUP_WINDOW_NS - PERMITTED_DRIFT_NS) {
+        return refuse({ tag: "TooOld" })
+      }
+      if (arg.created_at_time > time + PERMITTED_DRIFT_NS) {
+        return refuse({ tag: "CreatedInFuture", value: { ledger_time: time } })
+      }
+      const original = seen.get(txKey)
+      if (original !== undefined) {
+        return refuse({ tag: "Duplicate", value: { duplicate_of: original } })
+      }
+    }
+    if (arg.fee !== null && arg.fee !== fee) {
+      return refuse({ tag: "BadFee", value: { expected_fee: fee } })
+    }
+    const held = balanceOf(from)
+    if (held < arg.amount + fee) {
+      return refuse({ tag: "InsufficientFunds", value: { balance: held } })
+    }
+    accounts.set(keyOf(from), held - arg.amount - fee)
+    accounts.set(keyOf(arg.to), balanceOf(arg.to) + arg.amount)
+    const block = blocks++
+    if (arg.created_at_time !== null) seen.set(txKey, block)
+    return { tag: "Ok", value: block }
+  }
+
+  const handlersFor = (test: TestClient): TestHandlers<Actor> => {
+    return {
+      icrc1_name: () => name,
+      icrc1_symbol: () => symbol,
+      icrc1_decimals: () => decimals,
+      icrc1_fee: () => fee,
+      icrc1_total_supply: () =>
+        [...accounts.values()].reduce((sum, units) => sum + units, 0n),
+      icrc1_minting_account: () => null,
+      icrc1_metadata: () => [
+        ["icrc1:name", { tag: "Text", value: name }],
+        ["icrc1:symbol", { tag: "Text", value: symbol }],
+        ["icrc1:decimals", { tag: "Nat", value: BigInt(decimals) }],
+        ["icrc1:fee", { tag: "Nat", value: fee }],
+      ],
+      icrc1_supported_standards: () => [
+        { name: "ICRC-1", url: "https://github.com/dfinity/ICRC-1" },
+      ],
+      icrc1_balance_of: (account) => balanceOf(account),
+      icrc1_transfer: (arg, { caller }) => {
+        received.push({ arg, caller })
+        const code = rejectNext
+        rejectNext = undefined
+        if (code !== undefined) {
+          test.reject(
+            code,
+            `the mock ledger rejected this transfer (code ${code})`
+          )
+        }
+        const err = answerNext
+        answerNext = undefined
+        return err === undefined ? transfer(arg, caller) : refuse(err)
+      },
+    }
+  }
+
+  return {
+    id,
+    decimals,
+    fee,
+    mountOn(test, overrides = {}) {
+      test.mock<Actor>(actor, id, { ...handlersFor(test), ...overrides })
+      mounted = test
+    },
+    balanceOf,
+    credit(account, units) {
+      accounts.set(keyOf(account), balanceOf(account) + units)
+    },
+    rejectNextTransfer(code) {
+      rejectNext = code
+    },
+    answerNextTransfer(err) {
+      answerNext = err
+    },
+    throttleNextTransfer(times = 1) {
+      if (mounted === undefined) {
+        throw new Error("throttleNextTransfer(): mount the ledger first")
+      }
+      mounted.refuseNext(429, { method: "icrc1_transfer", canister: id, times })
+    },
+    received,
+  }
+}

package/examples/node-agent-tool/src/network.test.ts

@@ -0,0 +1,128 @@
+// Scenario 2: networks and the root-key rule.
+import { createClient, isReactorError } from "@ic-reactor/core"
+import { describe, expect, it } from "vitest"
+import { UsageError } from "./input.ts"
+import { LEDGERS, ledgerOn } from "./ledgers.ts"
+import { networkFrom } from "./network.ts"
+import { createCli } from "./test-kit.ts"
+
+const ROOT_KEY =
+  "308182301d060d2b0601040182dc7c0503010201060c2b0601040182dc7c05030201036100a5" +
+  "87ac27884f235a91ddd86927eec11e09872417231b41ab8fb95605c633af9702849c0ad6929613392b39c715fc232c0a0d8eb00a1ea91985b3e440bc9d0b78a5872f96dae753f395cd6602516ad58748d698958976c6c25b86c55aa30a3af9"
+
+describe("--network onto createClient's network", () => {
+  it("is mainnet by default and for ic, and the local replica for local", () => {
+    expect(networkFrom(undefined, undefined)).toMatchObject({
+      network: "ic",
+      flags: [],
+    })
+    expect(networkFrom("ic", undefined).network).toBe("ic")
+    expect(networkFrom("local", undefined).network).toBe("local")
+  })
+
+  it.each([
+    "http://127.0.0.1:8001",
+    "http://localhost:8000",
+    "http://backend.localhost:4943",
+    "http://[::1]:8000",
+  ])("takes %s as a local replica whose key the client fetches", (url) => {
+    expect(networkFrom(url, undefined).network).toEqual({
+      host: new URL(url).origin,
+    })
+  })
+
+  it("needs the root key of a replica that is not on this machine", () => {
+    expect(() => networkFrom("https://replica.example.org", undefined)).toThrow(
+      /--root-key/
+    )
+    expect(networkFrom("https://replica.example.org", ROOT_KEY)).toEqual({
+      network: {
+        host: "https://replica.example.org",
+        rootKey: Uint8Array.from(Buffer.from(ROOT_KEY, "hex")),
+      },
+      rootKey: "given with --root-key, never fetched",
+      flags: [
+        "--network",
+        "https://replica.example.org",
+        "--root-key",
+        ROOT_KEY,
+      ],
+    })
+  })
+
+  it("refuses what is not a network, and a root key for ic or local", () => {
+    for (const [flag, key] of [
+      ["mainnet", undefined],
+      ["ftp://127.0.0.1", undefined],
+      ["ic", ROOT_KEY],
+      ["local", ROOT_KEY],
+      ["https://replica.example.org", "xyz"],
+    ] as const) {
+      expect(() => networkFrom(flag, key)).toThrow(UsageError)
+    }
+  })
+
+  it("refuses a remote URL without a key before any client is built (exit 2)", async () => {
+    const { cli } = createCli()
+    const result = await cli([
+      "info",
+      "--network",
+      "https://replica.example.org",
+      "--json",
+    ])
+    expect(result.exitCode).toBe(2)
+    expect(result.options).toBeUndefined()
+    expect(result.docs[0]).toMatchObject({
+      ok: false,
+      kind: "usage",
+      message: expect.stringContaining("never fetched"),
+    })
+  })
+})
+
+/**
+ * Where the real client sends its first request on each network: a `fetch`
+ * that records the URL and fails, so nothing leaves the test.
+ */
+async function firstRequests(
+  flag: string,
+  rootKey?: string
+): Promise<string[]> {
+  const urls: string[] = []
+  const client = createClient({
+    network: networkFrom(flag, rootKey).network,
+    identity: "anonymous",
+    fetch: async (input) => {
+      urls.push(input instanceof Request ? input.url : String(input))
+      throw new TypeError("offline")
+    },
+  })
+  try {
+    await ledgerOn(client, LEDGERS.icp).icrc1_fee()
+  } catch (error) {
+    expect(isReactorError(error)).toBe(true)
+  } finally {
+    client.dispose()
+  }
+  return urls.map((url) => new URL(url).origin + new URL(url).pathname)
+}
+
+describe("the root key, as the client then behaves", () => {
+  it("fetches it from a local replica, first", async () => {
+    const urls = await firstRequests("http://127.0.0.1:8001")
+    expect(urls[0]).toBe("http://127.0.0.1:8001/api/v2/status")
+  })
+
+  it("never fetches it on mainnet or from a remote replica given a key", async () => {
+    const mainnet = await firstRequests("ic")
+    const remote = await firstRequests("https://replica.example.org", ROOT_KEY)
+    expect(mainnet.length).toBeGreaterThan(0)
+    expect(mainnet.every((url) => url.startsWith("https://icp-api.io/"))).toBe(
+      true
+    )
+    expect(remote.length).toBeGreaterThan(0)
+    for (const url of [...mainnet, ...remote]) {
+      expect(url).not.toMatch(/\/api\/v2\/status$/)
+    }
+  })
+})

package/examples/node-agent-tool/src/network.ts

@@ -0,0 +1,101 @@
+// Scenario 2, networks: `--network ic|local|<url>` onto createClient's
+// `network` option, and the root-key rule (packages/core/llms.txt, Setup).
+//
+// The root key is what every certificate is checked against, so it is never
+// taken from a replica that is not on this machine:
+//
+// - `ic`: mainnet through https://icp-api.io, with the root key the agent
+//   ships with. Nothing is fetched.
+// - `local`: icp-cli's local network, http://127.0.0.1:8000. The client
+//   fetches that replica's key.
+// - a local <url> (localhost, *.localhost, 127.0.0.0/8, [::1]), such as an
+//   icp-cli network on another port: `{ host }`, and the client fetches its key.
+// - any other <url>: `{ host, rootKey }`, with the key given as
+//   `--root-key <hex>`. Without one this tool refuses: a key fetched from a
+//   remote host would be whatever that host chose to send.
+import type { Network } from "@ic-reactor/core"
+import { hexArg, UsageError } from "./input.ts"
+
+/** A network, chosen on the command line. */
+export interface NetworkChoice {
+  /** What `createClient({ network })` is given. */
+  readonly network: Network
+  /** Where the root key comes from, for a person to read. */
+  readonly rootKey: string
+  /** The flags that pick this network again, for a command printed to re-run. */
+  readonly flags: readonly string[]
+}
+
+/** Whether a URL's host is this machine: the same rule the client applies. */
+export function isLocalHost(hostname: string): boolean {
+  return (
+    hostname === "localhost" ||
+    hostname.endsWith(".localhost") ||
+    /^127\.\d{1,3}\.\d{1,3}\.\d{1,3}$/.test(hostname) ||
+    hostname === "[::1]"
+  )
+}
+
+/**
+ * The network `--network` and `--root-key` name; mainnet when neither is given.
+ *
+ * @throws UsageError for a value that is not `ic`, `local` or an http(s) URL,
+ * a remote URL without a root key, or a root key given for `ic` or `local`.
+ */
+export function networkFrom(
+  flag: string | undefined,
+  rootKeyHex: string | undefined
+): NetworkChoice {
+  const name = flag ?? "ic"
+  if (name === "ic" || name === "local") {
+    if (rootKeyHex !== undefined) {
+      throw new UsageError(
+        `--root-key goes with a --network <url>: "${name}" has its root key already`
+      )
+    }
+    return name === "ic"
+      ? {
+          network: "ic",
+          rootKey: "mainnet's, built into the agent",
+          flags: flag === undefined ? [] : ["--network", "ic"],
+        }
+      : {
+          network: "local",
+          rootKey: "fetched from the local replica",
+          flags: ["--network", "local"],
+        }
+  }
+
+  let url: URL
+  try {
+    url = new URL(name)
+  } catch {
+    throw new UsageError(
+      `--network ${JSON.stringify(name)} is not ic, local or a URL such as http://127.0.0.1:8000`
+    )
+  }
+  if (url.protocol !== "http:" && url.protocol !== "https:") {
+    throw new UsageError(`--network ${name}: the URL is http or https`)
+  }
+  const host = url.origin
+  const flags = ["--network", host]
+
+  if (rootKeyHex !== undefined) {
+    return {
+      network: { host, rootKey: hexArg(rootKeyHex, "--root-key") },
+      rootKey: "given with --root-key, never fetched",
+      flags: [...flags, "--root-key", rootKeyHex],
+    }
+  }
+  if (isLocalHost(url.hostname)) {
+    return {
+      network: { host },
+      rootKey: `fetched from ${host}, which is on this machine`,
+      flags,
+    }
+  }
+  throw new UsageError(
+    `--network ${host} is not on this machine, so its root key is never fetched from it: ` +
+      `pass the replica's root key as --root-key <hex> (DER), or use --network ic for mainnet`
+  )
+}