@ic-reactor/mcp 0.0.0-stage → 0.0.0

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

@@ -0,0 +1,242 @@
+// Scenario 1: identity. Keys are generated here, never real ones.
+import { createPublicKey, generateKeyPairSync } from "node:crypto"
+import { describe, expect, it } from "vitest"
+import { identityFromPem, SEED_VARIABLE } from "./identity.ts"
+import { UsageError } from "./input.ts"
+import { createCli, generatePem } from "./test-kit.ts"
+
+const ANONYMOUS = "2vxsx-fae"
+
+describe("loading a key", () => {
+  it.each(["ed25519", "secp256k1"] as const)(
+    "reads a %s PEM into an identity with the key's principal",
+    (algorithm) => {
+      const key = generatePem(algorithm)
+      const loaded = identityFromPem(key.pem, "--pem key.pem")
+      expect(loaded.algorithm).toBe(algorithm)
+      expect(loaded.identity.getPrincipal().toText()).toBe(key.principal)
+    }
+  )
+
+  it("reads a secp256k1 key in PKCS#8 form, and after an EC PARAMETERS block", () => {
+    const { privateKey, publicKey } = generateKeyPairSync("ec", {
+      namedCurve: "secp256k1",
+    })
+    const pkcs8 = privateKey.export({ format: "pem", type: "pkcs8" }).toString()
+    const sec1 = privateKey.export({ format: "pem", type: "sec1" }).toString()
+    const withParameters = `-----BEGIN EC PARAMETERS-----\nBgUrgQQACg==\n-----END EC PARAMETERS-----\n${sec1}`
+    const expected = identityFromPem(sec1, "sec1").identity.getPrincipal()
+    expect(publicKey.asymmetricKeyType).toBe("ec")
+    for (const pem of [pkcs8, withParameters]) {
+      expect(identityFromPem(pem, "pem").identity.getPrincipal().toText()).toBe(
+        expected.toText()
+      )
+    }
+  })
+
+  it("reads dfx's Ed25519 form, which carries the public key too", () => {
+    const key = generatePem("ed25519")
+    const publicKey = new Uint8Array(
+      Buffer.from(
+        createPublicKey(key.pem).export({ format: "jwk" }).x ?? "",
+        "base64url"
+      )
+    )
+    // SEQUENCE { version 1, Ed25519, OCTET STRING { OCTET STRING seed }, [1] public key }
+    const der = Uint8Array.from([
+      0x30,
+      0x53,
+      0x02,
+      0x01,
+      0x01,
+      0x30,
+      0x05,
+      0x06,
+      0x03,
+      0x2b,
+      0x65,
+      0x70,
+      0x04,
+      0x22,
+      0x04,
+      0x20,
+      ...key.seed,
+      0xa1,
+      0x23,
+      0x03,
+      0x21,
+      0x00,
+      ...publicKey,
+    ])
+    const pem = `-----BEGIN PRIVATE KEY-----\n${Buffer.from(der).toString("base64")}\n-----END PRIVATE KEY-----\n`
+    expect(identityFromPem(pem, "pem").identity.getPrincipal().toText()).toBe(
+      key.principal
+    )
+
+    const other = generatePem("ed25519").seed
+    const mismatched = Uint8Array.from([
+      ...der.slice(0, 16),
+      ...other,
+      ...der.slice(48),
+    ])
+    const lying = `-----BEGIN PRIVATE KEY-----\n${Buffer.from(mismatched).toString("base64")}\n-----END PRIVATE KEY-----\n`
+    expect(() => identityFromPem(lying, "pem")).toThrow(/public key/)
+  })
+
+  it("refuses an encrypted key, a P-256 key and text that is no key", () => {
+    const { privateKey } = generateKeyPairSync("ed25519")
+    const encrypted = privateKey
+      .export({
+        format: "pem",
+        type: "pkcs8",
+        cipher: "aes-256-cbc",
+        passphrase: "test",
+      })
+      .toString()
+    const p256 = generateKeyPairSync("ec", { namedCurve: "P-256" })
+      .privateKey.export({ format: "pem", type: "pkcs8" })
+      .toString()
+    expect(() => identityFromPem(encrypted, "pem")).toThrow(/encrypted/)
+    expect(() => identityFromPem(p256, "pem")).toThrow(/P-256/)
+    expect(() => identityFromPem("hello", "pem")).toThrow(UsageError)
+  })
+})
+
+describe("whoami", () => {
+  it("is anonymous without a key, and says writes are refused", async () => {
+    const { cli } = createCli()
+    const human = await cli(["whoami"])
+    expect(human.exitCode).toBe(0)
+    expect(human.options?.identity).toBe("anonymous")
+    expect(human.stdout.join("\n")).toMatch(/principal\s+2vxsx-fae/)
+    expect(human.stdout.join("\n")).toMatch(/refused by the client/)
+
+    const json = await cli(["whoami", "--json"])
+    expect(json.docs).toEqual([
+      {
+        ok: true,
+        command: "whoami",
+        principal: ANONYMOUS,
+        status: "anonymous",
+        canWrite: false,
+        identity: {
+          algorithm: null,
+          source: expect.stringContaining("anonymous"),
+        },
+        network: "ic",
+      },
+    ])
+    expect(json.requests).toEqual([])
+  })
+
+  it.each(["ed25519", "secp256k1"] as const)(
+    "signs as the %s key of --pem",
+    async (algorithm) => {
+      const key = generatePem(algorithm)
+      const { cli } = createCli({ files: { "me.pem": key.pem } })
+      const result = await cli(["whoami", "--pem", "me.pem", "--json"])
+      expect(result.exitCode).toBe(0)
+      expect(result.docs[0]).toMatchObject({
+        principal: key.principal,
+        status: "signed-in",
+        canWrite: true,
+        identity: { algorithm, source: `--pem me.pem (${algorithm})` },
+      })
+    }
+  )
+
+  it(`signs as the Ed25519 seed in ${SEED_VARIABLE}`, async () => {
+    const key = generatePem("ed25519")
+    const { cli } = createCli()
+    const result = await cli(["whoami", "--json"], {
+      env: { [SEED_VARIABLE]: Buffer.from(key.seed).toString("hex") },
+    })
+    expect(result.docs[0]).toMatchObject({
+      principal: key.principal,
+      status: "signed-in",
+    })
+  })
+
+  it("refuses two keys at once, a missing file and a bad seed, building no client", async () => {
+    const key = generatePem("ed25519")
+    const { cli } = createCli({ files: { "me.pem": key.pem } })
+    const seed = { [SEED_VARIABLE]: Buffer.from(key.seed).toString("hex") }
+    for (const [argv, env, reason] of [
+      [["whoami", "--pem", "me.pem"], seed, /both --pem and/],
+      [["whoami", "--pem", "missing.pem"], {}, /ENOENT/],
+      [["whoami"], { [SEED_VARIABLE]: "abc" }, /exactly 64 hex digits/],
+    ] as const) {
+      const result = await cli(argv, { env })
+      expect(result.exitCode).toBe(2)
+      expect(result.stderr.join("\n")).toMatch(reason)
+      expect(result.options).toBeUndefined()
+    }
+  })
+
+  it(`never prints a malformed ${SEED_VARIABLE}, which is a private key`, async () => {
+    const hex = Buffer.from(generatePem("ed25519").seed).toString("hex")
+    const { cli } = createCli()
+    for (const [seed, problem] of [
+      [`0x${hex}`, /starts with 0x/],
+      [`${hex} `, /holds white space/],
+      [`${hex}\n`, /holds white space/],
+      [`${hex.slice(0, 63)}g`, /not a hex digit/],
+      [hex.slice(0, 62), /has 62 hex digits/],
+      [`${hex}00`, /has 66 hex digits/],
+    ] as const) {
+      for (const json of [false, true]) {
+        const result = await cli(
+          ["balance", ANONYMOUS, ...(json ? ["--json"] : [])],
+          { env: { [SEED_VARIABLE]: seed } }
+        )
+        expect(result.exitCode).toBe(2)
+        expect(result.options).toBeUndefined()
+        const printed = [...result.stdout, ...result.stderr].join("\n")
+        expect(printed).toMatch(problem)
+        // Neither the value nor any long run of its digits is printed.
+        expect(printed).not.toContain(hex.slice(0, 16))
+        expect(printed).not.toContain(hex.slice(-16))
+        if (json) {
+          expect(result.docs[0]).toMatchObject({ ok: false, kind: "usage" })
+        }
+      }
+    }
+  })
+})
+
+describe("a key signs what the replica checks", () => {
+  it.each(["ed25519", "secp256k1"] as const)(
+    "a transfer is sent as the %s key's principal",
+    async (algorithm) => {
+      const key = generatePem(algorithm)
+      const { cli, ledger } = createCli({
+        files: { "me.pem": key.pem },
+        ledger: { balances: [[key.principal, 500_000_000n]] },
+      })
+      const result = await cli(["transfer", ANONYMOUS, "1", "--pem", "me.pem"])
+      expect(result.exitCode).toBe(0)
+      const call = result.requests.find((r) => r.endpoint === "call")
+      expect(call?.caller).toBe(key.principal)
+      expect(call?.refused).toBeUndefined()
+      expect(ledger.received.map((r) => r.caller)).toEqual([key.principal])
+    }
+  )
+
+  it("an anonymous client refuses the write before sending it (exit 4)", async () => {
+    const { cli, ledger } = createCli()
+    const human = await cli(["transfer", ANONYMOUS, "1"])
+    expect(human.exitCode).toBe(4)
+    expect(human.stderr.join("\n")).toMatch(/error: unauthenticated/)
+    expect(human.stderr.join("\n")).toMatch(/Pass --pem <file>/)
+    expect(human.requests.some((r) => r.endpoint === "call")).toBe(false)
+    expect(ledger.received).toEqual([])
+
+    const json = await cli(["transfer", ANONYMOUS, "1", "--json"])
+    expect(json.docs[0]).toMatchObject({
+      ok: false,
+      command: "transfer",
+      kind: "unauthenticated",
+      mayHaveExecuted: false,
+    })
+  })
+})

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

@@ -0,0 +1,228 @@
+// Scenario 1, identity: who the client calls as.
+//
+// A tool that runs in a terminal or under an AI agent has no sign-in flow: it
+// is handed a key, or it only reads. createClient takes exactly one caller
+// (packages/core/llms.txt, "Who calls"):
+//
+// - `--pem <file>`: a fixed Identity built from an Ed25519 or secp256k1 private
+//   key in PEM form, such as `icp identity export` or `dfx identity export`
+//   prints;
+// - else NODE_AGENT_TOOL_SEED: 64 hex digits, the seed of an Ed25519 key;
+// - else `identity: "anonymous"`. That client reads, and refuses every update
+//   before sending it (kind "unauthenticated"). It is never a
+//   `new AnonymousIdentity()`, which would sign and send writes anonymously.
+//
+// A key is never generated here: who calls is always written down.
+import { createPrivateKey } from "node:crypto"
+import type { Identity } from "@icp-sdk/core/agent"
+import { Ed25519KeyIdentity } from "@icp-sdk/core/identity"
+import { Secp256k1KeyIdentity } from "@icp-sdk/core/identity/secp256k1"
+import { UsageError } from "./input.ts"
+
+/** The environment variable that holds an Ed25519 seed. */
+export const SEED_VARIABLE = "NODE_AGENT_TOOL_SEED"
+
+/** Who calls, and how they were chosen. */
+export interface Caller {
+  /** What `createClient({ identity })` is given. */
+  readonly identity: Identity | "anonymous"
+  /** The key's algorithm, or `null` for an anonymous caller. */
+  readonly algorithm: "ed25519" | "secp256k1" | null
+  /** Where the key came from, for `whoami`. */
+  readonly source: string
+  /** The flags that pick this caller again, for a command printed to re-run. */
+  readonly flags: readonly string[]
+}
+
+/** The anonymous caller: reads only. */
+export const ANONYMOUS_CALLER: Caller = Object.freeze({
+  identity: "anonymous",
+  algorithm: null,
+  source: `anonymous (no --pem and no ${SEED_VARIABLE}): reads only`,
+  flags: [],
+})
+
+/**
+ * The caller `--pem` or the seed variable names, or the anonymous one.
+ *
+ * @throws UsageError for both at once, or a key that cannot be read.
+ */
+export function callerFrom(
+  pemFile: string | undefined,
+  env: Readonly<Record<string, string | undefined>>,
+  readFile: (path: string) => string
+): Caller {
+  const seed = env[SEED_VARIABLE]
+  if (pemFile !== undefined && seed !== undefined && seed !== "") {
+    throw new UsageError(
+      `both --pem and ${SEED_VARIABLE} name a key: give one, so that who signs is never a guess`
+    )
+  }
+  if (pemFile !== undefined) {
+    let pem: string
+    try {
+      pem = readFile(pemFile)
+    } catch (error) {
+      throw new UsageError(
+        `--pem ${pemFile}: ${error instanceof Error ? error.message : String(error)}`
+      )
+    }
+    const { identity, algorithm } = identityFromPem(pem, `--pem ${pemFile}`)
+    return {
+      identity,
+      algorithm,
+      source: `--pem ${pemFile} (${algorithm})`,
+      flags: ["--pem", pemFile],
+    }
+  }
+  if (seed !== undefined && seed !== "") {
+    return {
+      identity: Ed25519KeyIdentity.fromSecretKey(seedBytes(seed)),
+      algorithm: "ed25519",
+      source: `${SEED_VARIABLE} (ed25519)`,
+      flags: [],
+    }
+  }
+  return ANONYMOUS_CALLER
+}
+
+/**
+ * The 32 bytes of the seed in NODE_AGENT_TOOL_SEED.
+ *
+ * The seed is a private key, so a refusal says what is wrong with it and
+ * never quotes it: the message goes to stderr, or to stdout in --json mode,
+ * and an agent logs both and reads them back into its context.
+ *
+ * @throws UsageError for anything but 64 hex digits.
+ */
+function seedBytes(seed: string): Uint8Array {
+  const problem = /^0x/i.test(seed)
+    ? "starts with 0x"
+    : /\s/.test(seed)
+      ? "holds white space"
+      : /[^0-9a-fA-F]/.test(seed)
+        ? "holds a character that is not a hex digit"
+        : seed.length !== 64
+          ? `has ${seed.length} hex digits`
+          : undefined
+  if (problem !== undefined) {
+    throw new UsageError(
+      `${SEED_VARIABLE} ${problem}: it takes an Ed25519 seed as exactly 64 hex digits (32 bytes), with no 0x and no spaces. Its value is not printed, since it is a private key.`
+    )
+  }
+  return new Uint8Array(Buffer.from(seed, "hex"))
+}
+
+// ---------------------------------------------------------------------------
+// PEM files
+// ---------------------------------------------------------------------------
+
+/**
+ * The private key of a PEM file as an Identity.
+ *
+ * - Ed25519 comes as PKCS#8 (`BEGIN PRIVATE KEY`). dfx writes the form that
+ *   also carries the public key, which OpenSSL (and so `node:crypto`) refuses,
+ *   so the 32-byte seed is read from the DER here, and a public key next to it
+ *   must match.
+ * - secp256k1 comes as SEC1 (`BEGIN EC PRIVATE KEY`, possibly after an
+ *   `EC PARAMETERS` block) or PKCS#8; `node:crypto` reads both.
+ *
+ * @throws UsageError for anything else, an encrypted key included.
+ */
+export function identityFromPem(
+  pem: string,
+  what: string
+): { identity: Identity; algorithm: "ed25519" | "secp256k1" } {
+  const labels = [...pem.matchAll(/-----BEGIN ([A-Z0-9 ]+)-----/g)].map(
+    (match) => match[1]
+  )
+  if (labels.includes("ENCRYPTED PRIVATE KEY")) {
+    throw new UsageError(
+      `${what} is encrypted: export the key unencrypted (icp identity export <name>)`
+    )
+  }
+  const der = derOf(pem, "PRIVATE KEY")
+  const seed = der === undefined ? undefined : ed25519SeedOf(der)
+  if (der !== undefined && seed !== undefined) {
+    const identity = Ed25519KeyIdentity.fromSecretKey(seed)
+    const stated = ed25519PublicKeyOf(der)
+    const actual = new Uint8Array(identity.getPublicKey().toRaw())
+    if (stated !== undefined && !sameBytes(stated, actual)) {
+      throw new UsageError(
+        `${what}: the public key in the file is not the private key's`
+      )
+    }
+    return { identity, algorithm: "ed25519" }
+  }
+
+  let jwk: { kty?: string; crv?: string; d?: string }
+  try {
+    jwk = createPrivateKey(pem).export({ format: "jwk" })
+  } catch {
+    throw new UsageError(
+      `${what} holds no private key this tool can read: it reads Ed25519 and secp256k1 keys in PEM form`
+    )
+  }
+  if (jwk.kty !== "EC" || jwk.crv !== "secp256k1" || jwk.d === undefined) {
+    throw new UsageError(
+      `${what} holds a ${jwk.crv ?? jwk.kty ?? "different"} key: this tool signs with Ed25519 or secp256k1 keys`
+    )
+  }
+  const secret = new Uint8Array(Buffer.from(jwk.d, "base64url"))
+  return {
+    identity: Secp256k1KeyIdentity.fromSecretKey(secret),
+    algorithm: "secp256k1",
+  }
+}
+
+/** The DER bytes of the first `label` block of a PEM text. */
+function derOf(pem: string, label: string): Uint8Array | undefined {
+  const match = new RegExp(
+    `-----BEGIN ${label}-----([A-Za-z0-9+/=\\s]+)-----END ${label}-----`
+  ).exec(pem)
+  return match?.[1] === undefined
+    ? undefined
+    : new Uint8Array(Buffer.from(match[1].replace(/\s+/g, ""), "base64"))
+}
+
+/**
+ * PKCS#8 for Ed25519 (RFC 8410): SEQUENCE { version 0 or 1, the algorithm
+ * 1.3.101.112, OCTET STRING { OCTET STRING (32-byte seed) } [, public key] }.
+ */
+const ED25519_ALGORITHM_AND_SEED = [
+  0x30, 0x05, 0x06, 0x03, 0x2b, 0x65, 0x70, 0x04, 0x22, 0x04, 0x20,
+]
+
+function ed25519SeedOf(der: Uint8Array): Uint8Array | undefined {
+  const version = der[4]
+  const prefixed =
+    der[0] === 0x30 &&
+    der[1] === der.length - 2 &&
+    der[2] === 0x02 &&
+    der[3] === 0x01 &&
+    (version === 0 || version === 1) &&
+    ED25519_ALGORITHM_AND_SEED.every((byte, i) => der[5 + i] === byte)
+  if (!prefixed) return undefined
+  const start = 5 + ED25519_ALGORITHM_AND_SEED.length
+  const seed = der.slice(start, start + 32)
+  return seed.length === 32 ? seed : undefined
+}
+
+/** The public key a version 1 key carries after its seed, in either tagging dfx and OpenSSL use. */
+function ed25519PublicKeyOf(der: Uint8Array): Uint8Array | undefined {
+  const rest = der.slice(5 + ED25519_ALGORITHM_AND_SEED.length + 32)
+  const explicit = [0xa1, 0x23, 0x03, 0x21, 0x00]
+  const implicit = [0x81, 0x21, 0x00]
+  for (const tag of [explicit, implicit]) {
+    if (
+      rest.length === tag.length + 32 &&
+      tag.every((byte, i) => rest[i] === byte)
+    ) {
+      return rest.slice(tag.length)
+    }
+  }
+  return undefined
+}
+
+const sameBytes = (a: Uint8Array, b: Uint8Array): boolean =>
+  a.length === b.length && a.every((byte, i) => byte === b[i])

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

@@ -0,0 +1,110 @@
+// Text from the command line to the values a call takes, or a refusal before
+// anything is sent.
+//
+// Library rules shown here (packages/core/llms.txt, "Values"):
+// - a principal is made with `principal(text)`, which throws for text that is
+//   not one; the refusal is caught and reported, never cast around;
+// - a token amount is read with `parseUnits(text, decimals)`, which throws for
+//   "1e3", "1,5", a negative or too many fraction digits. Never `Number()`.
+//
+// Every function throws a UsageError: exit code 2, kind "usage", and no write
+// is sent. (A transfer's amount is read after the ledger's decimals are.)
+import { principal, type Principal } from "@meantjs/schema"
+import { parseUnits } from "@ic-reactor/core"
+
+/** Input refused by this tool, before any write was sent. */
+export class UsageError extends Error {
+  override name = "UsageError"
+  /** The command the input was for, when the command line got that far. */
+  readonly command: string | undefined
+
+  constructor(message: string, command?: string) {
+    super(message)
+    this.command = command
+  }
+}
+
+const reason = (error: unknown): string =>
+  (error instanceof Error ? error.message : String(error)).replace(
+    /^\[ic-reactor\] /,
+    ""
+  )
+
+/** A principal typed by a person or an agent. */
+export function principalArg(text: string, what: string): Principal {
+  try {
+    return principal(text)
+  } catch (error) {
+    throw new UsageError(
+      `${what} ${JSON.stringify(text)} is not a principal (${reason(error)})`
+    )
+  }
+}
+
+/** An amount in tokens, such as "1.5", as base units of a ledger with `decimals`. */
+export function amountArg(
+  text: string,
+  decimals: number,
+  what: string
+): bigint {
+  try {
+    return parseUnits(text, decimals)
+  } catch (error) {
+    throw new UsageError(
+      `${what} ${JSON.stringify(text)} is not an amount of a token with ${decimals} decimals (${reason(error)})`
+    )
+  }
+}
+
+/** Hex text as bytes; `length` pins the byte count. */
+export function hexArg(
+  text: string,
+  what: string,
+  length?: number
+): Uint8Array {
+  if (!/^(?:[0-9a-fA-F]{2})*$/.test(text)) {
+    throw new UsageError(`${what} ${JSON.stringify(text)} is not hex`)
+  }
+  const bytes = Uint8Array.from(text.match(/../g) ?? [], (pair) =>
+    Number.parseInt(pair, 16)
+  )
+  if (length !== undefined && bytes.length !== length) {
+    throw new UsageError(
+      `${what} is ${length} bytes (${length * 2} hex digits), got ${bytes.length}`
+    )
+  }
+  return bytes
+}
+
+/** An ICRC-1 subaccount: exactly 32 bytes of hex. */
+export const subaccountArg = (text: string, what: string): Uint8Array =>
+  hexArg(text, what, 32)
+
+/**
+ * A whole number of nanoseconds. Only the form is checked here: a value past
+ * the `nat64` range is left to the client, which refuses to encode it
+ * (`invalid_args`) before sending.
+ */
+export function nanosArg(text: string, what: string): bigint {
+  if (!/^\d+$/.test(text)) {
+    throw new UsageError(
+      `${what} ${JSON.stringify(text)} is not a whole number of nanoseconds`
+    )
+  }
+  return BigInt(text)
+}
+
+/** A polling interval in milliseconds, at least 100. */
+export function intervalArg(text: string): number {
+  const ms = /^\d+$/.test(text) ? Number.parseInt(text, 10) : Number.NaN
+  if (!Number.isSafeInteger(ms) || ms < 100) {
+    throw new UsageError(
+      `--interval ${JSON.stringify(text)} is not a number of milliseconds of at least 100`
+    )
+  }
+  return ms
+}
+
+/** Bytes as lowercase hex. */
+export const toHex = (bytes: Uint8Array): string =>
+  Array.from(bytes, (b) => b.toString(16).padStart(2, "0")).join("")

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

@@ -0,0 +1,74 @@
+// Scenario 3: many ledgers, one interface.
+import { createTestClient } from "@ic-reactor/core/testing"
+import { describe, expect, it } from "vitest"
+import { UsageError } from "./input.ts"
+import { LEDGERS, ledgerFrom, ledgerOn } from "./ledgers.ts"
+import { createCli } from "./test-kit.ts"
+
+describe("--ledger", () => {
+  it("names the mainnet ledgers", () => {
+    expect(LEDGERS).toEqual({
+      icp: "ryjl3-tyaaa-aaaaa-aaaba-cai",
+      ckbtc: "mxzaz-hqaaa-aaaar-qaada-cai",
+      cketh: "ss2fx-dyaaa-aaaar-qacoq-cai",
+    })
+    expect(ledgerFrom(undefined)).toEqual({
+      id: LEDGERS.icp,
+      name: "icp",
+      flags: ["--ledger", "icp"],
+    })
+    expect(ledgerFrom("cketh").id).toBe(LEDGERS.cketh)
+  })
+
+  it("takes any canister id, and refuses what is not one", () => {
+    expect(ledgerFrom("aaaaa-aa")).toEqual({
+      id: "aaaaa-aa",
+      name: null,
+      flags: ["--ledger", "aaaaa-aa"],
+    })
+    expect(() => ledgerFrom("bitcoin")).toThrow(UsageError)
+  })
+
+  it("is one canister object per id, and another for certified reads", () => {
+    const { client } = createTestClient()
+    const icp = ledgerOn(client, LEDGERS.icp)
+    expect(ledgerOn(client, LEDGERS.icp)).toBe(icp)
+    expect(ledgerOn(client, LEDGERS.ckbtc)).not.toBe(icp)
+    expect(ledgerOn(client, LEDGERS.icp, true)).not.toBe(icp)
+    client.dispose()
+  })
+
+  it.each(["ckbtc", "cketh"] as const)(
+    "sends every call of --ledger %s to that ledger",
+    async (name) => {
+      const { cli } = createCli({
+        ledger: {
+          id: LEDGERS[name],
+          symbol: name,
+          decimals: name === "cketh" ? 18 : 8,
+        },
+      })
+      const result = await cli(["info", "--ledger", name, "--json"])
+      expect(result.exitCode).toBe(0)
+      expect(result.docs[0]).toMatchObject({
+        ledger: { id: LEDGERS[name], name },
+        symbol: name,
+      })
+      expect(result.requests).toHaveLength(5)
+      expect(new Set(result.requests.map((r) => r.canisterId))).toEqual(
+        new Set([LEDGERS[name]])
+      )
+    }
+  )
+
+  it("reports a canister that is not there as a rejected read (exit 7)", async () => {
+    const { cli } = createCli()
+    const result = await cli(["info", "--ledger", LEDGERS.ckbtc, "--json"])
+    expect(result.exitCode).toBe(7)
+    expect(result.docs[0]).toMatchObject({
+      ok: false,
+      kind: "rejected",
+      mayHaveExecuted: false,
+    })
+  })
+})