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

package/src/utils/arkivTransactions.ts

@@ -1,155 +1,300 @@
-import { type Hex, hexToString, TransactionExecutionError, toBytes, toHex, toRlp } from "viem"
+import {
+  type Address,
+  ContractFunctionExecutionError,
+  ContractFunctionRevertedError,
+  decodeEventLog,
+  type Hex,
+  parseAbi,
+  TransactionExecutionError,
+  type TransactionReceipt,
+} 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 { EntityMutationError } 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 { compress } from "./compression"
+
 import { getLogger } from "./logger"
-import { validateAttribute, validateExpiresIn } from "./validation"
+import { describeEntityRevert } from "./revert"
 
 const logger = getLogger("utils:arkiv-transactions")
 
-export function opsToTxData({
-  creates,
-  updates,
-  deletes,
-  extensions,
-  ownershipChanges,
-}: {
-  creates?: CreateEntityParameters[]
-  updates?: UpdateEntityParameters[]
-  deletes?: DeleteEntityParameters[]
-  extensions?: ExtendEntityParameters[]
-  ownershipChanges?: ChangeOwnershipParameters[]
-}) {
-  function formatAttributes<T extends string | number | bigint | boolean>(attribute: {
-    key: string
-    value: T
-  }): [Hex, Hex] {
-    return [
-      toHex(attribute.key),
-      toHex(typeof attribute.value === "number" && attribute.value === 0 ? "" : attribute.value),
-    ]
+// RFC 2045 token chars, lowercase only. Rejects uppercase to prevent text/plain vs Text/Plain ambiguity.
+const MIME_REGEX = /^[a-z][a-z0-9!#$&\-^_]*\/[a-z0-9][a-z0-9!#$&\-^_.+]*$/
+
+function validateContentType(contentType: string): void {
+  if (!MIME_REGEX.test(contentType)) {
+    throw new InvalidContentTypeError(contentType)
   }
+}
 
-  const payload = [
-    //creates
-    (creates ?? []).map((item) => {
-      validateExpiresIn(item.expiresIn)
-      item.attributes.forEach(validateAttribute)
-      return [
-        toHex(item.expiresIn / BLOCK_TIME),
-        toHex(item.contentType),
-        toHex(item.payload),
-        item.attributes
-          .filter((attribute) => typeof attribute.value === "string")
-          .map(formatAttributes),
-        item.attributes
-          .filter((attribute) => typeof attribute.value === "number")
-          .map(formatAttributes),
-      ]
-    }),
-    //updates
-    (updates ?? []).map((item) => {
-      validateExpiresIn(item.expiresIn)
-      item.attributes.forEach(validateAttribute)
-      return [
-        item.entityKey,
-        toHex(item.contentType),
-        toHex(item.expiresIn / BLOCK_TIME),
-        toHex(item.payload),
-        item.attributes
-          .filter((attribute) => typeof attribute.value === "string")
-          .map(formatAttributes),
-        item.attributes
-          .filter((attribute) => typeof attribute.value === "number")
-          .map(formatAttributes),
-      ]
-    }),
-    //deletes
-    (deletes ?? []).map((item) => item.entityKey),
-    //extends
-    (extensions ?? []).map((item) => {
-      validateExpiresIn(item.expiresIn)
-      return [item.entityKey, toHex(item.expiresIn / BLOCK_TIME)]
-    }),
-    //ownershipChanges TODO
-    (ownershipChanges ?? []).map((item) => [item.entityKey, item.newOwner]),
-  ]
+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 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 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)",
+])
 
-  logger("txData to send as RLP %o length %d", payload, payload.length)
+const EXECUTE_ABI = [...EXECUTE_FUNCTION_ABI, ...ENTITY_ERRORS_ABI]
 
-  return toRlp(payload)
+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, data: Hex, txParams?: TxParams) {
+export async function sendArkivTransaction(
+  client: ArkivClient,
+  ops: {
+    creates?: CreateEntityParameters[]
+    patches?: PatchEntityParameters[]
+    deletes?: DeleteEntityParameters[]
+    extensions?: ExtendEntityParameters[]
+    ownershipChanges?: ChangeOwnershipParameters[]
+  },
+  txParams?: TxParams,
+): Promise<SendArkivTransactionResult> {
   if (!client.account) throw new Error("Account required")
+  if (!client.chain) throw new Error("Chain required")
   const walletClient = client as WalletArkivClient
 
-  logger("Sending transaction %o", {
-    account: client.account,
-    chain: client.chain,
-    to: ARKIV_ADDRESS,
-    value: 0n,
-    data,
-    ...txParams,
+  const { creates, patches, deletes, extensions, ownershipChanges } = ops
+
+  // 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 expiryContext = { currentBlock }
+
+  const createOps = (creates ?? []).map((item) => {
+    validateContentType(item.contentType)
+
+    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,
+      }),
+    ),
+  ]
+
+  if (operations.length === 0) {
+    throw new Error("No operations to perform")
+  }
+
+  logger("Sending execute with %d operations %o", operations.length, operations)
+
   try {
-    const compressed = await compress(toBytes(data))
-    const txHash = await walletClient.sendTransaction({
+    const txHash = await walletClient.writeContract({
+      address: ARKIV_ADDRESS,
+      abi: EXECUTE_ABI,
+      functionName: "execute",
+      args: [operations],
       account: client.account,
       chain: client.chain,
-      to: ARKIV_ADDRESS,
-      value: 0n,
-      data: toHex(compressed),
       ...txParams,
     })
 
     const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash })
     logger("Tx receipt %o", receipt)
+
     if (receipt.status === "reverted") {
       try {
-        const callResult = await walletClient.call({
+        await walletClient.simulateContract({
+          address: ARKIV_ADDRESS,
+          abi: EXECUTE_ABI,
+          functionName: "execute",
+          args: [operations],
           account: client.account,
-          to: ARKIV_ADDRESS,
-          value: 0n,
-          data: toHex(compressed),
-          ...txParams,
+          chain: client.chain,
         })
-        throw new EntityMutationError(
-          `Transaction ${receipt.transactionHash} reverted. Please make sure the data for entities doesn't contain invalid characters or invalid data types.
-          Reason: ${callResult.data ? hexToString(callResult.data) : "No reason provided by backend."}`,
-        )
       } catch (err) {
-        const error = err as { cause?: { details?: string } }
-        const reason = error.cause?.details ?? "No reason provided by backend."
-        logger(
-          "Error while calling to get more details about reverted transaction. Reason: %s",
-          reason,
-        )
+        const error = err as { shortMessage?: string; cause?: { details?: string } }
+        const reason =
+          describeEntityRevert(err) ??
+          error.shortMessage ??
+          error.cause?.details ??
+          "No reason provided by backend."
         throw new EntityMutationError(
           `Transaction ${receipt.transactionHash} reverted. Reason: ${reason}`,
         )
       }
+      throw new EntityMutationError(
+        `Transaction ${receipt.transactionHash} reverted. No reason provided by backend.`,
+      )
     }
 
-    return receipt
+    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}`
+    } else if (error instanceof ContractFunctionExecutionError) {
+      logger("Contract function execution error data:", error.shortMessage)
+      if (error.cause instanceof ContractFunctionRevertedError) {
+        message += `: ${error.cause.message}`
+      } else {
+        message += ": Execution error without revert data"
+      }
     } else if (error instanceof EntityMutationError) {
       throw error
+    } else if (error instanceof Error) {
+      message += `: ${error.message}`
     }
 
-    logger("%s Detailed error stack: %o", message, error)
-    throw new EntityMutationError(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 }
+}
+
+/** 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()
+  })
+})