@arkiv-network/sdk 0.0.25

package/src/actions/public/query.ts

@@ -0,0 +1,15 @@
+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: "golembase_queryEntities",
+		params: [query],
+	})
+
+	const entities = await Promise.all(
+		result.map((entity) => entityFromRpcResult(client, entity.key, entity.value)),
+	)
+
+	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/createEntity.ts

@@ -0,0 +1,43 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { Annotation, TxParams } from "../../types"
+import { opsToTxData, sendArkivTransaction } from "../../utils/arkivTransactions"
+
+/**
+ * Parameters for the createEntity function.
+ * - payload: The payload of the entity.
+ * - annotations: The annotations of the entity.
+ * - expiresIn: The expires in of the entity in seconds.
+ */
+export type CreateEntityParameters = {
+	payload: Uint8Array
+	annotations: Annotation[]
+	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,45 @@
+import type { Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import type { Annotation, 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.
+ * - annotations: The annotations of the entity.
+ * - expiresIn: The expires in of the entity in seconds.
+ */
+export type UpdateEntityParameters = {
+	entityKey: Hex
+	payload: Uint8Array | string
+	annotations: Annotation[]
+	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.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.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
+	>
+}