@ic-reactor/mcp 0.0.0-stage → 0.0.0

package/examples/icrc-ledger/src/blocks.test.ts

@@ -0,0 +1,247 @@
+// The Blocks section's reads, over the in-memory replica: a mocked ICP ledger
+// whose oldest blocks live in a mocked archive canister, reached through the
+// func reference the ledger's reply carries, as on mainnet.
+import { c, principal } from "@meantjs/schema"
+import { isReactorError, type ReactorError } from "@ic-reactor/core"
+import { createTestClient, type TestHandlers } from "@ic-reactor/core/testing"
+import { afterEach, describe, expect, it } from "vitest"
+import {
+  archivedRangeOptions,
+  blockRows,
+  blocksLedgerOn,
+  operationOf,
+} from "./blocks.ts"
+import {
+  actor,
+  QueryArchiveFn,
+  type Actor,
+  type Block,
+  type GetBlocksArgs,
+  type QueryArchiveResult,
+} from "./canisters/icp_ledger.ts"
+import { ICP_LEDGER } from "./ledger.ts"
+
+/** The ICP ledger's first archive canister on mainnet. */
+const ARCHIVE = "qjdve-lqaaa-aaaaa-aaaeq-cai"
+/** Blocks 0 to 5 are archived; the ledger holds 6 to 9. */
+const ARCHIVED = 6n
+const CHAIN = 10n
+
+/** The block at `index`: a mint of `index` ICP. */
+const blockAt = (index: bigint): Block => ({
+  parent_hash: null,
+  timestamp: { timestamp_nanos: 1_620_000_000_000_000_000n + index },
+  transaction: {
+    memo: index,
+    icrc1_memo: null,
+    created_at_time: { timestamp_nanos: 0n },
+    operation: {
+      tag: "Mint",
+      value: { to: new Uint8Array(32), amount: { e8s: index * 100_000_000n } },
+    },
+  },
+})
+
+const range = (from: bigint, to: bigint): Block[] => {
+  const blocks: Block[] = []
+  for (let i = from; i < to; i++) blocks.push(blockAt(i))
+  return blocks
+}
+
+const min = (a: bigint, b: bigint) => (a < b ? a : b)
+const max = (a: bigint, b: bigint) => (a > b ? a : b)
+
+/**
+ * The archive canister's interface is the func type's own: a service whose
+ * one method is `QueryArchiveFn`, served under the name the callback gives.
+ */
+const archiveService = c.service({ get_blocks: QueryArchiveFn })
+type ArchiveActor = {
+  get_blocks: (arg: GetBlocksArgs) => Promise<QueryArchiveResult>
+}
+
+const clients: Array<{ dispose(): void }> = []
+afterEach(() => {
+  for (const client of clients.splice(0)) client.dispose()
+})
+
+/**
+ * A test client with the ledger and its archive mocked. The archive holds
+ * blocks from `archiveFrom` on, and answers `BadFirstBlockIndex` below it.
+ */
+function setup(archiveFrom = 0n) {
+  const test = createTestClient()
+  clients.push(test.client)
+  const ledgerHandlers: TestHandlers<Actor> = {
+    query_blocks: ({ start, length }) => {
+      const end = min(start + length, CHAIN)
+      const archivedEnd = min(end, ARCHIVED)
+      return {
+        chain_length: CHAIN,
+        certificate: null,
+        first_block_index: max(start, ARCHIVED),
+        blocks: range(max(start, ARCHIVED), end),
+        archived_blocks:
+          start < archivedEnd
+            ? [
+                {
+                  start,
+                  length: archivedEnd - start,
+                  callback: {
+                    principal: principal(ARCHIVE),
+                    method: "get_blocks",
+                  },
+                },
+              ]
+            : [],
+      }
+    },
+  }
+  const archiveHandlers: TestHandlers<ArchiveActor> = {
+    get_blocks: ({ start, length }) =>
+      start < archiveFrom
+        ? {
+            tag: "Err",
+            value: {
+              tag: "BadFirstBlockIndex",
+              value: { requested_index: start, first_valid_index: archiveFrom },
+            },
+          }
+        : { tag: "Ok", value: { blocks: range(start, start + length) } },
+  }
+  test.mock<Actor>(actor, ICP_LEDGER, ledgerHandlers)
+  test.mock<ArchiveActor>(archiveService, ARCHIVE, archiveHandlers)
+  return { ...test, ledger: blocksLedgerOn(test.client) }
+}
+
+/** The queries the replica received for the archive canister. */
+const archiveReads = (requests: ReturnType<typeof setup>["requests"]) =>
+  requests.filter((r) => r.endpoint === "query" && r.canisterId === ARCHIVE)
+
+describe("reading the ICP ledger's blocks across its archive", () => {
+  it("reads the archived part of a range from the canister and method the reply's callback names", async () => {
+    const { client, ledger, requests } = setup()
+    const args = { start: 4n, length: 4n }
+
+    const reply = await client.queryClient.fetchQuery(
+      client.queryOptions(ledger, "query_blocks", args)
+    )
+    expect(reply.archived_blocks).toEqual([
+      {
+        start: 4n,
+        length: 2n,
+        callback: { principal: ARCHIVE, method: "get_blocks" },
+      },
+    ])
+    const archived = await Promise.all(
+      reply.archived_blocks.map((r) =>
+        client.queryClient.fetchQuery(archivedRangeOptions(client, args, r))
+      )
+    )
+
+    const rows = blockRows(reply, archived)
+    expect(rows.map((row) => [row.index, row.from])).toEqual([
+      [4n, ARCHIVE],
+      [5n, ARCHIVE],
+      [6n, ICP_LEDGER],
+      [7n, ICP_LEDGER],
+    ])
+    expect(rows.map((row) => operationOf(row.block))).toEqual([
+      { kind: "Mint", e8s: 400_000_000n },
+      { kind: "Mint", e8s: 500_000_000n },
+      { kind: "Mint", e8s: 600_000_000n },
+      { kind: "Mint", e8s: 700_000_000n },
+    ])
+    expect(archiveReads(requests).map((r) => r.methodName)).toEqual([
+      "get_blocks",
+    ])
+  })
+
+  it("sends nothing to an archive when the ledger still holds the whole range", async () => {
+    const { client, ledger, requests } = setup()
+
+    const reply = await client.queryClient.fetchQuery(
+      client.queryOptions(ledger, "query_blocks", { start: 7n, length: 3n })
+    )
+
+    expect(reply.archived_blocks).toEqual([])
+    expect(blockRows(reply, []).map((row) => row.index)).toEqual([7n, 8n, 9n])
+    expect(archiveReads(requests)).toHaveLength(0)
+  })
+
+  it("rejects an archive's Err arm as canister_err, with the QueryArchiveError in err", async () => {
+    const { client, ledger } = setup(2n)
+    const args = { start: 0n, length: 3n }
+    const reply = await ledger.query_blocks(args)
+    const [only] = reply.archived_blocks
+    expect(only).toBeDefined()
+
+    let failure: ReactorError<unknown> | undefined
+    try {
+      await client.queryClient.fetchQuery(
+        archivedRangeOptions(client, args, only!)
+      )
+    } catch (error) {
+      if (!isReactorError(error)) throw error
+      failure = error
+    }
+
+    expect(failure?.kind).toBe("canister_err")
+    expect(failure?.mayHaveExecuted).toBe(false)
+    expect(failure?.err).toEqual({
+      tag: "BadFirstBlockIndex",
+      value: { requested_index: 0n, first_valid_index: 2n },
+    })
+  })
+
+  it("caches an archived range under the ledger's key, so a ledger invalidation reaches it", async () => {
+    const { client, ledger, requests } = setup()
+    const args = { start: 0n, length: 2n }
+    const reply = await ledger.query_blocks(args)
+    const options = archivedRangeOptions(
+      client,
+      args,
+      reply.archived_blocks[0]!
+    )
+
+    await client.queryClient.fetchQuery({ ...options, staleTime: Infinity })
+    await client.queryClient.fetchQuery({ ...options, staleTime: Infinity })
+    expect(archiveReads(requests)).toHaveLength(1)
+
+    await client.queryClient.invalidateQueries({
+      queryKey: client.queryKey(ledger),
+    })
+    expect(
+      client.queryClient.getQueryState(options.queryKey)?.isInvalidated
+    ).toBe(true)
+  })
+
+  it("reads the archive with a plain query under a certified ledger, and keeps 'certified' out of its key", async () => {
+    const { client, ledger, requests } = setup()
+    const certified = blocksLedgerOn(client, true)
+    const args = { start: 0n, length: 2n }
+    const reply = await client.queryClient.fetchQuery(
+      client.queryOptions(certified, "query_blocks", args)
+    )
+    const options = archivedRangeOptions(
+      client,
+      args,
+      reply.archived_blocks[0]!
+    )
+
+    const range = await client.queryClient.fetchQuery(options)
+
+    expect(range.blocks).toHaveLength(2)
+    // The ledger's page went through consensus; the archive's did not.
+    const sent = (id: string) =>
+      requests.filter((r) => r.canisterId === id).map((r) => r.endpoint)
+    expect(sent(ICP_LEDGER)).toContain("call")
+    expect(sent(ARCHIVE)).toContain("query")
+    expect(sent(ARCHIVE)).not.toContain("call")
+    // So the key is the plain page's, and a plain page finds it cached.
+    expect(options.queryKey).not.toContain("certified")
+    expect(options.queryKey.slice(0, -5)).toEqual(
+      client.queryKey(ledger, "query_blocks", args)
+    )
+  })
+})

package/examples/icrc-ledger/src/blocks.ts

@@ -0,0 +1,140 @@
+// The ICP ledger's blocks, archives included. The ledger keeps only its newest
+// blocks; a `query_blocks` reply names an archive canister and method for each
+// older range (a Candid func reference), and `client.func()` calls it. Plain
+// TypeScript, so the Mainnet tab, scripts/smoke.ts and blocks.test.ts share it.
+import type { Client, ReactorError } from "@ic-reactor/core"
+import { queryOptions } from "@tanstack/react-query"
+import {
+  actor,
+  QueryArchiveFn,
+  type Actor,
+  type ArchivedBlocksRange,
+  type Block,
+  type BlockRange,
+  type GetBlocksArgs,
+  type QueryArchiveError,
+  type QueryBlocksResponse,
+} from "./canisters/icp_ledger.ts"
+import { ICP_LEDGER } from "./ledger.ts"
+
+/**
+ * The ICP ledger's blocks on `client`. `certified` certifies `query_blocks`
+ * and nothing else: an archived range is read through `client.func()`, which
+ * has no certified path (see {@link archivedRangeOptions}).
+ */
+export const blocksLedgerOn = (client: Client, certified = false) =>
+  client.canister<Actor>(actor, { id: ICP_LEDGER, certified })
+
+/**
+ * The function an archive callback stands for. A generated func type is only
+ * `{ principal, method }`, so the signature is written here from the `.did`:
+ * `func (GetBlocksArgs) -> (QueryArchiveResult) query`, whose `Ok` payload the
+ * client resolves with and whose `Err` it rejects as `canister_err`.
+ */
+export type ReadArchive = (arg: GetBlocksArgs) => Promise<BlockRange>
+
+/**
+ * TanStack Query options for one archived range of a `query_blocks` reply:
+ * `client.func()` turns the range's callback into a call to its archive
+ * canister, and the result is cached like any read.
+ *
+ * The archive is always read with a plain query, never certified, even when
+ * the `query_blocks` read that named the range was: `client.func()` has no
+ * certified path. So the key never says otherwise. There is no options
+ * builder for a func reference, so the key is the key of the plain
+ * `query_blocks` read with the same `args` (`client.queryKey()`, which holds
+ * the network, the caller and the ledger, and no `'certified'` segment), plus
+ * the range. Keyed so, it stays under its ledger: an invalidation of the
+ * ledger's reads covers it, and a certified page and a plain one share the
+ * archive's answer. The call is made as the caller current when it runs, as a
+ * direct call is, and the default `retry` of `client.queryClient` applies to
+ * it. TanStack's `queryOptions()` tags the key with the data and the error, so
+ * `useQuery` types `error` as a `ReactorError` whose `err` is a
+ * `QueryArchiveError`.
+ *
+ * @param args - The arguments of the `query_blocks` read whose reply carried
+ * `range`, certified or not.
+ */
+export function archivedRangeOptions(
+  client: Client,
+  args: GetBlocksArgs,
+  range: ArchivedBlocksRange
+) {
+  const read = client.func<ReadArchive>(QueryArchiveFn, range.callback)
+  return queryOptions<BlockRange, ReactorError<QueryArchiveError>>({
+    queryKey: [
+      ...client.queryKey(blocksLedgerOn(client), "query_blocks", args),
+      "archived",
+      range.callback.principal,
+      range.callback.method,
+      range.start.toString(),
+      range.length.toString(),
+    ],
+    queryFn: () => read({ start: range.start, length: range.length }),
+  })
+}
+
+/** A block, its index, and the canister that answered with it. */
+export interface BlockRow {
+  readonly index: bigint
+  readonly block: Block
+  /** The ledger's id, or the archive canister's for an archived block. */
+  readonly from: string
+}
+
+/**
+ * The blocks of a `query_blocks` reply in index order: those of each archived
+ * range (from `archived[i]`, the read of `reply.archived_blocks[i]`, or
+ * nothing while it is loading) and those the ledger itself sent.
+ */
+export function blockRows(
+  reply: QueryBlocksResponse,
+  archived: ReadonlyArray<BlockRange | undefined>
+): BlockRow[] {
+  const rows: BlockRow[] = []
+  reply.archived_blocks.forEach((range, i) => {
+    archived[i]?.blocks.forEach((block, offset) =>
+      rows.push({
+        index: range.start + BigInt(offset),
+        block,
+        from: range.callback.principal,
+      })
+    )
+  })
+  reply.blocks.forEach((block, offset) =>
+    rows.push({
+      index: reply.first_block_index + BigInt(offset),
+      block,
+      from: ICP_LEDGER,
+    })
+  )
+  return rows.sort((a, b) =>
+    a.index < b.index ? -1 : a.index > b.index ? 1 : 0
+  )
+}
+
+/** What a block did, in a few words, with its amount in e8s. */
+export function operationOf(block: Block): {
+  readonly kind: string
+  readonly e8s: bigint | undefined
+} {
+  const operation = block.transaction.operation
+  if (operation === null) return { kind: "unknown", e8s: undefined }
+  switch (operation.tag) {
+    case "Mint":
+      return { kind: "Mint", e8s: operation.value.amount.e8s }
+    case "Burn":
+      return { kind: "Burn", e8s: operation.value.amount.e8s }
+    case "Transfer":
+      return { kind: "Transfer", e8s: operation.value.amount.e8s }
+    case "Approve":
+      return { kind: "Approve", e8s: operation.value.allowance.e8s }
+  }
+}
+
+/** A block's timestamp in UTC, to the second: `2021-05-06 19:17:10`. */
+export const blockTime = (block: Block): string =>
+  new Date(Number(block.timestamp.timestamp_nanos / 1_000_000n))
+    .toISOString()
+    .replace("T", " ")
+    .replace(/\.\d+Z$/, "")

package/examples/icrc-ledger/src/canisters/ckbtc_minter.envelope.json

@@ -0,0 +1,96 @@
+{
+  "contract": {
+    "actor": {
+      "kind": "service",
+      "service": 0
+    },
+    "canonicalization_profile": "candid-core-canon-1",
+    "declarations": [],
+    "format": "candid-core",
+    "format_version": 1,
+    "identities": {
+      "contract": "candid-core:contract:v1:sha256:318c534f5de259c21358bce29c6828838cd201f792f313e2e8fb35952d726491",
+      "interface": "candid-core:interface:v1:sha256:9f403605107d9e4adddd8a85c4b7b87d0fa5528c74c303ee31a3676c509d6132"
+    },
+    "producer": {
+      "candid_parser_version": "0.4.0",
+      "candid_version": "0.10.30",
+      "name": "meant",
+      "version": "0.1.0"
+    },
+    "semantics_profile": "candid-1",
+    "types": [
+      {
+        "kind": "service",
+        "methods": [
+          {
+            "function": 1,
+            "id": 2716106269,
+            "name": "get_btc_address"
+          }
+        ]
+      },
+      {
+        "args": [
+          2
+        ],
+        "kind": "func",
+        "mode": "update",
+        "results": [
+          8
+        ]
+      },
+      {
+        "fields": [
+          {
+            "id": 947296307,
+            "type": 3
+          },
+          {
+            "id": 1349681965,
+            "type": 5
+          }
+        ],
+        "kind": "record"
+      },
+      {
+        "inner": 4,
+        "kind": "opt"
+      },
+      {
+        "kind": "primitive",
+        "primitive": "principal"
+      },
+      {
+        "inner": 6,
+        "kind": "opt"
+      },
+      {
+        "inner": 7,
+        "kind": "vec"
+      },
+      {
+        "kind": "primitive",
+        "primitive": "nat8"
+      },
+      {
+        "kind": "primitive",
+        "primitive": "text"
+      }
+    ]
+  },
+  "extensions": {
+    "org.candid-core.field-names/v1": [
+      [
+        2,
+        947296307,
+        "owner"
+      ],
+      [
+        2,
+        1349681965,
+        "subaccount"
+      ]
+    ]
+  }
+}

package/examples/icrc-ledger/src/canisters/ckbtc_minter.ts

@@ -0,0 +1,16 @@
+// Generated by Meant from a Meant Contract. Do not edit.
+import * as $ from "@meantjs/schema";
+
+const $actor: $.Schema<$.Principal> = $.c.rec(() => $.c.service({ get_btc_address: $.c.func([$.c.record({ owner: $.c.opt($.c.principal), subaccount: $.c.opt($.c.blob()) })], [$.c.text], "update") }));
+export type Actor = {
+  /**
+   * Returns the Bitcoin address to which the owner should send BTC
+   * before converting the amount to ckBTC using the [update_balance]
+   * endpoint.
+   *
+   * If the owner is not set, it defaults to the caller's principal.
+   * The resolved owner must be a non-anonymous principal.
+   */
+  get_btc_address: ((arg0: { owner: $.Principal | null; subaccount: Uint8Array | null }) => Promise<string>) & $.WithMode<"update">;
+};
+export { $actor as actor };