@arkiv-network/sdk 0.7.0 → 0.8.0-dev.1

package/src/actions/public/getEntity.ts

@@ -1,50 +1,34 @@
-import { bytesToHex, type Hex, hexToBytes } from "viem"
+import type { Hex } from "viem"
+import { key } from "../../attr"
 import type { ArkivClient } from "../../clients/baseClient"
 import { NoEntityFoundError } from "../../errors"
-import { entityFromRpcResult } from "../../utils/entities"
+import { runQuery } from "../../query/engine"
+import { eq } from "../../query/expression"
+import { type FullEntity, toRpcSelect } from "../../query/selection"
 
-export async function getEntity(client: ArkivClient, key: Hex) {
-  // Normalize the key into bytes
-  let bytes: Uint8Array
-  try {
-    bytes = hexToBytes(key)
-  } catch {
-    throw new Error(`Invalid key format: ${key}. Key must be a valid hex string.`)
-  }
-
-  if (bytes.length !== 32) {
-    throw new Error(
-      `Invalid key length: ${bytes.length} bytes. Key must be 32 bytes (64 hex characters) long.`,
-    )
-  }
-
-  const hexKey = bytesToHex(bytes)
-
-  const result = await client.request({
-    method: "arkiv_query",
-    params: [
-      `$key = ${hexKey}`,
-      {
-        includeData: {
-          key: true,
-          attributes: true,
-          payload: true,
-          contentType: true,
-          expiration: true,
-          owner: true,
-          creator: true,
-          createdAtBlock: true,
-          lastModifiedAtBlock: true,
-          transactionIndexInBlock: true,
-          operationIndexInTransaction: true,
-        },
-      },
-    ],
+/**
+ * Reads one entity by key, with every field selected.
+ *
+ * Returns a {@link FullEntity} rather than an {@link Entity}: the selection is fixed at `"*"`, so
+ * every field is populated and none of them needs a `?` at the call site. The bare `Entity` type
+ * has every field optional because a `select()` result carries only what it asked for.
+ *
+ * @throws {InvalidValueError} If the key is not 32 bytes.
+ * @throws {NoEntityFoundError} If no live entity has that key — it never existed, or it was
+ * deleted or has expired.
+ */
+export async function getEntity(client: ArkivClient, entityKey: Hex): Promise<FullEntity> {
+  const { entities } = await runQuery(client, {
+    query: eq("$key", key(entityKey)).toString(),
+    select: toRpcSelect("*"),
+    limit: 1,
   })
 
-  if (!result.data.length) {
-    throw new NoEntityFoundError()
+  const entity = entities[0]
+  if (entity === undefined) {
+    throw new NoEntityFoundError(entityKey)
   }
-
-  return await entityFromRpcResult(result.data[0])
+  // Every field was selected, so the runtime Entity carries them all; the cast is the same
+  // narrowing `client.select("*")` gets from its own inference.
+  return entity as unknown as FullEntity
 }

package/src/actions/public/getEntityNonce.ts

@@ -0,0 +1,30 @@
+import type { Address } from "viem"
+import { readContract } from "viem/actions"
+import type { ArkivClient } from "../../clients/baseClient"
+import { ARKIV_ADDRESS } from "../../consts"
+import { ENTITY_NONCE_ABI } from "../../entity/operations"
+import { getLogger } from "../../utils/logger"
+
+const logger = getLogger("actions:public:get-entity-nonce")
+
+/**
+ * Reads an owner's entity-minting nonce — how many entities that account has created.
+ *
+ * This is not the account's transaction nonce. The engine keeps a separate counter per creator and
+ * mixes it into every key it mints, which is what makes two identical creates from one account land
+ * on different keys.
+ *
+ * @param owner - The account whose nonce to read.
+ * @returns The number of entities `owner` has created so far, which is the nonce its next create
+ * will use.
+ */
+export async function getEntityNonce(client: ArkivClient, owner: Address): Promise<bigint> {
+  const nonce = await readContract(client, {
+    address: ARKIV_ADDRESS,
+    abi: ENTITY_NONCE_ABI,
+    functionName: "entityNonce",
+    args: [owner],
+  })
+  logger("entity nonce of %s is %s", owner, nonce)
+  return nonce
+}

package/src/actions/public/predictEntityKeys.test.ts

@@ -0,0 +1,143 @@
+import { describe, expect, it, vi } from "bun:test"
+import { encodeFunctionResult, type Hex } from "viem"
+import type { ArkivClient } from "../../clients/baseClient"
+import { ARKIV_ADDRESS } from "../../consts"
+import { predictEntityKey } from "../../entity/key"
+import { ENTITY_NONCE_ABI } from "../../entity/operations"
+import { getEntityNonce } from "./getEntityNonce"
+import { predictEntityKeys } from "./predictEntityKeys"
+
+const OWNER = "0x1111111111111111111111111111111111111111" as const
+const CHAIN_ID = 1337
+
+/** A client whose `eth_call` answers one nonce, and records what it was asked. */
+function makeClient(nonce: bigint, options: { chain?: boolean } = {}) {
+  const request = vi.fn(async ({ method }: { method: string }) => {
+    if (method === "eth_call") {
+      return encodeFunctionResult({
+        abi: ENTITY_NONCE_ABI,
+        functionName: "entityNonce",
+        result: nonce,
+      })
+    }
+    if (method === "eth_chainId") return `0x${CHAIN_ID.toString(16)}`
+    throw new Error(`unexpected request: ${method}`)
+  })
+  const client = {
+    ...(options.chain === false ? {} : { chain: { id: CHAIN_ID } }),
+    request,
+  } as unknown as ArkivClient
+  return { client, request }
+}
+
+/** The `eth_call` the client was asked to make. */
+function ethCall(request: ReturnType<typeof vi.fn>) {
+  const call = request.mock.calls.find(([body]) => body.method === "eth_call")
+  return call?.[0].params[0] as { to: Hex; data: Hex }
+}
+
+describe("getEntityNonce", () => {
+  it("reads the owner's minting nonce off the registry", async () => {
+    const { client, request } = makeClient(7n)
+
+    expect(await getEntityNonce(client, OWNER)).toBe(7n)
+
+    // The selector is part of the node's ABI: `cast sig 'entityNonce(address)'` is 0x36917bfd.
+    const { to, data } = ethCall(request)
+    expect(to).toBe(ARKIV_ADDRESS)
+    expect(data).toBe(`0x36917bfd000000000000000000000000${OWNER.slice(2)}`)
+  })
+
+  it("reports a fresh account as zero rather than as an absence", async () => {
+    const { client } = makeClient(0n)
+    expect(await getEntityNonce(client, OWNER)).toBe(0n)
+  })
+})
+
+describe("predictEntityKeys", () => {
+  it("derives one pair per create, walking the nonce forward", async () => {
+    const { client } = makeClient(7n)
+
+    const pairs = await predictEntityKeys(client, { owner: OWNER, salts: [1n, 2n, 3n] })
+
+    expect(pairs).toEqual([
+      { salt: 1n, key: predictEntityKey({ owner: OWNER, nonce: 7n, salt: 1n, chainId: CHAIN_ID }) },
+      { salt: 2n, key: predictEntityKey({ owner: OWNER, nonce: 8n, salt: 2n, chainId: CHAIN_ID }) },
+      { salt: 3n, key: predictEntityKey({ owner: OWNER, nonce: 9n, salt: 3n, chainId: CHAIN_ID }) },
+    ])
+    // Distinct keys, which is the whole point of the nonce.
+    expect(new Set(pairs.map((pair) => pair.key)).size).toBe(3)
+  })
+
+  it("makes up the salts when only asked for a count, and pairs each with its key", async () => {
+    const { client } = makeClient(0n)
+
+    // A literal count is a tuple, so this destructures without a cast — that it compiles is the
+    // assertion.
+    const [first, second] = await predictEntityKeys(client, { owner: OWNER, count: 2 })
+
+    // Random salts, so the only thing worth asserting is that the keys follow from them.
+    expect(first.key).toBe(
+      predictEntityKey({ owner: OWNER, nonce: 0n, salt: first.salt, chainId: CHAIN_ID }),
+    )
+    expect(second.key).toBe(
+      predictEntityKey({ owner: OWNER, nonce: 1n, salt: second.salt, chainId: CHAIN_ID }),
+    )
+    expect(first.salt).not.toBe(second.salt)
+  })
+
+  it("keeps a runtime count a plain array rather than guessing its length", async () => {
+    const { client } = makeClient(0n)
+    const count: number = 3
+
+    const pairs = await predictEntityKeys(client, { owner: OWNER, count })
+
+    expect(pairs).toHaveLength(3)
+    expect(pairs.map((pair) => pair.key)).toEqual(
+      pairs.map((pair, index) =>
+        predictEntityKey({
+          owner: OWNER,
+          nonce: BigInt(index),
+          salt: pair.salt,
+          chainId: CHAIN_ID,
+        }),
+      ),
+    )
+  })
+
+  it("prefers the salts it was given over the count", async () => {
+    const { client } = makeClient(0n)
+    const pairs = await predictEntityKeys(client, { owner: OWNER, count: 5, salts: [9n] })
+    expect(pairs).toEqual([
+      { salt: 9n, key: predictEntityKey({ owner: OWNER, nonce: 0n, salt: 9n, chainId: CHAIN_ID }) },
+    ])
+  })
+
+  it("asks the chain for its id when the client was built without one", async () => {
+    const { client, request } = makeClient(0n, { chain: false })
+
+    const [only] = await predictEntityKeys(client, { owner: OWNER, salts: [1n] })
+
+    expect(request.mock.calls.some(([body]) => body.method === "eth_chainId")).toBe(true)
+    expect(only.key).toBe(
+      predictEntityKey({ owner: OWNER, nonce: 0n, salt: 1n, chainId: CHAIN_ID }),
+    )
+  })
+
+  it("refuses a request that does not say how many keys it wants", async () => {
+    const { client } = makeClient(0n)
+    await expect(predictEntityKeys(client, { owner: OWNER })).rejects.toThrow(/`count` or `salts`/)
+    await expect(predictEntityKeys(client, { owner: OWNER, salts: [] })).rejects.toThrow(/empty/)
+    await expect(predictEntityKeys(client, { owner: OWNER, count: 0 })).rejects.toThrow(
+      /positive whole number/,
+    )
+    await expect(predictEntityKeys(client, { owner: OWNER, count: 1.5 })).rejects.toThrow(
+      /positive whole number/,
+    )
+  })
+
+  it("rejects a salt too wide for the uint128 the engine mixes in", async () => {
+    const { client } = makeClient(0n)
+    await expect(predictEntityKeys(client, { owner: OWNER, salts: [2n ** 128n] })).rejects.toThrow()
+  })
+})

package/src/actions/public/predictEntityKeys.ts

@@ -0,0 +1,138 @@
+import type { Address, Hex } from "viem"
+import { getChainId } from "viem/actions"
+import type { ArkivClient } from "../../clients/baseClient"
+import { predictEntityKey, randomSalt, validateSalt } from "../../entity/key"
+import { getEntityNonce } from "./getEntityNonce"
+
+/**
+ * A key a create will be given, together with the salt that mints it.
+ *
+ * The two travel as a pair because neither is any use alone: a create defaults to a *random* salt,
+ * so the key only comes out as predicted if that same create carries this salt.
+ */
+export type PredictedEntityKey = {
+  /** The key the create will be given. */
+  key: Hex
+  /** The salt the create must carry for its key to come out as {@link PredictedEntityKey.key}. */
+  salt: bigint
+}
+
+/** Parameters for {@link predictEntityKeys}. */
+export type PredictEntityKeysParameters<
+  TCount extends number = number,
+  TSalts extends readonly bigint[] | undefined = readonly bigint[] | undefined,
+> = {
+  /** The account that will sign the creates. Its nonce is what the keys are derived from. */
+  owner: Address
+  /**
+   * How many creates the batch will carry. Ignored when `salts` is given, which already says how
+   * many there are.
+   *
+   * A literal count comes back as a fixed-length tuple, so `count: 2` destructures into two named
+   * pairs without a cast.
+   */
+  count?: TCount | undefined
+  /**
+   * The salt each create will carry, in batch order. Defaults to `count` fresh random salts —
+   * either way each key comes back paired with the salt that mints it.
+   */
+  salts?: TSalts
+}
+
+/**
+ * The keys a batch would mint, in batch order, each paired with its salt.
+ *
+ * The length follows the request whenever it is known statically: a literal `count`, or a `salts`
+ * tuple, gives a fixed-length tuple; a count computed at runtime gives a plain array.
+ *
+ * `TSalts` is wrapped in a tuple to stop the conditional distributing over it. Left naked, the
+ * `readonly bigint[] | undefined` default would take both branches and union a tuple with an array,
+ * which widens the length straight back to `number`.
+ */
+export type PredictEntityKeysReturnType<
+  TCount extends number = number,
+  TSalts extends readonly bigint[] | undefined = readonly bigint[] | undefined,
+> = [TSalts] extends [readonly bigint[]]
+  ? { -readonly [Index in keyof TSalts]: PredictedEntityKey }
+  : Repeat<PredictedEntityKey, TCount>
+
+/**
+ * A tuple of `TLength` × `T`, or a plain array when the length is only known at runtime.
+ *
+ * Written tail-recursively so TypeScript can build the batch sizes anyone would actually send.
+ */
+type Repeat<T, TLength extends number, TAcc extends T[] = []> = number extends TLength
+  ? T[]
+  : TAcc["length"] extends TLength
+    ? TAcc
+    : Repeat<T, TLength, [...TAcc, T]>
+
+/**
+ * Works out the keys an account's next creates will be given, before sending them.
+ *
+ * A key is `keccak256(chainId ++ registry ++ owner ++ nonce ++ salt)`. Everything but the nonce is
+ * known to the caller, and the nonce is read here — so a batch can reference a key it is about to
+ * mint, storing it as a `key` attribute on a sibling entity created in the same transaction.
+ *
+ * Each key arrives paired with its salt, and the create must be given that salt: a create left to
+ * pick its own salt picks a random one, which mints a different key.
+ *
+ * The prediction is valid only while nothing else from this owner is in flight. Every create that
+ * lands first takes the nonce with it and moves these keys. For a key you can rely on
+ * unconditionally, read it back from the create instead — `createEntity` and `mutateEntities`
+ * report the keys the engine actually minted.
+ *
+ * @param parameters - Owner, and either a count or the salts. {@link PredictEntityKeysParameters}
+ * @returns One `{ key, salt }` pair per create, in batch order. {@link PredictEntityKeysReturnType}
+ *
+ * @example A batch whose second entity points at its first.
+ * import { key } from "@arkiv-network/sdk/attr"
+ *
+ * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
+ * await wallet.mutateEntities({
+ *   creates: [
+ *     { payload, contentType, expires, salt: parent.salt },
+ *     {
+ *       payload,
+ *       contentType,
+ *       expires,
+ *       salt: child.salt,
+ *       attributes: { parent: key(parent.key) },
+ *     },
+ *   ],
+ * })
+ */
+export async function predictEntityKeys<
+  const TCount extends number = number,
+  const TSalts extends readonly bigint[] | undefined = undefined,
+>(
+  client: ArkivClient,
+  { owner, count, salts }: PredictEntityKeysParameters<TCount, TSalts>,
+): Promise<PredictEntityKeysReturnType<TCount, TSalts>> {
+  const resolvedSalts = resolveSalts(count, salts)
+
+  const chainId = client.chain?.id ?? (await getChainId(client))
+  const nonce = await getEntityNonce(client, owner)
+
+  return resolvedSalts.map((salt, index) => ({
+    key: predictEntityKey({ owner, nonce: nonce + BigInt(index), salt, chainId }),
+    salt,
+  })) as PredictEntityKeysReturnType<TCount, TSalts>
+}
+
+/** The salts to derive from: the ones given, or `count` fresh random ones. */
+function resolveSalts(count: number | undefined, salts: readonly bigint[] | undefined): bigint[] {
+  if (salts !== undefined) {
+    if (salts.length === 0) {
+      throw new Error("predictEntityKeys: `salts` is empty — there is nothing to predict")
+    }
+    return salts.map(validateSalt)
+  }
+  if (count === undefined) {
+    throw new Error("predictEntityKeys: pass either `count` or `salts`")
+  }
+  if (!Number.isInteger(count) || count <= 0) {
+    throw new Error(`predictEntityKeys: \`count\` must be a positive whole number, got ${count}`)
+  }
+  return Array.from({ length: count }, () => randomSalt())
+}

package/src/actions/public/query.ts

@@ -1,83 +1,47 @@
-import { numberToHex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
+import { runQuery } from "../../query/engine"
+import type { Expression } from "../../query/expression"
+import { type SelectArg, toRpcSelect } from "../../query/selection"
 import type { Entity } from "../../types/entity"
-import type { RpcQueryOptions } from "../../types/rpcSchema"
-import { entityFromRpcResult } from "../../utils/entities"
-
-export type QueryOptionsIncludeData = {
-  attributes?: boolean
-  payload?: boolean
-  metadata?: boolean
-}
-/**
- * @deprecated Server-side ordering is not supported by the network. Sort the fetched
- * entities in JavaScript instead (e.g. `entities.sort(...)`). This type will be removed
- * in a future release.
- */
-export type QueryOptionsOrderBy = {
-  name: string
-  type: "string" | "numeric"
-  desc: "asc" | "desc"
-}
 
 export type QueryOptions = {
-  includeData?: QueryOptionsIncludeData
-  atBlock?: bigint
-  /**
-   * @deprecated Server-side ordering is not supported by the network, so this option has no
-   * effect on the returned order. Sort the fetched entities in JavaScript instead
-   * (e.g. `entities.sort(...)`). This option will be removed in a future release.
-   */
-  orderBy?: QueryOptionsOrderBy[]
-  resultsPerPage?: number | undefined
+  /** What to return. Defaults to everything. */
+  select?: SelectArg | undefined
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined
+  /** Page size, up to the node maximum of 200. */
+  limit?: number | undefined
+  /** Cursor from a previous page. */
   cursor?: string | undefined
 }
 
 export type QueryReturnType = {
   entities: Entity[]
+  /** The cursor for the next page, or `undefined` when no pages remain. */
   cursor: string | undefined
-  blockNumber: bigint | undefined
+  /** The block the page was read at. */
+  blockNumber: bigint
 }
 
-export async function query(client: ArkivClient, query: string, queryOptions?: QueryOptions) {
-  const rpcQueryOptions: RpcQueryOptions = {
-    includeData: {
-      key: true,
-      payload: queryOptions?.includeData?.payload ?? true,
-      attributes: queryOptions?.includeData?.attributes ?? false,
-      contentType: queryOptions?.includeData?.metadata ?? false,
-      expiration: queryOptions?.includeData?.metadata ?? false,
-      owner: queryOptions?.includeData?.metadata ?? false,
-      creator: queryOptions?.includeData?.metadata ?? false,
-      createdAtBlock: queryOptions?.includeData?.metadata ?? false,
-      lastModifiedAtBlock: queryOptions?.includeData?.metadata ?? false,
-      transactionIndexInBlock: queryOptions?.includeData?.metadata ?? false,
-      operationIndexInTransaction: queryOptions?.includeData?.metadata ?? false,
-    },
-    ...(queryOptions?.atBlock !== undefined && { atBlock: numberToHex(queryOptions.atBlock) }),
-    ...(queryOptions?.orderBy && {
-      orderBy: queryOptions?.orderBy.map((order) => ({
-        name: order.name,
-        type: order.type,
-        desc: order.desc === "desc",
-      })),
-    }),
-    ...(queryOptions?.resultsPerPage !== undefined && {
-      resultsPerPage: numberToHex(queryOptions.resultsPerPage),
-    }),
-    ...(queryOptions?.cursor !== undefined && { cursor: queryOptions?.cursor }),
-  }
-
-  const result = await client.request({
-    method: "arkiv_query",
-    params: [query, rpcQueryOptions],
+/**
+ * Runs a single query and returns one page, with no builder in between.
+ *
+ * Takes either an {@link Expression} or a raw query string. The string form is an escape hatch for
+ * a query built elsewhere — it goes to the node exactly as written, with none of the name, type or
+ * operator checks the expression combinators apply.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+export function query(
+  client: ArkivClient,
+  query: Expression | string,
+  options: QueryOptions = {},
+): Promise<QueryReturnType> {
+  return runQuery(client, {
+    query: query.toString(),
+    select: toRpcSelect(options.select),
+    limit: options.limit,
+    cursor: options.cursor,
+    atBlock: options.atBlock,
   })
-
-  const entities = await Promise.all(result.data.map((entity) => entityFromRpcResult(entity)))
-
-  return {
-    entities,
-    cursor: result.cursor,
-    blockNumber: BigInt(result.blockNumber),
-  }
 }