@arkiv-network/sdk 0.0.25

package/src/clients/decorators/arkivPublic.ts

@@ -0,0 +1,167 @@
+import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem"
+import { getBlockTiming } from "../../actions/public/getBlockTiming"
+import { getEntity } from "../../actions/public/getEntity"
+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
+	 * - JSON-RPC Methods: [`golembase_getStorageValue`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_getstoragevalue)
+	 * - JSON-RPC Methods: [`golembase_getEntityMetaData`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_getEntityMetaData)
+	 *
+	 * @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[]>
+
+	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),
+		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,232 @@
+import type { Account, Chain, Client, Transport, WalletActions } from "viem"
+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
+		 * - JSON-RPC Methods: [`golembase_getStorageValue`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_getstoragevalue)
+		 * - JSON-RPC Methods: [`golembase_getEntityMetaData`](https://docs.golemdb.io/dev/json-rpc-api/#golembase_getEntityMetaData)
+		 *
+		 * @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" } })),
+		 *   annotations: [{ 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>
+
+		/**
+		 * 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" } })),
+		 *     annotations: [{ key: "testKey", value: "testValue" }],
+		 *     expiresIn: 1000,
+		 *   }],
+		 *   updates: [{
+		 *     entityKey: "0x123",
+		 *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
+		 *     annotations: [{ 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),
+		mutateEntities: (data: MutateEntitiesParameters, txParams?: TxParams) =>
+			mutateEntities(client, data, txParams),
+	}
+}

package/src/consts.ts

@@ -0,0 +1,2 @@
+export const ARKIV_ADDRESS = "0x0000000000000000000000000000000060138453" 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 { Annotation } from "./types/annotation"
+export type { Entity } from "./types/entity"
+export type { ArkivRpcSchema } from "./types/rpcSchema"

package/src/query/engine.ts

@@ -0,0 +1,86 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import type { Predicate } from "./predicate"
+
+function processPredicates(predicates: Predicate[]): string {
+	const processValue = (value: string | number) => {
+		if (typeof value === "string") {
+			return `"${value}"`
+		}
+		return value
+	}
+	return predicates
+		.map((predicate) => {
+			switch (predicate.type) {
+				case "eq":
+					return `${predicate.key} = ${processValue(predicate.value)}`
+				case "neq":
+					return `${predicate.key} != ${processValue(predicate.value)}`
+				case "gt":
+					return `${predicate.key} > ${processValue(predicate.value)}`
+				case "gte":
+					return `${predicate.key} >= ${processValue(predicate.value)}`
+				case "lt":
+					return `${predicate.key} < ${processValue(predicate.value)}`
+				case "lte":
+					return `${predicate.key} <= ${processValue(predicate.value)}`
+				case "not":
+					return `!${predicate.key}`
+				case "or":
+					return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(" || ")})`
+				case "and":
+					return `(${predicate.predicates.map((predicate) => processPredicates([predicate])).join(" && ")})`
+				default:
+					return ""
+			}
+		})
+		.join(" && ")
+}
+
+export async function processQuery(
+	client: ArkivClient,
+	queryParams: {
+		predicates: Predicate[]
+		limit: number | undefined
+		offset: number | undefined
+		ownedBy: Hex | undefined
+		validBeforeBlock?: number | undefined
+		withAnnotations?: boolean | undefined
+		withMetadata?: boolean | undefined
+	},
+) {
+	const { predicates, limit, offset, ownedBy, validBeforeBlock, withAnnotations, withMetadata } =
+		queryParams
+
+	console.debug(
+		`Processing query with params: predicates: ${predicates}, limit: ${limit}, offset: ${offset}, ownedBy: ${ownedBy}, validBeforeBlock: ${validBeforeBlock}, withAnnotations: ${withAnnotations}, withMetadata: ${withMetadata}`,
+	)
+
+	let query = processPredicates(predicates)
+	if (ownedBy) {
+		query += ` && $owner=${ownedBy}`
+	}
+	if (limit) {
+		query += ` limit=${limit}`
+	}
+
+	if (offset) {
+		query += ` offset=${offset}`
+	}
+
+	// remove leading and trailing spaces and leading &&
+	query = query.trim()
+	if (query.startsWith("&& ")) {
+		query = query.slice(3)
+	}
+
+	console.debug(`Built query to send: ${query}`)
+
+	const result = await client.request({
+		method: "golembase_queryEntities",
+		params: [query],
+	})
+	console.debug("Raw result from query: ", result)
+
+	return result
+}

package/src/query/errors.ts

@@ -0,0 +1,17 @@
+export class NoMoreResultsError extends Error {
+	constructor() {
+		super("No more results")
+	}
+}
+
+export class NoOffsetOrLimitError extends Error {
+	constructor() {
+		super("Offset and limit must be defined to fetch next or previous")
+	}
+}
+
+export class OffsetCannotBeLessThanZeroError extends Error {
+	constructor() {
+		super("Offset cannot be less than 0")
+	}
+}

package/src/query/index.ts

@@ -0,0 +1,4 @@
+export * from "./errors"
+export * from "./predicate"
+export * from "./queryBuilder"
+export * from "./queryResult"

package/src/query/predicate.ts

@@ -0,0 +1,140 @@
+export type PredicateType = "eq" | "neq" | "gt" | "gte" | "lt" | "lte" | "not"
+export type PredicateContainerType = "or" | "and"
+
+export type Predicate =
+	| {
+			type: PredicateType
+			key: string
+			value: string | number
+	  }
+	| {
+			type: PredicateContainerType
+			predicates: Predicate[]
+	  }
+
+/**
+ * Creates an OR predicate
+ * @param predicates - The predicates to combine
+ * @returns The OR predicate
+ *
+ * @example
+ * const predicates = [eq("name", "John"), eq("age", 30)]
+ * const result = or(predicates)
+ * // result = { type: "or", predicates: [eq("name", "John"), eq("age", 30)] }
+ *
+ */
+export function or(predicates: Predicate[]): Predicate {
+	return { type: "or", predicates }
+}
+
+/**
+ * Creates an AND predicate
+ * @param predicates - The predicates to combine
+ * @returns The AND predicate
+ *
+ * @example
+ * const predicates = [eq("name", "John"), eq("age", 30)]
+ * const result = and(predicates)
+ * // result = { type: "and", predicates: [eq("name", "John"), eq("age", 30)] }
+ *
+ */
+export function and(predicates: Predicate[]): Predicate {
+	return { type: "and", predicates }
+}
+
+/**
+ * Creates an equality predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The equality predicate
+ *
+ * @example
+ * const predicate = eq("name", "John")
+ * // result = { type: "eq", key: "name", value: "John" }
+ */
+export function eq(key: string, value: string | number): Predicate {
+	return { type: "eq", key, value }
+}
+
+/**
+ * Creates a not equal predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The not equal predicate
+ *
+ * @example
+ * const predicate = neq("name", "John")
+ * // result = { type: "neq", key: "name", value: "John" }
+ */
+export function neq(key: string, value: string | number): Predicate {
+	return { type: "neq", key, value }
+}
+
+/**
+ * Creates a greater than predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The greater than predicate
+ *
+ * @example
+ * const predicate = gt("name", "John")
+ * // result = { type: "gt", key: "name", value: "John" }
+ */
+export function gt(key: string, value: string | number): Predicate {
+	return { type: "gt", key, value }
+}
+
+/**
+ * Creates a greater than or equal predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The greater than or equal predicate
+ *
+ * @example
+ * const predicate = gte("name", "John")
+ * // result = { type: "gte", key: "name", value: "John" }
+ */
+export function gte(key: string, value: string | number): Predicate {
+	return { type: "gte", key, value }
+}
+
+/**
+ * Creates a less than predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The less than predicate
+ *
+ * @example
+ * const predicate = lt("name", "John")
+ * // result = { type: "lt", key: "name", value: "John" }
+ */
+export function lt(key: string, value: string | number): Predicate {
+	return { type: "lt", key, value }
+}
+
+/**
+ * Creates a less than or equal predicate
+ * @param key - The key to compare
+ * @param value - The value to compare
+ * @returns The less than or equal predicate
+ *
+ * @example
+ * const predicate = lte("name", "John")
+ * // result = { type: "lte", key: "name", value: "John" }
+ */
+export function lte(key: string, value: string | number): Predicate {
+	return { type: "lte", key, value }
+}
+
+/**
+ * Creates a not predicate
+ * @param key - The key to compare
+ * @returns The not predicate
+ *
+ * @example
+ * const predicate = not("name")
+ * // result = { type: "not", key: "name", value: "" }
+ */
+export function not(key: string): Predicate {
+	return { type: "not", key, value: "" }
+}