@arkiv-network/sdk 0.6.8-dev.5 → 0.7.0-dev.1

package/dist/types/index.js

@@ -1 +1,4 @@
-import "../types-H-TSmRpm.js";
+import { n as EntityOperationType } from "../entity-DGfVyB-a.js";
+import "../types-Ci4BRClw.js";
+
+export { EntityOperationType };

package/dist/utils/index.cjs

@@ -1,5 +1,5 @@
-const require_consts = require('../consts-AUoL-v42.cjs');
-const require_payload = require('../payload-DpA5PA-w.cjs');
+const require_consts = require('../consts-CxT1-RXU.cjs');
+const require_payload = require('../payload-D8YLKcJj.cjs');
 
 //#region src/utils/expirationTime.ts
 const ExpirationTime = {

package/dist/utils/index.d.ts

@@ -1,4 +1,4 @@
-import { n as stringToPayload, t as jsonToPayload } from "../payload-B2kFJyah.js";
+import { n as stringToPayload, t as jsonToPayload } from "../payload-C2KHOUoj.js";
 
 //#region src/utils/expirationTime.d.ts
 declare const ExpirationTime: {

package/dist/utils/index.js

@@ -1,5 +1,5 @@
-import { n as BLOCK_TIME } from "../consts-BV4PR-de.js";
-import { n as stringToPayload, t as jsonToPayload } from "../payload-Claf2jUO.js";
+import { n as BLOCK_TIME } from "../consts-Bz0LZQZY.js";
+import { n as stringToPayload, t as jsonToPayload } from "../payload-BpNUPOnY.js";
 
 //#region src/utils/expirationTime.ts
 const ExpirationTime = {

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkiv-network/sdk",
-  "version": "0.6.8-dev.5",
+  "version": "0.7.0-dev.1",
   "description": "TypeScript client library for Arkiv's blockchains interactions",
   "type": "module",
   "target": "esnext",

package/src/actions/public/subscribeEntityEvents.ts

@@ -1,6 +1,7 @@
-import { decodeEventLog, type Hex, parseAbi, toHex } from "viem"
+import { decodeEventLog, type Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { PublicArkivClient } from "../../clients/createPublicClient"
+import { EntityOperationType } from "../../types/entity"
 import type {
   OnEntityCreatedEvent,
   OnEntityDeletedEvent,
@@ -9,18 +10,12 @@ import type {
   OnEntityOwnerChangedEvent,
   OnEntityUpdatedEvent,
 } from "../../types/events"
+import { ENTITY_OPERATION_EVENT_ABI } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:public:subscribe-entity-events")
 
-export const arkivABI = parseAbi([
-  "event ArkivEntityCreated(uint256 indexed entityKey, address indexed ownerAddress, uint256 expirationBlock, uint256 cost)",
-  "event ArkivEntityUpdated(uint256 indexed entityKey, address indexed ownerAddress, uint256 oldExpirationBlock, uint256 newExpirationBlock, uint256 cost)",
-  "event ArkivEntityExpired(uint256 indexed entityKey, address indexed ownerAddress)",
-  "event ArkivEntityDeleted(uint256 indexed entityKey, address indexed ownerAddress)",
-  "event ArkivEntityBTLExtended(uint256 indexed entityKey, address indexed ownerAddress, uint256 oldExpirationBlock, uint256 newExpirationBlock, uint256 cost)",
-  "event ArkivEntityOwnerChanged(uint256 indexed entityKey, address indexed oldOwnerAddress, address indexed newOwnerAddress)",
-])
+export const arkivABI = ENTITY_OPERATION_EVENT_ABI
 
 export async function subscribeEntityEvents(
   client: ArkivClient,
@@ -57,54 +52,33 @@ export async function subscribeEntityEvents(
           data: log.data,
         })
         logger("event from subscribeEntityEvents %o", event)
-        switch (event.eventName) {
-          case "ArkivEntityCreated":
-            onEntityCreated?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              owner: event.args.ownerAddress,
-              expirationBlock: Number(event.args.expirationBlock),
-              cost: event.args.cost,
-            })
-            break
-          case "ArkivEntityUpdated":
-            onEntityUpdated?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              owner: event.args.ownerAddress,
-              oldExpirationBlock: Number(event.args.oldExpirationBlock),
-              newExpirationBlock: Number(event.args.newExpirationBlock),
-              cost: event.args.cost,
-            })
+
+        if (event.eventName !== "EntityOperation") continue
+
+        const entityKey = event.args.entityKey as Hex
+        const owner = event.args.owner
+        const expiresAt = event.args.expiresAt
+        const entityHash = event.args.entityHash as Hex
+        const opType = Number(event.args.operationType)
+
+        switch (opType) {
+          case EntityOperationType.Create:
+            onEntityCreated?.({ entityKey, owner, expiresAt, entityHash })
             break
-          case "ArkivEntityDeleted":
-            onEntityDeleted?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              owner: event.args.ownerAddress,
-            })
+          case EntityOperationType.Update:
+            onEntityUpdated?.({ entityKey, owner, expiresAt, entityHash })
             break
-          case "ArkivEntityBTLExtended":
-            onEntityExpiresInExtended?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              owner: event.args.ownerAddress,
-              oldExpirationBlock: Number(event.args.oldExpirationBlock),
-              newExpirationBlock: Number(event.args.newExpirationBlock),
-              cost: event.args.cost,
-            })
+          case EntityOperationType.Extend:
+            onEntityExpiresInExtended?.({ entityKey, owner, expiresAt, entityHash })
             break
-          case "ArkivEntityExpired":
-            onEntityExpired?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              owner: event.args.ownerAddress,
-            })
+          case EntityOperationType.Transfer:
+            onEntityOwnerChanged?.({ entityKey, owner, entityHash })
             break
-          case "ArkivEntityOwnerChanged":
-            onEntityOwnerChanged?.({
-              entityKey: toHex(event.args.entityKey, { size: 32 }),
-              oldOwner: event.args.oldOwnerAddress,
-              newOwner: event.args.newOwnerAddress,
-            })
+          case EntityOperationType.Delete:
+            onEntityDeleted?.({ entityKey, owner })
             break
           default:
-            console.warn("unknown event from subscribeEntityEvents", event)
+            onEntityExpired?.({ entityKey, owner })
             break
         }
       }

package/src/actions/wallet/changeOwnership.ts

@@ -1,14 +1,15 @@
 import type { Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:change-ownership")
 
 /**
- * Parameters for the deleteEntity function.
- * - entityKey: The key of the entity to delete.
+ * Parameters for the changeOwnership function.
+ * - entityKey: The key of the entity.
+ * - newOwner: The address of the new owner.
  */
 export type ChangeOwnershipParameters = {
   entityKey: Hex
@@ -16,7 +17,7 @@ export type ChangeOwnershipParameters = {
 }
 
 /**
- * Return type for the deleteEntity function.
+ * Return type for the changeOwnership function.
  * - entityKey: The key of the entity.
  * - txHash: The transaction hash.
  */
@@ -31,8 +32,7 @@ export async function changeOwnership(
   txParams?: TxParams,
 ): Promise<ChangeOwnershipReturnType> {
   logger("changeOwnership %o", data)
-  const txData = opsToTxData({ ownershipChanges: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt } = await sendArkivTransaction(client, { ownershipChanges: [data] }, txParams)
 
   logger("Receipt from changeOwnership %o", receipt)
 

package/src/actions/wallet/createEntity.ts

@@ -1,7 +1,7 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { Attribute, MimeType, TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:create-entity")
@@ -46,13 +46,16 @@ export async function createEntity(
   txParams?: TxParams,
 ): Promise<CreateEntityReturnType> {
   logger("createEntity %o", data)
-  const txData = opsToTxData({ creates: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt, createdEntityKeys } = await sendArkivTransaction(
+    client,
+    { creates: [data] },
+    txParams,
+  )
 
   logger("Receipt from createEntity %o", receipt)
 
   return {
     txHash: receipt.transactionHash as Hash,
-    entityKey: receipt.logs[0].topics[1] as Hex,
+    entityKey: createdEntityKeys[0],
   }
 }

package/src/actions/wallet/deleteEntity.ts

@@ -1,7 +1,7 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:delete-entity")
@@ -30,8 +30,7 @@ export async function deleteEntity(
   txParams?: TxParams,
 ): Promise<DeleteEntityReturnType> {
   logger("deleteEntity %o", data)
-  const txData = opsToTxData({ deletes: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt } = await sendArkivTransaction(client, { deletes: [data] }, txParams)
 
   logger("Receipt from deleteEntity %o", receipt)
 

package/src/actions/wallet/extendEntity.ts

@@ -1,7 +1,7 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:extend-entity")
@@ -37,13 +37,12 @@ export async function extendEntity(
   txParams?: TxParams,
 ): Promise<ExtendEntityReturnType> {
   logger("extendEntity %o", data)
-  const txData = opsToTxData({ extensions: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt } = await sendArkivTransaction(client, { extensions: [data] }, txParams)
 
   logger("Receipt from extendEntity %o", receipt)
 
   return {
     txHash: receipt.transactionHash as Hash,
-    entityKey: receipt.logs[0].topics[1] as Hex,
+    entityKey: data.entityKey,
   }
 }

package/src/actions/wallet/mutateEntities.ts

@@ -1,17 +1,16 @@
-import type { Hash, Hex, TransactionReceipt } from "viem"
+import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 import type { ChangeOwnershipParameters } from "./changeOwnership"
-
-const logger = getLogger("actions:wallet:mutate-entities")
-
 import type { CreateEntityParameters } from "./createEntity"
 import type { DeleteEntityParameters } from "./deleteEntity"
 import type { ExtendEntityParameters } from "./extendEntity"
 import type { UpdateEntityParameters } from "./updateEntity"
 
+const logger = getLogger("actions:wallet:mutate-entities")
+
 /**
  * Parameters for the mutateEntities function.
  * - creates: The creates to perform.
@@ -27,39 +26,6 @@ export type MutateEntitiesParameters = {
   ownershipChanges?: ChangeOwnershipParameters[]
 }
 
-function parseReceipt(receipt: TransactionReceipt, params: MutateEntitiesParameters) {
-  const createdEntities: Hex[] = []
-  const updatedEntities: Hex[] = []
-  const deletedEntities: Hex[] = []
-  const extendedEntities: Hex[] = []
-  const ownershipChanges: Hex[] = []
-
-  const totalCreates = params.creates?.length ?? 0
-  const totalUpdates = params.updates?.length ?? 0
-  const totalDeletes = params.deletes?.length ?? 0
-  const totalExtensions = params.extensions?.length ?? 0
-
-  // iterate over all logs and parse the event
-  // logs go in the following order: creates, deleted, updates, extends, ownership changes
-  for (let index = 0; index < receipt.logs.length; index++) {
-    const log = receipt.logs[index]
-
-    if (index < totalCreates) {
-      createdEntities.push(log.topics[1] as Hex)
-    } else if (index < totalCreates + totalDeletes) {
-      deletedEntities.push(log.topics[1] as Hex)
-    } else if (index < totalCreates + totalUpdates + totalDeletes) {
-      updatedEntities.push(log.topics[1] as Hex)
-    } else if (index < totalCreates + totalUpdates + totalDeletes + totalExtensions) {
-      extendedEntities.push(log.topics[1] as Hex)
-    } else {
-      ownershipChanges.push(log.topics[1] as Hex)
-    }
-  }
-
-  return { createdEntities, updatedEntities, deletedEntities, extendedEntities, ownershipChanges }
-}
-
 /**
  * Return type for the mutateEntities function.
  * - txHash: The transaction hash.
@@ -77,6 +43,7 @@ export type MutateEntitiesReturnType = {
   extendedEntities: Hex[]
   ownershipChanges: Hex[]
 }
+
 export async function mutateEntities(
   client: ArkivClient,
   data: MutateEntitiesParameters,
@@ -86,26 +53,16 @@ export async function mutateEntities(
     throw new Error("No operations to perform")
   }
 
-  const txData = opsToTxData({
-    creates: data.creates ?? [],
-    updates: data.updates ?? [],
-    deletes: data.deletes ?? [],
-    extensions: data.extensions ?? [],
-    ownershipChanges: data.ownershipChanges ?? [],
-  })
-
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams)
 
   logger("Receipt from mutateEntities %o", receipt)
 
-  const { createdEntities, updatedEntities, deletedEntities, extendedEntities, ownershipChanges } =
-    parseReceipt(receipt, data)
   return {
     txHash: receipt.transactionHash as Hash,
-    createdEntities,
-    updatedEntities,
-    deletedEntities,
-    extendedEntities,
-    ownershipChanges,
+    createdEntities: createdEntityKeys,
+    updatedEntities: (data.updates ?? []).map((u) => u.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/updateEntity.ts

@@ -1,7 +1,7 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { Attribute, MimeType, TxParams } from "../../types"
-import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:update-entity")
@@ -48,13 +48,12 @@ export async function updateEntity(
   txParams?: TxParams,
 ): Promise<UpdateEntityReturnType> {
   logger("updateEntity %o", data)
-  const txData = opsToTxData({ updates: [data] })
-  const receipt = await sendArkivTransaction(client, txData, txParams)
+  const { receipt } = await sendArkivTransaction(client, { updates: [data] }, txParams)
 
   logger("Receipt from updateEntity %o", receipt)
 
   return {
     txHash: receipt.transactionHash as Hash,
-    entityKey: receipt.logs[0].topics[1] as Hex,
+    entityKey: data.entityKey,
   }
 }

package/src/clients/decorators/arkivWallet.ts

@@ -35,7 +35,10 @@ export type WalletArkivActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
-> = Pick<PublicActions<transport, chain, account>, "waitForTransactionReceipt" | "call"> &
+> = Pick<
+  PublicActions<transport, chain, account>,
+  "waitForTransactionReceipt" | "call" | "simulateContract" | "readContract" | "getBlockNumber"
+> &
   Pick<
     WalletActions<chain, account>,
     | "addChain"
@@ -45,6 +48,7 @@ export type WalletArkivActions<
     | "sendRawTransaction"
     | "signMessage"
     | "signTransaction"
+    | "writeContract"
   > & {
     /**
      * Creates a new entity.

package/src/consts.ts

@@ -1,2 +1,3 @@
-export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+//export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+export const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044" as `0x${string}`
 export const BLOCK_TIME = 2 // 2 seconds

package/src/errors.ts

@@ -16,13 +16,32 @@ export class InvalidExpirationError extends Error {
 }
 export class InvalidAttributeError extends Error {
   constructor(key: string, value: number) {
+    const remedy = Number.isInteger(value)
+      ? `Offset it into the non-negative range (e.g. store ${String(value)} + OFFSET, subtracting OFFSET on read) to keep numeric ordering/range queries; otherwise store it as a string (e.g. "${String(value)}")`
+      : `To keep numeric ordering/range queries, scale it to an integer (e.g. Math.round(${String(value)} * 1000), dividing by 1000 on read); otherwise store it as a string (e.g. "${String(value)}")`
     super(
-      `Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be integers. To keep numeric ordering/range queries, scale it to an integer (e.g. Math.round(${String(value)} * 1000), dividing by 1000 on read); otherwise store it as a string (e.g. "${String(value)}").`,
+      `Invalid numeric value for attribute "${key}": ${String(value)}. Numeric attribute values must be non-negative integers (stored on-chain as unsigned 256-bit). ${remedy}.`,
     )
     this.name = "InvalidAttributeError"
   }
 }
 
+export class InvalidAttributeKeyError extends Error {
+  constructor(key: string, reason: string) {
+    super(
+      `Invalid attribute key "${key}": ${reason}. Keys must be 1-32 bytes, start with a lowercase letter (a-z), and contain only a-z, 0-9, ".", "-" or "_".`,
+    )
+    this.name = "InvalidAttributeKeyError"
+  }
+}
+
+export class DuplicateAttributeError extends Error {
+  constructor(key: string) {
+    super(`Duplicate attribute key "${key}". Attribute keys must be unique per entity.`)
+    this.name = "DuplicateAttributeError"
+  }
+}
+
 export class NoMoreResultsError extends Error {
   constructor() {
     super("No more results")
@@ -43,3 +62,12 @@ export class NoEntityFoundError extends Error {
     this.name = "NoEntityFoundError"
   }
 }
+
+export class InvalidContentTypeError extends Error {
+  constructor(contentType: string) {
+    super(
+      `Invalid content type "${contentType}". Must follow RFC 2045 MIME grammar and be lowercase only (e.g. "text/plain").`,
+    )
+    this.name = "InvalidContentTypeError"
+  }
+}

package/src/query/engine.test.ts

@@ -47,6 +47,51 @@ describe("processQuery tests", () => {
     })
   })
 
+  it("should serialize 32-byte hex values as unquoted literals and other hex as strings", async () => {
+    const hexValue = "0xdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeefdeadbeef"
+    const predicates = [
+      { type: "eq" as const, key: "hexattr", value: hexValue },
+      { type: "eq" as const, key: "strattr", value: "value" },
+      // hex-looking but not 32 bytes — stored as strings, so compared quoted
+      { type: "eq" as const, key: "shorthex", value: "0xab" },
+      { type: "eq" as const, key: "addrhex", value: "0x6186b0dba9652262942d5a465d49686eb560834c" },
+    ]
+    await processQuery(client, {
+      predicates,
+      limit: undefined,
+      cursor: undefined,
+      ownedBy: undefined,
+      createdBy: undefined,
+      orderBy: undefined,
+      validAtBlock: undefined,
+      withAttributes: undefined,
+      withMetadata: undefined,
+      withPayload: undefined,
+    })
+
+    expect(client.request).lastCalledWith({
+      method: "arkiv_query",
+      params: [
+        `hexattr = ${hexValue} && strattr = "value" && shorthex = "0xab" && addrhex = "0x6186b0dba9652262942d5a465d49686eb560834c"`,
+        {
+          includeData: {
+            key: true,
+            attributes: false,
+            contentType: false,
+            payload: false,
+            expiration: false,
+            owner: false,
+            creator: false,
+            createdAtBlock: false,
+            lastModifiedAtBlock: false,
+            transactionIndexInBlock: false,
+            operationIndexInTransaction: false,
+          },
+        },
+      ],
+    })
+  })
+
   it("should process all simple predicates - flat", async () => {
     const predicates = [
       { type: "eq" as const, key: "key", value: "value" },

package/src/query/engine.ts

@@ -3,6 +3,7 @@ import { hexToNumber, numberToHex } from "viem"
 import type { ArkivClient } from "../clients/baseClient"
 import type { RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions } from "../types/rpcSchema"
 import { getLogger } from "../utils/logger"
+import { isEntityKey } from "../utils/validation"
 import type { Predicate } from "./predicate"
 
 const logger = getLogger("query:engine")
@@ -10,7 +11,11 @@ const logger = getLogger("query:engine")
 function processPredicates(predicates: Predicate[]): string {
   const processValue = (value: string | number) => {
     if (typeof value === "string") {
-      return `"${value}"`
+      // 32-byte hex strings are stored as the EntityKey attribute type (see
+      // encodeAttribute), which the query language only matches against unquoted
+      // hex literals. All other strings — including shorter hex — are stored and
+      // compared as quoted strings.
+      return isEntityKey(value) ? value : `"${value}"`
     }
     return value
   }

package/src/query/selectQueryBuilder.test.ts

@@ -1,6 +1,7 @@
 import { afterEach, beforeEach, describe, expect, jest, test } from "bun:test"
 import type { ArkivClient } from "../clients/baseClient"
 import type { Entity } from "../types/entity"
+import { RpcAttributeValueType } from "../types/rpcSchema"
 import * as entitiesUtils from "../utils/entities"
 import * as engine from "./engine"
 import { eq, gte } from "./predicate"
@@ -150,8 +151,10 @@ describe("SelectQueryBuilder", () => {
             key: "0xabc",
             owner: "0xowner",
             value: "0x68656c6c6f", // "hello"
-            stringAttributes: [{ key: "category", value: "docs" }],
-            numericAttributes: [{ key: "score", value: "0x2a" }],
+            attributes: [
+              { key: "category", value: "docs", valueType: RpcAttributeValueType.String },
+              { key: "score", value: "0x2a", valueType: RpcAttributeValueType.Uint },
+            ],
           },
         ],
         cursor: "",

package/src/types/attributes.ts

@@ -1,16 +1,28 @@
+import type { Hex } from "viem"
+
 /**
  * An entity attribute (key/value pair).
  *
- * Arkiv supports both string and number values. Numeric values **must be
- * integers** — passing a non-integer number (e.g. `1.5`) throws an
- * {@link InvalidAttributeError} at mutation time. To store a non-integer value:
+ * Arkiv supports string, Hex and number values.
+ *
+ * Hex values are stored as the on-chain `EntityKey` type **only when they are
+ * exactly 32 bytes** (66 characters, e.g. an entity key). Hex-looking strings
+ * of any other length are stored as plain strings: they round-trip unchanged
+ * and compare lexicographically, not as hex.
+ *
+ * Numeric values **must be non-negative integers** (they are stored on-chain
+ * as unsigned 256-bit) — passing a non-integer (e.g. `1.5`) or negative number
+ * throws an {@link InvalidAttributeError} at mutation time. To store a
+ * non-integer value:
  * - Scale it to an integer (e.g. `1.5` -> `1500`, dividing by the same factor on
  *   read) to keep numeric ordering and range queries working.
  * - Or pass it as a string (e.g. `"1.5"`), which sorts lexicographically and so
  *   does not support numeric comparisons.
+ *
+ * To store a negative value, offset it into the non-negative range (subtracting
+ * the offset on read) or store it as a string.
  */
 export type Attribute = {
   key: string
-  /** Attribute value. A `number` must be an integer (scale non-integers, e.g. `1.5` -> `1500`, or use a string). Throws {@link InvalidAttributeError} otherwise. */
-  value: string | number
+  value: number | string | Hex
 }

package/src/types/entity.ts

@@ -1,10 +1,20 @@
 import { bytesToString, type Hex } from "viem"
+
+export enum EntityOperationType {
+  Create = 1,
+  Update = 2,
+  Extend = 3,
+  Transfer = 4,
+  Delete = 5,
+  Expire = 6,
+}
+
 import type { MimeType } from "../types"
 import type { Attribute } from "./attributes"
 
 export class Entity {
   key: Hex
-  contentType: MimeType | undefined
+  contentType: MimeType | `${string}/${string}` | undefined
   owner: Hex | undefined
   creator: Hex | undefined
   expiresAtBlock: bigint | undefined
@@ -17,7 +27,7 @@ export class Entity {
 
   constructor(
     key: Hex,
-    contentType: MimeType | undefined = undefined,
+    contentType: MimeType | `${string}/${string}` | undefined = undefined,
     owner: Hex | undefined = undefined,
     creator: Hex | undefined = undefined,
     expiresAtBlock: bigint | undefined = undefined,