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

package/src/actions/advanced/advanced.test.ts

@@ -0,0 +1,258 @@
+import { describe, expect, it, vi } from "bun:test"
+import {
+  encodeAbiParameters,
+  encodeEventTopics,
+  type Hex,
+  parseAbiParameters,
+  type TransactionReceipt,
+  TransactionReceiptNotFoundError,
+} from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import { ARKIV_ADDRESS } from "../../consts"
+import { ENTITY_EVENTS_ABI } from "../../entity/events"
+import { ExpirationTime } from "../../utils/expirationTime"
+import { buildMutation } from "./buildMutation"
+import { decodeMutationResult, getMutationResult } from "./getMutationResult"
+import { pingTransaction } from "./pingTransaction"
+import { sendMutation } from "./sendMutation"
+
+const ENTITY_KEY = `0x${"ab".repeat(32)}` as const
+const OWNER = "0x1111111111111111111111111111111111111111"
+const NEW_OWNER = "0x2222222222222222222222222222222222222222"
+const TX_HASH = `0x${"cd".repeat(32)}` as const
+
+const CREATE = {
+  payload: new Uint8Array([1, 2, 3]),
+  contentType: "application/json",
+  expires: ExpirationTime.atBlock(1_000_000n),
+}
+
+function makeWalletClient() {
+  const writeContract = vi.fn().mockResolvedValue(TX_HASH)
+  const getBlockNumber = vi.fn().mockResolvedValue(100n)
+  const waitForTransactionReceipt = vi.fn()
+  const simulateContract = vi.fn()
+  return {
+    client: {
+      account: { address: OWNER },
+      chain: { id: 1 },
+      getBlockNumber,
+      writeContract,
+      waitForTransactionReceipt,
+      simulateContract,
+    } as unknown as ArkivClient,
+    writeContract,
+    getBlockNumber,
+    waitForTransactionReceipt,
+    simulateContract,
+  }
+}
+
+function makeReceiptClient(receiptOrError: TransactionReceipt | Error) {
+  const getTransactionReceipt =
+    receiptOrError instanceof Error
+      ? vi.fn().mockRejectedValue(receiptOrError)
+      : vi.fn().mockResolvedValue(receiptOrError)
+  return {
+    client: { getTransactionReceipt } as unknown as ArkivClient,
+    getTransactionReceipt,
+  }
+}
+
+/** A receipt log as the engine emits it: topics for the indexed args, data for the rest. */
+function entityLog(
+  eventName: (typeof ENTITY_EVENTS_ABI)[number]["name"],
+  args: Record<string, unknown>,
+  data: Hex = "0x",
+  address: string = ARKIV_ADDRESS,
+) {
+  return {
+    address,
+    topics: encodeEventTopics({ abi: ENTITY_EVENTS_ABI, eventName, args } as never),
+    data,
+  }
+}
+
+function receiptWith(logs: unknown[], status: "success" | "reverted" = "success") {
+  return {
+    status,
+    transactionHash: TX_HASH,
+    blockNumber: 123n,
+    logs,
+  } as unknown as TransactionReceipt
+}
+
+describe("buildMutation", () => {
+  it("spends no RPC call when every expiry is an absolute block", async () => {
+    const { client, getBlockNumber } = makeWalletClient()
+    const built = await buildMutation(client, {
+      creates: [CREATE],
+      extensions: [{ entityKey: ENTITY_KEY, expires: ExpirationTime.atBlock(2_000_000n) }],
+    })
+    expect(getBlockNumber).not.toHaveBeenCalled()
+    expect(built.operations).toHaveLength(2)
+    expect(built.to).toBe(ARKIV_ADDRESS)
+    expect(built.data.startsWith("0x")).toBe(true)
+    expect(built.expected).toEqual({
+      creates: 1,
+      patches: 0,
+      deletes: 0,
+      extensions: 1,
+      ownershipChanges: 0,
+    })
+  })
+
+  it("fetches the head once for a relative lifetime, and not at all when it is supplied", async () => {
+    const { client, getBlockNumber } = makeWalletClient()
+    const relative = { ...CREATE, expires: ExpirationTime.fromDays(1) }
+
+    await buildMutation(client, { creates: [relative] })
+    expect(getBlockNumber).toHaveBeenCalledTimes(1)
+
+    getBlockNumber.mockClear()
+    await buildMutation(client, { creates: [relative] }, { currentBlock: 100n })
+    expect(getBlockNumber).not.toHaveBeenCalled()
+  })
+
+  it("needs no head for batches without expiries at all", async () => {
+    const { client, getBlockNumber } = makeWalletClient()
+    const built = await buildMutation(client, {
+      deletes: [{ entityKey: ENTITY_KEY }],
+      ownershipChanges: [{ entityKey: ENTITY_KEY, newOwner: NEW_OWNER }],
+    })
+    expect(getBlockNumber).not.toHaveBeenCalled()
+    expect(built.operations).toHaveLength(2)
+  })
+
+  it("still rejects an empty batch locally", async () => {
+    const { client } = makeWalletClient()
+    await expect(buildMutation(client, {})).rejects.toThrow(/No operations/)
+  })
+})
+
+describe("sendMutation", () => {
+  it("submits once and never waits, polls or simulates", async () => {
+    const { client, writeContract, waitForTransactionReceipt, simulateContract, getBlockNumber } =
+      makeWalletClient()
+    const { txHash, expected } = await sendMutation(client, { creates: [CREATE] })
+
+    expect(txHash).toBe(TX_HASH)
+    expect(expected.creates).toBe(1)
+    expect(writeContract).toHaveBeenCalledTimes(1)
+    // The whole point of the advanced path: nothing beyond the submission itself.
+    expect(getBlockNumber).not.toHaveBeenCalled()
+    expect(waitForTransactionReceipt).not.toHaveBeenCalled()
+    expect(simulateContract).not.toHaveBeenCalled()
+  })
+
+  it("forwards txParams so viem has nothing left to look up", async () => {
+    const { client, writeContract } = makeWalletClient()
+    await sendMutation(
+      client,
+      { deletes: [{ entityKey: ENTITY_KEY }] },
+      { txParams: { nonce: 7, gas: 1_000_000n, gasPrice: 2n } },
+    )
+    const call = writeContract.mock.calls[0][0]
+    expect(call.nonce).toBe(7)
+    expect(call.gas).toBe(1_000_000n)
+    expect(call.gasPrice).toBe(2n)
+  })
+
+  it("requires an account and a chain", async () => {
+    const { client } = makeWalletClient()
+    const noAccount = { ...(client as object), account: undefined } as unknown as ArkivClient
+    await expect(sendMutation(noAccount, { creates: [CREATE] })).rejects.toThrow(/Account/)
+  })
+})
+
+describe("pingTransaction", () => {
+  it("reports pending instead of throwing when the receipt is not there yet", async () => {
+    const { client, getTransactionReceipt } = makeReceiptClient(
+      new TransactionReceiptNotFoundError({ hash: TX_HASH }),
+    )
+    expect(await pingTransaction(client, TX_HASH)).toEqual({ status: "pending" })
+    expect(getTransactionReceipt).toHaveBeenCalledTimes(1)
+  })
+
+  it("reports a mined transaction with its block", async () => {
+    const { client } = makeReceiptClient(receiptWith([]))
+    expect(await pingTransaction(client, TX_HASH)).toEqual({ status: "success", blockNumber: 123n })
+  })
+
+  it("reports a reverted transaction as reverted, not as an error", async () => {
+    const { client } = makeReceiptClient(receiptWith([], "reverted"))
+    expect(await pingTransaction(client, TX_HASH)).toEqual({
+      status: "reverted",
+      blockNumber: 123n,
+    })
+  })
+
+  it("lets transport errors through untouched", async () => {
+    const { client } = makeReceiptClient(new Error("connection refused"))
+    await expect(pingTransaction(client, TX_HASH)).rejects.toThrow(/connection refused/)
+  })
+})
+
+describe("getMutationResult and decodeMutationResult", () => {
+  const createdData = encodeAbiParameters(parseAbiParameters("uint64, uint8"), [555n, 0])
+  const extendedData = encodeAbiParameters(parseAbiParameters("uint64"), [999n])
+  const fullReceipt = receiptWith([
+    entityLog("EntityCreated", { entityKey: ENTITY_KEY, owner: OWNER }, createdData),
+    entityLog("EntityPatched", { entityKey: ENTITY_KEY, owner: OWNER }),
+    entityLog("EntityDeleted", { entityKey: ENTITY_KEY, owner: OWNER }),
+    entityLog("ExpiryExtended", { entityKey: ENTITY_KEY, owner: OWNER }, extendedData),
+    entityLog("OwnershipTransferred", {
+      entityKey: ENTITY_KEY,
+      previousOwner: OWNER,
+      newOwner: NEW_OWNER,
+    }),
+  ])
+
+  it("turns one receipt fetch into the full decoded result", async () => {
+    const { client, getTransactionReceipt } = makeReceiptClient(fullReceipt)
+    const result = await getMutationResult(client, TX_HASH)
+
+    expect(getTransactionReceipt).toHaveBeenCalledTimes(1)
+    if (result.status === "pending") throw new Error("expected a mined result")
+    expect(result.txHash).toBe(TX_HASH)
+    expect(result.blockNumber).toBe(123n)
+    expect(result.createdEntities).toEqual([ENTITY_KEY])
+    expect(result.createdExpiries).toEqual([555n])
+    expect(result.patchedEntities).toEqual([ENTITY_KEY])
+    expect(result.deletedEntities).toEqual([ENTITY_KEY])
+    expect(result.extendedEntities).toEqual([ENTITY_KEY])
+    expect(result.extendedExpiries).toEqual([999n])
+    expect(result.ownershipChanges).toEqual([ENTITY_KEY])
+    expect(result.receipt).toBe(fullReceipt)
+  })
+
+  it("reports pending before the transaction is mined", async () => {
+    const { client } = makeReceiptClient(new TransactionReceiptNotFoundError({ hash: TX_HASH }))
+    expect(await getMutationResult(client, TX_HASH)).toEqual({ status: "pending" })
+  })
+
+  it("decodes a held receipt with zero RPC calls", () => {
+    const result = decodeMutationResult(fullReceipt)
+    expect(result.status).toBe("success")
+    expect(result.createdEntities).toEqual([ENTITY_KEY])
+  })
+
+  it("skips logs from other contracts and events it has no name for", () => {
+    const foreign = entityLog(
+      "EntityCreated",
+      { entityKey: ENTITY_KEY, owner: OWNER },
+      createdData,
+      "0x9999999999999999999999999999999999999999",
+    )
+    const unknown = { address: ARKIV_ADDRESS, topics: [`0x${"ff".repeat(32)}`], data: "0x" }
+    const result = decodeMutationResult(receiptWith([foreign, unknown]))
+    expect(result.createdEntities).toEqual([])
+  })
+
+  it("is lenient: a reverted receipt decodes to empty arrays, never an error", () => {
+    const result = decodeMutationResult(receiptWith([], "reverted"))
+    expect(result.status).toBe("reverted")
+    expect(result.createdEntities).toEqual([])
+    expect(result.deletedEntities).toEqual([])
+  })
+})

package/src/actions/advanced/buildMutation.ts

@@ -0,0 +1,104 @@
+import { type Address, encodeFunctionData, type Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { PublicArkivClient } from "../../clients/createPublicClient"
+import { ARKIV_ADDRESS } from "../../consts"
+import { EXECUTE_ABI, type Operation } from "../../entity/operations"
+import {
+  buildEntityOperations,
+  type EntityMutationOps,
+  mutationNeedsBlockNumber,
+} from "../../utils/arkivTransactions"
+import { getLogger } from "../../utils/logger"
+
+const logger = getLogger("actions:advanced:build-mutation")
+
+/** Options for the advanced-path builders ({@link buildMutation}, {@link sendMutation}). */
+export type BuildMutationOptions = {
+  /**
+   * The chain head to resolve relative expiries against.
+   *
+   * Pass a block number you already hold — from a previous call, `getBlockTiming()`, or your own
+   * tracking — and the build spends no RPC call at all. Without it, one `eth_blockNumber` is made,
+   * and only when the batch actually needs the head (a relative lifetime or a `Date` deadline);
+   * purely absolute `atBlock(n)` expiries never trigger it.
+   *
+   * Supplying it also buys back a check: absolute expiries are validated against it, so an
+   * `atBlock(n)` already in the past throws {@link InvalidExpiryError} locally instead of
+   * reverting on-chain. When the head is neither supplied nor fetched, that dead-on-arrival
+   * check is skipped — the one local validation of the everyday path this path trades away.
+   */
+  currentBlock?: bigint
+}
+
+/** What {@link buildMutation} hands back: the batch in every form a sender might want. */
+export type BuildMutationReturnType = {
+  /** The encoded batch, in engine order, for `writeContract`-style sends. */
+  operations: Operation[]
+  /** The Arkiv engine address the transaction must be sent to. */
+  to: Address
+  /**
+   * The full `execute(operations)` calldata. Sign a transaction carrying it offline (with your own
+   * nonce, gas and fees) and the whole mutation costs exactly one `eth_sendRawTransaction`.
+   */
+  data: Hex
+  /**
+   * How many operations of each kind went into the batch — which is how many events of each kind a
+   * successful transaction emits, in batch order, for cross-checking a decoded result.
+   */
+  expected: {
+    creates: number
+    patches: number
+    deletes: number
+    extensions: number
+    ownershipChanges: number
+  }
+}
+
+/**
+ * Encodes a mutation batch without sending anything.
+ *
+ * This is the first step of the advanced path: it performs only local validation and encoding, so
+ * it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
+ * and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
+ * to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
+ *
+ * One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
+ * locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
+ * expiry encodes cleanly and the engine reverts it on-chain — see
+ * {@link BuildMutationOptions.currentBlock}.
+ *
+ * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
+ * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+ * @throws {EmptyPatchError} If a patch has nothing to apply.
+ */
+export async function buildMutation(
+  client: ArkivClient,
+  data: EntityMutationOps,
+  options: BuildMutationOptions = {},
+): Promise<BuildMutationReturnType> {
+  // The head is fetched only when an expiry is actually measured from it and the caller did not
+  // supply one — the advanced path never spends an RPC call it can avoid.
+  const currentBlock =
+    options.currentBlock ??
+    (mutationNeedsBlockNumber(data)
+      ? // Every SDK-built client carries viem's `publicActions`; `PublicArkivClient` is the type
+        // that says so, the same narrowing `sendArkivTransaction` does to `WalletArkivClient`.
+        await (client as PublicArkivClient).getBlockNumber()
+      : 0n)
+
+  const operations = buildEntityOperations(data, { currentBlock })
+  logger("Built %d operations at block %d", operations.length, currentBlock)
+
+  return {
+    operations,
+    to: ARKIV_ADDRESS,
+    data: encodeFunctionData({ abi: EXECUTE_ABI, functionName: "execute", args: [operations] }),
+    expected: {
+      creates: data.creates?.length ?? 0,
+      patches: data.patches?.length ?? 0,
+      deletes: data.deletes?.length ?? 0,
+      extensions: data.extensions?.length ?? 0,
+      ownershipChanges: data.ownershipChanges?.length ?? 0,
+    },
+  }
+}

package/src/actions/advanced/getMutationResult.ts

@@ -0,0 +1,112 @@
+import { type Hash, type Hex, type TransactionReceipt, TransactionReceiptNotFoundError } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { PublicArkivClient } from "../../clients/createPublicClient"
+import { collectMutationEvents } from "../../utils/arkivTransactions"
+import { getLogger } from "../../utils/logger"
+
+const logger = getLogger("actions:advanced:get-mutation-result")
+
+/**
+ * A mined mutation, decoded from its receipt alone.
+ *
+ * Everything here comes out of the events the batch emitted, so no request context is needed to
+ * read it — a process that holds nothing but the transaction hash gets the full picture. Arrays
+ * are in batch order, which is the order the operations were applied in.
+ */
+export type MutationResult = {
+  /** `success` means the whole batch applied; `reverted` means none of it did (arrays are empty). */
+  status: "success" | "reverted"
+  /** The transaction hash. */
+  txHash: Hash
+  /** The block the transaction landed in. */
+  blockNumber: bigint
+  /** The keys the engine minted for the created entities, in batch order. */
+  createdEntities: Hex[]
+  /** The block each created entity expires at, as the engine recorded it, in the same order. */
+  createdExpiries: bigint[]
+  /** The keys of the patched entities. */
+  patchedEntities: Hex[]
+  /** The keys of the deleted entities. */
+  deletedEntities: Hex[]
+  /** The keys of the extended entities. */
+  extendedEntities: Hex[]
+  /** The block each extended entity now expires at, in the same order. */
+  extendedExpiries: bigint[]
+  /** The keys of the entities handed to a new owner. */
+  ownershipChanges: Hex[]
+  /** The raw receipt, so nothing the chain said is lost. */
+  receipt: TransactionReceipt
+}
+
+/** Return type for {@link getMutationResult}: the decoded result, or still pending. */
+export type GetMutationResultReturnType = MutationResult | { status: "pending" }
+
+/**
+ * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
+ *
+ * The pure tail of the advanced path: if a receipt reached you some other way — your own
+ * `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
+ * expiries without touching the network. Lenient by design: it reports what the events say,
+ * without counting them against a request it never saw.
+ */
+export function decodeMutationResult(receipt: TransactionReceipt): MutationResult {
+  const events = collectMutationEvents(receipt.logs)
+  return {
+    status: receipt.status,
+    txHash: receipt.transactionHash,
+    blockNumber: receipt.blockNumber,
+    createdEntities: events.created.map((e) => e.entityKey),
+    createdExpiries: events.created.map((e) => e.expiresAt),
+    patchedEntities: events.patched.map((e) => e.entityKey),
+    deletedEntities: events.deleted.map((e) => e.entityKey),
+    extendedEntities: events.extended.map((e) => e.entityKey),
+    extendedExpiries: events.extended.map((e) => e.expiresAt),
+    ownershipChanges: events.ownershipTransferred.map((e) => e.entityKey),
+    receipt,
+  }
+}
+
+/**
+ * Fetches a transaction's receipt — once — and decodes what the mutation did.
+ *
+ * Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
+ * decoded entity events as well: created keys, recorded expiries, and the keys of everything
+ * patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
+ * `{ status: "pending" }` — check `status` before reading the rest.
+ *
+ * No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
+ * spending a `simulateContract` on the why is your call, not the SDK's.
+ */
+export async function getMutationResult(
+  client: ArkivClient,
+  txHash: Hash,
+): Promise<GetMutationResultReturnType> {
+  const receipt = await fetchReceipt(client, txHash)
+  if (receipt === undefined) {
+    logger("Tx %s still pending", txHash)
+    return { status: "pending" }
+  }
+  return decodeMutationResult(receipt)
+}
+
+/**
+ * One `eth_getTransactionReceipt`, with "not there yet" as a value instead of an exception.
+ *
+ * Internal seam shared with `pingTransaction`; not part of the package's public surface.
+ */
+export async function fetchReceipt(
+  client: ArkivClient,
+  txHash: Hash,
+): Promise<TransactionReceipt | undefined> {
+  // The one action this needs is on every SDK-built client — both factories extend viem's
+  // `publicActions` — and `PublicArkivClient` is the type that says so, the same way
+  // `sendArkivTransaction` narrows to `WalletArkivClient`.
+  const reader = client as PublicArkivClient
+  try {
+    return await reader.getTransactionReceipt({ hash: txHash })
+  } catch (error) {
+    // viem models an unmined transaction as a throw; the advanced path models it as a state.
+    if (error instanceof TransactionReceiptNotFoundError) return undefined
+    throw error
+  }
+}

package/src/actions/advanced/index.ts

@@ -0,0 +1,21 @@
+/**
+ * The advanced path: send, ping and read results as separate, single-RPC-call steps.
+ *
+ * The everyday actions (`createEntity`, `mutateEntities`, …) bundle send + wait + decode into one
+ * call, which is convenient and spends several RPC requests. These actions unbundle that so a
+ * caller can hit the theoretical minimum:
+ *
+ * 1. {@link buildMutation} — encode locally (0 RPC calls with `currentBlock` supplied)
+ * 2. {@link sendMutation} — submit and return the hash (1 call with full `txParams`)
+ * 3. {@link pingTransaction} — one `eth_getTransactionReceipt`, on your schedule
+ * 4. {@link getMutationResult} / {@link decodeMutationResult} — the same single call (or none)
+ *    turned into entity keys and expiries
+ */
+export type { BuildMutationOptions, BuildMutationReturnType } from "./buildMutation"
+export { buildMutation } from "./buildMutation"
+export type { GetMutationResultReturnType, MutationResult } from "./getMutationResult"
+export { decodeMutationResult, getMutationResult } from "./getMutationResult"
+export type { PingTransactionReturnType } from "./pingTransaction"
+export { pingTransaction } from "./pingTransaction"
+export type { SendMutationOptions, SendMutationReturnType } from "./sendMutation"
+export { sendMutation } from "./sendMutation"

package/src/actions/advanced/pingTransaction.ts

@@ -0,0 +1,43 @@
+import type { Hash } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import { getLogger } from "../../utils/logger"
+import { fetchReceipt } from "./getMutationResult"
+
+const logger = getLogger("actions:advanced:ping-transaction")
+
+/** Return type for {@link pingTransaction}. */
+export type PingTransactionReturnType =
+  | {
+      /** Not mined yet (or unknown to this node). Ping again later. */
+      status: "pending"
+      blockNumber?: undefined
+    }
+  | {
+      /** Mined. `success` means the whole batch applied; `reverted` means none of it did. */
+      status: "success" | "reverted"
+      /** The block the transaction landed in. */
+      blockNumber: bigint
+    }
+
+/**
+ * Asks the chain — once — whether a transaction has landed.
+ *
+ * Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
+ * back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
+ * path — you own the schedule, the SDK owns nothing.
+ *
+ * When it reports `success` and you need the created keys or recorded expiries, spend the next
+ * call on `getMutationResult` — or none at all, if you predicted the keys up front with
+ * `predictEntityKeys`.
+ */
+export async function pingTransaction(
+  client: ArkivClient,
+  txHash: Hash,
+): Promise<PingTransactionReturnType> {
+  const receipt = await fetchReceipt(client, txHash)
+  if (receipt === undefined) {
+    logger("Tx %s still pending", txHash)
+    return { status: "pending" }
+  }
+  return { status: receipt.status, blockNumber: receipt.blockNumber }
+}

package/src/actions/advanced/sendMutation.ts

@@ -0,0 +1,59 @@
+import type { Hash } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { TxParams } from "../../types"
+import { type EntityMutationOps, submitMutation } from "../../utils/arkivTransactions"
+import { getLogger } from "../../utils/logger"
+import {
+  type BuildMutationOptions,
+  type BuildMutationReturnType,
+  buildMutation,
+} from "./buildMutation"
+
+const logger = getLogger("actions:advanced:send-mutation")
+
+/** Options for {@link sendMutation}. */
+export type SendMutationOptions = BuildMutationOptions & {
+  /**
+   * Transaction parameters. Supply `nonce`, `gas` and the fee fields and viem has nothing left to
+   * look up — the send collapses to a single `eth_sendRawTransaction`.
+   */
+  txParams?: TxParams
+}
+
+/** Return type for {@link sendMutation}. */
+export type SendMutationReturnType = {
+  /** The transaction hash. Poll it with `pingTransaction` / fetch it with `getMutationResult`. */
+  txHash: Hash
+  /** The per-kind operation counts of the batch that was sent, for cross-checking the result. */
+  expected: BuildMutationReturnType["expected"]
+}
+
+/**
+ * Signs and sends a mutation batch, returning as soon as the transaction is submitted.
+ *
+ * The fire-and-forget half of the advanced path. Unlike `mutateEntities`, this does **not** wait
+ * for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
+ * costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
+ * RPC call; each omitted piece adds only the lookup viem needs to fill it.
+ *
+ * Follow up separately, on your own schedule:
+ * - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
+ * - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
+ *
+ * @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
+ * the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
+ * Anything after that — inclusion, success — is yours to check.
+ */
+export async function sendMutation(
+  client: ArkivClient,
+  data: EntityMutationOps,
+  options: SendMutationOptions = {},
+): Promise<SendMutationReturnType> {
+  const { operations, expected } = await buildMutation(client, data, options)
+
+  logger("Sending execute with %d operations (no wait)", operations.length)
+
+  const txHash = await submitMutation(client, operations, options.txParams)
+
+  return { txHash, expected }
+}

package/src/actions/public/getEntity.ts

@@ -1,50 +1,34 @@
-import { bytesToHex, type Hex, hexToBytes } from "viem"
+import type { Hex } from "viem"
+import { key } from "../../attr"
 import type { ArkivClient } from "../../clients/baseClient"
 import { NoEntityFoundError } from "../../errors"
-import { entityFromRpcResult } from "../../utils/entities"
+import { runQuery } from "../../query/engine"
+import { eq } from "../../query/expression"
+import { type FullEntity, toRpcSelect } from "../../query/selection"
 
-export async function getEntity(client: ArkivClient, key: Hex) {
-  // Normalize the key into bytes
-  let bytes: Uint8Array
-  try {
-    bytes = hexToBytes(key)
-  } catch {
-    throw new Error(`Invalid key format: ${key}. Key must be a valid hex string.`)
-  }
-
-  if (bytes.length !== 32) {
-    throw new Error(
-      `Invalid key length: ${bytes.length} bytes. Key must be 32 bytes (64 hex characters) long.`,
-    )
-  }
-
-  const hexKey = bytesToHex(bytes)
-
-  const result = await client.request({
-    method: "arkiv_query",
-    params: [
-      `$key = ${hexKey}`,
-      {
-        includeData: {
-          key: true,
-          attributes: true,
-          payload: true,
-          contentType: true,
-          expiration: true,
-          owner: true,
-          creator: true,
-          createdAtBlock: true,
-          lastModifiedAtBlock: true,
-          transactionIndexInBlock: true,
-          operationIndexInTransaction: true,
-        },
-      },
-    ],
+/**
+ * Reads one entity by key, with every field selected.
+ *
+ * Returns a {@link FullEntity} rather than an {@link Entity}: the selection is fixed at `"*"`, so
+ * every field is populated and none of them needs a `?` at the call site. The bare `Entity` type
+ * has every field optional because a `select()` result carries only what it asked for.
+ *
+ * @throws {InvalidValueError} If the key is not 32 bytes.
+ * @throws {NoEntityFoundError} If no live entity has that key — it never existed, or it was
+ * deleted or has expired.
+ */
+export async function getEntity(client: ArkivClient, entityKey: Hex): Promise<FullEntity> {
+  const { entities } = await runQuery(client, {
+    query: eq("$key", key(entityKey)).toString(),
+    select: toRpcSelect("*"),
+    limit: 1,
   })
 
-  if (!result.data.length) {
-    throw new NoEntityFoundError()
+  const entity = entities[0]
+  if (entity === undefined) {
+    throw new NoEntityFoundError(entityKey)
   }
-
-  return await entityFromRpcResult(result.data[0])
+  // Every field was selected, so the runtime Entity carries them all; the cast is the same
+  // narrowing `client.select("*")` gets from its own inference.
+  return entity as unknown as FullEntity
 }