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

package/src/utils/arkivTransactions.ts

@@ -2,31 +2,41 @@ import {
   type Address,
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
-  encodePacked,
+  decodeEventLog,
+  type Hash,
   type Hex,
-  keccak256,
   parseAbi,
-  stringToBytes,
   TransactionExecutionError,
   type TransactionReceipt,
-  toBytes,
-  toHex,
 } from "viem"
 import type { ChangeOwnershipParameters } from "../actions/wallet/changeOwnership"
 import type { CreateEntityParameters } from "../actions/wallet/createEntity"
 import type { DeleteEntityParameters } from "../actions/wallet/deleteEntity"
 import type { ExtendEntityParameters } from "../actions/wallet/extendEntity"
-import type { UpdateEntityParameters } from "../actions/wallet/updateEntity"
+import type { PatchEntityParameters } from "../actions/wallet/patchEntity"
+// Internal seam: the ABI encoders are not part of the package's public surface.
+import { encodeAttributes, encodeMutations } from "../attr/attributes"
 import type { ArkivClient } from "../clients/baseClient"
 import type { WalletArkivClient } from "../clients/createWalletClient"
-import { ARKIV_ADDRESS, BLOCK_TIME } from "../consts"
-import { DuplicateAttributeError, EntityMutationError, InvalidContentTypeError } from "../errors"
+import { ARKIV_ADDRESS } from "../consts"
+import { ENTITY_EVENTS_ABI } from "../entity/events"
+import { type Expiry, type ExpiryContext, resolveExpiry } from "../entity/expiry"
+import { encodeCreationFlags } from "../entity/flags"
+import { randomSalt, validateSalt } from "../entity/key"
+import {
+  createOperation,
+  deleteOperation,
+  EXECUTE_ABI as EXECUTE_FUNCTION_ABI,
+  extendExpiryOperation,
+  type Operation,
+  patchOperation,
+  transferOwnershipOperation,
+} from "../entity/operations"
+import { EmptyPatchError, EntityMutationError, InvalidContentTypeError } from "../errors"
 import type { TxParams } from "../types"
-import { EntityOperationType } from "../types/entity"
-import { RpcAttributeValueType as AttributeValueType } from "../types/rpcSchema"
 
 import { getLogger } from "./logger"
-import { isEntityKey, validateAttribute, validateExpiresIn } from "./validation"
+import { describeEntityRevert } from "./revert"
 
 const logger = getLogger("utils:arkiv-transactions")
 
@@ -39,229 +49,75 @@ function validateContentType(contentType: string): void {
   }
 }
 
-// Mime128 = struct { bytes32[4] data }  (128-byte fixed MIME type container)
-// Attribute = struct { bytes32 name, uint8 valueType, bytes32[4] value }
-// BlockNumber = type BlockNumber is uint32
-export const ENTITY_EXECUTE_ABI = parseAbi([
-  "function execute((uint8 operationType, bytes32 entityKey, bytes payload, (bytes32[4] data) contentType, (bytes32 name, uint8 valueType, bytes32[4] value)[] attributes, uint32 expiresIn, address newOwner)[] ops) external",
-])
-
-export const ENTITY_OPERATION_EVENT_ABI = parseAbi([
-  "event EntityOperation(bytes32 indexed entityKey, uint8 indexed operationType, address indexed owner, uint32 expiresAt, bytes32 entityHash)",
-])
-
 export const ENTITY_ERRORS_ABI = parseAbi([
+  // Batch and operation framing.
   "error EmptyBatch()",
+  "error InvalidOpType(uint8 operation)",
+  "error NonCanonicalOperationData(uint8 operation)",
+  // The attribute triple list, structural.
   "error AttributesNotSorted()",
-  "error InvalidValueType(bytes32 name, uint8 valueType)",
-  "error InvalidOpType(uint8 operationType)",
-  "error ExpiryInPast(uint32 expiresAt, uint32 currentBlock)",
   "error TooManyAttributes(uint256 count, uint256 maxCount)",
+  "error EmptyMutations(bytes32 entityKey)",
+  "error TombstoneInCreate(bytes32 name)",
+  "error TombstoneValueNotEmpty(bytes32 name)",
+  "error SystemAttributeNotWritable(bytes32 name)",
+  "error InvalidValueType(bytes32 name, uint8 typeId)",
+  // Attribute-name validation. `Ident32` is a bytes32 on the wire.
+  "error Ident32Empty()",
+  "error Ident32InvalidByte(uint256 position, bytes1 value)",
+  // Entity state and authorisation.
   "error EntityNotFound(bytes32 entityKey)",
+  "error EntityExpired(bytes32 entityKey, uint64 expiresAt)",
   "error NotOwner(bytes32 entityKey, address caller, address owner)",
-  "error EntityExpired(bytes32 entityKey, uint32 expiresAt)",
-  "error ExpiryNotExtended(bytes32 entityKey, uint32 newExpiresAt, uint32 currentExpiresAt)",
+  "error ReadOnlyEntity(bytes32 entityKey)",
+  "error ReservedCreationFlags(uint8 creationFlags)",
+  // Expiry. The engine bounds an expiry only by the width of the field and by liveness — there is
+  // no MAX_EXPIRES_AT or MAX_LIFETIME, so there is no error for exceeding one.
+  "error ExpiryDeadOnArrival(uint64 target, uint64 currentBlock)",
+  "error ExpiryNotExtended(bytes32 entityKey, uint64 newExpiresAt, uint64 currentExpiresAt)",
+  // Ownership transfer.
   "error TransferToZeroAddress(bytes32 entityKey)",
   "error TransferToSelf(bytes32 entityKey)",
-  "error EntityNotExpired(bytes32 entityKey, uint32 expiresAt)",
-  "error Ident32Empty()",
-  "error Ident32TooLong(uint256 length)",
-  "error Ident32InvalidByte(uint256 position, bytes1 value)",
-  "error MimeEmpty()",
-  "error MimeTooLong(uint256 length, uint256 maxLength)",
-  "error MimeInvalidByte(uint256 position, bytes1 value)",
-  "error MimeIncomplete()",
 ])
 
-const EXECUTE_ABI = [...ENTITY_EXECUTE_ABI, ...ENTITY_ERRORS_ABI]
-
-const ENTITY_NONCE_ABI = parseAbi(["function nonces(address owner) view returns (uint32)"])
-
-const ZERO_ADDRESS: Address = "0x0000000000000000000000000000000000000000"
-const ZERO_32 = `0x${"00".repeat(32)}` as Hex
-const EMPTY_BYTES128 = [ZERO_32, ZERO_32, ZERO_32, ZERO_32] as const
-
-// Encode a string or bytes into a bytes32[4] (128-byte) container, left-aligned.
-function encodeBytes128(data: Uint8Array): readonly [Hex, Hex, Hex, Hex] {
-  const padded = new Uint8Array(128)
-  padded.set(data.slice(0, 128))
-  return [
-    toHex(padded.slice(0, 32)),
-    toHex(padded.slice(32, 64)),
-    toHex(padded.slice(64, 96)),
-    toHex(padded.slice(96, 128)),
-  ]
-}
-
-// Mime128 struct: bytes32[4] data, string packed left-aligned into 128 bytes.
-function encodeMime128(contentType: string): { data: readonly [Hex, Hex, Hex, Hex] } {
-  return { data: contentType ? encodeBytes128(stringToBytes(contentType)) : EMPTY_BYTES128 }
-}
-
-function encodeAttribute(attr: { key: string; value: Hex | string | number }) {
-  validateAttribute(attr)
-  const name = toHex(attr.key, { size: 32 })
-
-  if (typeof attr.value === "string") {
-    // Only exact 32-byte hex (an entity key) gets the EntityKey type; shorter or
-    // longer hex-looking strings are stored as plain strings so they round-trip
-    // unchanged and stay matchable by quoted string queries.
-    if (isEntityKey(attr.value)) {
-      return {
-        name,
-        valueType: AttributeValueType.EntityKey,
-        value: [toHex(toBytes(attr.value), { size: 32 }), ZERO_32, ZERO_32, ZERO_32] as const,
-      }
-    }
-    return {
-      name,
-      valueType: AttributeValueType.String,
-      // stringToBytes, not toBytes: toBytes hex-decodes hex-looking strings, which
-      // would corrupt string values like "0xab" instead of UTF-8 encoding them
-      value: encodeBytes128(stringToBytes(attr.value)),
-    }
-  }
-
-  return {
-    name,
-    valueType: AttributeValueType.Uint,
-    value: [toHex(BigInt(attr.value), { size: 32 }), ZERO_32, ZERO_32, ZERO_32] as const,
-  }
-}
-
-// The registry requires attributes strictly ascending by their bytes32 name — the
-// canonical serialization hashes into the state root, and strict ordering doubles as
-// the uniqueness check (AttributesNotSorted). Sort here so callers can pass any order;
-// duplicates would revert on-chain, so reject them client-side with a clear error.
-function encodeAttributes(attrs: { key: string; value: Hex | string | number }[]) {
-  const encoded = attrs
-    .map((attr) => ({ key: attr.key, ...encodeAttribute(attr) }))
-    .sort((a, b) => (a.name < b.name ? -1 : a.name > b.name ? 1 : 0))
-  for (let i = 1; i < encoded.length; i++) {
-    if (encoded[i].name === encoded[i - 1].name) {
-      throw new DuplicateAttributeError(encoded[i].key)
-    }
-  }
-  return encoded.map(({ key: _, ...attr }) => attr)
-}
-
-function toBTL(expiresIn: number): number {
-  validateExpiresIn(expiresIn)
-  return Math.ceil(expiresIn / BLOCK_TIME)
-}
-
-// entityKey = keccak256(chainId || registryAddress || ownerAddress || nonce)
-function deriveEntityKey(chainId: number, owner: Address, nonce: bigint): Hex {
-  return keccak256(
-    encodePacked(
-      ["uint256", "address", "address", "uint32"],
-      [BigInt(chainId), ARKIV_ADDRESS, owner, Number(nonce)],
-    ),
-  )
-}
+const EXECUTE_ABI = [...EXECUTE_FUNCTION_ABI, ...ENTITY_ERRORS_ABI]
 
 export type SendArkivTransactionResult = {
   receipt: TransactionReceipt
+  /** The keys the engine minted for the entities this transaction created, in batch order. */
   createdEntityKeys: Hex[]
+  /** The block each created entity expires at, as the engine recorded it, in the same order. */
+  createdExpiries: bigint[]
+  /** The block each extended entity now expires at, as the engine recorded it, in batch order. */
+  extendedExpiries: bigint[]
 }
 
 export async function sendArkivTransaction(
   client: ArkivClient,
-  ops: {
-    creates?: CreateEntityParameters[]
-    updates?: UpdateEntityParameters[]
-    deletes?: DeleteEntityParameters[]
-    extensions?: ExtendEntityParameters[]
-    ownershipChanges?: ChangeOwnershipParameters[]
-  },
+  ops: EntityMutationOps,
   txParams?: TxParams,
 ): Promise<SendArkivTransactionResult> {
   if (!client.account) throw new Error("Account required")
   if (!client.chain) throw new Error("Chain required")
   const walletClient = client as WalletArkivClient
 
-  const { creates, updates, deletes, extensions, ownershipChanges } = ops
-  const owner = client.account.address as Address
+  const { creates, extensions } = ops
 
-  const ownerNonce: bigint = creates?.length
-    ? BigInt(
-        await walletClient.readContract({
-          address: ARKIV_ADDRESS,
-          abi: ENTITY_NONCE_ABI,
-          functionName: "nonces",
-          args: [owner],
-        }),
-      )
-    : 0n
+  // The block height, to resolve any relative expiry — which both creates and extensions carry.
+  // Skipped entirely for a batch with neither. Deliberately fetched even when every expiry is
+  // absolute (where `mutationNeedsBlockNumber` would say no): the head is what makes the local
+  // dead-on-arrival check in `resolveExpiry` work, and the everyday path buys that check — the
+  // advanced path is where both are traded away for the saved call.
+  const currentBlock =
+    creates?.length || extensions?.length ? await walletClient.getBlockNumber() : 0n
 
-  const createdEntityKeys: Hex[] = (creates ?? []).map((_, i) =>
-    deriveEntityKey(client.chain!.id, owner, ownerNonce + BigInt(i)),
-  )
+  const operations = buildEntityOperations(ops, { currentBlock })
 
-  for (const item of creates ?? []) validateContentType(item.contentType)
-  for (const item of updates ?? []) validateContentType(item.contentType)
-
-  const operations = [
-    ...(creates ?? []).map((item, i) => ({
-      operationType: EntityOperationType.Create,
-      entityKey: createdEntityKeys[i],
-      payload: toHex(item.payload),
-      contentType: encodeMime128(item.contentType),
-      attributes: encodeAttributes(item.attributes),
-      expiresIn: toBTL(item.expiresIn),
-      newOwner: ZERO_ADDRESS,
-    })),
-    ...(updates ?? []).map((item) => ({
-      operationType: EntityOperationType.Update,
-      entityKey: item.entityKey,
-      payload: toHex(item.payload),
-      contentType: encodeMime128(item.contentType),
-      attributes: encodeAttributes(item.attributes),
-      expiresIn: 0, // contract ignores expiresAt on UPDATE
-      newOwner: ZERO_ADDRESS,
-    })),
-    ...(deletes ?? []).map((item) => ({
-      operationType: EntityOperationType.Delete,
-      entityKey: item.entityKey,
-      payload: "0x" as Hex,
-      contentType: encodeMime128(""),
-      attributes: [] as never[],
-      expiresIn: 0,
-      newOwner: ZERO_ADDRESS,
-    })),
-    ...(extensions ?? []).map((item) => ({
-      operationType: EntityOperationType.Extend,
-      entityKey: item.entityKey,
-      payload: "0x" as Hex,
-      contentType: encodeMime128(""),
-      attributes: [] as never[],
-      expiresIn: toBTL(item.expiresIn),
-      newOwner: ZERO_ADDRESS,
-    })),
-    ...(ownershipChanges ?? []).map((item) => ({
-      operationType: EntityOperationType.Transfer,
-      entityKey: item.entityKey,
-      payload: "0x" as Hex,
-      contentType: encodeMime128(""),
-      attributes: [] as never[],
-      expiresIn: 0,
-      newOwner: item.newOwner as Address,
-    })),
-  ]
+  logger("Sending execute with %d operations %o", operations.length, operations)
 
-  logger("Sending execute with %d operations %s", operations.length, JSON.stringify(operations))
+  const txHash = await submitMutation(client, operations, txParams)
 
   try {
-    const txHash = await walletClient.writeContract({
-      address: ARKIV_ADDRESS,
-      abi: EXECUTE_ABI,
-      functionName: "execute",
-      args: [operations],
-      account: client.account,
-      chain: client.chain,
-      ...txParams,
-    })
-
     const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash })
     logger("Tx receipt %o", receipt)
 
@@ -278,7 +134,10 @@ export async function sendArkivTransaction(
       } catch (err) {
         const error = err as { shortMessage?: string; cause?: { details?: string } }
         const reason =
-          error.shortMessage ?? error.cause?.details ?? "No reason provided by backend."
+          describeEntityRevert(err) ??
+          error.shortMessage ??
+          error.cause?.details ??
+          "No reason provided by backend."
         throw new EntityMutationError(
           `Transaction ${receipt.transactionHash} reverted. Reason: ${reason}`,
         )
@@ -288,22 +147,294 @@ export async function sendArkivTransaction(
       )
     }
 
-    return { receipt, createdEntityKeys }
+    return {
+      receipt,
+      ...readAppliedOperations(receipt, {
+        creates: creates?.length ?? 0,
+        extensions: extensions?.length ?? 0,
+      }),
+    }
   } catch (error) {
-    let message = "Transaction failed"
-    if (error instanceof TransactionExecutionError) {
-      message += `: ${error.details}`
-    } else if (error instanceof ContractFunctionExecutionError) {
-      logger("Contract function execution error data:", error.shortMessage)
-      if (error.cause instanceof ContractFunctionRevertedError) {
-        message += `: ${error.cause.message}`
-      } else {
-        message += ": Execution error without revert data"
-      }
-    } else if (error instanceof EntityMutationError) {
-      throw error
+    throw asEntityMutationError(error)
+  }
+}
+
+/**
+ * Wraps whatever a write step threw into an {@link EntityMutationError} — engine terms when the
+ * revert data decodes, the node's own message otherwise. An {@link EntityMutationError} passes
+ * through unchanged, so wrapped steps compose without double-wrapping.
+ */
+function asEntityMutationError(error: unknown): EntityMutationError {
+  if (error instanceof EntityMutationError) return error
+
+  const described = describeEntityRevert(error)
+  if (described !== undefined) {
+    return new EntityMutationError(`Transaction failed: ${described}`, { cause: error })
+  }
+
+  let message = "Transaction failed"
+  if (error instanceof TransactionExecutionError) {
+    message += `: ${error.details}`
+  } else if (error instanceof ContractFunctionExecutionError) {
+    logger("Contract function execution error data:", error.shortMessage)
+    if (error.cause instanceof ContractFunctionRevertedError) {
+      message += `: ${error.cause.message}`
+    } else {
+      message += ": Execution error without revert data"
     }
+  } else if (error instanceof Error) {
+    message += `: ${error.message}`
+  }
+
+  return new EntityMutationError(message, { cause: error })
+}
+
+/**
+ * The keys and expiries the engine recorded, read back from the events the batch emitted.
+ */
+function readAppliedOperations(
+  receipt: TransactionReceipt,
+  expected: { creates: number; extensions: number },
+): Omit<SendArkivTransactionResult, "receipt"> {
+  const events = collectMutationEvents(receipt.logs)
 
-    throw new EntityMutationError(message)
+  const createdEntityKeys = events.created.map((e) => e.entityKey)
+  const createdExpiries = events.created.map((e) => e.expiresAt)
+  const extendedExpiries = events.extended.map((e) => e.expiresAt)
+
+  // Operations apply in batch order and emit one event each, and creates lead the batch — so these
+  // arrive already aligned with the parameters they came from. A count that disagrees means that
+  // assumption broke, and a misaligned array would hand back a key belonging to another entity.
+  assertCount(receipt, "create", createdEntityKeys.length, expected.creates)
+  assertCount(receipt, "extension", extendedExpiries.length, expected.extensions)
+
+  return { createdEntityKeys, createdExpiries, extendedExpiries }
+}
+
+/** One log as an entity event, or `undefined` for anything this SDK has no name for. */
+function decodeEntityLog(log: TransactionReceipt["logs"][number]) {
+  try {
+    return decodeEventLog({ abi: ENTITY_EVENTS_ABI, topics: log.topics, data: log.data })
+  } catch {
+    // An event a newer engine emits and this ABI does not describe. Not this function's business.
+    return undefined
+  }
+}
+
+function assertCount(receipt: TransactionReceipt, what: string, got: number, want: number): void {
+  if (got === want) return
+  // Deliberately explicit that the write succeeded: this throws *after* a successful transaction,
+  // and a caller who reads it as a failure and retries would create the entities a second time.
+  throw new EntityMutationError(
+    `Transaction ${receipt.transactionHash} succeeded — do not retry it — but emitted ${got} ` +
+      `${what} event(s) for ${want} ${what} operation(s). The batch was applied; the SDK cannot ` +
+      `say which entity each operation produced, so read them back to find them.`,
+  )
+}
+
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+// The seams the advanced path is built on.
+//
+// `sendArkivTransaction` above is the everyday path: encode, send, wait, decode, diagnose. These
+// are the same steps as separate pieces, so `actions/advanced` can spend exactly the RPC calls a
+// caller asks for and no more — without a second copy of the encoding or the event decoding.
+// ─────────────────────────────────────────────────────────────────────────────────────────────────
+
+/** The five kinds of entity operation one Arkiv transaction can batch. */
+export type EntityMutationOps = {
+  /** The entities to create. */
+  creates?: CreateEntityParameters[]
+  /** The patches to apply. */
+  patches?: PatchEntityParameters[]
+  /** The entities to delete. */
+  deletes?: DeleteEntityParameters[]
+  /** The expiries to set. */
+  extensions?: ExtendEntityParameters[]
+  /** The ownership transfers to perform. */
+  ownershipChanges?: ChangeOwnershipParameters[]
+}
+
+/**
+ * Whether encoding the batch actually requires the chain head.
+ *
+ * Only a relative lifetime (`minLifetime > 0`) or a wall-clock deadline (a `Date`) is measured
+ * from the current block. A purely absolute `atBlock(n)` expiry encodes the same bytes whatever
+ * the head is, so a batch of those — or one with no expiries at all — needs no `eth_blockNumber`.
+ */
+export function mutationNeedsBlockNumber(ops: EntityMutationOps): boolean {
+  return [...(ops.creates ?? []), ...(ops.extensions ?? [])].some((item) => {
+    const expires = item.expires as Expiry | undefined
+    // Malformed expiries are rejected by buildEntityOperations without needing the head.
+    if (expires === undefined || typeof expires.minLifetime !== "bigint") return false
+    return expires.minLifetime !== 0n || expires.expiresAt instanceof Date
+  })
+}
+
+/**
+ * Encodes a batch into the `execute` operations, in the order the engine applies them: creates,
+ * patches, deletes, extensions, ownership transfers.
+ *
+ * Pure — every check here is local (content types, salts, expiry bounds, non-empty patches and a
+ * non-empty batch), so the only chain input is `context.currentBlock`. Callers that carry no
+ * relative expiry (see {@link mutationNeedsBlockNumber}) can pass `0n`, which disables the
+ * dead-on-arrival pre-check and leaves that to the engine.
+ */
+export function buildEntityOperations(ops: EntityMutationOps, context: ExpiryContext): Operation[] {
+  const { creates, patches, deletes, extensions, ownershipChanges } = ops
+
+  const createOps = (creates ?? []).map((item) => {
+    validateContentType(item.contentType)
+
+    const salt = item.salt === undefined ? randomSalt() : validateSalt(item.salt)
+    const expiry = resolveExpiry(item.expires, context)
+
+    return createOperation({
+      salt,
+      expiry,
+      creationFlags: encodeCreationFlags(item.flags),
+      attributes: encodeAttributes(item.attributes, {
+        payload: item.payload,
+        contentType: item.contentType,
+      }),
+    })
+  })
+
+  const patchOps = (patches ?? []).map((item) => {
+    if (item.contentType !== undefined) validateContentType(item.contentType)
+    const mutations = encodeMutations(item)
+    if (mutations.length === 0) {
+      throw new EmptyPatchError(item.entityKey)
+    }
+    return patchOperation({ entityKey: item.entityKey, mutations })
+  })
+
+  // An extension resolves its expiry exactly as a create does — the engine applies the same
+  // `max(expiresAt, currentBlock + minLifetime)` to both — so the same bounds are checked here
+  // rather than left to a revert.
+  const extendOps = (extensions ?? []).map((item) => {
+    const expiry = resolveExpiry(item.expires, context)
+    return extendExpiryOperation({ entityKey: item.entityKey, expiry })
+  })
+
+  const operations: Operation[] = [
+    ...createOps,
+    ...patchOps,
+    ...(deletes ?? []).map((item) => deleteOperation({ entityKey: item.entityKey })),
+    ...extendOps,
+    ...(ownershipChanges ?? []).map((item) =>
+      transferOwnershipOperation({
+        entityKey: item.entityKey,
+        newOwner: item.newOwner as Address,
+      }),
+    ),
+  ]
+
+  if (operations.length === 0) {
+    throw new Error("No operations to perform")
+  }
+
+  return operations
+}
+
+/**
+ * Signs and sends an encoded batch, wrapping any node rejection in {@link EntityMutationError}.
+ *
+ * The submission half both write paths share: one `writeContract` — an `eth_sendRawTransaction`,
+ * plus only the lookups viem needs for whatever `txParams` leaves out — with no waiting and no
+ * polling. A rejection is reported in engine terms when the node returned decodable revert data,
+ * and with the node's own message otherwise; either way the caller sees an
+ * {@link EntityMutationError}.
+ *
+ * Internal seam shared with `actions/advanced/sendMutation`; not part of the package's public
+ * surface.
+ */
+export async function submitMutation(
+  client: ArkivClient,
+  operations: Operation[],
+  txParams?: TxParams,
+): Promise<Hash> {
+  if (!client.account) throw new Error("Account required")
+  if (!client.chain) throw new Error("Chain required")
+  const walletClient = client as WalletArkivClient
+
+  try {
+    return await walletClient.writeContract({
+      address: ARKIV_ADDRESS,
+      abi: EXECUTE_ABI,
+      functionName: "execute",
+      args: [operations],
+      account: client.account,
+      chain: client.chain,
+      ...txParams,
+    })
+  } catch (error) {
+    throw asEntityMutationError(error)
+  }
+}
+
+/** Everything the batch's events say happened, one entry per applied operation, per kind. */
+export type MutationEvents = {
+  created: { entityKey: Hex; owner: Address; expiresAt: bigint }[]
+  patched: { entityKey: Hex; owner: Address }[]
+  deleted: { entityKey: Hex; owner: Address }[]
+  extended: { entityKey: Hex; owner: Address; expiresAt: bigint }[]
+  ownershipTransferred: { entityKey: Hex; previousOwner: Address; newOwner: Address }[]
+}
+
+/**
+ * Reads the entity events out of a receipt's logs, exactly as they were emitted.
+ *
+ * Lenient by design: it reports what the events say and nothing else — no counting against what
+ * was asked for (the caller may not have the request at hand) and no error for a receipt with no
+ * entity events at all. Logs from other contracts and events this SDK has no name for are skipped.
+ */
+export function collectMutationEvents(logs: TransactionReceipt["logs"]): MutationEvents {
+  const events: MutationEvents = {
+    created: [],
+    patched: [],
+    deleted: [],
+    extended: [],
+    ownershipTransferred: [],
   }
+
+  // `?? []` so a receipt without logs decodes to "nothing happened" rather than a TypeError.
+  for (const log of logs ?? []) {
+    // Only the operation address emits these, and a batch's transaction can carry logs from
+    // anything else it touched.
+    if (log.address.toLowerCase() !== ARKIV_ADDRESS.toLowerCase()) continue
+    const decoded = decodeEntityLog(log)
+    if (decoded === undefined) continue
+
+    switch (decoded.eventName) {
+      case "EntityCreated":
+        events.created.push({
+          entityKey: decoded.args.entityKey,
+          owner: decoded.args.owner,
+          expiresAt: decoded.args.expiresAt,
+        })
+        break
+      case "EntityPatched":
+        events.patched.push({ entityKey: decoded.args.entityKey, owner: decoded.args.owner })
+        break
+      case "EntityDeleted":
+        events.deleted.push({ entityKey: decoded.args.entityKey, owner: decoded.args.owner })
+        break
+      case "ExpiryExtended":
+        events.extended.push({
+          entityKey: decoded.args.entityKey,
+          owner: decoded.args.owner,
+          expiresAt: decoded.args.expiresAt,
+        })
+        break
+      case "OwnershipTransferred":
+        events.ownershipTransferred.push({
+          entityKey: decoded.args.entityKey,
+          previousOwner: decoded.args.previousOwner,
+          newOwner: decoded.args.newOwner,
+        })
+        break
+    }
+  }
+
+  return events
 }