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

package/src/utils/arkivTransactions.ts

@@ -2,31 +2,40 @@ import {
   type Address,
   ContractFunctionExecutionError,
   ContractFunctionRevertedError,
-  encodePacked,
+  decodeEventLog,
   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 { 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,137 +48,54 @@ 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[]
+    patches?: PatchEntityParameters[]
     deletes?: DeleteEntityParameters[]
     extensions?: ExtendEntityParameters[]
     ownershipChanges?: ChangeOwnershipParameters[]
@@ -180,76 +106,67 @@ export async function sendArkivTransaction(
   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, patches, deletes, extensions, ownershipChanges } = 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.
+  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 expiryContext = { currentBlock }
+
+  const createOps = (creates ?? []).map((item) => {
+    validateContentType(item.contentType)
 
-  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,
-    })),
+    const salt = item.salt === undefined ? randomSalt() : validateSalt(item.salt)
+    const expiry = resolveExpiry(item.expires, expiryContext)
+
+    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, expiryContext)
+    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,
+      }),
+    ),
   ]
 
-  logger("Sending execute with %d operations %s", operations.length, JSON.stringify(operations))
+  if (operations.length === 0) {
+    throw new Error("No operations to perform")
+  }
+
+  logger("Sending execute with %d operations %o", operations.length, operations)
 
   try {
     const txHash = await walletClient.writeContract({
@@ -278,7 +195,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,8 +208,19 @@ export async function sendArkivTransaction(
       )
     }
 
-    return { receipt, createdEntityKeys }
+    return {
+      receipt,
+      ...readAppliedOperations(receipt, {
+        creates: createOps.length,
+        extensions: extendOps.length,
+      }),
+    }
   } catch (error) {
+    const described = error instanceof EntityMutationError ? undefined : describeEntityRevert(error)
+    if (described !== undefined) {
+      throw new EntityMutationError(`Transaction failed: ${described}`, { cause: error })
+    }
+
     let message = "Transaction failed"
     if (error instanceof TransactionExecutionError) {
       message += `: ${error.details}`
@@ -302,8 +233,68 @@ export async function sendArkivTransaction(
       }
     } else if (error instanceof EntityMutationError) {
       throw error
+    } else if (error instanceof Error) {
+      message += `: ${error.message}`
+    }
+
+    throw 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 createdEntityKeys: Hex[] = []
+  const createdExpiries: bigint[] = []
+  const extendedExpiries: bigint[] = []
+
+  // `?? []` so a receipt without logs is reported by the count check below, which explains what is
+  // missing and that the write succeeded, rather than as a TypeError from this loop.
+  for (const log of receipt.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
+
+    if (decoded.eventName === "EntityCreated") {
+      createdEntityKeys.push(decoded.args.entityKey)
+      createdExpiries.push(decoded.args.expiresAt)
+    } else if (decoded.eventName === "ExpiryExtended") {
+      extendedExpiries.push(decoded.args.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 }
+}
 
-    throw new EntityMutationError(message)
+/** 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.`,
+  )
+}

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()
+  })
+})