@arkiv-network/sdk 0.1.1-dev.0 → 0.1.2-dev.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@arkiv-network/sdk",
-  "version": "0.1.1-dev.0",
+  "version": "0.1.2-dev.0",
   "description": "TypeScript-only client library for Arkiv blockchain interactions",
   "type": "module",
   "target": "esnext",
@@ -10,28 +10,40 @@
   "sideEffects": false,
   "exports": {
     ".": {
+      "bun": "./src/index.ts",
       "import": "./dist/index.js",
-      "require": "./dist/index.cjs"
+      "require": "./dist/index.cjs",
+      "default": "./dist/index.js"
     },
     "./accounts": {
+      "bun": "./src/accounts/index.ts",
       "import": "./dist/accounts/index.js",
-      "require": "./dist/accounts/index.cjs"
+      "require": "./dist/accounts/index.cjs",
+      "default": "./dist/accounts/index.js"
     },
     "./chains": {
+      "bun": "./src/chains/index.ts",
       "import": "./dist/chains/index.js",
-      "require": "./dist/chains/index.cjs"
+      "require": "./dist/chains/index.cjs",
+      "default": "./dist/chains/index.js"
     },
     "./query": {
+      "bun": "./src/query/index.ts",
       "import": "./dist/query/index.js",
-      "require": "./dist/query/index.cjs"
+      "require": "./dist/query/index.cjs",
+      "default": "./dist/query/index.js"
     },
     "./types": {
+      "bun": "./src/types/index.ts",
       "import": "./dist/types/index.js",
-      "require": "./dist/types/index.cjs"
+      "require": "./dist/types/index.cjs",
+      "default": "./dist/types/index.js"
     },
     "./utils": {
+      "bun": "./src/utils/index.ts",
       "import": "./dist/utils/index.js",
-      "require": "./dist/utils/index.cjs"
+      "require": "./dist/utils/index.cjs",
+      "default": "./dist/utils/index.js"
     },
     "./package.json": "./package.json"
   },
@@ -52,13 +64,15 @@
     }
   },
   "files": [
-    "dist"
+    "dist",
+    "src"
   ],
   "scripts": {
     "build": "tsdown",
     "type-check": "tsc --noEmit",
     "lint": "biome check src/",
     "lint:fix": "biome check --write src/",
+    "test:unit": "bun test src/**/*",
     "package": "rimraf arkiv-network-sdk-*.tgz && bun run build && bun pm pack --no-cache",
     "package:test": "bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",
     "prepublishOnly": "bun run build && bun run package && mv arkiv-network-sdk-*.tgz arkiv-network-sdk-latest.tgz",

package/src/accounts/index.ts

@@ -0,0 +1 @@
+export * from "viem/accounts"

package/src/actions/public/buildQuery.ts

@@ -0,0 +1,6 @@
+import type { ArkivClient } from "../../clients/baseClient"
+import { QueryBuilder } from "../../query/queryBuilder"
+
+export async function buildQuery(client: ArkivClient) {
+  return new QueryBuilder(client)
+}

package/src/actions/public/getBlockTiming.ts

@@ -0,0 +1,20 @@
+import type { ArkivClient } from "../../clients/baseClient"
+
+export type GetBlockTimingReturnType = {
+  currentBlock: bigint
+  currentBlockTime: number
+  blockDuration: number
+}
+
+export async function getBlockTiming(client: ArkivClient) {
+  const blockTiming = await client.request({
+    method: "arkiv_getBlockTiming",
+    params: [],
+  })
+  console.debug("Block timing", blockTiming)
+  return {
+    currentBlock: blockTiming.current_block,
+    currentBlockTime: blockTiming.current_block_time,
+    blockDuration: blockTiming.duration,
+  }
+}

package/src/actions/public/getEntity.ts

@@ -0,0 +1,18 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import { NoEntityFoundError } from "../../query/errors"
+import { entityFromRpcResult } from "../../utils/entities"
+
+export async function getEntity(client: ArkivClient, key: Hex) {
+  const result = await client.request({
+    method: "arkiv_query",
+    params: [`$key = ${key}`],
+  })
+  console.debug("GetEntity result", result)
+
+  if (!result.data) {
+    throw new NoEntityFoundError()
+  }
+
+  return entityFromRpcResult(result.data[0])
+}

package/src/actions/public/getEntityCount.ts

@@ -0,0 +1,10 @@
+import type { ArkivClient } from "../../clients/baseClient"
+
+export async function getEntityCount(client: ArkivClient) {
+  const count = await client.request({
+    method: "arkiv_getEntityCount",
+    params: [],
+  })
+
+  return count
+}

package/src/actions/public/query.ts

@@ -0,0 +1,13 @@
+import type { ArkivClient } from "../../clients/baseClient"
+import { entityFromRpcResult } from "../../utils/entities"
+
+export async function query(client: ArkivClient, query: string) {
+  const result = await client.request({
+    method: "arkiv_query",
+    params: [query],
+  })
+
+  const entities = await Promise.all(result.data.map((entity) => entityFromRpcResult(entity)))
+
+  return entities
+}

package/src/actions/public/subscribeEntityEvents.ts

@@ -0,0 +1,105 @@
+import { decodeEventLog, parseAbi, toHex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { PublicArkivClient } from "../../clients/createPublicClient"
+import type {
+  OnEntityCreatedEvent,
+  OnEntityDeletedEvent,
+  OnEntityExpiredEvent,
+  OnEntityExpiresInExtendedEvent,
+  OnEntityUpdatedEvent,
+} from "../../types/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)",
+])
+
+export async function subscribeEntityEvents(
+  client: ArkivClient,
+  {
+    onError,
+    onEntityCreated,
+    onEntityUpdated,
+    onEntityDeleted,
+    onEntityExpired,
+    onEntityExpiresInExtended,
+  }: {
+    onError: ((error: Error) => void) | undefined
+    onEntityCreated?: ((event: OnEntityCreatedEvent) => void) | undefined
+    onEntityUpdated?: ((event: OnEntityUpdatedEvent) => void) | undefined
+    onEntityDeleted?: ((event: OnEntityDeletedEvent) => void) | undefined
+    onEntityExpired?: ((event: OnEntityExpiredEvent) => void) | undefined
+    onEntityExpiresInExtended?: ((event: OnEntityExpiresInExtendedEvent) => void) | undefined
+  },
+  pollingInterval?: number,
+  fromBlock?: bigint,
+): Promise<() => void> {
+  const unsubscribe = (client as PublicArkivClient).watchEvent({
+    pollingInterval: pollingInterval ?? 1000,
+    fromBlock: fromBlock ?? 0n,
+    events: arkivABI,
+    onLogs: (logs) => {
+      console.debug("logs from subscribeEntityEvents", logs)
+      for (const log of logs) {
+        const event = decodeEventLog({
+          abi: arkivABI,
+          topics: log.topics,
+          data: log.data,
+        })
+        console.debug("event from subscribeEntityEvents", 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,
+            })
+            break
+          case "ArkivEntityDeleted":
+            onEntityDeleted?.({
+              entityKey: toHex(event.args.entityKey, { size: 32 }),
+              owner: event.args.ownerAddress,
+            })
+            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,
+            })
+            break
+          case "ArkivEntityExpired":
+            onEntityExpired?.({
+              entityKey: toHex(event.args.entityKey, { size: 32 }),
+              owner: event.args.ownerAddress,
+            })
+            break
+          default:
+            console.warn("unknown event from subscribeEntityEvents", event)
+            break
+        }
+      }
+    },
+    onError: (error) => {
+      console.error("error from subscribeEntityEvents", error)
+      onError?.(error)
+    },
+  })
+
+  return unsubscribe
+}

package/src/actions/wallet/changeOwnership.ts

@@ -0,0 +1,40 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the deleteEntity function.
+ * - entityKey: The key of the entity to delete.
+ */
+export type ChangeOwnershipParameters = {
+  entityKey: Hex
+  newOwner: Hex
+}
+
+/**
+ * Return type for the deleteEntity function.
+ * - entityKey: The key of the entity.
+ * - txHash: The transaction hash.
+ */
+export type ChangeOwnershipReturnType = {
+  entityKey: Hex
+  txHash: string
+}
+
+export async function changeOwnership(
+  client: ArkivClient,
+  data: ChangeOwnershipParameters,
+  txParams?: TxParams,
+): Promise<ChangeOwnershipReturnType> {
+  console.debug("changeOwnership", data)
+  const txData = opsToTxData({ ownershipChanges: [data] })
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from changeOwnership", receipt)
+
+  return {
+    txHash: receipt.transactionHash,
+    entityKey: data.entityKey,
+  }
+}

package/src/actions/wallet/createEntity.ts

@@ -0,0 +1,45 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { Attribute, MimeType, TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the createEntity function.
+ * - payload: The payload of the entity.
+ * - attributes: The attributes of the entity.
+ * - contentType: The content type of the entity.
+ * - expiresIn: The expires in of the entity in seconds.
+ */
+export type CreateEntityParameters = {
+  payload: Uint8Array
+  attributes: Attribute[]
+  contentType: MimeType
+  expiresIn: number
+}
+
+/**
+ * Return type for the createEntity function.
+ * - entityKey: The key of the entity.
+ * - txHash: The transaction hash.
+ */
+export type CreateEntityReturnType = {
+  entityKey: Hex
+  txHash: string
+}
+
+export async function createEntity(
+  client: ArkivClient,
+  data: CreateEntityParameters,
+  txParams?: TxParams,
+): Promise<CreateEntityReturnType> {
+  console.debug("createEntity", data)
+  const txData = opsToTxData({ creates: [data] })
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from createEntity", receipt)
+
+  return {
+    txHash: receipt.transactionHash,
+    entityKey: receipt.logs[0].topics[1] as Hex,
+  }
+}

package/src/actions/wallet/deleteEntity.ts

@@ -0,0 +1,39 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the deleteEntity function.
+ * - entityKey: The key of the entity to delete.
+ */
+export type DeleteEntityParameters = {
+  entityKey: Hex
+}
+
+/**
+ * Return type for the deleteEntity function.
+ * - entityKey: The key of the entity.
+ * - txHash: The transaction hash.
+ */
+export type DeleteEntityReturnType = {
+  entityKey: Hex
+  txHash: string
+}
+
+export async function deleteEntity(
+  client: ArkivClient,
+  data: DeleteEntityParameters,
+  txParams?: TxParams,
+): Promise<DeleteEntityReturnType> {
+  console.debug("deleteEntity", data)
+  const txData = opsToTxData({ deletes: [data] })
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from deleteEntity", receipt)
+
+  return {
+    txHash: receipt.transactionHash,
+    entityKey: data.entityKey,
+  }
+}

package/src/actions/wallet/extendEntity.ts

@@ -0,0 +1,41 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the extendEntity function.
+ * - entityKey: The key of the entity to extend.
+ * - expiresIn: The expires in of the entity in seconds.
+ */
+export type ExtendEntityParameters = {
+  entityKey: Hex
+  expiresIn: number
+}
+
+/**
+ * Return type for the extendEntity function.
+ * - entityKey: The key of the entity.
+ * - txHash: The transaction hash.
+ */
+export type ExtendEntityReturnType = {
+  entityKey: Hex
+  txHash: string
+}
+
+export async function extendEntity(
+  client: ArkivClient,
+  data: ExtendEntityParameters,
+  txParams?: TxParams,
+): Promise<ExtendEntityReturnType> {
+  console.debug("extendEntity", data)
+  const txData = opsToTxData({ extensions: [data] })
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from extendEntity", receipt)
+
+  return {
+    txHash: receipt.transactionHash,
+    entityKey: receipt.logs[0].topics[1] as Hex,
+  }
+}

package/src/actions/wallet/mutateEntities.ts

@@ -0,0 +1,100 @@
+import type { Hex, TransactionReceipt } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+import type { CreateEntityParameters } from "./createEntity"
+import type { DeleteEntityParameters } from "./deleteEntity"
+import type { ExtendEntityParameters } from "./extendEntity"
+import type { UpdateEntityParameters } from "./updateEntity"
+
+/**
+ * Parameters for the mutateEntities function.
+ * - creates: The creates to perform.
+ * - updates: The updates to perform.
+ * - deletes: The deletes to perform.
+ * - extensions: The extensions to perform.
+ */
+export type MutateEntitiesParameters = {
+  creates?: CreateEntityParameters[]
+  updates?: UpdateEntityParameters[]
+  deletes?: DeleteEntityParameters[]
+  extensions?: ExtendEntityParameters[]
+}
+
+function parseReceipt(receipt: TransactionReceipt, params: MutateEntitiesParameters) {
+  const createdEntities: Hex[] = []
+  const updatedEntities: Hex[] = []
+  const deletedEntities: Hex[] = []
+  const extendedEntities: Hex[] = []
+  const totalCreates = params.creates?.length ?? 0
+  const totalUpdates = params.updates?.length ?? 0
+  const totalDeletes = params.deletes?.length ?? 0
+
+  // iterate over all logs and parse the event
+  // each odd log is the interested ones, logs goes in order like: creates, deleted, updates, extends
+  for (let i = 0; i < receipt.logs.length; i++) {
+    const log = receipt.logs[i]
+    if (i % 2 === 1) continue
+
+    const index = i / 2
+    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 {
+      extendedEntities.push(log.topics[1] as Hex)
+    }
+  }
+
+  return { createdEntities, updatedEntities, deletedEntities, extendedEntities }
+}
+
+/**
+ * Return type for the mutateEntities function.
+ * - txHash: The transaction hash.
+ * - createdEntities: The keys of the created entities.
+ * - updatedEntities: The keys of the updated entities.
+ * - deletedEntities: The keys of the deleted entities.
+ * - extendedEntities: The keys of the extended entities.
+ */
+export type MutateEntitiesReturnType = {
+  txHash: string
+  createdEntities: Hex[]
+  updatedEntities: Hex[]
+  deletedEntities: Hex[]
+  extendedEntities: Hex[]
+}
+export async function mutateEntities(
+  client: ArkivClient,
+  data: MutateEntitiesParameters,
+  txParams?: TxParams,
+): Promise<MutateEntitiesReturnType> {
+  if (!data.creates && !data.updates && !data.deletes && !data.extensions) {
+    throw new Error("No operations to perform")
+  }
+
+  const txData = opsToTxData({
+    creates: data.creates ?? [],
+    updates: data.updates ?? [],
+    deletes: data.deletes ?? [],
+    extensions: data.extensions ?? [],
+  })
+
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from mutateEntities", receipt)
+
+  const { createdEntities, updatedEntities, deletedEntities, extendedEntities } = parseReceipt(
+    receipt,
+    data,
+  )
+  return {
+    txHash: receipt.transactionHash,
+    createdEntities,
+    updatedEntities,
+    deletedEntities,
+    extendedEntities,
+  }
+}

package/src/actions/wallet/updateEntity.ts

@@ -0,0 +1,47 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { Attribute, MimeType, TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the updateEntity function.
+ * - entityKey: The key of the entity to update.
+ * - payload: The payload of the entity.
+ * - attributes: The attributes of the entity.
+ * - contentType: The content type of the entity.
+ * - expiresIn: The expires in of the entity in seconds.
+ */
+export type UpdateEntityParameters = {
+  entityKey: Hex
+  payload: Uint8Array
+  attributes: Attribute[]
+  contentType: MimeType
+  expiresIn: number
+}
+
+/**
+ * Return type for the updateEntity function.
+ * - entityKey: The key of the entity.
+ * - txHash: The transaction hash.
+ */
+export type UpdateEntityReturnType = {
+  entityKey: Hex
+  txHash: string
+}
+
+export async function updateEntity(
+  client: ArkivClient,
+  data: UpdateEntityParameters,
+  txParams?: TxParams,
+): Promise<UpdateEntityReturnType> {
+  console.debug("updateEntity", data)
+  const txData = opsToTxData({ updates: [data] })
+  const receipt = await sendArkivTransaction(client, txData, txParams)
+
+  console.debug("Receipt from updateEntity", receipt)
+
+  return {
+    txHash: receipt.transactionHash,
+    entityKey: receipt.logs[0].topics[1] as Hex,
+  }
+}

package/src/chains/index.ts

@@ -0,0 +1,3 @@
+export { kaolin } from "./kaolin"
+export { localhost } from "./localhost"
+export { marketplace } from "./marketplace"

package/src/chains/kaolin.ts

@@ -0,0 +1,26 @@
+import { defineChain } from "viem"
+
+export const kaolin = defineChain({
+  id: 60138453025,
+  name: "Kaolin",
+  network: "kaolin",
+  nativeCurrency: {
+    name: "Ethereum",
+    symbol: "ETH",
+    decimals: 18,
+  },
+  rpcUrls: {
+    default: {
+      http: ["https://kaolin.hoodi.arkiv.network/rpc"],
+      webSocket: ["wss://kaolin.hoodi.arkiv.network/rpc/ws"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Kaolin Arkiv Explorer",
+      url: "https://explorer.kaolin.hoodi.arkiv.network",
+      apiUrl: "https://explorer.kaolin.hoodi.arkiv.network/api",
+    },
+  },
+  testnet: true,
+})

package/src/chains/localhost.ts

@@ -0,0 +1,14 @@
+import { defineChain } from "viem"
+
+export const localhost = defineChain({
+  id: 1337,
+  name: "Localhost",
+  nativeCurrency: {
+    decimals: 18,
+    name: "Ether",
+    symbol: "ETH",
+  },
+  rpcUrls: {
+    default: { http: ["http://127.0.0.1:8545"] },
+  },
+})

package/src/chains/marketplace.ts

@@ -0,0 +1,26 @@
+import { defineChain } from "viem"
+
+export const marketplace = defineChain({
+  id: 60138453027,
+  name: "Marketplace",
+  network: "marketplace",
+  nativeCurrency: {
+    name: "Ethereum",
+    symbol: "ETH",
+    decimals: 18,
+  },
+  rpcUrls: {
+    default: {
+      http: ["https://marketplace.hoodi.arkiv.network/rpc"],
+      webSocket: ["wss://marketplace.hoodi.arkiv.network/rpc/ws"],
+    },
+  },
+  blockExplorers: {
+    default: {
+      name: "Marketplace Arkiv Explorer",
+      url: "https://explorer.marketplace.hoodi.arkiv.network",
+      apiUrl: "https://explorer.marketplace.hoodi.arkiv.network/api",
+    },
+  },
+  testnet: true,
+})

package/src/clients/baseClient.ts

@@ -0,0 +1,9 @@
+import type { Account, Chain, Client, RpcSchema, Transport } from "viem"
+import type { ArkivRpcSchema } from "../types/rpcSchema"
+
+export type ArkivClient<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = ArkivRpcSchema,
+> = Client<transport, chain, accountOrAddress, rpcSchema>

package/src/clients/createPublicClient.test.ts

@@ -0,0 +1,22 @@
+import { expect, test, vi } from "bun:test"
+import { createTransport, type EIP1193RequestFn } from "viem"
+import { createPublicClient } from "./createPublicClient"
+
+const mockTransport = () =>
+  createTransport({
+    key: "mock",
+    name: "Mock Transport",
+    request: vi.fn(() => null) as unknown as EIP1193RequestFn,
+    type: "mock",
+  })
+
+test("creates", () => {
+  const { uid, ...client } = createPublicClient({
+    transport: mockTransport,
+  })
+
+  expect(uid).toBeDefined()
+  expect(client.getEntity).toBeDefined()
+  expect(typeof client.getEntity).toBe("function")
+  expect(client.createEntity).not.toBeDefined()
+})