@arkiv-network/sdk 0.0.25

package/src/query/queryBuilder.ts

@@ -0,0 +1,174 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import { entityFromRpcResult } from "../utils/entities"
+import { processQuery } from "./engine"
+import type { Predicate } from "./predicate"
+import { QueryResult } from "./queryResult"
+
+/**
+ * QueryBuilder is a helper class to build queries to the Arkiv DBChains.
+ * It can be used to fetch entities from the Arkiv DBChains. It follows the Builder pattern allowing chaining of methods.
+ * @param client - The Arkiv client
+ * @returns The QueryBuilder instance {@link QueryBuilder}
+ */
+export class QueryBuilder {
+	private _client: ArkivClient
+	private _ownedBy: Hex | undefined
+	private _validBeforeBlock: number | undefined
+	private _withAnnotations: boolean | undefined
+	private _withMetadata: boolean | undefined
+	private _limit: number | undefined
+	private _offset: number | undefined
+	private _predicates: Predicate[]
+
+	constructor(client: ArkivClient) {
+		this._client = client
+		this._predicates = []
+	}
+
+	/**
+	 * Sets the ownedBy filter
+	 * @param ownedBy - The address of the owner
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.ownedBy("0x1234567890123456789012345678901234567890")
+	 */
+	ownedBy(ownedBy: Hex) {
+		this._ownedBy = ownedBy
+		return this
+	}
+
+	/**
+	 * Sets the withAnnotations flag which will return the annotations for the entities if true
+	 * @param withAnnotations - The boolean value to set
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.withAnnotations(true)
+	 */
+	withAnnotations(withAnnotations: boolean = true) {
+		this._withAnnotations = withAnnotations
+		return this
+	}
+
+	/**
+	 * Sets the withMetadata flag which will return the metadata (like owner, expiredAt, etc.) for the entities if true
+	 * @param withMetadata - The boolean value to set
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.withMetadata(true)
+	 */
+	withMetadata(withMetadata: boolean = true) {
+		this._withMetadata = withMetadata
+		return this
+	}
+
+	/**
+	 * Sets the limit for the query
+	 * @param limit - The number of entities to return
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.limit(10)
+	 */
+	limit(limit: number) {
+		this._limit = limit
+		return this
+	}
+
+	/**
+	 * Sets the offset for the query
+	 * @param offset - The number of entities to skip
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.offset(10)
+	 */
+	offset(offset: number) {
+		this._offset = offset
+		return this
+	}
+
+	/**
+	 * Sets the predicates for the query limiting the results. It can be a single predicate or an array of predicates combined with 'and'.
+	 * Predicates can be nested using 'or' and 'and' predicates.
+	 * @param predicates - The predicates to set
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.where(eq("name", "John"))
+	 * builder.where([eq("name", "John"), eq("age", 30)])
+	 * builder.where([eq("name", "John"), or([eq("age", 30), eq("age", 31)])])
+	 * builder.where([eq("name", "John"), and([eq("age", 30), eq("age", 31)])])
+	 * builder.where([eq("name", "John"), or([eq("age", 30), and([eq("age", 31), eq("age", 32)])])])
+	 * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), eq("age", 32)])])])
+	 * builder.where([eq("name", "John"), and([eq("age", 30), or([eq("age", 31), and([eq("age", 32), eq("age", 33)])])])])
+	 */
+	where(predicates: Predicate[] | Predicate) {
+		if (Array.isArray(predicates)) {
+			this._predicates.push(...predicates)
+		} else {
+			this._predicates.push(predicates)
+		}
+		return this
+	}
+
+	/**
+	 * Fetches the entities from the query. Re
+	 * It will return a QueryResult instance which can be used to fetch the next and previous pages.
+	 * @returns The QueryResult instance {@link QueryResult}
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * const result = await builder.where(eq("name", "John")).fetch()
+	 * // result = { entities: [Entity, Entity, Entity], next: async () => QueryResult, previous: async () => QueryResult }
+	 */
+	async fetch() {
+		const queryResult = await processQuery(this._client, {
+			predicates: this._predicates,
+			limit: this._limit,
+			offset: this._offset,
+			ownedBy: this._ownedBy,
+			validBeforeBlock: this._validBeforeBlock,
+			withAnnotations: this._withAnnotations,
+			withMetadata: this._withMetadata,
+		})
+
+		const entities = await Promise.all(
+			queryResult.map((entity) => entityFromRpcResult(this._client, entity.key, entity.value)),
+		)
+
+		return new QueryResult(entities, this, this._limit, this._offset)
+	}
+
+	/**
+	 * Counts the entities from the query.
+	 * @returns The number of entities
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * const result = await builder.where(eq("name", "John")).count()
+	 * // result = 10
+	 */
+	async count() {
+		const queryResult = await processQuery(this._client, {
+			predicates: this._predicates,
+			limit: this._limit,
+			offset: this._offset,
+			ownedBy: this._ownedBy,
+			validBeforeBlock: this._validBeforeBlock,
+			withAnnotations: this._withAnnotations,
+			withMetadata: this._withMetadata,
+		})
+
+		return queryResult.length
+	}
+}

package/src/query/queryResult.ts

@@ -0,0 +1,46 @@
+import type { Entity } from "../types/entity"
+import { NoMoreResultsError, NoOffsetOrLimitError, OffsetCannotBeLessThanZeroError } from "./errors"
+import type { QueryBuilder } from "./queryBuilder"
+
+export class QueryResult {
+	entities: Entity[]
+	private limit: number | undefined
+	private offset: number | undefined
+	private queryBuilder: QueryBuilder
+
+	constructor(
+		entities: Entity[],
+		queryBuilder: QueryBuilder,
+		limit: number | undefined = undefined,
+		offset: number | undefined = undefined,
+	) {
+		this.entities = entities
+		this.limit = limit
+		this.offset = offset
+		this.queryBuilder = queryBuilder
+	}
+
+	async next() {
+		if (this.offset === undefined || this.limit === undefined) {
+			throw new NoOffsetOrLimitError()
+		}
+		if (this.limit < this.entities.length) {
+			throw new NoMoreResultsError()
+		}
+		this.offset += this.limit
+		const result = await this.queryBuilder.offset(this.offset).fetch()
+		this.entities = result.entities
+	}
+
+	async previous() {
+		if (this.offset === undefined || this.limit === undefined) {
+			throw new NoOffsetOrLimitError()
+		}
+		if (this.offset - this.limit < 0) {
+			throw new OffsetCannotBeLessThanZeroError()
+		}
+		this.offset -= this.limit
+		const result = await this.queryBuilder.offset(this.offset).fetch()
+		this.entities = result.entities
+	}
+}

package/src/types/annotation.ts

@@ -0,0 +1,4 @@
+export type Annotation = {
+	key: string
+	value: string | number
+}

package/src/types/entity.ts

@@ -0,0 +1,38 @@
+import { bytesToString, type Hex } from "viem"
+import type { Annotation } from "./annotation"
+
+export class Entity {
+	key: Hex
+	owner: Hex
+	expiresAtBlock: number
+	payload: Uint8Array
+	annotations: Annotation[]
+
+	constructor(
+		key: Hex,
+		owner: Hex,
+		expiresAtBlock: number,
+		payload: Uint8Array,
+		annotations: Annotation[],
+	) {
+		this.key = key
+		this.owner = owner
+		this.expiresAtBlock = expiresAtBlock
+		this.payload = payload
+		this.annotations = annotations
+	}
+
+	toText(): string {
+		return bytesToString(this.payload)
+	}
+
+	toJson(): any {
+		return {
+			$key: this.key,
+			$annotations: this.annotations,
+			$owner: this.owner,
+			$expiresAtBlock: this.expiresAtBlock,
+			...JSON.parse(bytesToString(this.payload)),
+		}
+	}
+}

package/src/types/events.ts

@@ -0,0 +1,34 @@
+import type { Hex } from "viem"
+
+export type OnEntityCreatedEvent = {
+	entityKey: Hex
+	owner: Hex
+	expirationBlock: number
+	cost: bigint
+}
+
+export type OnEntityUpdatedEvent = {
+	entityKey: Hex
+	owner: Hex
+	oldExpirationBlock: number
+	newExpirationBlock: number
+	cost: bigint
+}
+
+export type OnEntityDeletedEvent = {
+	entityKey: Hex
+	owner: Hex
+}
+
+export type OnEntityExpiredEvent = {
+	entityKey: Hex
+	owner: Hex
+}
+
+export type OnEntityExpiresInExtendedEvent = {
+	entityKey: Hex
+	owner: Hex
+	oldExpirationBlock: number
+	newExpirationBlock: number
+	cost: bigint
+}

package/src/types/index.ts

@@ -0,0 +1,3 @@
+export type { Annotation } from "./annotation"
+export type { Entity } from "./entity"
+export type { TxParams } from "./txParams"

package/src/types/rpcSchema.ts

@@ -0,0 +1,35 @@
+import type { Hex, PublicRpcSchema } from "viem"
+
+export type ArkivRpcSchema = [
+	{
+		Method: "golembase_getStorageValue"
+		Parameters?: [entityId: Hex]
+		ReturnType: string
+	},
+	{
+		Method: "golembase_queryEntities"
+		Parameters?: [query: string]
+		ReturnType: [{ key: Hex; value: string }]
+	},
+	{
+		Method: "golembase_getEntityMetaData"
+		Parameters?: [entityId: Hex]
+		ReturnType: {
+			expiresAtBlock: number
+			owner: Hex
+			numericAnnotations: [{ key: string; value: number }]
+			stringAnnotations: [{ key: string; value: string }]
+		}
+	},
+	{
+		Method: "arkiv_getBlockTiming"
+		Parameters?: []
+		ReturnType: {
+			current_block: bigint
+			current_block_time: number
+			duration: number
+		}
+	},
+]
+
+export type PublicArkivRpcSchema = [...PublicRpcSchema, ...ArkivRpcSchema]

package/src/types/txParams.ts

@@ -0,0 +1,15 @@
+export type TxParams =
+	| {
+			gas?: bigint
+			nonce?: number
+			gasPrice?: bigint
+			maxFeePerGas?: never
+			maxPriorityFeePerGas?: never
+	  }
+	| {
+			gas?: bigint
+			nonce?: number
+			maxFeePerGas?: bigint
+			maxPriorityFeePerGas?: bigint
+			gasPrice?: never
+	  }

package/src/utils/arkivTransactions.ts

@@ -0,0 +1,91 @@
+import { type Hex, toHex, toRlp } from "viem"
+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 { ArkivClient } from "../clients/baseClient"
+import type { WalletArkivClient } from "../clients/createWalletClient"
+import { ARKIV_ADDRESS, BLOCK_TIME } from "../consts"
+import type { TxParams } from "../types"
+
+export function opsToTxData({
+	creates,
+	updates,
+	deletes,
+	extensions,
+}: {
+	creates?: CreateEntityParameters[]
+	updates?: UpdateEntityParameters[]
+	deletes?: DeleteEntityParameters[]
+	extensions?: ExtendEntityParameters[]
+}) {
+	function formatAnnotation<T extends string | number | bigint | boolean>(annotation: {
+		key: string
+		value: T
+	}): [Hex, Hex] {
+		return [toHex(annotation.key), toHex(annotation.value)]
+	}
+
+	const payload = [
+		//creates
+		(creates ?? []).map((item) => [
+			toHex(item.expiresIn / BLOCK_TIME),
+			toHex(item.payload),
+			item.annotations
+				.filter((annotation) => typeof annotation.value === "string")
+				.map(formatAnnotation),
+			item.annotations
+				.filter((annotation) => typeof annotation.value === "number")
+				.map(formatAnnotation),
+		]),
+		//updates
+		(updates ?? []).map((item) => [
+			item.entityKey,
+			toHex(item.expiresIn / BLOCK_TIME),
+			toHex(item.payload),
+			item.annotations
+				.filter((annotation) => typeof annotation.value === "string")
+				.map(formatAnnotation),
+			item.annotations
+				.filter((annotation) => typeof annotation.value === "number")
+				.map(formatAnnotation),
+		]),
+		//deletes
+		(deletes ?? []).map((item) => item.entityKey),
+		//extends
+		(extensions ?? []).map((item) => [item.entityKey, toHex(item.expiresIn / BLOCK_TIME)]),
+	]
+
+	console.debug("txData to send as RLP", payload)
+
+	return toRlp(payload)
+}
+
+export async function sendArkivTransaction(client: ArkivClient, data: Hex, txParams?: TxParams) {
+	if (!client.account) throw new Error("Account required")
+	const walletClient = client as WalletArkivClient
+
+	console.debug("Sending transaction", {
+		account: client.account,
+		chain: client.chain,
+		to: ARKIV_ADDRESS,
+		value: 0n,
+		data,
+		...txParams,
+	})
+
+	const txHash = await walletClient.sendTransaction({
+		account: client.account,
+		chain: client.chain,
+		to: ARKIV_ADDRESS,
+		value: 0n,
+		data,
+		...txParams,
+	})
+
+	const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash })
+
+	console.debug("Tx receipt", receipt)
+
+	return receipt
+}

package/src/utils/entities.ts

@@ -0,0 +1,22 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../clients/baseClient"
+import { Entity } from "../types/entity"
+
+export async function entityFromRpcResult(client: ArkivClient, key: Hex, payload: string) {
+	const metadata = await client.request({
+		method: "golembase_getEntityMetaData",
+		params: [key],
+	})
+	console.debug("Metadata", metadata)
+
+	return new Entity(key, metadata.owner, metadata.expiresAtBlock, Uint8Array.fromBase64(payload), [
+		...metadata.numericAnnotations.map(({ key, value }) => ({
+			key,
+			value: value,
+		})),
+		...metadata.stringAnnotations.map(({ key, value }) => ({
+			key,
+			value,
+		})),
+	])
+}

package/src/utils/expirationTime.ts

@@ -0,0 +1,13 @@
+import { BLOCK_TIME } from "../consts"
+
+export const ExpirationTime = {
+	fromSeconds: (seconds: number) => seconds,
+	fromMinutes: (minutes: number) => minutes * 60,
+	fromHours: (hours: number) => hours * 60 * 60,
+	fromDays: (days: number) => days * 24 * 60 * 60,
+	fromWeeks: (weeks: number) => weeks * 7 * 24 * 60 * 60,
+	fromMonths: (months: number) => months * 30 * 24 * 60 * 60,
+	fromYears: (years: number) => years * 365 * 24 * 60 * 60,
+	fromBlocks: (blocks: number) => blocks * BLOCK_TIME,
+	fromDate: (date: Date) => Math.floor(date.getTime() / 1000) - Math.floor(Date.now() / 1000),
+}

package/src/utils/index.ts

@@ -0,0 +1,3 @@
+export * from "viem/utils"
+export * from "./expirationTime"
+export * from "./payload"

package/src/utils/payload.ts

@@ -0,0 +1,9 @@
+import { toBytes } from "viem"
+
+export function jsonToPayload(json: object): Uint8Array {
+	return toBytes(JSON.stringify(json))
+}
+
+export function stringToPayload(data: string): Uint8Array {
+	return toBytes(data)
+}