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

package/src/utils/chains.test.ts

@@ -1,21 +1,14 @@
 import { describe, expect, test } from "bun:test"
-import { braga, kaolin, localhost } from "../chains"
+import { cheesecake, localhost } from "../chains"
 import { chainFromName } from "./chains"
 
 describe("chainFromName", () => {
   describe("valid chain names", () => {
-    test("returns braga chain for 'braga'", () => {
-      const chain = chainFromName("braga")
-      expect(chain).toBe(braga)
-      expect(chain.id).toBe(60138453102)
-      expect(chain.name).toBe("Braga")
-    })
-
-    test("returns kaolin chain for 'kaolin'", () => {
-      const chain = chainFromName("kaolin")
-      expect(chain).toBe(kaolin)
-      expect(chain.id).toBe(60138453025)
-      expect(chain.name).toBe("Kaolin")
+    test("returns cheesecake chain for 'cheesecake'", () => {
+      const chain = chainFromName("cheesecake")
+      expect(chain).toBe(cheesecake)
+      expect(chain.id).toBe(7733102)
+      expect(chain.name).toBe("Cheesecake")
     })
 
     test("returns localhost chain for 'localhost'", () => {
@@ -28,17 +21,14 @@ describe("chainFromName", () => {
 
   describe("case insensitivity", () => {
     test("handles uppercase chain names", () => {
-      expect(chainFromName("BRAGA")).toBe(braga)
-      expect(chainFromName("KAOLIN")).toBe(kaolin)
+      expect(chainFromName("CHEESECAKE")).toBe(cheesecake)
       expect(chainFromName("LOCALHOST")).toBe(localhost)
     })
 
     test("handles mixed case chain names", () => {
-      expect(chainFromName("Braga")).toBe(braga)
-      expect(chainFromName("Kaolin")).toBe(kaolin)
+      expect(chainFromName("Cheesecake")).toBe(cheesecake)
       expect(chainFromName("Localhost")).toBe(localhost)
-      expect(chainFromName("bRaGa")).toBe(braga)
-      expect(chainFromName("kAoLiN")).toBe(kaolin)
+      expect(chainFromName("cHeEsEcAkE")).toBe(cheesecake)
     })
   })
 
@@ -52,22 +42,28 @@ describe("chainFromName", () => {
     })
 
     test("throws error for chain name with whitespace", () => {
-      expect(() => chainFromName("kaolin ")).toThrow("Unknown chain: kaolin ")
-      expect(() => chainFromName(" kaolin")).toThrow("Unknown chain:  kaolin")
+      expect(() => chainFromName("cheesecake ")).toThrow("Unknown chain: cheesecake ")
+      expect(() => chainFromName(" cheesecake")).toThrow("Unknown chain:  cheesecake")
     })
 
     test("throws error for similar but incorrect chain names", () => {
-      expect(() => chainFromName("kaolinn")).toThrow("Unknown chain: kaolinn")
+      expect(() => chainFromName("cheesecakee")).toThrow("Unknown chain: cheesecakee")
+      expect(() => chainFromName("cheesecak")).toThrow("Unknown chain: cheesecak")
       expect(() => chainFromName("mendoza")).toThrow("Unknown chain: mendoza")
       expect(() => chainFromName("marketplace")).toThrow("Unknown chain: marketplace")
       expect(() => chainFromName("rosario")).toThrow("Unknown chain: rosario")
       expect(() => chainFromName("local")).toThrow("Unknown chain: local")
     })
+
+    test("throws error for the retired chains", () => {
+      expect(() => chainFromName("braga")).toThrow("Unknown chain: braga")
+      expect(() => chainFromName("kaolin")).toThrow("Unknown chain: kaolin")
+    })
   })
 
   describe("chain properties", () => {
     test("returned chain has required viem Chain properties", () => {
-      const chain = chainFromName("kaolin")
+      const chain = chainFromName("cheesecake")
 
       expect(chain).toHaveProperty("id")
       expect(chain).toHaveProperty("name")
@@ -79,12 +75,13 @@ describe("chainFromName", () => {
     })
 
     test("returned chain has rpcUrls configured", () => {
-      const chain = chainFromName("braga")
+      const chain = chainFromName("cheesecake")
 
       expect(chain.rpcUrls).toBeDefined()
       expect(chain.rpcUrls.default).toBeDefined()
       expect(chain.rpcUrls.default.http).toBeInstanceOf(Array)
       expect(chain.rpcUrls.default.http.length).toBeGreaterThan(0)
+      expect(chain.rpcUrls.default.webSocket?.length).toBeGreaterThan(0)
     })
   })
 })

package/src/utils/compression.ts

@@ -17,7 +17,7 @@ async function getZlib(): Promise<typeof import("zlib") | null> {
 
   if (!zlib) {
     try {
-      zlib = await import("zlib")
+      zlib = await import("node:zlib")
     } catch (error) {
       console.error("Error importing zlib", error)
       return null

package/src/utils/entities.test.ts

@@ -0,0 +1,62 @@
+import { describe, expect, it } from "bun:test"
+import type { RpcEntity } from "../types/rpcSchema"
+import { entityFromRpcResult } from "./entities"
+
+const KEY = `0x${"aa".repeat(32)}` as const
+
+/** A minimal row, with only the field under test varying. */
+function rowWith(creationFlags: RpcEntity["creationFlags"]): RpcEntity {
+  return { key: KEY, creationFlags }
+}
+
+describe("the creationFlags projection", () => {
+  it("decodes the bare byte a pre-spec node sends", () => {
+    expect(entityFromRpcResult(rowWith(0b11)).creationFlags).toEqual({
+      readonly: true,
+      permissionlessExtension: true,
+      raw: 0b11,
+    })
+  })
+
+  it("prefers raw over the booleans sent alongside it", () => {
+    // `raw` is the byte the engine stored, so it is the one reading that cannot disagree with what
+    // is on chain — and it keeps bits this SDK has no name for visible.
+    const flags = entityFromRpcResult(
+      rowWith({ readonly: false, permissionlessExtension: false, raw: 0b101 }),
+    ).creationFlags
+    expect(flags).toEqual({ readonly: true, permissionlessExtension: false, raw: 0b101 })
+  })
+
+  it("reads raw as the 0x quantity every other numeric field already uses", () => {
+    // createdAt, updatedAt and expiresAt are all hex on this surface, so a node rendering the flags
+    // byte the same way is the expected spelling, not a malformed response.
+    expect(
+      entityFromRpcResult(rowWith({ raw: "0x03" } as unknown as RpcEntity["creationFlags"]))
+        .creationFlags,
+    ).toEqual({ readonly: true, permissionlessExtension: true, raw: 3 })
+  })
+
+  it("falls back to the booleans when no byte arrives", () => {
+    expect(
+      entityFromRpcResult(
+        rowWith({ readonly: true, permissionlessExtension: false } as RpcEntity["creationFlags"]),
+      ).creationFlags,
+    ).toEqual({ readonly: true, permissionlessExtension: false, raw: 0b1 })
+  })
+
+  it("drops an unreadable encoding instead of failing the whole read", () => {
+    // Nothing on the decode path catches, so a throw here would not fail this field — it would
+    // fail the entire getEntity/fetch and take every other entity on the page with it.
+    for (const unreadable of [{}, { raw: "nonsense" }, { raw: 999 }, "flags"]) {
+      const entity = entityFromRpcResult(
+        rowWith(unreadable as unknown as RpcEntity["creationFlags"]),
+      )
+      expect(entity.creationFlags).toBeUndefined()
+      expect(entity.key).toBe(KEY)
+    }
+  })
+
+  it("stays undefined when the projection did not ask for it", () => {
+    expect(entityFromRpcResult({ key: KEY }).creationFlags).toBeUndefined()
+  })
+})

package/src/utils/entities.ts

@@ -1,47 +1,119 @@
-import { type Hex, toBytes } from "viem"
-import type { Attribute } from "../types/attributes"
-import { Entity } from "../types/entity"
+import { checksumAddress, type Hex, hexToBytes } from "viem"
+import type { AttributeSchema, Attributes } from "../attr"
+// Internal seam: the JSON-RPC decoder is not part of the package's public surface.
+import { asTypeTag, decodeRpcValue } from "../attr/codec"
+import {
+  decodeCreationFlags,
+  encodeCreationFlags,
+  type ResolvedCreationFlags,
+} from "../entity/flags"
+import { Entity, type EntityFields } from "../types/entity"
 import type { RpcEntity } from "../types/rpcSchema"
-import { RpcAttributeValueType } from "../types/rpcSchema"
 import { getLogger } from "./logger"
 
-function decodeAttributeValue(value: string, valueType: RpcAttributeValueType): Attribute["value"] {
-  switch (valueType) {
-    case RpcAttributeValueType.Uint:
-      return Number(BigInt(value as Hex))
-    case RpcAttributeValueType.EntityKey:
-      return value as Hex
-    case RpcAttributeValueType.String:
-    default:
-      return value
+const logger = getLogger("utils:entities")
+
+/**
+ * Turns the attribute array a query returns into a name-keyed map of typed values.
+ *
+ * Attribute names are unique per entity, so the map loses nothing and gives callers
+ * `entity.attributes.level.value` instead of a linear search.
+ */
+function decodeAttributes(rpcAttributes: NonNullable<RpcEntity["attributes"]>): Attributes {
+  const attributes: Record<string, ReturnType<typeof decodeRpcValue>> = {}
+  for (const { name, type, value } of rpcAttributes) {
+    attributes[name] = decodeRpcValue(type, value)
   }
+  return attributes
 }
 
-const logger = getLogger("utils:entities")
+/** The same, for the values-free `attributeSchema` projection. */
+function decodeSchema(entries: NonNullable<RpcEntity["attributeSchema"]>): AttributeSchema {
+  const schema: Record<string, ReturnType<typeof asTypeTag>> = {}
+  for (const { name, type } of entries) {
+    schema[name] = asTypeTag(type)
+  }
+  return schema
+}
 
-export async function entityFromRpcResult(rpcEntity: RpcEntity) {
+/**
+ * Builds an {@link Entity} from a query result row.
+ *
+ * A field the query did not select is absent from the response and stays `undefined` here — the
+ * decoder never substitutes an empty value for one that was not asked for.
+ */
+export function entityFromRpcResult(rpcEntity: RpcEntity): Entity {
   logger("entityFromRpcResult %o", rpcEntity)
 
-  return new Entity(
-    rpcEntity.key,
-    rpcEntity.contentType,
-    rpcEntity.owner,
-    rpcEntity.creator,
-    rpcEntity.expiresAt !== undefined ? BigInt(rpcEntity.expiresAt) : undefined,
-    rpcEntity.createdAtBlock !== undefined ? BigInt(rpcEntity.createdAtBlock) : undefined,
-    rpcEntity.lastModifiedAtBlock !== undefined ? BigInt(rpcEntity.lastModifiedAtBlock) : undefined,
-    rpcEntity.transactionIndexInBlock !== undefined
-      ? BigInt(rpcEntity.transactionIndexInBlock)
-      : undefined,
-    rpcEntity.operationIndexInTransaction !== undefined
-      ? BigInt(rpcEntity.operationIndexInTransaction)
-      : undefined,
-    rpcEntity.value !== undefined ? toBytes(rpcEntity.value) : undefined,
-    [
-      ...(rpcEntity.attributes ?? []).map(({ key, value, valueType }) => ({
-        key,
-        value: decodeAttributeValue(value, valueType),
-      })),
-    ],
-  )
+  const fields: EntityFields = {
+    key: rpcEntity.key,
+    owner: toAddress(rpcEntity.owner),
+    creator: toAddress(rpcEntity.creator),
+    createdAt: toBlock(rpcEntity.createdAt),
+    updatedAt: toBlock(rpcEntity.updatedAt),
+    expiresAt: toBlock(rpcEntity.expiresAt),
+    creationFlags: decodeFlags(rpcEntity.creationFlags),
+    contentType: rpcEntity.contentType,
+    payload: rpcEntity.payload !== undefined ? hexToBytes(rpcEntity.payload) : undefined,
+    attributeSchema:
+      rpcEntity.attributeSchema !== undefined ? decodeSchema(rpcEntity.attributeSchema) : undefined,
+    attributes:
+      rpcEntity.attributes !== undefined ? decodeAttributes(rpcEntity.attributes) : undefined,
+  }
+
+  return new Entity(fields)
+}
+
+function toBlock(value: string | undefined): bigint | undefined {
+  return value === undefined ? undefined : BigInt(value)
+}
+
+function toAddress(value: Hex | undefined): Hex | undefined {
+  if (value === undefined) return undefined
+  if (!/^0x[0-9a-fA-F]{40}$/.test(value)) {
+    logger("unreadable address %o", value)
+    return value
+  }
+  return checksumAddress(value)
+}
+
+/**
+ * Resolves the `creationFlags` projection, preferring the byte.
+ */
+function decodeFlags(
+  value: NonNullable<RpcEntity["creationFlags"]> | undefined,
+): ResolvedCreationFlags | undefined {
+  if (value === undefined) return undefined
+
+  const raw = toFlagsByte(typeof value === "number" ? value : value.raw)
+  if (raw !== undefined) return decodeCreationFlags(raw)
+
+  if (
+    typeof value === "object" &&
+    (value.readonly ?? value.permissionlessExtension) !== undefined
+  ) {
+    return decodeCreationFlags(
+      encodeCreationFlags({
+        readonly: value.readonly ?? false,
+        permissionlessExtension: value.permissionlessExtension ?? false,
+      }),
+    )
+  }
+
+  logger("unreadable creationFlags %o", value)
+  return undefined
+}
+
+/**
+ * A flags byte in whichever spelling arrived: a JSON number, or the `0x` QUANTITY that every other
+ * numeric field on {@link RpcEntity} already uses. `undefined` for anything that is not a byte.
+ */
+function toFlagsByte(value: unknown): number | undefined {
+  const parsed =
+    typeof value === "number"
+      ? value
+      : typeof value === "string" && /^(0x[0-9a-fA-F]+|\d+)$/.test(value)
+        ? Number(value)
+        : Number.NaN
+  return Number.isInteger(parsed) && parsed >= 0 && parsed <= 0xff ? parsed : undefined
 }

package/src/utils/expirationTime.ts

@@ -1,13 +1,117 @@
-import { BLOCK_TIME } from "../consts"
+import { InvalidExpiryError } from "../entity/errors"
+import { type Expiry, type Lifetime, makeExpiry, toBlocks } from "../entity/expiry"
+import { MAX_EXPIRES_AT } from "../entity/params"
 
+/**
+ * The optional floor a deadline can carry.
+ *
+ * `atLeast` takes a duration — one of the `from*` helpers — and never another deadline, so
+ * `atBlock(x, { atLeast: atBlock(y) })` does not compile. Two deadlines are not a thing the engine
+ * can resolve.
+ */
+export type DeadlineOptions = {
+  /** Live at least this long from now, even if the deadline is sooner. */
+  atLeast?: Lifetime | undefined
+}
+
+function lifetimeOf(seconds: number): Lifetime {
+  return makeExpiry(toBlocks(seconds), 0n) as Lifetime
+}
+
+function deadlineOf(expiresAt: bigint | Date, options?: DeadlineOptions): Expiry {
+  return makeExpiry(options?.atLeast?.minLifetime ?? 0n, expiresAt)
+}
+
+/**
+ * Builds the `expires` of a create or an extension.
+ *
+ * Every helper returns the `{ minLifetime, expiresAt }` pair the ABI carries, so what you write is
+ * what goes on the wire. The `from*` helpers fill `minLifetime` and leave `expiresAt` at `0n`;
+ * {@link ExpirationTime.atBlock} and {@link ExpirationTime.atDate} do the reverse. The engine takes
+ * whichever comes later, which is why a deadline can also carry a floor.
+ *
+ * Values are plain data — no methods, no prototype — so they log, clone and compare like any other
+ * object.
+ *
+ * @example The 90% case: a duration, and nothing else to think about.
+ * await client.createEntity({ payload, contentType, expires: ExpirationTime.fromDays(30) })
+ *
+ * @example An exact block, or a wall-clock date.
+ * expires: ExpirationTime.atBlock(1_200_000n)
+ * expires: ExpirationTime.atDate(new Date("2027-01-01"))
+ *
+ * @example A deadline that still guarantees a minimum life.
+ * expires: ExpirationTime.atBlock(1_200_000n, { atLeast: ExpirationTime.fromDays(1) })
+ */
 export const ExpirationTime = {
-  fromSeconds: (seconds: number) => seconds,
-  fromMinutes: (minutes: number) => minutes * 60,
-  fromHours: (hours: number) => hours * 60 * 60,
-  fromDays: (days: number) => days * 24 * 60 * 60,
-  fromWeeks: (weeks: number) => weeks * 7 * 24 * 60 * 60,
-  fromMonths: (months: number) => months * 30 * 24 * 60 * 60,
-  fromYears: (years: number) => years * 365 * 24 * 60 * 60,
-  fromBlocks: (blocks: number) => blocks * BLOCK_TIME,
-  fromDate: (date: Date) => Math.floor(date.getTime() / 1000) - Math.floor(Date.now() / 1000),
+  /**
+   * A raw number of seconds. Must be a whole number of blocks' worth — see the other helpers, which
+   * all produce one by construction.
+   *
+   * @throws {InvalidExpiryError} If the duration is not a positive multiple of the block time.
+   */
+  fromSeconds: (seconds: number): Lifetime => lifetimeOf(seconds),
+  fromMinutes: (minutes: number): Lifetime => lifetimeOf(minutes * 60),
+  fromHours: (hours: number): Lifetime => lifetimeOf(hours * 60 * 60),
+  fromDays: (days: number): Lifetime => lifetimeOf(days * 24 * 60 * 60),
+  fromWeeks: (weeks: number): Lifetime => lifetimeOf(weeks * 7 * 24 * 60 * 60),
+  fromMonths: (months: number): Lifetime => lifetimeOf(months * 30 * 24 * 60 * 60),
+  fromYears: (years: number): Lifetime => lifetimeOf(years * 365 * 24 * 60 * 60),
+
+  /**
+   * A number of blocks, for callers who think in the chain's own unit. Always exact — there is no
+   * conversion to be approximate about.
+   *
+   * @throws {InvalidExpiryError} If the count is not a positive whole number.
+   */
+  fromBlocks: (blocks: number): Lifetime => {
+    if (!Number.isInteger(blocks) || blocks <= 0) {
+      throw new InvalidExpiryError(
+        `a lifetime must be a positive whole number of blocks, got ${blocks}`,
+      )
+    }
+    return makeExpiry(BigInt(blocks), 0n) as Lifetime
+  },
+
+  /**
+   * An absolute block height.
+   *
+   * @param block - The block the entity expires at.
+   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
+   * @throws {InvalidExpiryError} If the height is negative.
+   */
+  atBlock: (block: bigint, options?: DeadlineOptions): Expiry => {
+    if (typeof block !== "bigint" || block < 0n) {
+      throw new InvalidExpiryError(`a deadline must be a non-negative block height, got ${block}`)
+    }
+    return deadlineOf(block, options)
+  },
+
+  /**
+   * A wall-clock instant, placed against the block the transaction is built on.
+   *
+   * A date cannot land on a block boundary in general, so it rounds **up** to the next block: the
+   * entity lives until at least the instant asked for. This is why a date is never rejected for
+   * "not being a whole number of blocks" the way a duration is — it becomes a block height, not a
+   * duration.
+   *
+   * @param date - When the entity should expire.
+   * @param options - Optionally, a floor: `{ atLeast: ExpirationTime.fromDays(1) }`.
+   * @throws {InvalidExpiryError} If the value is not a valid `Date`.
+   */
+  atDate: (date: Date, options?: DeadlineOptions): Expiry => {
+    if (!(date instanceof Date) || Number.isNaN(date.getTime())) {
+      throw new InvalidExpiryError(`a deadline must be a valid Date, got ${String(date)}`)
+    }
+    return deadlineOf(date, options)
+  },
+
+  /**
+   * An entity that should never expire.
+   *
+   * This is `atBlock(MAX_EXPIRES_AT)` — the largest expiry the `uint64` field holds — and the
+   * engine treats it as an ordinary deadline rather than a special case. There is no permanence
+   * flag; a block height no chain will reach is what permanence is.
+   */
+  permanent: (): Expiry => deadlineOf(MAX_EXPIRES_AT),
 }

package/src/utils/logger.ts

@@ -144,8 +144,8 @@ function getColorForNamespace(namespace: string): { css: string; ansi: string }
 
   // Use absolute value and modulo to get index
   const colorIndex = Math.abs(hash) % COLOR_PALETTE.length
-  const cssColor = COLOR_PALETTE[colorIndex]
-  const ansiColor = ANSI_COLORS[colorIndex % ANSI_COLORS.length]
+  const cssColor = COLOR_PALETTE[colorIndex] ?? "inherit"
+  const ansiColor = ANSI_COLORS[colorIndex % ANSI_COLORS.length] ?? ""
 
   const color = { css: cssColor, ansi: ansiColor }
 

package/src/utils/revert.test.ts

@@ -0,0 +1,99 @@
+import { describe, expect, it } from "bun:test"
+import { BaseError, ContractFunctionRevertedError, type Hex, toHex } from "viem"
+import { describeEntityRevert } from "./revert"
+
+/**
+ * Wraps a decoded revert the way viem delivers one: the `ContractFunctionRevertedError` is nested
+ * in a cause chain, which is why `describeEntityRevert` walks rather than type-checks the top.
+ */
+function reverted(errorName: string, args: readonly unknown[]): BaseError {
+  const inner = new ContractFunctionRevertedError({
+    abi: [],
+    functionName: "execute",
+  })
+  // The constructor cannot build `data` without a real ABI decode, so it is set directly — the
+  // shape is what matters here, not how viem arrived at it.
+  Object.assign(inner, { data: { errorName, args } })
+  return new BaseError('The contract function "execute" reverted.', { cause: inner })
+}
+
+/** An Ident32 name cell: the name, left-aligned and null-padded to 32 bytes. */
+const ident = (name: string): Hex => toHex(name, { size: 32 })
+
+const KEY = `0x${"ab".repeat(32)}` as Hex
+
+describe("describeEntityRevert", () => {
+  it("ignores anything that is not a decoded engine revert", () => {
+    expect(describeEntityRevert(new Error("boom"))).toBeUndefined()
+    expect(describeEntityRevert("boom")).toBeUndefined()
+    expect(describeEntityRevert(undefined)).toBeUndefined()
+    expect(describeEntityRevert(new BaseError("no cause"))).toBeUndefined()
+  })
+
+  describe("attribute names", () => {
+    it("names the offending character rather than printing the byte alone", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [5n, "0x21"]))
+      expect(message).toContain('"!"')
+      expect(message).toContain("0x21")
+      expect(message).toContain("byte 5")
+    })
+
+    it("quotes the name charset the SDK itself validates against", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [0n, "0x2f"]))
+      expect(message).toContain('"A"-"Z"')
+      expect(message).toContain('"a"-"z"')
+      expect(message).toContain("with a letter first")
+    })
+
+    it("renders an unprintable byte as a byte", () => {
+      const message = describeEntityRevert(reverted("Ident32InvalidByte", [1n, "0x07"]))
+      expect(message).toContain("byte 0x07")
+    })
+  })
+
+  describe("names carried in a bytes32 cell", () => {
+    it("reads the name back out of its null padding", () => {
+      expect(
+        describeEntityRevert(reverted("SystemAttributeNotWritable", [ident("$owner")])),
+      ).toContain('"$owner"')
+      expect(describeEntityRevert(reverted("TombstoneInCreate", [ident("gone")]))).toContain(
+        '"gone"',
+      )
+      expect(describeEntityRevert(reverted("InvalidValueType", [ident("level"), 99]))).toContain(
+        '"level"',
+      )
+    })
+  })
+
+  describe("entity state", () => {
+    it("abbreviates the key so it does not bury the sentence", () => {
+      const message = describeEntityRevert(reverted("EntityNotFound", [KEY]))
+      expect(message).toContain("…")
+      expect(message).not.toContain(KEY)
+    })
+
+    it("explains a readonly entity in terms of what is still allowed", () => {
+      const message = describeEntityRevert(reverted("ReadOnlyEntity", [KEY]))
+      expect(message).toContain("readonly")
+      expect(message).toContain("extended")
+    })
+
+    it("renders reserved creation flags as the bits they are", () => {
+      const message = describeEntityRevert(reverted("ReservedCreationFlags", [0b100]))
+      expect(message).toContain("0b00000100")
+    })
+  })
+
+  describe("expiry", () => {
+    it("says which way the extension went wrong", () => {
+      const message = describeEntityRevert(reverted("ExpiryNotExtended", [KEY, 100n, 500n]))
+      expect(message).toContain("already expires at block 500")
+      expect(message).toContain("shorten")
+    })
+  })
+
+  it("falls back to naming the error when it has no tailored explanation", () => {
+    const message = describeEntityRevert(reverted("SomeFutureError", []))
+    expect(message).toBe("the engine rejected the batch with SomeFutureError")
+  })
+})