@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/schema/attributes.test.ts

@@ -0,0 +1,266 @@
+import { describe, expect, it } from "bun:test"
+import { hexToString } from "viem"
+import { encodeCreate, encodePatch, MAX_ENTITY_BYTES } from "./attributes"
+import {
+  ConflictingMutationError,
+  EntityTooLargeError,
+  InvalidAttributeNameError,
+  InvalidValueError,
+  MissingValueError,
+  SchemaDefinitionError,
+  SchemaMismatchError,
+} from "./errors"
+import { isValidAttributeName, validateAttributeName } from "./names"
+import { defineSchema, type Schema } from "./schema"
+import { INDEXED_FLAG, TYPE_IDS } from "./types"
+import { bytes, dec, i32, str, u64 } from "./values"
+
+const Posts = defineSchema({
+  category: str().indexed(),
+  score: dec().indexed().optional(),
+  title: str(),
+  body: bytes(),
+  thumbnail: bytes().optional(),
+  mimeType: str().default("text/markdown"),
+})
+
+/** The encoded attributes keyed by their decoded name, for asserting on one at a time. */
+function byName(attributes: ReturnType<typeof encodeCreate>) {
+  return Object.fromEntries(
+    attributes.map((attribute) => [hexToString(attribute.name, { size: 32 }), attribute]),
+  )
+}
+
+describe("encodeCreate", () => {
+  const values = { category: "docs", title: "Hello", body: new Uint8Array([1, 2]) }
+
+  it("flags indexed columns in bit 7 of the typeId, and leaves the rest unflagged", () => {
+    const encoded = byName(encodeCreate(Posts, { ...values, score: dec("4.1") }))
+    expect(encoded.category?.typeId).toBe(TYPE_IDS.str | INDEXED_FLAG)
+    expect(encoded.score?.typeId).toBe(TYPE_IDS.dec | INDEXED_FLAG)
+    expect(encoded.title?.typeId).toBe(TYPE_IDS.str)
+    expect(encoded.body?.typeId).toBe(TYPE_IDS.bytes)
+  })
+
+  it("writes a defaulted column left out with its default", () => {
+    const encoded = byName(encodeCreate(Posts, values))
+    expect(hexToString(encoded.mimeType?.value ?? "0x")).toBe("text/markdown")
+  })
+
+  it("prefers a given value over the default", () => {
+    const encoded = byName(encodeCreate(Posts, { ...values, mimeType: "text/plain" }))
+    expect(hexToString(encoded.mimeType?.value ?? "0x")).toBe("text/plain")
+  })
+
+  it("leaves out an optional column that is not given, or given as undefined", () => {
+    expect(byName(encodeCreate(Posts, values)).thumbnail).toBeUndefined()
+    expect(
+      byName(encodeCreate(Posts, { ...values, thumbnail: undefined })).thumbnail,
+    ).toBeUndefined()
+  })
+
+  it("carries any number of bytes columns", () => {
+    const encoded = byName(encodeCreate(Posts, { ...values, thumbnail: bytes("0xffd8") }))
+    expect(encoded.body?.value).toBe("0x0102")
+    expect(encoded.thumbnail?.value).toBe("0xffd8")
+  })
+
+  it("sorts strictly ascending by the encoded name, whatever order the schema declares", () => {
+    const names = encodeCreate(Posts, values).map((attribute) => attribute.name)
+    expect(names).toEqual([...names].sort())
+  })
+
+  it("rejects a required column left out, naming it", () => {
+    const { title: _, ...withoutTitle } = values
+    expect(() => encodeCreate(Posts, withoutTitle)).toThrow(SchemaMismatchError)
+    expect(() => encodeCreate(Posts, withoutTitle)).toThrow(/"title".*required str column/)
+  })
+
+  it("rejects a column the schema does not have", () => {
+    expect(() => encodeCreate(Posts, { ...values, extra: 1 })).toThrow(/"extra".*does not have/)
+  })
+
+  it("rejects a value of another type than its column, bare or tagged", () => {
+    // A bare string is a str, never a dec — the schema does not reinterpret it.
+    expect(() => encodeCreate(Posts, { ...values, score: "4.1" })).toThrow(
+      /"score": a dec column, but the value is a str/,
+    )
+    expect(() => encodeCreate(Posts, { ...values, title: i32(1) })).toThrow(SchemaMismatchError)
+  })
+
+  it("rejects null rather than treating it as absent", () => {
+    expect(() => encodeCreate(Posts, { ...values, thumbnail: null })).toThrow(MissingValueError)
+  })
+
+  it("rejects a column where a value belongs", () => {
+    expect(() => encodeCreate(Posts, { ...values, title: str() })).toThrow(/a column, not a value/)
+  })
+
+  it("rejects something that is not a schema", () => {
+    expect(() => encodeCreate({ columns: {} } as unknown as Schema, {})).toThrow(
+      SchemaDefinitionError,
+    )
+  })
+
+  it("accepts an empty schema, which writes no attributes", () => {
+    expect(encodeCreate(defineSchema({}), {})).toEqual([])
+  })
+})
+
+describe("a named schema's tag", () => {
+  const Tagged = defineSchema("posts", { title: str() })
+
+  it("is written on every create, as an indexed str", () => {
+    const encoded = byName(encodeCreate(Tagged, { title: "Hi" }))
+    expect(encoded["arkiv.schema"]?.typeId).toBe(TYPE_IDS.str | INDEXED_FLAG)
+    expect(hexToString(encoded["arkiv.schema"]?.value ?? "0x")).toBe("posts")
+  })
+
+  it("is not written by an unnamed schema", () => {
+    expect(
+      byName(encodeCreate(Posts, { category: "c", title: "t", body: new Uint8Array() }))[
+        "arkiv.schema"
+      ],
+    ).toBeUndefined()
+  })
+
+  it("is not touched by a patch, which changes only what it names", () => {
+    expect(byName(encodePatch(Tagged, { set: { title: "Hi" } }))["arkiv.schema"]).toBeUndefined()
+  })
+
+  it("cannot be written or unset as a column", () => {
+    expect(() => encodeCreate(Tagged, { title: "Hi", "arkiv.schema": "other" })).toThrow(
+      SchemaMismatchError,
+    )
+    expect(() => encodePatch(Tagged, { unset: ["arkiv.schema"] as never })).toThrow(
+      SchemaMismatchError,
+    )
+  })
+})
+
+describe("encodePatch", () => {
+  it("writes only what it names, with each column's indexed flag", () => {
+    const encoded = byName(encodePatch(Posts, { set: { category: "news", title: "Hi" } }))
+    expect(Object.keys(encoded).sort()).toEqual(["category", "title"])
+    expect(encoded.category?.typeId).toBe(TYPE_IDS.str | INDEXED_FLAG)
+    expect(encoded.title?.typeId).toBe(TYPE_IDS.str)
+  })
+
+  it("does not apply defaults — a patch changes only what it names", () => {
+    expect(byName(encodePatch(Posts, { set: { title: "Hi" } })).mimeType).toBeUndefined()
+  })
+
+  it("tombstones an optional column", () => {
+    const [tombstone] = encodePatch(Posts, { unset: ["thumbnail"] })
+    expect(tombstone).toMatchObject({ typeId: 0, value: "0x" })
+  })
+
+  it("refuses to unset a required column", () => {
+    expect(() => encodePatch(Posts, { unset: ["title"] as never })).toThrow(
+      /"title": a required column/,
+    )
+  })
+
+  it("refuses to unset or set a column the schema does not have", () => {
+    expect(() => encodePatch(Posts, { unset: ["nope"] as never })).toThrow(SchemaMismatchError)
+    expect(() => encodePatch(Posts, { set: { nope: 1 } })).toThrow(SchemaMismatchError)
+  })
+
+  it("rejects a name that is both set and unset", () => {
+    expect(() =>
+      encodePatch(Posts, { set: { thumbnail: new Uint8Array() }, unset: ["thumbnail"] }),
+    ).toThrow(ConflictingMutationError)
+  })
+
+  it("rejects a set value of the wrong type", () => {
+    expect(() => encodePatch(Posts, { set: { score: 4 } })).toThrow(SchemaMismatchError)
+  })
+
+  it("sorts writes and tombstones together", () => {
+    const names = encodePatch(Posts, { set: { title: "t", category: "c" }, unset: ["score"] }).map(
+      (attribute) => attribute.name,
+    )
+    expect(names).toEqual([...names].sort())
+  })
+
+  it("rejects an unset that is not an array", () => {
+    expect(() => encodePatch(Posts, { unset: "thumbnail" as never })).toThrow(TypeError)
+  })
+})
+
+describe("bytes", () => {
+  it("is never an indexed column's type", () => {
+    expect(() =>
+      encodeCreate(defineSchema({ n: u64().indexed() }), { n: bytes("0x01") as never }),
+    ).toThrow(/a u64 column, but the value is a bytes/)
+  })
+
+  it("rejects a value over the 128 KiB cap", () => {
+    expect(() =>
+      encodeCreate(Posts, {
+        category: "c",
+        title: "t",
+        body: new Uint8Array(128 * 1024 + 1),
+      }),
+    ).toThrow(InvalidValueError)
+  })
+})
+
+describe("the total bytes cap", () => {
+  const half = new Uint8Array(MAX_ENTITY_BYTES / 2)
+  const base = { category: "docs", title: "Hello" }
+
+  it("accepts bytes columns that add up to the cap", () => {
+    expect(() => encodeCreate(Posts, { ...base, body: half, thumbnail: half })).not.toThrow()
+  })
+
+  it("rejects a create whose bytes columns add up to more", () => {
+    const over = new Uint8Array(MAX_ENTITY_BYTES / 2 + 1)
+    expect(() => encodeCreate(Posts, { ...base, body: half, thumbnail: over })).toThrow(
+      EntityTooLargeError,
+    )
+  })
+
+  it("applies to a patch's writes too", () => {
+    const over = new Uint8Array(MAX_ENTITY_BYTES / 2 + 1)
+    expect(() => encodePatch(Posts, { set: { body: half, thumbnail: over } })).toThrow(
+      /at most 131072 bytes in total, got 131073/,
+    )
+  })
+})
+
+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 schema = defineSchema({ level: i32(), Level: i32() })
+    expect(encodeCreate(schema, { 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", "Between", "key", "str", "bytes", "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)
+  })
+})

package/src/schema/attributes.ts

@@ -0,0 +1,212 @@
+import { type AbiAttribute, encodeAbiAttribute, encodeTombstone } from "./codec"
+import type { AnyColumn } from "./column"
+import {
+  ConflictingMutationError,
+  EntityTooLargeError,
+  SchemaDefinitionError,
+  SchemaMismatchError,
+} from "./errors"
+import { describeColumns, isSchema, lookupColumn, SCHEMA_ATTRIBUTE, type Schema } from "./schema"
+import { type ArkivValue, INDEXED_FLAG, TYPE_IDS, type TypeTag } from "./types"
+import { toValue, type ValueInput } from "./values"
+
+/**
+ * The most data the `bytes` columns of one create or patch may hold together, in bytes. Each
+ * `bytes` value is also capped on its own, at `MAX_BYTES_LENGTH`.
+ *
+ * Provisional: the protocol has not settled a per-entity cap yet, so this keeps the budget the
+ * single payload had — and an operation much larger than it would not fit in a transaction the
+ * node accepts anyway.
+ */
+export const MAX_ENTITY_BYTES = 128 * 1024
+
+/**
+ * An entity's attributes as a whole — what the `$attributes` selection returns — keyed by name,
+ * every value typed.
+ *
+ * The vocabulary is the same in both directions, so a value read from here drops straight back into
+ * a write — as long as its name is a column of the schema the write goes through.
+ */
+export type Attributes = Readonly<Record<string, ArkivValue>>
+
+/**
+ * The names, types and indexing of an entity's attributes, with no values — what the
+ * `$attributeSchema` selection returns. `indexed` is `undefined` when the node did not say.
+ *
+ * It is for finding out what entities hold before fetching their values. Values can be large — a
+ * `bytes` attribute holds up to 128 KiB — and an RPC endpoint may cap how big a response it sends,
+ * so a page of 100 entities with every attribute can be more than it will return. The schema is a
+ * few bytes per attribute: select it for a page, then fetch the attributes you need by name, or the
+ * large ones a few entities at a time.
+ *
+ * It also tells apart two entities that use the same name with different types, and shows which
+ * attributes are indexed, and so can be filtered on.
+ */
+export type AttributeSchema = Readonly<
+  Record<string, { type: TypeTag; indexed: boolean | undefined }>
+>
+
+/**
+ * Encodes a create's values into the ABI attribute array it carries: every column the
+ * values name, plus the default of every defaulted column they leave out, each flagged indexed or
+ * not as its column says — and, for a named schema, the indexed tag that marks the entity as its.
+ *
+ * @throws {SchemaDefinitionError} If `schema` is not a schema built with `defineSchema`.
+ * @throws {TypeError} If `values` is not an object.
+ * @throws {SchemaMismatchError} If a value names a column the schema lacks, a required column is
+ * left out, or a value's type is not its column's.
+ * @throws {MissingValueError} If a value is `null`.
+ * @throws {UntypedValueError} If a value is neither a tagged value nor a bare form.
+ * @throws {InvalidValueError} If a value does not fit its type.
+ * @throws {EntityTooLargeError} If the `bytes` values add up to more than {@link MAX_ENTITY_BYTES}.
+ */
+export function encodeCreate(
+  schema: Schema,
+  values: Readonly<Record<string, unknown>>,
+): AbiAttribute[] {
+  assertSchema(schema)
+  for (const name of keysOf(values, "create")) columnFor(schema, name, "create")
+
+  const attributes: AbiAttribute[] = []
+  if (schema.tag !== undefined) {
+    attributes.push(encodeAbiAttribute(SCHEMA_ATTRIBUTE, schema.tag, true))
+  }
+  for (const [name, column] of Object.entries(schema.columns)) {
+    const input = Object.hasOwn(values, name) ? values[name] : undefined
+    if (input === undefined) {
+      if (column.defaultValue !== undefined) {
+        attributes.push(encodeAbiAttribute(name, column.defaultValue, column.isIndexed))
+      } else if (!column.isOptional) {
+        throw new SchemaMismatchError(
+          name,
+          `the create leaves out a required ${column.type} column. Give it a value, or declare ` +
+            `it ${column.type}().optional() or with a .default(...)`,
+        )
+      }
+      continue
+    }
+    attributes.push(encodeColumn(name, column, input))
+  }
+  assertBytesFit(attributes)
+  return attributes.sort(byName)
+}
+
+/**
+ * Encodes a patch into the ABI attribute array it carries: a write for each column in `set`, with
+ * the indexed flag its column declares, and a tombstone for each name in `unset`. A column `set`
+ * to `undefined` is left out, as it is from a create.
+ *
+ * Writing a column with a different indexed flag than the entity holds flips its indexing, so a
+ * schema that marks a column `.indexed()` indexes it from the next patch that writes it.
+ *
+ * @throws {SchemaDefinitionError} If `schema` is not a schema built with `defineSchema`.
+ * @throws {SchemaMismatchError} If a name is not a column, a value's type is not its column's, or
+ * `unset` names a required column.
+ * @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
+ * @throws {MissingValueError} If a value in `set` is `null`.
+ * @throws {UntypedValueError} If a value in `set` is neither a tagged value nor a bare form.
+ * @throws {InvalidValueError} If a value does not fit its type.
+ * @throws {EntityTooLargeError} If the `bytes` values in `set` add up to more than
+ * {@link MAX_ENTITY_BYTES}.
+ * @throws {TypeError} If `set` is not an object, or `unset` is not an array.
+ */
+export function encodePatch(
+  schema: Schema,
+  {
+    set = {},
+    unset = [],
+  }: {
+    set?: Readonly<Record<string, unknown>> | undefined
+    unset?: readonly string[] | undefined
+  },
+): AbiAttribute[] {
+  assertSchema(schema)
+
+  const mutations: AbiAttribute[] = []
+  for (const name of keysOf(set, "patch")) {
+    const column = columnFor(schema, name, "patch")
+    const input = set[name]
+    if (input !== undefined) mutations.push(encodeColumn(name, column, input))
+  }
+
+  if (!Array.isArray(unset)) {
+    throw new TypeError(`"unset" must be an array of column names`)
+  }
+  for (const name of new Set(unset)) {
+    const column = columnFor(schema, name, "patch")
+    if (!column.isOptional) {
+      throw new SchemaMismatchError(
+        name,
+        "a required column, so unsetting it would leave the entity without a value its schema " +
+          `requires. Declare it ${column.type}().optional() to allow that`,
+      )
+    }
+    if (Object.hasOwn(set, name) && set[name] !== undefined) {
+      throw new ConflictingMutationError(name)
+    }
+    mutations.push(encodeTombstone(name))
+  }
+  assertBytesFit(mutations)
+  return mutations.sort(byName)
+}
+
+function assertSchema(schema: Schema): void {
+  if (!isSchema(schema)) {
+    throw new SchemaDefinitionError(
+      "expected a schema built with defineSchema(...) — writes are typed by the schema they name",
+    )
+  }
+}
+
+function keysOf(
+  values: Readonly<Record<string, unknown>>,
+  operation: "create" | "patch",
+): string[] {
+  if (typeof values !== "object" || values === null) {
+    throw new TypeError(`The ${operation} values must be an object keyed by column name`)
+  }
+  return Object.keys(values)
+}
+
+function columnFor(schema: Schema, name: string, operation: "create" | "patch"): AnyColumn {
+  const column = lookupColumn(schema, name)
+  if (column === undefined) {
+    throw new SchemaMismatchError(
+      name,
+      `the ${operation} names a column this schema does not have. Its columns are ` +
+        describeColumns(schema),
+    )
+  }
+  return column
+}
+
+/** One column's value, resolved, checked against the column's type, and encoded. */
+function encodeColumn(name: string, column: AnyColumn, input: unknown): AbiAttribute {
+  const value = toValue(input as ValueInput, name)
+  if (value.type !== column.type) {
+    throw new SchemaMismatchError(
+      name,
+      `a ${column.type} column, but the value is a ${value.type}. Write ${column.type}(...) ` +
+        "around the value",
+    )
+  }
+  return encodeAbiAttribute(name, value, column.isIndexed)
+}
+
+/** Throws if the `bytes` values among `attributes` add up to more than {@link MAX_ENTITY_BYTES}. */
+function assertBytesFit(attributes: readonly AbiAttribute[]): void {
+  let total = 0
+  for (const { typeId, value } of attributes) {
+    if ((typeId & ~INDEXED_FLAG) === TYPE_IDS.bytes) total += (value.length - 2) / 2
+  }
+  if (total > MAX_ENTITY_BYTES) throw new EntityTooLargeError(total, MAX_ENTITY_BYTES)
+}
+
+/**
+ * The engine requires attributes **strictly ascending by their `bytes32` name**: that ordering is
+ * what the canonical serialization hashes into the state root, and it doubles as the uniqueness
+ * check.
+ */
+function byName(a: AbiAttribute, b: AbiAttribute): number {
+  return a.name < b.name ? -1 : a.name > b.name ? 1 : 0
+}

package/src/{attr → schema}/codec.test.ts

@@ -2,6 +2,7 @@ import { describe, expect, it } from "bun:test"
 import type { Hex } from "viem"
 import {
   decodeRpcValue,
+  decodeTypeId,
   decodeValueBytes,
   encodeAbiAttribute,
   encodeTombstone,
@@ -9,13 +10,13 @@ import {
 } from "./codec"
 import { InvalidValueError, UnknownAttributeTypeError } from "./errors"
 import type { ArkivValue } from "./types"
-import { addr, bool, bytes32, dec, i32, key, str, u64, u256 } from "./values"
+import { addr, bool, bytes, bytes32, dec, i32, key, str, u64, u256 } from "./values"
 
 const ZERO = `0x${"00".repeat(32)}` as Hex
 const KEY = `0x${"ab".repeat(32)}` as Hex
 const VITALIK = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
 
-/** One value of every user-settable type, including the awkward edges of each. */
+/** One value of every type, including the awkward edges of each. */
 const SAMPLES: ArkivValue[] = [
   bool(true),
   bool(false),
@@ -37,6 +38,8 @@ const SAMPLES: ArkivValue[] = [
   str(""),
   str("hello"),
   str("é".repeat(64)),
+  bytes(new Uint8Array()),
+  bytes("0xdeadbeef"),
 ]
 
 describe("ABI value encoding", () => {
@@ -50,7 +53,7 @@ describe("ABI value encoding", () => {
 
   it("gives every word type exactly 32 bytes", () => {
     for (const value of SAMPLES) {
-      if (value.type === "str") continue
+      if (value.type === "str" || value.type === "bytes") continue
       expect(encodeValueBytes(value)).toHaveLength(2 + 64)
     }
   })
@@ -83,6 +86,11 @@ describe("ABI value encoding", () => {
     expect(encodeValueBytes(str("é"))).toBe("0xc3a9")
   })
 
+  it("gives bytes their raw bytes, with no padding", () => {
+    expect(encodeValueBytes(bytes("0xdeadbeef"))).toBe("0xdeadbeef")
+    expect(encodeValueBytes(bytes(new Uint8Array()))).toBe("0x")
+  })
+
   it("rejects a word a well-formed encoder would not have produced", () => {
     expect(() => decodeValueBytes("bool", `0x${"00".repeat(31)}02`)).toThrow(/exactly 0 or 1/)
     expect(() => decodeValueBytes("u256", "0x2a")).toThrow(/must be 32 bytes, got 1/)
@@ -97,12 +105,23 @@ describe("ABI value encoding", () => {
 
 describe("encodeAbiAttribute", () => {
   it("packs the name left-aligned into its bytes32 cell", () => {
-    const attribute = encodeAbiAttribute("level", i32(10))
+    const attribute = encodeAbiAttribute("level", i32(10), false)
     // "level" is 6c6576656c, null-padded to 32 bytes.
     expect(attribute.name).toBe(`0x6c6576656c${"00".repeat(27)}`)
     expect(attribute.typeId).toBe(2)
   })
 
+  it("sets bit 7 of the typeId for an indexed attribute, and only that bit", () => {
+    expect(encodeAbiAttribute("level", i32(10), true).typeId).toBe(0x82)
+    expect(encodeAbiAttribute("tag", str("x"), true).typeId).toBe(0x88)
+    expect(encodeAbiAttribute("tag", str("x"), false).typeId).toBe(0x08)
+  })
+
+  it("refuses to index bytes, which the engine would revert", () => {
+    expect(() => encodeAbiAttribute("body", bytes("0x01"), true)).toThrow(/never indexed/)
+    expect(encodeAbiAttribute("body", bytes("0x01"), false).typeId).toBe(7)
+  })
+
   it("encodes a tombstone as a zero-length value under typeId 0", () => {
     expect(encodeTombstone("flagged")).toEqual({
       name: `0x666c6167676564${"00".repeat(25)}`,
@@ -112,6 +131,19 @@ describe("encodeAbiAttribute", () => {
   })
 })
 
+describe("decodeTypeId", () => {
+  it("splits the type from the indexed flag", () => {
+    expect(decodeTypeId(0x88)).toEqual({ tag: "str", indexed: true })
+    expect(decodeTypeId(0x07)).toEqual({ tag: "bytes", indexed: false })
+    expect(decodeTypeId(0x87)).toEqual({ tag: "bytes", indexed: true })
+  })
+
+  it("rejects a type it does not know, flagged or not", () => {
+    expect(() => decodeTypeId(0x7f)).toThrow(UnknownAttributeTypeError)
+    expect(() => decodeTypeId(0x80)).toThrow(UnknownAttributeTypeError)
+  })
+})
+
 describe("decodeRpcValue", () => {
   it("reads the JSON encoding each type declares", () => {
     expect(decodeRpcValue("bool", true).value).toBe(true)
@@ -133,7 +165,7 @@ describe("decodeRpcValue", () => {
     expect(decodeRpcValue("i32", "-42").value).toBe(-42)
   })
 
-  it("decodes the system-only bytes type, which only ever arrives as a payload", () => {
+  it("decodes bytes as lowercase hex", () => {
     expect(decodeRpcValue("bytes", "0xDEADBEEF").value).toBe("0xdeadbeef")
   })
 

package/src/{attr → schema}/codec.ts

@@ -1,7 +1,14 @@
 import { bytesToString, type Hex, hexToBytes, pad, size, stringToBytes, toHex } from "viem"
 import { unitsToDecimal } from "./decimal"
 import { InvalidValueError, UnknownAttributeTypeError } from "./errors"
-import { type AnyArkivValue, makeValue, type StrValue, TYPE_IDS, type TypeTag } from "./types"
+import {
+  type ArkivValue,
+  INDEXED_FLAG,
+  makeValue,
+  type StrValue,
+  TYPE_IDS,
+  type TypeTag,
+} from "./types"
 import { addr, bool, bytes32, dec, decUnits, i32, key, u64, u256 } from "./values"
 
 function strFromChain(value: string): StrValue {
@@ -12,13 +19,14 @@ function strFromChain(value: string): StrValue {
  * The `typeId` marking a tombstone — an attribute being unset. It carries a zero-length value and
  * is legal only in a patch's mutation list, never in a create.
  */
-export const TOMBSTONE_TYPE_ID = 0
+const TOMBSTONE_TYPE_ID = 0
 
 /**
  * An attribute in its ABI form: `(Ident32 name, uint8 typeId, bytes value)`.
  *
- * The `value` encoding is selected by `typeId`: an exact 32-byte word for the word types, the raw
- * bytes for `str` and `bytes`, and zero-length for a tombstone.
+ * The low seven bits of `typeId` select the type, and bit 7 ({@link INDEXED_FLAG}) says whether
+ * the node indexes the attribute. The `value` encoding is selected by the type: an exact 32-byte
+ * word for the word types, the raw bytes for `str` and `bytes`, and zero-length for a tombstone.
  */
 export type AbiAttribute = {
   name: Hex
@@ -35,7 +43,7 @@ export type AbiAttribute = {
  *   bytes, in the encoding Solidity would use — right-aligned, and sign-extended for `i32`.
  * - `str` becomes its raw UTF-8 bytes, and `bytes` its raw bytes: variable length, no padding.
  */
-export function encodeValueBytes(value: AnyArkivValue): Hex {
+export function encodeValueBytes(value: ArkivValue): Hex {
   switch (value.type) {
     case "bool":
       return pad(value.value ? "0x01" : "0x00", { size: 32 })
@@ -66,7 +74,7 @@ export function encodeValueBytes(value: AnyArkivValue): Hex {
  * 32 bytes, an `i32` that is not sign-extended, a `bool` that is neither 0 nor 1 — rather than
  * silently truncating it.
  */
-export function decodeValueBytes(tag: TypeTag, value: Hex): AnyArkivValue {
+export function decodeValueBytes(tag: TypeTag, value: Hex): ArkivValue {
   if (tag === "str") return strFromChain(bytesToString(hexToBytes(value)))
   if (tag === "bytes") return makeValue("bytes", value.toLowerCase() as Hex)
 
@@ -118,18 +126,39 @@ export function decodeValueBytes(tag: TypeTag, value: Hex): AnyArkivValue {
 /**
  * Encodes a named, typed attribute into its ABI form.
  *
- * @param name - The attribute name. Assumed already validated, or a system (`$`) name the SDK sets
- * itself.
+ * @param name - The attribute name. Assumed already validated.
+ * @param indexed - Whether the node should index it. Never true for `bytes`, which the engine
+ * rejects with the flag set.
+ * @throws {InvalidValueError} If asked to index a `bytes` value.
  */
-export function encodeAbiAttribute(name: string, value: AnyArkivValue): AbiAttribute {
+export function encodeAbiAttribute(
+  name: string,
+  value: ArkivValue,
+  indexed: boolean,
+): AbiAttribute {
+  if (indexed && value.type === "bytes") {
+    throw new InvalidValueError("bytes", `<${name}>`, "bytes are stored, never indexed")
+  }
   return {
     // Ident32 is left-aligned and null-padded, which is what `toHex` does for a string.
     name: toHex(name, { size: 32 }),
-    typeId: TYPE_IDS[value.type],
+    typeId: TYPE_IDS[value.type] | (indexed ? INDEXED_FLAG : 0),
     value: encodeValueBytes(value),
   }
 }
 
+/**
+ * Splits a wire `typeId` into its type and indexed flag.
+ *
+ * @throws {UnknownAttributeTypeError} If the low seven bits name no known type.
+ */
+export function decodeTypeId(typeId: number): { tag: TypeTag; indexed: boolean } {
+  const base = typeId & ~INDEXED_FLAG
+  const tag = (Object.keys(TYPE_IDS) as TypeTag[]).find((candidate) => TYPE_IDS[candidate] === base)
+  if (tag === undefined) throw new UnknownAttributeTypeError(typeId)
+  return { tag, indexed: (typeId & INDEXED_FLAG) !== 0 }
+}
+
 /** Encodes a tombstone — the mutation that unsets `name`. Legal only in a patch. */
 export function encodeTombstone(name: string): AbiAttribute {
   return { name: toHex(name, { size: 32 }), typeId: TOMBSTONE_TYPE_ID, value: "0x" }
@@ -149,7 +178,7 @@ export function encodeTombstone(name: string): AbiAttribute {
  * @throws {UnknownAttributeTypeError} If the tag names no known type.
  * @throws {InvalidValueError} If the value does not parse as that type.
  */
-export function decodeRpcValue(type: string, value: unknown): AnyArkivValue {
+export function decodeRpcValue(type: string, value: unknown): ArkivValue {
   const tag = asTypeTag(type)
   switch (tag) {
     case "bool":