@arkiv-network/sdk 0.0.36-dev.0 → 0.0.36-dev.1

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@arkiv-network/sdk",
-	"version": "0.0.36-dev.0",
+	"version": "0.0.36-dev.1",
 	"description": "TypeScript-only client library for Arkiv blockchain interactions",
 	"type": "module",
 	"main": "./dist/_cjs/index.js",

package/src/actions/public/getEntity.ts

@@ -1,13 +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 payload = await client.request({
-		method: "golembase_getStorageValue",
-		params: [key],
+	const result = await client.request({
+		method: "arkiv_query",
+		params: [`$key = ${key}`],
 	})
-	console.debug("Payload", payload)
+	console.debug("GetEntity result", result)
 
-	return entityFromRpcResult(client, key, payload)
+	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

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

package/src/clients/decorators/arkivPublic.ts

@@ -1,6 +1,7 @@
 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"
@@ -95,6 +96,42 @@ export type PublicArkivActions<
 	 */
 	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
@@ -131,6 +168,7 @@ export function publicArkivActions<
 		query: (rawQuery: string) => query(client, rawQuery),
 		buildQuery: () => new QueryBuilder(client),
 		getBlockTiming: () => getBlockTiming(client),
+		getEntityCount: () => getEntityCount(client),
 		subscribeEntityEvents: (
 			{
 				onError,

package/src/query/engine.ts

@@ -1,5 +1,6 @@
 import type { Hex } from "viem"
 import type { ArkivClient } from "../clients/baseClient"
+import type { RpcQueryOptions } from "../types/rpcSchema"
 import type { Predicate } from "./predicate"
 
 function processPredicates(predicates: Predicate[]): string {
@@ -42,31 +43,33 @@ export async function processQuery(
 	queryParams: {
 		predicates: Predicate[]
 		limit: number | undefined
-		offset: number | undefined
+		cursor: string | undefined
 		ownedBy: Hex | undefined
-		validBeforeBlock?: number | undefined
+		validAtBlock?: bigint | undefined
 		withAnnotations?: boolean | undefined
 		withMetadata?: boolean | undefined
+		withPayload?: boolean | undefined
 	},
 ) {
-	const { predicates, limit, offset, ownedBy, validBeforeBlock, withAnnotations, withMetadata } =
-		queryParams
+	const {
+		predicates,
+		limit,
+		cursor,
+		ownedBy,
+		validAtBlock,
+		withAnnotations,
+		withMetadata,
+		withPayload,
+	} = queryParams
 
 	console.debug(
-		`Processing query with params: predicates: ${predicates}, limit: ${limit}, offset: ${offset}, ownedBy: ${ownedBy}, validBeforeBlock: ${validBeforeBlock}, withAnnotations: ${withAnnotations}, withMetadata: ${withMetadata}`,
+		`Processing query with params: predicates: ${predicates}, cursor: ${cursor}, limit: ${limit}, ownedBy: ${ownedBy}, validAtBlock: ${validAtBlock}, withAnnotations: ${withAnnotations}, withMetadata: ${withMetadata}, withPayload: ${withPayload}`,
 	)
 
 	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()
@@ -74,11 +77,31 @@ export async function processQuery(
 		query = query.slice(3)
 	}
 
-	console.debug(`Built query to send: ${query}`)
+	const queryOptions: RpcQueryOptions = {
+		includeData: {
+			key: true,
+			annotations: withAnnotations ?? false,
+			payload: withPayload ?? false,
+			expiration: withMetadata ?? false,
+			owner: withMetadata ?? false,
+		},
+	}
+
+	if (validAtBlock !== undefined) {
+		queryOptions.atBlock = validAtBlock
+	}
+	if (limit !== undefined) {
+		queryOptions.resultsPerPage = limit
+	}
+	if (cursor !== undefined) {
+		queryOptions.cursor = cursor
+	}
+
+	console.debug(`Built query to send: ${query}, queryOptions: ${JSON.stringify(queryOptions)}`)
 
 	const result = await client.request({
-		method: "golembase_queryEntities",
-		params: [query],
+		method: "arkiv_query",
+		params: [query, queryOptions],
 	})
 	console.debug("Raw result from query: ", result)
 

package/src/query/errors.ts

@@ -4,9 +4,9 @@ export class NoMoreResultsError extends Error {
 	}
 }
 
-export class NoOffsetOrLimitError extends Error {
+export class NoCursorOrLimitError extends Error {
 	constructor() {
-		super("Offset and limit must be defined to fetch next or previous")
+		super("Cursor and limit must be defined to fetch next")
 	}
 }
 
@@ -15,3 +15,9 @@ export class OffsetCannotBeLessThanZeroError extends Error {
 		super("Offset cannot be less than 0")
 	}
 }
+
+export class NoEntityFoundError extends Error {
+	constructor() {
+		super("No entity found")
+	}
+}

package/src/query/queryBuilder.ts

@@ -14,11 +14,12 @@ import { QueryResult } from "./queryResult"
 export class QueryBuilder {
 	private _client: ArkivClient
 	private _ownedBy: Hex | undefined
-	private _validBeforeBlock: number | undefined
+	private _validAtBlock: bigint | undefined
 	private _withAnnotations: boolean | undefined
 	private _withMetadata: boolean | undefined
+	private _withPayload: boolean | undefined
 	private _limit: number | undefined
-	private _offset: number | undefined
+	private _cursor: string | undefined
 	private _predicates: Predicate[]
 
 	constructor(client: ArkivClient) {
@@ -68,6 +69,20 @@ export class QueryBuilder {
 		return this
 	}
 
+	/**
+	 * Sets the withPayload flag which will return the payload for the entities if true
+	 * @param withPayload - The boolean value to set
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.withPayload(true)
+	 */
+	withPayload(withPayload: boolean = true) {
+		this._withPayload = withPayload
+		return this
+	}
+
 	/**
 	 * Sets the limit for the query
 	 * @param limit - The number of entities to return
@@ -83,16 +98,31 @@ export class QueryBuilder {
 	}
 
 	/**
-	 * Sets the offset for the query
-	 * @param offset - The number of entities to skip
+	 * Sets the cursor for the query - it is advances setting which rather shouldn't be used manually but it is provided from query result if limit is used (pagination).
+	 * @param cursor - The cursor to set which tells to RPC Query server where to start or continue the query.
 	 * @returns The QueryBuilder instance
 	 *
 	 * @example
 	 * const builder = new QueryBuilder(client)
 	 * builder.offset(10)
 	 */
-	offset(offset: number) {
-		this._offset = offset
+	cursor(cursor: string) {
+		this._cursor = cursor
+		return this
+	}
+
+	/**
+	 * Sets the validAtBlock for the query which tells at which block height the state we are intested.
+	 * If not set, the latest block is  used.
+	 * @param validAtBlock - The block number to set
+	 * @returns The QueryBuilder instance
+	 *
+	 * @example
+	 * const builder = new QueryBuilder(client)
+	 * builder.validAtBlock(10000)
+	 */
+	validAtBlock(validAtBlock: bigint) {
+		this._validAtBlock = validAtBlock
 		return this
 	}
 
@@ -135,18 +165,22 @@ export class QueryBuilder {
 		const queryResult = await processQuery(this._client, {
 			predicates: this._predicates,
 			limit: this._limit,
-			offset: this._offset,
+			cursor: this._cursor,
 			ownedBy: this._ownedBy,
-			validBeforeBlock: this._validBeforeBlock,
+			validAtBlock: this._validAtBlock,
 			withAnnotations: this._withAnnotations,
 			withMetadata: this._withMetadata,
+			withPayload: this._withPayload,
 		})
 
 		const entities = await Promise.all(
-			queryResult.map((entity) => entityFromRpcResult(this._client, entity.key, entity.value)),
+			queryResult.data.map((entity) => entityFromRpcResult(entity)),
 		)
 
-		return new QueryResult(entities, this, this._limit, this._offset)
+		this.cursor(queryResult.cursor)
+		this.validAtBlock(queryResult.blockNumber)
+
+		return new QueryResult(entities, this, this._cursor, this._limit, this._validAtBlock)
 	}
 
 	/**
@@ -162,13 +196,14 @@ export class QueryBuilder {
 		const queryResult = await processQuery(this._client, {
 			predicates: this._predicates,
 			limit: this._limit,
-			offset: this._offset,
+			cursor: this._cursor,
 			ownedBy: this._ownedBy,
-			validBeforeBlock: this._validBeforeBlock,
-			withAnnotations: this._withAnnotations,
-			withMetadata: this._withMetadata,
+			validAtBlock: this._validAtBlock,
+			withAnnotations: false,
+			withMetadata: false,
+			withPayload: false,
 		})
 
-		return queryResult.length
+		return queryResult.data.length ?? 0
 	}
 }

package/src/query/queryResult.ts

@@ -1,46 +1,57 @@
 import type { Entity } from "../types/entity"
-import { NoMoreResultsError, NoOffsetOrLimitError, OffsetCannotBeLessThanZeroError } from "./errors"
+import { NoCursorOrLimitError, NoMoreResultsError } from "./errors"
 import type { QueryBuilder } from "./queryBuilder"
 
 export class QueryResult {
 	entities: Entity[]
-	private limit: number | undefined
-	private offset: number | undefined
-	private queryBuilder: QueryBuilder
+	private _endOfIteration: boolean
+	private _cursor: string | undefined
+	private _limit: number | undefined
+	private _validAtBlock: bigint | undefined
+	private _queryBuilder: QueryBuilder
+
+	// Public getters for internal state
+	get queryBuilder(): QueryBuilder {
+		return this._queryBuilder
+	}
+
+	get cursor(): string | undefined {
+		return this._cursor
+	}
 
 	constructor(
 		entities: Entity[],
 		queryBuilder: QueryBuilder,
-		limit: number | undefined = undefined,
-		offset: number | undefined = undefined,
+		cursor: string | undefined,
+		limit: number | undefined,
+		validAtBlock: bigint | undefined,
 	) {
 		this.entities = entities
-		this.limit = limit
-		this.offset = offset
-		this.queryBuilder = queryBuilder
+		this._queryBuilder = queryBuilder
+		this._endOfIteration = !limit || entities.length < limit
+		this._cursor = cursor
+		this._limit = limit
+		this._validAtBlock = validAtBlock
 	}
 
 	async next() {
-		if (this.offset === undefined || this.limit === undefined) {
-			throw new NoOffsetOrLimitError()
+		if (this._cursor === undefined || this._limit === undefined) {
+			throw new NoCursorOrLimitError()
 		}
-		if (this.limit < this.entities.length) {
+		if (this._endOfIteration) {
 			throw new NoMoreResultsError()
 		}
-		this.offset += this.limit
-		const result = await this.queryBuilder.offset(this.offset).fetch()
+		this._queryBuilder.cursor(this._cursor)
+		const result = await this._queryBuilder.fetch()
 		this.entities = result.entities
-	}
+		// Update the query builder reference
+		this._queryBuilder = result.queryBuilder
+		// Check if we've reached the end (no more cursor or we got fewer entities than limit)
+		this._endOfIteration = !result.cursor || result.entities.length < this._limit
+		// Update the cursor
+		this._cursor = result.cursor
 
-	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
+		// TODO check current block height and if it is not too old
+		console.debug("Current block height for next page: ", this._validAtBlock)
 	}
 }

package/src/types/entity.ts

@@ -4,14 +4,14 @@ import type { Annotation } from "./annotation"
 export class Entity {
 	key: Hex
 	owner: Hex
-	expiresAtBlock: number
+	expiresAtBlock: bigint
 	payload: Uint8Array
 	annotations: Annotation[]
 
 	constructor(
 		key: Hex,
 		owner: Hex,
-		expiresAtBlock: number,
+		expiresAtBlock: bigint,
 		payload: Uint8Array,
 		annotations: Annotation[],
 	) {

package/src/types/rpcSchema.ts

@@ -1,5 +1,29 @@
 import type { Hex, PublicRpcSchema } from "viem"
 
+export type RpcEntity = {
+	key: Hex
+	value: string
+	expiresAt: bigint
+	owner: Hex
+	stringAnnotations?: [{ key: string; value: string }]
+	numericAnnotations?: [{ key: string; value: number }]
+}
+
+export type RpcQueryOptions = {
+	atBlock?: bigint
+	includeData?: RpcIncludeData
+	resultsPerPage?: number
+	cursor?: string
+}
+
+export type RpcIncludeData = {
+	key: boolean
+	annotations: boolean
+	payload: boolean
+	expiration: boolean
+	owner: boolean
+}
+
 export type ArkivRpcSchema = [
 	{
 		Method: "golembase_getStorageValue"
@@ -7,9 +31,13 @@ export type ArkivRpcSchema = [
 		ReturnType: string
 	},
 	{
-		Method: "golembase_queryEntities"
-		Parameters?: [query: string]
-		ReturnType: [{ key: Hex; value: string }]
+		Method: "arkiv_query"
+		Parameters?: [query: string, queryOptions?: RpcQueryOptions]
+		ReturnType: {
+			data: [RpcEntity]
+			blockNumber: bigint
+			cursor: string
+		}
 	},
 	{
 		Method: "golembase_getEntityMetaData"
@@ -30,6 +58,11 @@ export type ArkivRpcSchema = [
 			duration: number
 		}
 	},
+	{
+		Method: "arkiv_getEntityCount"
+		Parameters?: []
+		ReturnType: number
+	},
 ]
 
 export type PublicArkivRpcSchema = [...PublicRpcSchema, ...ArkivRpcSchema]

package/src/utils/entities.ts

@@ -1,20 +1,14 @@
-import type { Hex } from "viem"
-import type { ArkivClient } from "../clients/baseClient"
+import { toBytes } from "viem"
 import { Entity } from "../types/entity"
+import type { RpcEntity } from "../types/rpcSchema"
 
-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.stringAnnotations ?? []).map(({ key, value }) => ({
+export async function entityFromRpcResult(rpcEntity: RpcEntity) {
+	return new Entity(rpcEntity.key, rpcEntity.owner, rpcEntity.expiresAt, toBytes(rpcEntity.value), [
+		...(rpcEntity.stringAnnotations ?? []).map(({ key, value }) => ({
 			key,
 			value,
 		})),
-		...(metadata.numericAnnotations ?? []).map(({ key, value }) => ({
+		...(rpcEntity.numericAnnotations ?? []).map(({ key, value }) => ({
 			key,
 			value: value,
 		})),