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

package/src/clients/createPublicClient.ts

@@ -0,0 +1,65 @@
+import type {
+  Account,
+  Address,
+  Chain,
+  Client,
+  ParseAccount,
+  Prettify,
+  PublicClientConfig,
+  RpcSchema,
+  Transport,
+} from "viem"
+import { createClient, publicActions } from "viem"
+import type { ArkivRpcSchema } from "../types/rpcSchema"
+import { type PublicArkivActions, publicArkivActions } from "./decorators/arkivPublic"
+
+export type PublicArkivClient<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  accountOrAddress extends Account | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = ArkivRpcSchema,
+> = Prettify<
+  Client<transport, chain, accountOrAddress, rpcSchema, PublicArkivActions<transport, chain>>
+>
+
+/**
+ * Creates a Public Client with a given [Transport](https://viem.sh/docs/clients/intro) configured for a [Chain](https://viem.sh/docs/clients/chains).
+ *
+ * - Docs: https://docs.golemdb.io/ts-sdk/clients/public
+ *
+ * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.golemdb.io/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.golemdb.io/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Arkiv Public Client. {@link PublicArkivClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'arkiv'
+ * import { kaolin } from 'arkiv/chains'
+ *
+ * const client = createPublicClient({
+ *   chain: kaolin,
+ *   transport: http(),
+ * })
+ */
+export function createPublicClient<
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends Account | Address | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = ArkivRpcSchema,
+>(
+  parameters: PublicClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+): PublicArkivClient<transport, chain, ParseAccount<accountOrAddress>, rpcSchema> {
+  const { key = "public", name = "Public Client" } = parameters
+  const client = createClient({
+    ...parameters,
+    key,
+    name,
+  })
+
+  return client.extend(publicArkivActions).extend(publicActions) as unknown as PublicArkivClient<
+    transport,
+    chain,
+    ParseAccount<accountOrAddress>,
+    rpcSchema
+  >
+}

package/src/clients/createWalletClient.test.ts

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

package/src/clients/createWalletClient.ts

@@ -0,0 +1,70 @@
+import type {
+  Account,
+  Address,
+  Chain,
+  Client,
+  ParseAccount,
+  Prettify,
+  RpcSchema,
+  Transport,
+  WalletClientConfig,
+} from "viem"
+import { createClient, publicActions, walletActions } from "viem"
+import type { ArkivRpcSchema } from "../types/rpcSchema"
+import { publicArkivActions } from "./decorators/arkivPublic"
+import { type WalletArkivActions, walletArkivActions } from "./decorators/arkivWallet"
+
+export type WalletArkivClient<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+  rpcSchema extends RpcSchema | undefined = ArkivRpcSchema,
+> = Prettify<
+  Client<transport, chain, account, rpcSchema, WalletArkivActions<transport, chain, account>>
+>
+
+/**
+ * Creates a Public Client with a given [Transport](https://viem.sh/docs/clients/intro) configured for a [Chain](https://viem.sh/docs/clients/chains).
+ *
+ * - Docs: https://docs.golemdb.io/ts-sdk/clients/public
+ *
+ * A Public Client is an interface to "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/), [Arkiv JSON-RPC API](https://docs.golemdb.io/json-rpc/), and [Kaolin JSON-RPC API](https://kaolin.holesky.golemdb.io/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
+ *
+ * @param config - {@link PublicClientConfig}
+ * @returns A Arkiv Public Client. {@link PublicArkivClient}
+ *
+ * @example
+ * import { createPublicClient, http } from 'arkiv'
+ * import { kaolin } from 'arkiv/chains'
+ *
+ * const client = createPublicClient({
+ *   chain: kaolin,
+ *   transport: http(),
+ * })
+ */
+export function createWalletClient<
+  transport extends Transport,
+  chain extends Chain | undefined = undefined,
+  accountOrAddress extends Account | Address | undefined = undefined,
+  rpcSchema extends RpcSchema | undefined = ArkivRpcSchema,
+>(
+  parameters: WalletClientConfig<transport, chain, accountOrAddress, rpcSchema>,
+): WalletArkivClient<transport, chain, ParseAccount<accountOrAddress>, rpcSchema> {
+  const { key = "wallet", name = "Wallet Client" } = parameters
+  const client = createClient({
+    ...parameters,
+    key,
+    name,
+  })
+
+  return client
+    .extend(walletActions)
+    .extend(publicActions)
+    .extend(walletArkivActions)
+    .extend(publicArkivActions) as unknown as WalletArkivClient<
+    transport,
+    chain,
+    ParseAccount<accountOrAddress>,
+    rpcSchema
+  >
+}

package/src/clients/decorators/arkivPublic.ts

@@ -0,0 +1,203 @@
+import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem"
+import { getBlockTiming } from "../../actions/public/getBlockTiming"
+import { getEntity } from "../../actions/public/getEntity"
+import { getEntityCount } from "../../actions/public/getEntityCount"
+import { query } from "../../actions/public/query"
+import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
+import { QueryBuilder } from "../../query/queryBuilder"
+import type { Entity } from "../../types/entity"
+import type {
+  OnEntityCreatedEvent,
+  OnEntityDeletedEvent,
+  OnEntityExpiredEvent,
+  OnEntityExpiresInExtendedEvent,
+  OnEntityUpdatedEvent,
+} from "../../types/events"
+
+export type PublicArkivActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+> = Pick<
+  PublicActions<transport, chain, account>,
+  | "getBalance"
+  | "getBlock"
+  | "getBlockNumber"
+  | "getChainId"
+  | "getLogs"
+  | "getTransaction"
+  | "getTransactionCount"
+  | "getTransactionReceipt"
+  | "waitForTransactionReceipt"
+  | "watchEvent"
+> & {
+  /**
+   * Returns the entity with the given key.
+   *
+   * - Docs: https://docs.golemdb.io/ts-sdk/actions/public/getEntity
+   *
+   * @param args - {entityKey}
+   * @returns The entity with the given key. {@link Entity}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const entity = await client.getEntity("0x123")
+   * // {
+   * //   key: "0x123",
+   * //   value: "0x123",
+   * // }
+   */
+  getEntity: (key: Hex) => Promise<Entity>
+
+  /**
+   * Returns a QueryBuilder instance for building and executing queries.
+   * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
+   *
+   * - Docs: https://docs.golemdb.io/ts-sdk/actions/public/query
+   *
+   * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const query = client.buildQuery()
+   * const entities = await query.where("key", "=", "value").ownedBy("0x123").fetch()
+   *
+   */
+  buildQuery: () => QueryBuilder
+
+  /**
+   * Returns a QueryResult instance for fetching the results of a raw query.
+   * @returns A QueryResult instance for fetching the results of a raw query. {@link QueryResult}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const queryResult = client.query('key = value && $owner = 0x123')
+   *
+   */
+  query: (query: string) => Promise<Entity[]>
+
+  /**
+   * Returns the number of entities in the DBChain.
+   * @returns The number of entities in the DBChain. {@link number}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const entityCount = await client.getEntityCount()
+   * // entityCount = 0
+   */
+  getEntityCount: () => Promise<number>
+
+  /**
+   * Returns the current block timing.
+   * @returns The current block timing. {@link GetBlockTimingReturnType}
+   *
+   * @example
+   * import { createPublicClient, http } from 'arkiv'
+   * import { kaolin } from 'arkiv/chains'
+   *
+   * const client = createPublicClient({
+   *   chain: kaolin,
+   *   transport: http(),
+   * })
+   * const blockTiming = await client.getBlockTiming()
+   * // {
+   * //   currentBlock: 10n, // block number
+   * //   currentBlockTime: 1234567890, // block timestamp
+   * //   blockDuration: 2, // in seconds
+   * // }
+   */
+  getBlockTiming: () => Promise<{
+    currentBlock: bigint
+    currentBlockTime: number
+    blockDuration: number
+  }>
+
+  subscribeEntityEvents: (
+    {
+      onError,
+      onEntityCreated,
+      onEntityUpdated,
+      onEntityDeleted,
+      onEntityExpiresInExtended,
+    }: {
+      onError?: (error: Error) => void
+      onEntityCreated?: (event: OnEntityCreatedEvent) => void
+      onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
+      onEntityDeleted?: (event: OnEntityDeletedEvent) => void
+      onEntityExpired?: (event: OnEntityExpiredEvent) => void
+      onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
+    },
+    pollingInterval?: number,
+    fromBlock?: bigint,
+  ) => Promise<() => void>
+}
+
+export function publicArkivActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+>(client: Client<transport, chain, account>) {
+  return {
+    getEntity: (key: Hex) => getEntity(client, key),
+    query: (rawQuery: string) => query(client, rawQuery),
+    buildQuery: () => new QueryBuilder(client),
+    getBlockTiming: () => getBlockTiming(client),
+    getEntityCount: () => getEntityCount(client),
+    subscribeEntityEvents: (
+      {
+        onError,
+        onEntityCreated,
+        onEntityUpdated,
+        onEntityDeleted,
+        onEntityExpired,
+        onEntityExpiresInExtended,
+      }: {
+        onError?: (error: Error) => void
+        onEntityCreated?: (event: OnEntityCreatedEvent) => void
+        onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
+        onEntityDeleted?: (event: OnEntityDeletedEvent) => void
+        onEntityExpired?: (event: OnEntityExpiredEvent) => void
+        onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
+      },
+      pollingInterval?: number,
+      fromBlock?: bigint,
+    ) =>
+      subscribeEntityEvents(
+        client,
+        {
+          onError,
+          onEntityCreated,
+          onEntityUpdated,
+          onEntityDeleted,
+          onEntityExpired,
+          onEntityExpiresInExtended,
+        },
+        pollingInterval,
+        fromBlock,
+      ),
+  }
+}

package/src/clients/decorators/arkivWallet.ts

@@ -0,0 +1,250 @@
+import type { Account, Chain, Client, Transport, WalletActions } from "viem"
+import type {
+  ChangeOwnershipParameters,
+  ChangeOwnershipReturnType,
+} from "../../actions/wallet/changeOwnership"
+import { changeOwnership } from "../../actions/wallet/changeOwnership"
+import {
+  type CreateEntityParameters,
+  type CreateEntityReturnType,
+  createEntity,
+} from "../../actions/wallet/createEntity"
+import type {
+  DeleteEntityParameters,
+  DeleteEntityReturnType,
+} from "../../actions/wallet/deleteEntity"
+import { deleteEntity } from "../../actions/wallet/deleteEntity"
+import type {
+  ExtendEntityParameters,
+  ExtendEntityReturnType,
+} from "../../actions/wallet/extendEntity"
+import { extendEntity } from "../../actions/wallet/extendEntity"
+import type {
+  MutateEntitiesParameters,
+  MutateEntitiesReturnType,
+} from "../../actions/wallet/mutateEntities"
+import { mutateEntities } from "../../actions/wallet/mutateEntities"
+import type {
+  UpdateEntityParameters,
+  UpdateEntityReturnType,
+} from "../../actions/wallet/updateEntity"
+import { updateEntity } from "../../actions/wallet/updateEntity"
+import type { Entity, TxParams } from "../../types"
+import type { PublicArkivActions } from "./arkivPublic"
+
+export type WalletArkivActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+> = PublicArkivActions<transport, chain, account> &
+  Pick<
+    WalletActions<chain, account>,
+    | "sendTransaction"
+    | "sendTransactionSync"
+    | "sendRawTransaction"
+    | "sendRawTransactionSync"
+    | "signMessage"
+    | "signTransaction"
+  > & {
+    /**
+     * Returns the entity with the given key.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/public/getEntity
+     *
+     * @param args - {entityKey}
+     * @returns The entity with the given key. {@link Entity}
+     *
+     * @example
+     * import { createPublicClient, http } from 'arkiv'
+     * import { kaolin } from 'arkiv/chains'
+     *
+     * const client = createPublicClient({
+     *   chain: kaolin,
+     *   transport: http(),
+     * })
+     * const { entityKey, txHash } = await client.createEntity({
+     *   payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
+     *   attributes: [{ key: "testKey", value: "testValue" }],
+     *   expiresIn: 1000,
+     * })
+     * console.log("entityKey", entityKey)
+     * console.log("txHash", txHash)
+     * // {
+     * //   entityKey: "0x123",
+     * //   txHash: "0x123",
+     * // }
+     */
+    createEntity: (
+      data: CreateEntityParameters,
+      txParams?: TxParams,
+    ) => Promise<CreateEntityReturnType>
+
+    /**
+     * Updates the entity with the given key.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/wallet/updateEntity
+     * - JSON-RPC Methods: [`golembase_updateEntity`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_updateEntity)
+     *
+     * @param args - {entityKey, data}
+     * @returns The entity with the given key. {@link Entity}
+     *
+     * @example
+     * import { createWalletClient, http } from 'arkiv'
+     * import { kaolin } from 'arkiv/chains'
+     *
+     * const client = createWalletClient({
+     *   chain: kaolin,
+     *   transport: http(),
+     * })
+     */
+    updateEntity: (
+      data: UpdateEntityParameters,
+      txParams?: TxParams,
+    ) => Promise<UpdateEntityReturnType>
+
+    /**
+     * Deletes the entity with the given key.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/wallet/deleteEntity
+     * - JSON-RPC Methods: [`golembase_deleteEntity`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_deleteEntity)
+     *
+     * @param args - {entityKey}
+     * @returns The entity with the given key. {@link Entity}
+     *
+     * @example
+     * import { createWalletClient, http } from 'arkiv'
+     * import { kaolin } from 'arkiv/chains'
+     *
+     * const client = createWalletClient({
+     *   chain: kaolin,
+     *   transport: http(),
+     * })
+     * const { entityKey, txHash } = await client.deleteEntity({ entityKey: "0x123" })
+     * console.log("entityKey", entityKey)
+     * console.log("txHash", txHash)
+     * // {
+     * //   entityKey: "0x123",
+     * //   txHash: "0x123",
+     * // }
+     */
+    deleteEntity: (
+      data: DeleteEntityParameters,
+      txParams?: TxParams,
+    ) => Promise<DeleteEntityReturnType>
+
+    /**
+     * Extends the entity with the given key.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/wallet/extendEntity
+     * - JSON-RPC Methods: [`golembase_extendEntity`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_extendEntity)
+     *
+     * @param args - {entityKey, data}
+     * @returns The entity with the given key. {@link Entity}
+     *
+     * @example
+     * import { createWalletClient, http } from 'arkiv'
+     * import { kaolin } from 'arkiv/chains'
+     *
+     * const client = createWalletClient({
+     *   chain: kaolin,
+     *   transport: http(),
+     * })
+     * const { entityKey, txHash } = await client.extendEntity("0x123", {
+     *   expiresIn: 1000,
+     * })
+     * console.log("entityKey", entityKey)
+     * console.log("txHash", txHash)
+     * // {
+     * //   entityKey: "0x123",
+     * //   txHash: "0x123",
+     * // }
+     */
+    extendEntity: (
+      data: ExtendEntityParameters,
+      txParams?: TxParams,
+    ) => Promise<ExtendEntityReturnType>
+
+    /**
+     * Changes the ownership of the entity with the given address.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/wallet/changeOwnership
+     * - JSON-RPC Methods: [`golembase_ownershipChange`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_ownershipChange)
+     *
+     * @param args - {entityKey, newOwner}
+     * @returns The entity with the given address. {@link Entity}
+     */
+    changeOwnership: (
+      data: ChangeOwnershipParameters,
+      txParams?: TxParams,
+    ) => Promise<ChangeOwnershipReturnType>
+
+    /**
+     * Mutates the entities with the given keys.
+     *
+     * - Docs: https://docs.golemdb.io/ts-sdk/actions/wallet/mutateEntities
+     * - JSON-RPC Methods: [`golembase_mutateEntities`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_mutateEntities)
+     *
+     * @param args - {data}
+     * @returns The entity with the given key. {@link Entity}
+     *
+     * @example
+     * import { createWalletClient, http } from 'arkiv'
+     * import { kaolin } from 'arkiv/chains'
+     *
+     * const client = createWalletClient({
+     *   chain: kaolin,
+     *   transport: http(),
+     * })
+     * const { entityKey, txHash } = await client.mutateEntities({
+     *   creates: [{
+     *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
+     *     attriubutes: [{ key: "testKey", value: "testValue" }],
+     *     expiresIn: 1000,
+     *   }],
+     *   updates: [{
+     *     entityKey: "0x123",
+     *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
+     *     attributes: [{ key: "testKey", value: "testValue" }],
+     *     expiresIn: 1000,
+     *   }],
+     *   deletes: [{
+     *     entityKey: "0x321",
+     *   }],
+     *   extensions: [{
+     *     entityKey: "0x1234",
+     *     expiresIn: 1000,
+     *   }],
+     * })
+     * console.log("entityKey", entityKey)
+     * console.log("txHash", txHash)
+     * // {
+     * //   entityKey: "0x123",
+     * //   txHash: "0x123",
+     * // }
+     */
+    mutateEntities: (
+      data: MutateEntitiesParameters,
+      txParams?: TxParams,
+    ) => Promise<MutateEntitiesReturnType>
+  }
+
+export function walletArkivActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+>(client: Client<transport, chain, account>) {
+  return {
+    createEntity: (data: CreateEntityParameters, txParams?: TxParams) =>
+      createEntity(client, data, txParams),
+    updateEntity: (data: UpdateEntityParameters, txParams?: TxParams) =>
+      updateEntity(client, data, txParams),
+    deleteEntity: (data: DeleteEntityParameters, txParams?: TxParams) =>
+      deleteEntity(client, data, txParams),
+    extendEntity: (data: ExtendEntityParameters, txParams?: TxParams) =>
+      extendEntity(client, data, txParams),
+    changeOwnership: (data: ChangeOwnershipParameters, txParams?: TxParams) =>
+      changeOwnership(client, data, txParams),
+    mutateEntities: (data: MutateEntitiesParameters, txParams?: TxParams) =>
+      mutateEntities(client, data, txParams),
+  }
+}

package/src/consts.ts

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

package/src/index.ts

@@ -0,0 +1,21 @@
+// Export all public APIs
+
+export type {
+  Account,
+  Address,
+  Chain,
+  Hex,
+  PublicClientConfig,
+  RpcSchema,
+  Transport,
+} from "viem"
+// Re-export commonly used viem types for convenience
+export { http, toBytes, toHex, toRlp, webSocket } from "viem"
+export type { ArkivClient } from "./clients/baseClient"
+export type { PublicArkivClient } from "./clients/createPublicClient"
+export { createPublicClient } from "./clients/createPublicClient"
+export type { WalletArkivClient } from "./clients/createWalletClient"
+export { createWalletClient } from "./clients/createWalletClient"
+export type { Attribute } from "./types/attributes"
+export type { Entity } from "./types/entity"
+export type { ArkivRpcSchema } from "./types/rpcSchema"