Skip to content

PublicArkivActions

PublicArkivActions<transport, chain, account> = Pick<PublicActions<transport, chain, account>, "getBalance" | "getBlock" | "getBlockNumber" | "getChainId" | "getLogs" | "getTransaction" | "getTransactionCount" | "getTransactionReceipt" | "waitForTransactionReceipt" | "watchEvent"> & object

Defined in: src/clients/decorators/arkivPublic.ts:36

count: () => CountQueryBuilder

Returns a CountQueryBuilder: counts the entities a query matches, without fetching any of them.

It filters exactly as select does — .from(schema), .where(...), .ownedBy(...) and .createdBy(...) — and .fetch() resolves to a bigint. To show the total next to a page of rows, use select(...).withCount() instead.

  • JSON-RPC Methods: arkiv_query, with the count projection

CountQueryBuilder

const total = await client.count().from(Posts).ownedBy(account.address).fetch()
const news = await client.count().from(Posts).where(eq("category", "news")).fetch()

getBlockTiming: () => Promise<GetBlockTimingReturnType>

Returns the current block timing.

Promise<GetBlockTimingReturnType>

The current block timing. GetBlockTimingReturnType

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const blockTiming = await client.getBlockTiming()
// {
// currentBlock: 10n, // block number
// currentBlockTime: 1234567890, // block timestamp
// blockDuration: 2, // in seconds
// }

getEntity: {(key): Promise<Row<AllSelected, undefined>>; <S>(key, schema): Promise<Row<{ [K in string | number | symbol]: true }, S>>; }

Returns the entity with the given key.

Given a schema, it is read through it: the result is a flat row of every entity field and every column, each typed as the schema declares and checked against it.

  • JSON-RPC Methods: arkiv_getEntity

(key): Promise<Row<AllSelected, undefined>>

`0x${string}`

Promise<Row<AllSelected, undefined>>

<S>(key, schema): Promise<Row<{ [K in string | number | symbol]: true }, S>>

S extends Schema<Columns>

`0x${string}`

S

Promise<Row<{ [K in string | number | symbol]: true }, S>>

The entity key (hex string)

Optionally, the schema to read the entity through.

The entity with the given key, with every field populated — a FullEntity, or a FullRow through a schema.

If the key is not 32 bytes.

If no live entity has that key — it never existed, or it was deleted or has expired.

If, given a schema, the entity does not fit it.

If the schema given was not built with defineSchema.

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const entity = await client.getEntity(entityKey)
// {
// $key: "0x9f2c…",
// $owner: "0xabc…",
// $expiresAt: 1_297_000n,
// $attributes: { category: { type: "str", value: "docs" } },
// ...
// }
const post = await client.getEntity(entityKey, Posts)
// { $key: "0x9f2c…", $owner: "0xabc…", ..., category: { type: "str", value: "docs" }, ... }

getEntityNonce: (owner) => Promise<bigint>

Returns how many entities an account has created — its entity-minting nonce.

Not the account’s transaction nonce: the engine keeps its own counter per creator and mixes it into every key it mints, which is why two identical creates from one account never collide.

Address

The account whose nonce to read.

Promise<bigint>

The nonce the account’s next create will use.

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const nonce = await client.getEntityNonce("0xabc…")
// 7n — the next entity this account creates is its eighth

predictEntityKeys: <TCount, TSalts>(parameters) => Promise<PredictEntityKeysReturnType<TCount, TSalts>>

Works out the keys an account’s next creates will be given, before sending them.

The engine derives a key from the chain, the registry, the owner, the owner’s nonce and a salt — everything but the nonce is known to the caller, and the nonce is read here. This is what lets a batch reference an entity it is about to mint.

Each key arrives paired with the salt that mints it, because a create defaults to a random salt: a predicted key only holds if the create carries the salt it was predicted with. And the prediction holds only while nothing else from this owner is in flight — for a key you can rely on unconditionally, read it back from the create instead.

A literal count comes back as a fixed-length tuple, so the pairs destructure into names.

TCount extends number = number

TSalts extends readonly SaltInput[] | undefined = undefined

PredictEntityKeysParameters<TCount, TSalts>

Owner, and either a count or the salts. PredictEntityKeysParameters

Promise<PredictEntityKeysReturnType<TCount, TSalts>>

One { key, salt } pair per create, in batch order. PredictEntityKeysReturnType

A batch whose second entity points at its first.
import { defineSchema, key, str } from "@arkiv-network/sdk/schema"
const Nodes = defineSchema("nodes", { name: str(), parent: key().indexed().optional() })
const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
await wallet.executeBatch({
creates: [
{ schema: Nodes, values: { name: "root" }, expiration, salt: parent.salt },
{
schema: Nodes,
values: { name: "leaf", parent: key(parent.key) },
expiration,
salt: child.salt,
},
],
})

query: <S, K>(query, queryOptions?) => Promise<QueryReturnType<QueryRow<S>>>

Runs one query and returns one page, with no builder in between.

The selection means what it does in PublicArkivActions.select, and the results are the same flat rows a query without a schema returns, typed from the selection. Use select() to read through a schema. This also takes a raw string as an escape hatch for a query built elsewhere. A raw string goes to the node exactly as written, with none of the name, type or operator checks the expression combinators apply.

S extends SelectArg = "*"

K extends OrderTerm = OrderTerm

An Expression, or the raw query string.

Expression | string

QueryOptions<S, K>

Selection, sort, page size, offset and count. QueryOptions

Promise<QueryReturnType<QueryRow<S>>>

One page of entities. QueryReturnType

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { and, desc, eq, gte } from "@arkiv-network/sdk/query"
import { i32 } from "@arkiv-network/sdk/schema"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const page = await client.query(and(eq("category", "docs"), gte("level", i32(10))), {
select: { $key: true, title: true },
orderBy: desc("level", "i32"),
limit: 100,
})
// { entities: [{ $key: Hex; title: ArkivValue | undefined }], blockNumber: 32223n, count: undefined }
// The raw form, unchecked:
await client.query("category = str('docs') AND level >= i32(10)")

select: {(selection?): SelectQueryBuilder<"*">; <S>(selection): SelectQueryBuilder<SelectionOf<S>>; }

Returns a SelectQueryBuilder for building and executing queries — the recommended way to read entities. You declare up front which parts of an entity you want returned, so results always contain exactly the data you asked for.

The selection names entity fields and attributes side by side, and each result is a flat row. Chain .from(schema) to read through a schema: the selection keeps its meaning, but each attribute comes back typed and checked as the schema declares, and where may only filter on the schema’s indexed columns.

  • JSON-RPC Methods: arkiv_query

(selection?): SelectQueryBuilder<"*">

Select every field — and every column through a schema, or the $attributes map without one. Pass nothing or "*". The $attributeSchema is not included: select it by name.

"*"

SelectQueryBuilder<"*">

<S>(selection): SelectQueryBuilder<SelectionOf<S>>

Pick the fields to return. Set the ones you want to true (at least one is required); the result is typed to exactly those fields, so reading anything else is a compile error.

Entity fields start with $: $key, $owner, $creator, $createdAt, $updatedAt, $expiresAt and $creationFlags. $attributes reads every attribute as a map, and $attributeSchema their names, types and indexing without the values — a cheap way to find out what entities hold before fetching values that may be too large for one response. Any other name is an attribute, read as a field of its own: untyped without a schema, and through one typed and checked as the column it must be. An attribute name cannot start with $, so the two never collide.

Pass the selection inline so its fields stay literal true. A selection stored in a let/ const variable widens to boolean, and one typed SelectArg is only known at runtime: which fields come back is then decided at runtime, so every field of the result is optional — a PartialRow. Annotate a stored selection as const to keep it narrow.

S extends SelectArg

S & NonEmptySelection<S> & KnownSystemFields<S>

SelectQueryBuilder<SelectionOf<S>>

client.select({ $key: true, title: true }) // { $key: Hex; title: ArkivValue | undefined }
client.select({ $key: true, title: true }).from(Posts) // { $key: Hex; title: StrValue }
client.select({ $owner: true, $attributes: true }) // { $owner: Hex; $attributes: Attributes }
client.select({ $key: true, $attributeSchema: true }) // what do they hold? no values

What to include in the results. Omit it (or pass "*") to select everything, or pass an object to select specific parts (at least one field is required). Every part is opt-in, including the $key. The selection is flat — each field maps to a field of the result. SelectArg

A SelectQueryBuilder instance for building and executing queries. SelectQueryBuilder

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { and, eq, gt } from "@arkiv-network/sdk/query"
import { dec } from "@arkiv-network/sdk/schema"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
// through a schema — rows typed { $key: Hex; author: AddrValue; title: StrValue }
await client
.select({ $key: true, author: true, title: true })
.from(Posts)
.where(and(eq("category", "docs"), gt("score", dec("4.0"))))
.fetch()
// every field and column
await client.select().from(Posts).where(eq("category", "docs")).fetch()
// the same selection without a schema — rows typed
// { $key: Hex; author: ArkivValue | undefined; title: ArkivValue | undefined }
await client.select({ $key: true, author: true, title: true }).where(eq("category", "docs")).fetch()

watchEntityEvents: (parameters) => () => void

Watches entity events, calling the handlers you pass as they arrive.

All five are decoded from logs — onEntityCreated, onEntityPatched, onExpiryExtended, onOwnershipTransferred, onEntityDeleted — and each carries the block, transaction and log index it came from, which is the order the operations were applied in. onEvent receives all of them, whatever their type.

WatchEntityEventsParameters

Handlers and options, all optional. WatchEntityEventsParameters

A function that stops the watcher.

(): void

void

import { createPublicClient } from "@arkiv-network/sdk"
import { rabdi } from "@arkiv-network/sdk/chains"
import { http } from "viem"
const client = createPublicClient({
chain: rabdi({ accessKey: "..." }),
transport: http(),
})
const unwatch = client.watchEntityEvents({
onEntityCreated: ({ entityKey, expiresAt }) => console.log(entityKey, "until", expiresAt),
onError: (error) => console.error("watchEntityEvents error", error),
})
unwatch() // stop watching

transport extends Transport = Transport

chain extends Chain | undefined = Chain | undefined

account extends Account | undefined = Account | undefined