@arkiv-network/sdk 0.7.0 → 0.8.0-dev.1

package/src/actions/public/watchEntityEvents.test.ts

@@ -0,0 +1,414 @@
+import { describe, expect, it } from "bun:test"
+import { type Abi, encodeAbiParameters, encodeEventTopics, getAbiItem, type Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import { ARKIV_ADDRESS } from "../../consts"
+import { ENTITY_EVENTS_ABI, type EntityEventName } from "../../entity/events"
+import type { EntityEvent } from "../../types/events"
+import { watchEntityEvents } from "./watchEntityEvents"
+
+const KEY_A = `0x${"aa".repeat(32)}` as Hex
+const KEY_B = `0x${"bb".repeat(32)}` as Hex
+const ALICE = "0x1111111111111111111111111111111111111111" as const
+const BOB = "0x2222222222222222222222222222222222222222" as const
+
+type Log = {
+  topics: Hex[]
+  data: Hex
+  blockNumber: bigint | null
+  transactionHash: Hex | null
+  logIndex: number | null
+}
+
+/**
+ * Builds the log the engine would emit for an event, from the same ABI the watcher decodes with.
+ *
+ * Encoding rather than hand-writing topics is what keeps the test honest about the indexed/
+ * non-indexed split: change the ABI and the log changes with it.
+ */
+function logFor(
+  eventName: EntityEventName,
+  args: Record<string, unknown>,
+  position: { blockNumber?: bigint; transactionHash?: Hex; logIndex?: number } = {},
+): Log {
+  const item = getAbiItem({ abi: ENTITY_EVENTS_ABI as Abi, name: eventName })
+  if (item === undefined || item.type !== "event") throw new Error(`no event ${eventName}`)
+
+  const unindexed = item.inputs.filter((input) => !("indexed" in input && input.indexed))
+  return {
+    topics: encodeEventTopics({
+      abi: ENTITY_EVENTS_ABI,
+      eventName,
+      // biome-ignore lint/suspicious/noExplicitAny: the arg shape varies per event by design.
+      args: args as any,
+    }) as Hex[],
+    data:
+      unindexed.length === 0
+        ? "0x"
+        : encodeAbiParameters(
+            unindexed,
+            unindexed.map((input) => args[input.name ?? ""]),
+          ),
+    blockNumber: position.blockNumber ?? 100n,
+    transactionHash: position.transactionHash ?? (`0x${"cc".repeat(32)}` as Hex),
+    logIndex: position.logIndex ?? 0,
+  }
+}
+
+type Harness = {
+  client: ArkivClient
+  /** Feeds logs to the watcher, as the poller would. */
+  emitLogs: (logs: Log[]) => void
+  /** Raises a transport error on the log watcher. */
+  failLogs: (error: Error) => void
+  watchEventCalls: Record<string, unknown>[]
+  stops: string[]
+}
+
+/** A client that hands back its watcher callbacks so a test can drive them directly. */
+function harness(): Harness {
+  const state: Partial<{
+    onLogs: (logs: Log[]) => void
+    onLogsError: (error: Error) => void
+  }> = {}
+  const watchEventCalls: Record<string, unknown>[] = []
+  const stops: string[] = []
+
+  const client = {
+    // biome-ignore lint/suspicious/noExplicitAny: a stand-in for viem's generic watcher.
+    watchEvent(parameters: any) {
+      watchEventCalls.push(parameters)
+      state.onLogs = parameters.onLogs
+      state.onLogsError = parameters.onError
+      return () => stops.push("logs")
+    },
+  } as unknown as ArkivClient
+
+  return {
+    client,
+    emitLogs: (logs) => state.onLogs?.(logs),
+    failLogs: (error) => state.onLogsError?.(error),
+    watchEventCalls,
+    stops,
+  }
+}
+
+/** Runs `body` with `console.error` captured, so a test can assert on the default error path. */
+function captureConsoleError(body: () => void): unknown[][] {
+  const calls: unknown[][] = []
+  const original = console.error
+  console.error = (...args: unknown[]) => {
+    calls.push(args)
+  }
+  try {
+    body()
+  } finally {
+    console.error = original
+  }
+  return calls
+}
+
+describe("decoding the five on-chain events", () => {
+  it("decodes a create, with the position it was applied at", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onEntityCreated: (event) => seen.push(event) })
+
+    h.emitLogs([
+      logFor(
+        "EntityCreated",
+        { entityKey: KEY_A, owner: ALICE, expiresAt: 1_200_000n, creationFlags: 0b11 },
+        { blockNumber: 42n, logIndex: 3 },
+      ),
+    ])
+
+    expect(seen).toEqual([
+      {
+        type: "EntityCreated",
+        entityKey: KEY_A,
+        owner: ALICE,
+        expiresAt: 1_200_000n,
+        // Decoded, with the byte kept alongside so a flag this SDK has no name for stays visible.
+        creationFlags: { readonly: true, permissionlessExtension: true, raw: 0b11 },
+        blockNumber: 42n,
+        transactionHash: `0x${"cc".repeat(32)}`,
+        logIndex: 3,
+      },
+    ])
+  })
+
+  it("decodes a patch", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onEntityPatched: (event) => seen.push(event) })
+
+    h.emitLogs([logFor("EntityPatched", { entityKey: KEY_A, owner: ALICE })])
+
+    expect(seen).toMatchObject([{ type: "EntityPatched", entityKey: KEY_A, owner: ALICE }])
+  })
+
+  it("decodes an extension", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onExpiryExtended: (event) => seen.push(event) })
+
+    h.emitLogs([logFor("ExpiryExtended", { entityKey: KEY_A, owner: ALICE, expiresAt: 999n })])
+
+    // `owner` is the entity's owner, not the caller — a permissionless extension is by a non-owner.
+    expect(seen).toMatchObject([
+      { type: "ExpiryExtended", entityKey: KEY_A, owner: ALICE, expiresAt: 999n },
+    ])
+  })
+
+  it("decodes a transfer, naming both sides", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onOwnershipTransferred: (event) => seen.push(event) })
+
+    h.emitLogs([
+      logFor("OwnershipTransferred", { entityKey: KEY_A, previousOwner: ALICE, newOwner: BOB }),
+    ])
+
+    expect(seen).toMatchObject([
+      { type: "OwnershipTransferred", entityKey: KEY_A, previousOwner: ALICE, newOwner: BOB },
+    ])
+  })
+
+  it("decodes a delete", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onEntityDeleted: (event) => seen.push(event) })
+
+    h.emitLogs([logFor("EntityDeleted", { entityKey: KEY_A, owner: ALICE })])
+
+    expect(seen).toMatchObject([{ type: "EntityDeleted", entityKey: KEY_A, owner: ALICE }])
+  })
+})
+
+describe("onEvent", () => {
+  it("receives every event in the order it was applied", () => {
+    const h = harness()
+    const seen: string[] = []
+    watchEntityEvents(h.client, { onEvent: (event) => seen.push(event.type) })
+
+    h.emitLogs([
+      logFor(
+        "EntityCreated",
+        { entityKey: KEY_A, owner: ALICE, expiresAt: 500n, creationFlags: 0 },
+        { logIndex: 0 },
+      ),
+      logFor("EntityPatched", { entityKey: KEY_A, owner: ALICE }, { logIndex: 1 }),
+      logFor(
+        "OwnershipTransferred",
+        { entityKey: KEY_A, previousOwner: ALICE, newOwner: BOB },
+        { logIndex: 2 },
+      ),
+      logFor("EntityDeleted", { entityKey: KEY_A, owner: BOB }, { logIndex: 3 }),
+    ])
+
+    expect(seen).toEqual([
+      "EntityCreated",
+      "EntityPatched",
+      "OwnershipTransferred",
+      "EntityDeleted",
+    ])
+  })
+
+  it("runs before the per-event handler for the same event", () => {
+    const h = harness()
+    const order: string[] = []
+    watchEntityEvents(h.client, {
+      onEvent: () => order.push("onEvent"),
+      onEntityCreated: () => order.push("onEntityCreated"),
+    })
+
+    h.emitLogs([
+      logFor("EntityCreated", { entityKey: KEY_A, owner: ALICE, expiresAt: 1n, creationFlags: 0 }),
+    ])
+
+    expect(order).toEqual(["onEvent", "onEntityCreated"])
+  })
+})
+
+describe("the watcher itself", () => {
+  it("only listens to the Arkiv operation address", () => {
+    const h = harness()
+    watchEntityEvents(h.client, { onEntityCreated: () => {} })
+
+    expect(h.watchEventCalls[0]).toMatchObject({ address: ARKIV_ADDRESS })
+  })
+
+  it("polls twice a block by default", () => {
+    const h = harness()
+    watchEntityEvents(h.client, { onEntityCreated: () => {} })
+
+    // Blocks are 2s, so a default that leaves an event a whole block stale is too slow.
+    expect(h.watchEventCalls[0]).toMatchObject({ pollingInterval: 1000 })
+  })
+
+  it("forwards fromBlock and pollingInterval, and omits fromBlock when unset", () => {
+    const withOptions = harness()
+    watchEntityEvents(withOptions.client, {
+      onEntityCreated: () => {},
+      fromBlock: 90n,
+      pollingInterval: 250,
+    })
+    expect(withOptions.watchEventCalls[0]).toMatchObject({ fromBlock: 90n, pollingInterval: 250 })
+
+    const bare = harness()
+    watchEntityEvents(bare.client, { onEntityCreated: () => {} })
+    expect(bare.watchEventCalls[0]).not.toHaveProperty("fromBlock")
+  })
+
+  it("stops the watcher when unwatched", () => {
+    const h = harness()
+    const unwatch = watchEntityEvents(h.client, { onEntityCreated: () => {} })
+
+    expect(h.stops).toEqual([])
+    unwatch()
+    expect(h.stops).toEqual(["logs"])
+  })
+
+  it("skips a log with no position rather than inventing one", () => {
+    const h = harness()
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, { onEvent: (event) => seen.push(event) })
+
+    const log = logFor("EntityCreated", {
+      entityKey: KEY_A,
+      owner: ALICE,
+      expiresAt: 1n,
+      creationFlags: 0,
+    })
+    h.emitLogs([{ ...log, blockNumber: null }])
+    h.emitLogs([{ ...log, transactionHash: null }])
+    h.emitLogs([{ ...log, logIndex: null }])
+
+    expect(seen).toEqual([])
+  })
+
+  it("reports a log it cannot decode instead of throwing out of the poller", () => {
+    const h = harness()
+    const errors: Error[] = []
+    const seen: EntityEvent[] = []
+    watchEntityEvents(h.client, {
+      onEvent: (event) => seen.push(event),
+      onError: (error) => errors.push(error),
+    })
+
+    const good = logFor("EntityDeleted", { entityKey: KEY_A, owner: ALICE })
+    // A create's topic with no data — the expiresAt word is missing.
+    const broken = {
+      ...logFor("EntityCreated", {
+        entityKey: KEY_A,
+        owner: ALICE,
+        expiresAt: 1n,
+        creationFlags: 0,
+      }),
+      data: "0x" as Hex,
+    }
+
+    expect(() => h.emitLogs([broken, good])).not.toThrow()
+    expect(errors).toHaveLength(1)
+    // The rest of the batch still gets through.
+    expect(seen).toMatchObject([{ type: "EntityDeleted" }])
+  })
+
+  it("forwards transport errors", () => {
+    const h = harness()
+    const errors: Error[] = []
+    watchEntityEvents(h.client, {
+      onEntityCreated: () => {},
+      onError: (error) => errors.push(error),
+    })
+
+    const boom = new Error("transport died")
+    h.failLogs(boom)
+
+    expect(errors).toEqual([boom])
+  })
+
+  it("logs to the console when no onError was given, so a dead watcher is not silent", () => {
+    const h = harness()
+    watchEntityEvents(h.client, { onEntityCreated: () => {} })
+
+    const boom = new Error("filter not found")
+    const logged = captureConsoleError(() => h.failLogs(boom))
+
+    expect(logged).toEqual([["watchEntityEvents error", boom]])
+  })
+})
+
+describe("a handler that throws", () => {
+  it("is reported, not allowed to escape into the poller", () => {
+    const h = harness()
+    const errors: Error[] = []
+    watchEntityEvents(h.client, {
+      onEntityCreated: () => {
+        throw new Error("consumer blew up")
+      },
+      onError: (error) => errors.push(error),
+    })
+
+    expect(() =>
+      h.emitLogs([
+        logFor("EntityCreated", {
+          entityKey: KEY_A,
+          owner: ALICE,
+          expiresAt: 200n,
+          creationFlags: 0,
+        }),
+      ]),
+    ).not.toThrow()
+    expect(errors).toMatchObject([{ message: "consumer blew up" }])
+  })
+
+  it("does not stop the other handlers for the same event", () => {
+    const h = harness()
+    const seen: string[] = []
+    watchEntityEvents(h.client, {
+      onEvent: () => {
+        throw new Error("onEvent blew up")
+      },
+      onEntityCreated: () => seen.push("onEntityCreated"),
+      onError: () => {},
+    })
+
+    h.emitLogs([
+      logFor("EntityCreated", {
+        entityKey: KEY_A,
+        owner: ALICE,
+        expiresAt: 200n,
+        creationFlags: 0,
+      }),
+    ])
+
+    expect(seen).toEqual(["onEntityCreated"])
+  })
+
+  it("does not stop the rest of the batch", () => {
+    const h = harness()
+    const seen: Hex[] = []
+    watchEntityEvents(h.client, {
+      onEntityCreated: ({ entityKey }) => {
+        seen.push(entityKey)
+        if (entityKey === KEY_A) throw new Error("first one blew up")
+      },
+      onError: () => {},
+    })
+
+    h.emitLogs([
+      logFor(
+        "EntityCreated",
+        { entityKey: KEY_A, owner: ALICE, expiresAt: 200n, creationFlags: 0 },
+        { logIndex: 0 },
+      ),
+      logFor(
+        "EntityCreated",
+        { entityKey: KEY_B, owner: BOB, expiresAt: 200n, creationFlags: 0 },
+        { logIndex: 1 },
+      ),
+    ])
+
+    expect(seen).toEqual([KEY_A, KEY_B])
+  })
+})

package/src/actions/public/watchEntityEvents.ts

@@ -0,0 +1,225 @@
+import { decodeEventLog, type Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { PublicArkivClient } from "../../clients/createPublicClient"
+import { ARKIV_ADDRESS, BLOCK_TIME } from "../../consts"
+import { ENTITY_EVENTS_ABI } from "../../entity/events"
+import { decodeCreationFlags } from "../../entity/flags"
+import type {
+  EntityCreatedEvent,
+  EntityDeletedEvent,
+  EntityEvent,
+  EntityEventContext,
+  EntityPatchedEvent,
+  ExpiryExtendedEvent,
+  OwnershipTransferredEvent,
+} from "../../types/events"
+import { getLogger } from "../../utils/logger"
+
+const logger = getLogger("actions:public:watch-entity-events")
+
+/**
+ * How often to poll, when the caller does not say.
+ *
+ * Half a block: fast enough that an event is never a whole block stale, slow enough not to hammer
+ * the node. viem's own default is derived from a 12-second Ethereum block and is far too slow here.
+ */
+const DEFAULT_POLLING_INTERVAL = (BLOCK_TIME * 1000) / 2
+
+/**
+ * Handlers and options for `client.watchEntityEvents`. Every handler is optional; the watcher does
+ * the work for the ones you pass.
+ */
+export type WatchEntityEventsParameters = {
+  onEntityCreated?: ((event: EntityCreatedEvent) => void) | undefined
+  onEntityPatched?: ((event: EntityPatchedEvent) => void) | undefined
+  onExpiryExtended?: ((event: ExpiryExtendedEvent) => void) | undefined
+  onOwnershipTransferred?: ((event: OwnershipTransferredEvent) => void) | undefined
+  onEntityDeleted?: ((event: EntityDeletedEvent) => void) | undefined
+  /**
+   * Every event, in application order, whatever its type. Runs *before* the per-event handler for
+   * the same event.
+   *
+   * This is the replay seam: operations apply in batch order and emit one event each, so an
+   * off-chain replica that consumes this in order sees exactly what the engine did.
+   */
+  onEvent?: ((event: EntityEvent) => void) | undefined
+  /**
+   * Transport failures, logs that will not decode, and anything one of your own handlers throws.
+   *
+   * Defaults to `console.error`. A watcher whose filter the node dropped otherwise just goes quiet,
+   * and a quiet watcher is indistinguishable from a quiet chain.
+   */
+  onError?: ((error: Error) => void) | undefined
+  /** Replay from this block before following the head. Defaults to the head. */
+  fromBlock?: bigint | undefined
+  /** How often to poll, in milliseconds. Defaults to half a block. */
+  pollingInterval?: number | undefined
+}
+
+/**
+ * Watches entity events, calling the handlers you pass as they arrive.
+ *
+ * Every event here is decoded from a log the Arkiv operation address emitted, and carries the
+ * block, transaction and log index it came from — so consuming them in order replays exactly what
+ * the engine did.
+ *
+ * @param parameters - Handlers and options. {@link WatchEntityEventsParameters}
+ * @returns A function that stops the watcher.
+ *
+ *
+ * @example
+ * import { createPublicClient } from "@arkiv-network/sdk"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { http } from "viem"
+ *
+ * const client = createPublicClient({ chain: cheesecake, transport: http() })
+ *
+ * const unwatch = client.watchEntityEvents({
+ *   onEntityCreated: ({ entityKey, owner, expiresAt }) =>
+ *     console.log("created", entityKey, "by", owner, "until block", expiresAt),
+ *   onEntityDeleted: ({ entityKey }) => console.log("deleted", entityKey),
+ *   onError: (error) => console.error(error),
+ * })
+ *
+ * unwatch()
+ */
+export function watchEntityEvents(
+  client: ArkivClient,
+  parameters: WatchEntityEventsParameters,
+): () => void {
+  const {
+    onEntityCreated,
+    onEntityPatched,
+    onExpiryExtended,
+    onOwnershipTransferred,
+    onEntityDeleted,
+    onEvent,
+    onError,
+    fromBlock,
+    pollingInterval = DEFAULT_POLLING_INTERVAL,
+  } = parameters
+
+  const publicClient = client as PublicArkivClient
+  const reportError = onError ?? logToConsole
+
+  function emit(event: EntityEvent): void {
+    deliver(onEvent, event)
+    switch (event.type) {
+      case "EntityCreated":
+        deliver(onEntityCreated, event)
+        break
+      case "EntityPatched":
+        deliver(onEntityPatched, event)
+        break
+      case "ExpiryExtended":
+        deliver(onExpiryExtended, event)
+        break
+      case "OwnershipTransferred":
+        deliver(onOwnershipTransferred, event)
+        break
+      case "EntityDeleted":
+        deliver(onEntityDeleted, event)
+        break
+    }
+  }
+
+  /**
+   * Runs one handler, keeping its failure to itself.
+   *
+   * A handler that throws is the consumer's problem, not the watcher's: letting it escape would
+   * reject the poll, drop the rest of the batch, and take down every other handler with it.
+   */
+  function deliver<TEvent>(handler: ((event: TEvent) => void) | undefined, event: TEvent): void {
+    if (handler === undefined) return
+    try {
+      handler(event)
+    } catch (error) {
+      reportError(asError(error))
+    }
+  }
+
+  const unwatchLogs = publicClient.watchEvent({
+    // Only the Arkiv operation address emits these. Without the filter any contract whose event
+    // happens to hash to the same topic lands in `onLogs`, and viem's observer key — which covers
+    // the address but not `events` — would make this subscription collide with any other
+    // unaddressed `watchEvent` on the same client.
+    address: ARKIV_ADDRESS,
+    events: ENTITY_EVENTS_ABI,
+    pollingInterval,
+    ...(fromBlock !== undefined && { fromBlock }),
+    onLogs: (logs) => {
+      logger("logs %o", logs)
+      for (const log of logs) {
+        // A log with no position cannot be placed in application order, which is the one thing an
+        // event consumer needs from it. Dropping it beats inventing a position it never had.
+        if (log.blockNumber === null || log.transactionHash === null || log.logIndex === null) {
+          continue
+        }
+        const context: EntityEventContext = {
+          blockNumber: log.blockNumber,
+          transactionHash: log.transactionHash,
+          logIndex: log.logIndex,
+        }
+
+        // Only the decode is guarded here. Dispatch guards each handler separately, so a consumer's
+        // exception is never reported as if the log were the thing that was malformed.
+        let event: EntityEvent
+        try {
+          event = toEntityEvent(log.topics, log.data, context)
+        } catch (error) {
+          reportError(asError(error))
+          continue
+        }
+        emit(event)
+      }
+    },
+    onError: (error) => reportError(error),
+  })
+
+  return unwatchLogs
+}
+
+/** The fallback when no `onError` was given — see {@link WatchEntityEventsParameters.onError}. */
+function logToConsole(error: Error): void {
+  console.error("watchEntityEvents error", error)
+}
+
+/** Handlers take an `Error`, and a `throw` can be anything. */
+function asError(error: unknown): Error {
+  return error instanceof Error ? error : new Error(String(error))
+}
+
+/**
+ * Decodes one log into the {@link EntityEvent} it carries.
+ *
+ * @throws If the log does not decode against {@link ENTITY_EVENTS_ABI}.
+ */
+function toEntityEvent(
+  topics: readonly Hex[],
+  data: Hex,
+  context: EntityEventContext,
+): EntityEvent {
+  const decoded = decodeEventLog({
+    abi: ENTITY_EVENTS_ABI,
+    topics: topics as [Hex, ...Hex[]] | [],
+    data,
+  })
+
+  switch (decoded.eventName) {
+    case "EntityCreated":
+      return {
+        type: "EntityCreated",
+        ...context,
+        ...decoded.args,
+        creationFlags: decodeCreationFlags(decoded.args.creationFlags),
+      }
+    case "EntityPatched":
+      return { type: "EntityPatched", ...context, ...decoded.args }
+    case "ExpiryExtended":
+      return { type: "ExpiryExtended", ...context, ...decoded.args }
+    case "OwnershipTransferred":
+      return { type: "OwnershipTransferred", ...context, ...decoded.args }
+    case "EntityDeleted":
+      return { type: "EntityDeleted", ...context, ...decoded.args }
+  }
+}

package/src/actions/wallet/changeOwnership.ts

@@ -1,14 +1,15 @@
-import type { Hex } from "viem"
+import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:change-ownership")
 
 /**
- * Parameters for the deleteEntity function.
- * - entityKey: The key of the entity to delete.
+ * Parameters for the changeOwnership function.
+ * - entityKey: The key of the entity.
+ * - newOwner: The address of the new owner.
  */
 export type ChangeOwnershipParameters = {
   entityKey: Hex
@@ -16,13 +17,13 @@ export type ChangeOwnershipParameters = {
 }
 
 /**
- * Return type for the deleteEntity function.
+ * Return type for the changeOwnership function.
  * - entityKey: The key of the entity.
  * - txHash: The transaction hash.
  */
 export type ChangeOwnershipReturnType = {
   entityKey: Hex
-  txHash: string
+  txHash: Hash
 }
 
 export async function changeOwnership(
@@ -31,8 +32,7 @@ export async function changeOwnership(
   txParams?: TxParams,
 ): Promise<ChangeOwnershipReturnType> {
   logger("changeOwnership %o", data)
-  const txData = opsToTxData({ ownershipChanges: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt } = await sendArkivTransaction(client, { ownershipChanges: [data] }, txParams)
 
   logger("Receipt from changeOwnership %o", receipt)