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

package/src/actions/wallet/createEntity.ts

@@ -1,43 +1,109 @@
 import type { Hash, Hex } from "viem"
+import type { AttributeInputs } from "../../attr"
 import type { ArkivClient } from "../../clients/baseClient"
-import type { Attribute, MimeType, TxParams } from "../../types"
+import type { CreationFlags, Expiry } from "../../entity"
+import { EntityMutationError } from "../../errors"
+import type { MimeType, TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:create-entity")
 
 /**
- * Parameters for the createEntity function.
- * - payload: The payload of the entity.
- * - attributes: The attributes of the entity. Attribute values may be strings
- *   or numbers, but numeric values **must be integers**. To store a non-integer,
- *   scale it to an integer (e.g. `1.5` -> `1500`) to preserve numeric ordering,
- *   or pass it as a string (e.g. `"1.5"`). A non-integer numeric value throws an
- *   {@link InvalidAttributeError}.
- * - contentType: The content type of the entity.
- * - expiresIn: How long until the entity expires, in seconds. Because Arkiv
- *   measures expiration in blocks (1 block = 2 seconds), this **must be a
- *   positive integer and a multiple of the block time (2 seconds)**
- *   Invalid values throw an {@link InvalidExpirationError}.
+ * Parameters for creating an entity.
+ *
+ * An entity always carries contents and a type for them, plus a lifetime. Attributes, flags and a
+ * salt are optional on top of that.
+ *
+ * @example
+ * const { entityKey } = await client.createEntity({
+ *   attributes: {
+ *     level:   i32(10),
+ *     balance: u256(1_000_000n),
+ *     score:   dec("3.5"),
+ *     name:    "Bob",   // bare string -> str
+ *     flagged: true,    // bare boolean -> bool
+ *   },
+ *   payload: jsonToPayload({ hello: "world" }),
+ *   contentType: "application/json",
+ *   expires: ExpirationTime.fromDays(30),
+ *   flags: { readonly: true },
+ * })
+ *
+ * @example Pin an absolute deadline, but refuse to create something nearly dead:
+ * await client.createEntity({
+ *   payload, contentType: "application/json",
+ *   expires: ExpirationTime.atDate(someDeadline, {
+ *     atLeast: ExpirationTime.fromDays(1),    // ...but live at least a day regardless
+ *   }),
+ * })
+ *
+ * @example An entity that is nothing but queryable attributes still declares its (empty) contents:
+ * await client.createEntity({
+ *   attributes: { parent: key(parentKey), rank: i32(3) },
+ *   payload: new Uint8Array(),
+ *   contentType: "application/octet-stream",
+ *   expires: ExpirationTime.fromDays(30),
+ * })
  */
 export type CreateEntityParameters = {
+  /**
+   * How long the entity should live, built with {@link ExpirationTime}.
+   *
+   * `ExpirationTime.fromDays(30)` is the everyday form. `atBlock` / `atDate` pin an absolute
+   * deadline instead, and either can carry `{ atLeast }` to guarantee a minimum life on top of it.
+   */
+  expires: Expiry
+  /**
+   * The entity's opaque payload. Travels to the engine as the `$payload` system attribute; on this
+   * surface it is just the entity's contents.
+   *
+   * Pass an empty `Uint8Array` for an entity that is nothing but queryable attributes — it is
+   * written as an empty payload rather than left unset, so what you pass is what is stored.
+   */
   payload: Uint8Array
-  /** Entity attributes. Numeric values must be integers (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
-  attributes: Attribute[]
-  contentType: MimeType | string
-  /** Seconds until expiry. Must be a positive integer and a multiple of the 2s block time.
-   * Throws {@link InvalidExpirationError} otherwise. */
-  expiresIn: number
+  /** The payload's MIME type, e.g. `"application/json"`. Sent as the `$contentType` cell. */
+  contentType: MimeType | (string & {})
+  /**
+   * The entity's queryable attributes, keyed by name. Values are the tagged constructors from
+   * `@arkiv-network/sdk/attr` — `i32`, `u256`, `dec`, `str`, `addr`, `key`, `bytes32`, `bool` — or
+   * a bare `boolean`, `number`, `bigint` or `string` where the type is unambiguous.
+   *
+   * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+   * @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
+   */
+  attributes?: AttributeInputs | undefined
+  /**
+   * Properties fixed at creation: `readonly` and `permissionlessExtension`. No operation changes
+   * them afterwards, so an entity is whatever it was created as for life. Both default to `false`.
+   */
+  flags?: CreationFlags | undefined
+  /**
+   * The salt mixed into the entity key. Defaults to 128 random bits, which makes the key
+   * unpredictable to everyone but the creator.
+   *
+   * Pass `0n` for a key derived from the owner and nonce alone — predictable by anyone, which is
+   * what you want only when a third party must be able to compute the key in advance.
+   */
+  salt?: bigint | undefined
 }
 
 /**
- * Return type for the createEntity function.
- * - entityKey: The key of the entity.
- * - txHash: The transaction hash.
+ * The result of creating an entity.
  */
 export type CreateEntityReturnType = {
+  /** The new entity's key. */
   entityKey: Hex
   txHash: Hash
+  /**
+   * The block the entity is expected to expire at, resolved against the block the transaction was
+   * built on.
+   *
+   * The engine resolves a duration against the block the transaction actually lands in, so for
+   * `ExpirationTime.fromDays(30)` and friends this is a lower bound: the real expiry is later by
+   * however many blocks passed between building and inclusion. An `atBlock` deadline is exact.
+   */
+  expiresAt: bigint
 }
 
 export async function createEntity(
@@ -46,7 +112,7 @@ export async function createEntity(
   txParams?: TxParams,
 ): Promise<CreateEntityReturnType> {
   logger("createEntity %o", data)
-  const { receipt, createdEntityKeys } = await sendArkivTransaction(
+  const { receipt, createdEntityKeys, createdExpiries } = await sendArkivTransaction(
     client,
     { creates: [data] },
     txParams,
@@ -54,8 +120,17 @@ export async function createEntity(
 
   logger("Receipt from createEntity %o", receipt)
 
+  const [entityKey] = createdEntityKeys
+  const [expiresAt] = createdExpiries
+  if (entityKey === undefined || expiresAt === undefined) {
+    throw new EntityMutationError(
+      `Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity key or expiry.`,
+    )
+  }
+
   return {
     txHash: receipt.transactionHash as Hash,
-    entityKey: createdEntityKeys[0],
+    entityKey,
+    expiresAt,
   }
 }

package/src/actions/wallet/extendEntity.ts

@@ -1,5 +1,7 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
+import type { Expiry } from "../../entity"
+import { EntityMutationError } from "../../errors"
 import type { TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
@@ -7,28 +9,38 @@ import { getLogger } from "../../utils/logger"
 const logger = getLogger("actions:wallet:extend-entity")
 
 /**
- * Parameters for the extendEntity function.
- * - entityKey: The key of the entity to extend.
- * - expiresIn: How long to extend the entity by, in seconds. Because Arkiv
- *   measures expiration in blocks (1 block = 2 seconds), this **must be a
- *   positive integer and a multiple of the block time (2 seconds)**.
- *   Invalid values throw an {@link InvalidExpirationError}.
+ * Parameters for extending an entity's life.
+ *
+ * An extension **sets a new expiry**; it does not add to the existing one. It is resolved exactly
+ * as a create's is — a duration counts from now, not from the entity's current expiry — so
+ * `ExpirationTime.fromDays(30)` means "alive for thirty more days from now" whatever the entity's
+ * remaining life happened to be.
+ *
+ * The engine rejects an extension that would not move the expiry later, so extending an entity by
+ * less than it already has left is an error rather than a silent shortening.
+ *
+ * @example
+ * await client.extendEntity({ entityKey, expires: ExpirationTime.fromDays(30) })
+ * await client.extendEntity({ entityKey, expires: ExpirationTime.atBlock(1_200_000n) })
  */
 export type ExtendEntityParameters = {
   entityKey: Hex
-  /** Seconds to extend by. Must be a positive integer and a multiple of the 2s block time.
-   * Throws {@link InvalidExpirationError} otherwise. */
-  expiresIn: number
+  /** The entity's new lifetime, built with {@link ExpirationTime}. */
+  expires: Expiry
 }
 
 /**
- * Return type for the extendEntity function.
- * - entityKey: The key of the entity.
- * - txHash: The transaction hash.
+ * The result of extending an entity.
  */
 export type ExtendEntityReturnType = {
   entityKey: Hex
   txHash: Hash
+  /**
+   * The block the entity is now expected to expire at, resolved against the block the transaction
+   * was built on. Durations are approximate, so treat this as the estimate the operation was built
+   * from rather than the block the engine settled on.
+   */
+  expiresAt: bigint
 }
 
 export async function extendEntity(
@@ -37,12 +49,24 @@ export async function extendEntity(
   txParams?: TxParams,
 ): Promise<ExtendEntityReturnType> {
   logger("extendEntity %o", data)
-  const { receipt } = await sendArkivTransaction(client, { extensions: [data] }, txParams)
+  const { receipt, extendedExpiries } = await sendArkivTransaction(
+    client,
+    { extensions: [data] },
+    txParams,
+  )
 
   logger("Receipt from extendEntity %o", receipt)
 
+  const [expiresAt] = extendedExpiries
+  if (expiresAt === undefined) {
+    throw new EntityMutationError(
+      `Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity expiry.`,
+    )
+  }
+
   return {
     txHash: receipt.transactionHash as Hash,
     entityKey: data.entityKey,
+    expiresAt,
   }
 }

package/src/actions/wallet/mutateEntities.test.ts

@@ -0,0 +1,76 @@
+import { describe, expect, it, vi } from "bun:test"
+import type { ArkivClient } from "../../clients/baseClient"
+import { mutateEntities } from "./mutateEntities"
+
+const ENTITY_KEY = `0x${"ab".repeat(32)}` as const
+const NEW_OWNER = "0x2222222222222222222222222222222222222222"
+
+function makeClient() {
+  const writeContract = vi.fn().mockResolvedValue("0xdeadbeef")
+  return {
+    client: {
+      account: { address: "0x1111111111111111111111111111111111111111" },
+      chain: { id: 1 },
+      getBlockNumber: vi.fn().mockResolvedValue(100n),
+      readContract: vi.fn().mockResolvedValue(7n),
+      writeContract,
+      waitForTransactionReceipt: vi.fn().mockResolvedValue({
+        status: "success",
+        transactionHash: "0xdeadbeef",
+        logs: [],
+      }),
+    } as unknown as ArkivClient,
+    writeContract,
+  }
+}
+
+describe("the empty-batch guard", () => {
+  it("counts every kind of operation, not just the first four", async () => {
+    // An ownership-only batch is a batch: it used to be rejected because the guard listed
+    // creates/updates/deletes/extensions and forgot ownershipChanges.
+    const { client, writeContract } = makeClient()
+    const result = await mutateEntities(client, {
+      ownershipChanges: [{ entityKey: ENTITY_KEY, newOwner: NEW_OWNER }],
+    })
+    expect(writeContract).toHaveBeenCalledTimes(1)
+    expect(result.ownershipChanges).toEqual([ENTITY_KEY])
+  })
+
+  it("rejects a batch with nothing in it", async () => {
+    const { client, writeContract } = makeClient()
+    await expect(mutateEntities(client, {})).rejects.toThrow(/No operations/)
+    // Present but empty is just as empty — the engine would revert with EmptyBatch().
+    await expect(mutateEntities(client, { deletes: [], ownershipChanges: [] })).rejects.toThrow(
+      /No operations/,
+    )
+    expect(writeContract).not.toHaveBeenCalled()
+  })
+
+  it("counts only real operation kinds, not whatever keys the caller passed", async () => {
+    const { client, writeContract } = makeClient()
+    // `updates` was this API's name for patches until they were renamed. Counting the caller's own
+    // keys would score this batch as non-empty and then drop it on the way to the wire, sending
+    // execute([]) — so the guard counts the five kinds that actually reach the transaction.
+    const stale = { updates: [{ entityKey: ENTITY_KEY, set: { level: 1 } }] } as never
+    await expect(mutateEntities(client, stale)).rejects.toThrow(/No operations/)
+    // A typo is the same mistake with a different name.
+    await expect(
+      mutateEntities(client, { delete: [{ entityKey: ENTITY_KEY }] } as never),
+    ).rejects.toThrow(/No operations/)
+    expect(writeContract).not.toHaveBeenCalled()
+  })
+
+  it("does not let a stale key smuggle itself into a batch that is otherwise valid", async () => {
+    const { client, writeContract } = makeClient()
+    // The dangerous shape: the creates apply and the transaction succeeds, so nothing surfaces the
+    // fact that the `updates` never happened. The guard cannot catch this one — only the caller's
+    // types can — but the result must at least not claim they did.
+    const result = await mutateEntities(client, {
+      deletes: [{ entityKey: ENTITY_KEY }],
+      updates: [{ entityKey: ENTITY_KEY, set: { level: 1 } }],
+    } as never)
+    expect(result.patchedEntities).toEqual([])
+    // Only the delete reached the wire, and the report says so.
+    expect(writeContract.mock.calls[0][0].args[0]).toHaveLength(1)
+  })
+})

package/src/actions/wallet/mutateEntities.ts

@@ -7,40 +7,42 @@ import type { ChangeOwnershipParameters } from "./changeOwnership"
 import type { CreateEntityParameters } from "./createEntity"
 import type { DeleteEntityParameters } from "./deleteEntity"
 import type { ExtendEntityParameters } from "./extendEntity"
-import type { UpdateEntityParameters } from "./updateEntity"
+import type { PatchEntityParameters } from "./patchEntity"
 
 const logger = getLogger("actions:wallet:mutate-entities")
 
 /**
  * Parameters for the mutateEntities function.
- * - creates: The creates to perform.
- * - updates: The updates to perform.
- * - deletes: The deletes to perform.
- * - extensions: The extensions to perform.
+ *
+ * At least one operation is required; a batch with nothing in it throws rather than spending gas on
+ * an empty transaction.
  */
 export type MutateEntitiesParameters = {
+  /** The entities to create. */
   creates?: CreateEntityParameters[]
-  updates?: UpdateEntityParameters[]
+  /** 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[]
 }
 
-/**
- * Return type for the mutateEntities function.
- * - txHash: The transaction hash.
- * - createdEntities: The keys of the created entities.
- * - updatedEntities: The keys of the updated entities.
- * - deletedEntities: The keys of the deleted entities.
- * - extendedEntities: The keys of the extended entities.
- * - ownershipChanges: The keys of the ownership changes.
- */
+/** Return type for the mutateEntities function. */
 export type MutateEntitiesReturnType = {
+  /** The transaction hash. */
   txHash: Hash
+  /** The keys of the created entities, in batch order. */
   createdEntities: Hex[]
-  updatedEntities: Hex[]
+  /** 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 keys of the entities handed to a new owner. */
   ownershipChanges: Hex[]
 }
 
@@ -49,10 +51,6 @@ export async function mutateEntities(
   data: MutateEntitiesParameters,
   txParams?: TxParams,
 ): Promise<MutateEntitiesReturnType> {
-  if (!data.creates && !data.updates && !data.deletes && !data.extensions) {
-    throw new Error("No operations to perform")
-  }
-
   const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams)
 
   logger("Receipt from mutateEntities %o", receipt)
@@ -60,7 +58,7 @@ export async function mutateEntities(
   return {
     txHash: receipt.transactionHash as Hash,
     createdEntities: createdEntityKeys,
-    updatedEntities: (data.updates ?? []).map((u) => u.entityKey),
+    patchedEntities: (data.patches ?? []).map((p) => p.entityKey),
     deletedEntities: (data.deletes ?? []).map((d) => d.entityKey),
     extendedEntities: (data.extensions ?? []).map((e) => e.entityKey),
     ownershipChanges: (data.ownershipChanges ?? []).map((o) => o.entityKey),

package/src/actions/wallet/patchEntity.ts

@@ -0,0 +1,90 @@
+import type { Hash, Hex } from "viem"
+import type { AttributeInputs } from "../../attr"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { MimeType, TxParams } from "../../types"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
+import { getLogger } from "../../utils/logger"
+
+const logger = getLogger("actions:wallet:patch-entity")
+
+/**
+ * Parameters for patching an entity.
+ *
+ * A patch names only what changes. Attributes it does not mention keep whatever value they have, and
+ * the payload and content type stay as they are unless given — so a caller can change one field
+ * without first reading the entity to learn what the others are, and without racing anyone else who
+ * is changing a different field.
+ *
+ * The entity's identity is fixed: a patch never moves the key, the owner, the creation flags or the
+ * expiry. Use `extendEntity` for the expiry and `changeOwnership` for the owner.
+ *
+ * @example Change one attribute and remove another, leaving the payload alone:
+ * await client.patchEntity({
+ *   entityKey,
+ *   set: { status: "published", level: i32(11) },
+ *   unset: ["draft"],
+ * })
+ *
+ * @example Replace the contents without touching a single attribute:
+ * await client.patchEntity({
+ *   entityKey,
+ *   payload: jsonToPayload({ hello: "again" }),
+ * })
+ */
+export type PatchEntityParameters = {
+  /** The entity to patch. */
+  entityKey: Hex
+  /**
+   * Attributes to write, keyed by name. An existing attribute is overwritten — including with a
+   * different type — and a name the entity does not carry yet is added.
+   *
+   * Values are the tagged constructors from `@arkiv-network/sdk/attr` — `i32`, `u256`, `dec`, `str`,
+   * `addr`, `key`, `bytes32`, `bool` — or a bare `boolean`, `number`, `bigint` or `string` where the
+   * type is unambiguous.
+   *
+   * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+   * @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
+   */
+  set?: AttributeInputs | undefined
+  /**
+   * Attribute names to remove. Naming one the entity does not carry is not an error — the outcome
+   * is the same either way, and a caller clearing a field should not have to know whether it was
+   * ever set.
+   *
+   * @throws {ConflictingMutationError} If a name also appears in `set`.
+   */
+  unset?: readonly string[] | undefined
+  /**
+   * The entity's new payload. Omit it to leave the current contents untouched; pass an empty
+   * `Uint8Array` to replace them with nothing.
+   */
+  payload?: Uint8Array | undefined
+  /**
+   * The payload's new MIME type. Omit it to keep the current one — which is what you want when the
+   * new payload is the same kind of thing as the old.
+   */
+  contentType?: MimeType | (string & {}) | undefined
+}
+
+/** The result of patching an entity. */
+export type PatchEntityReturnType = {
+  /** The patched entity's key — unchanged, since a patch never moves it. */
+  entityKey: Hex
+  txHash: Hash
+}
+
+export async function patchEntity(
+  client: ArkivClient,
+  data: PatchEntityParameters,
+  txParams?: TxParams,
+): Promise<PatchEntityReturnType> {
+  logger("patchEntity %o", data)
+  const { receipt } = await sendArkivTransaction(client, { patches: [data] }, txParams)
+
+  logger("Receipt from patchEntity %o", receipt)
+
+  return {
+    txHash: receipt.transactionHash as Hash,
+    entityKey: data.entityKey,
+  }
+}

package/src/attr/attributes.test.ts

@@ -0,0 +1,120 @@
+import { describe, expect, it } from "bun:test"
+import { encodeAttributes, encodeMutations, MAX_ATTRIBUTES, resolveAttributes } from "./attributes"
+import { InvalidAttributeNameError, TooManyAttributesError } from "./errors"
+import { isValidAttributeName, validateAttributeName } from "./names"
+import { dec, i32, str, u256 } from "./values"
+
+describe("resolveAttributes", () => {
+  it("types bare values and leaves tagged ones alone", () => {
+    const resolved = resolveAttributes({
+      level: 10,
+      balance: 1_000_000n,
+      name: "Bob",
+      flagged: true,
+      score: dec("3.5"),
+    })
+    expect(resolved.level).toEqual(i32(10))
+    expect(resolved.balance).toEqual(u256(1_000_000n))
+    expect(resolved.name).toEqual(str("Bob"))
+    expect(resolved.flagged.type).toBe("bool")
+    expect(resolved.score).toEqual(dec("3.5"))
+  })
+
+  it("reports the attribute count when there are too many", () => {
+    const tooMany = Object.fromEntries(
+      Array.from({ length: MAX_ATTRIBUTES + 1 }, (_, i) => [`a${i}`, i]),
+    )
+    expect(() => resolveAttributes(tooMany)).toThrow(TooManyAttributesError)
+    expect(() => resolveAttributes(tooMany)).toThrow(/at most 32 attributes, got 33/)
+  })
+})
+
+describe("the attribute cap", () => {
+  const attributes = (count: number) =>
+    Object.fromEntries(Array.from({ length: count }, (_, i) => [`a${i}`, i]))
+
+  it("counts the payload and content-type cells, which the engine also counts", () => {
+    // Under the cap on its own, over it once the two system cells are appended. Letting this
+    // through would spend gas on a transaction the engine answers with TooManyAttributes(34, 32).
+    expect(() =>
+      encodeAttributes(attributes(MAX_ATTRIBUTES), {
+        payload: new Uint8Array([1]),
+        contentType: "application/json",
+      }),
+    ).toThrow(/at most 32 attributes, got 34/)
+  })
+
+  it("leaves room for them rather than rejecting a full-but-legal operation", () => {
+    expect(
+      encodeAttributes(attributes(MAX_ATTRIBUTES - 2), {
+        payload: new Uint8Array([1]),
+        contentType: "application/json",
+      }),
+    ).toHaveLength(MAX_ATTRIBUTES)
+  })
+
+  it("counts tombstones in a patch — a removal occupies a cell like any other", () => {
+    expect(() =>
+      encodeMutations({
+        set: attributes(MAX_ATTRIBUTES - 1),
+        unset: ["gone_a", "gone_b"],
+      }),
+    ).toThrow(/at most 32 attributes, got 33/)
+  })
+})
+
+describe("encodeAttributes", () => {
+  it("sorts strictly ascending by the encoded name, whatever order they were written in", () => {
+    const encoded = encodeAttributes({ zebra: 1, apple: 2, mango: 3 })
+    const names = encoded.map((attribute) => attribute.name)
+    expect(names).toEqual([...names].sort())
+    expect(encoded).toHaveLength(3)
+  })
+
+  it("carries each value's typeId", () => {
+    const ids = encodeAttributes({ level: i32(1), score: dec("1"), tag: "x" }).map((a) => a.typeId)
+    expect([...ids].sort()).toEqual([2, 5, 8]) // i32, dec, str
+  })
+
+  it("accepts an empty attribute set", () => {
+    expect(encodeAttributes({})).toEqual([])
+  })
+})
+
+describe("validateAttributeName", () => {
+  it("accepts the Ident32 grammar, in either case", () => {
+    for (const name of ["a", "tag", "Tag", "projectId", "num_attr", "a.b-c_D9", "a".repeat(32)]) {
+      expect(isValidAttributeName(name)).toBe(true)
+    }
+  })
+
+  it("treats names as case-sensitive, so two casings are two attributes", () => {
+    const resolved = resolveAttributes({ level: 1, Level: 2 })
+    expect(resolved.level).toEqual(i32(1))
+    expect(resolved.Level).toEqual(i32(2))
+    expect(encodeAttributes({ level: 1, Level: 2 })).toHaveLength(2)
+  })
+
+  it("rejects names outside the grammar, pointing at the offending character", () => {
+    expect(() => validateAttributeName("")).toThrow(InvalidAttributeNameError)
+    expect(() => validateAttributeName("1tag")).toThrow(/starts with "1"/)
+    expect(() => validateAttributeName("_tag")).toThrow(/starts with "_"/)
+    expect(() => validateAttributeName("has space")).toThrow(/" " at position 3/)
+    expect(() => validateAttributeName("héllo")).toThrow(/"é" at position 1/)
+    expect(() => validateAttributeName("a:b")).toThrow(/":" at position 1/)
+    expect(() => validateAttributeName("a".repeat(33))).toThrow(/33 bytes long/)
+  })
+
+  it("reserves $ for the system attributes the engine sets", () => {
+    expect(() => validateAttributeName("$owner")).toThrow(/reserved for system attributes/)
+  })
+
+  it("rejects names the query language could never parse back, whatever their casing", () => {
+    for (const reserved of ["and", "OR", "Not", "key", "str", "u256", "EXISTS", "Bytes32"]) {
+      expect(() => validateAttributeName(reserved)).toThrow(/reserved by the query language/)
+    }
+    // Only the exact word is reserved — a name containing it is fine.
+    expect(isValidAttributeName("android")).toBe(true)
+    expect(isValidAttributeName("sortKey")).toBe(true)
+  })
+})