@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

package/src/clients/decorators/arkivAdvanced.ts

@@ -0,0 +1,144 @@
+import type { Account, Chain, Client, Hash, TransactionReceipt, Transport } from "viem"
+import type {
+  BuildMutationOptions,
+  BuildMutationReturnType,
+} from "../../actions/advanced/buildMutation"
+import { buildMutation } from "../../actions/advanced/buildMutation"
+import type {
+  GetMutationResultReturnType,
+  MutationResult,
+} from "../../actions/advanced/getMutationResult"
+import { decodeMutationResult, getMutationResult } from "../../actions/advanced/getMutationResult"
+import type { PingTransactionReturnType } from "../../actions/advanced/pingTransaction"
+import { pingTransaction } from "../../actions/advanced/pingTransaction"
+import type {
+  SendMutationOptions,
+  SendMutationReturnType,
+} from "../../actions/advanced/sendMutation"
+import { sendMutation } from "../../actions/advanced/sendMutation"
+import type { EntityMutationOps } from "../../utils/arkivTransactions"
+
+/**
+ * The read-only half of the advanced path — checking on a transaction and decoding its result —
+ * which needs no account, so a Public Client carries it too.
+ *
+ * Every action here costs at most one RPC call, and says exactly which.
+ */
+export type PublicAdvancedActions = {
+  /**
+   * Asks the chain — once — whether a transaction has landed. Exactly one
+   * `eth_getTransactionReceipt`, never a poll: an unmined transaction comes back as
+   * `{ status: "pending" }` and the schedule stays yours.
+   *
+   * @param txHash - The transaction hash returned by `sendMutation` (or any other send)
+   * @returns `{ status: "pending" }`, or `{ status: "success" | "reverted", blockNumber }`
+   *
+   * @example
+   * const { status } = await client.advanced.pingTransaction(txHash)
+   * if (status === "pending") scheduleAnotherPing()
+   */
+  pingTransaction: (txHash: Hash) => Promise<PingTransactionReturnType>
+
+  /**
+   * Fetches a transaction's receipt — once — and decodes what the mutation did: created keys and
+   * expiries, plus the keys of everything patched, deleted, extended or handed over. One
+   * `eth_getTransactionReceipt`; `{ status: "pending" }` if not mined yet. No revert diagnosis is
+   * run on a `reverted` result — that extra call is yours to spend or skip.
+   *
+   * @param txHash - The transaction hash
+   * @returns The decoded {@link MutationResult}, or `{ status: "pending" }`
+   *
+   * @example
+   * const result = await client.advanced.getMutationResult(txHash)
+   * if (result.status === "success") console.log(result.createdEntities)
+   */
+  getMutationResult: (txHash: Hash) => Promise<GetMutationResultReturnType>
+
+  /**
+   * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls** — for
+   * receipts that reached you through your own `waitForTransactionReceipt`, a block watcher, or a
+   * webhook.
+   *
+   * @param receipt - The transaction receipt
+   * @returns The decoded {@link MutationResult}
+   */
+  decodeMutationResult: (receipt: TransactionReceipt) => MutationResult
+}
+
+/**
+ * The advanced path on a Wallet Client: build, send, ping and read results as separate steps, each
+ * costing the minimum number of RPC calls — down to one per transaction when you supply what the
+ * SDK would otherwise look up.
+ *
+ * The everyday actions (`createEntity`, `executeBatch`, …) bundle send + wait + decode and are
+ * the right default. This namespace unbundles them for callers optimising their RPC budget.
+ *
+ * @example Minimal-call flow: one send, one ping, done.
+ * const { txHash } = await client.advanced.sendMutation(
+ *   { creates: [{ payload, contentType: "application/json", expires }] },
+ *   { currentBlock, txParams: { nonce, gas: 1_000_000n, maxFeePerGas, maxPriorityFeePerGas } },
+ * ) // exactly 1 RPC call: eth_sendRawTransaction
+ * // ... later, on your own schedule:
+ * const result = await client.advanced.getMutationResult(txHash) // 1 RPC call
+ * if (result.status === "success") console.log(result.createdEntities)
+ */
+export type WalletAdvancedActions = PublicAdvancedActions & {
+  /**
+   * Encodes a mutation batch without sending anything: zero RPC calls with `currentBlock` supplied
+   * (or when no expiry is relative), at most one `eth_blockNumber` otherwise. Returns the
+   * operations for `writeContract`, and the `{ to, data }` calldata for offline signing.
+   *
+   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
+   * @param options - Optional `currentBlock` to avoid the `eth_blockNumber` lookup
+   */
+  buildMutation: (
+    data: EntityMutationOps,
+    options?: BuildMutationOptions,
+  ) => Promise<BuildMutationReturnType>
+
+  /**
+   * Signs and sends a mutation batch, returning the hash as soon as the transaction is submitted —
+   * no waiting, no polling, no revert diagnosis. With `currentBlock` and full `txParams` (nonce,
+   * gas, fees) supplied this is exactly one `eth_sendRawTransaction`; each omitted piece adds only
+   * the lookup viem needs to fill it.
+   *
+   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
+   * @param options - Optional `currentBlock` and `txParams`
+   * @returns The transaction hash and the batch's per-kind operation counts
+   *
+   * @example
+   * const { txHash } = await client.advanced.sendMutation({
+   *   creates: [{ payload, contentType: "application/json", expires: ExpirationTime.atBlock(1_200_000n) }],
+   * })
+   */
+  sendMutation: (
+    data: EntityMutationOps,
+    options?: SendMutationOptions,
+  ) => Promise<SendMutationReturnType>
+}
+
+export function publicAdvancedActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+>(client: Client<transport, chain, account>): PublicAdvancedActions {
+  return {
+    pingTransaction: (txHash: Hash) => pingTransaction(client, txHash),
+    getMutationResult: (txHash: Hash) => getMutationResult(client, txHash),
+    decodeMutationResult: (receipt: TransactionReceipt) => decodeMutationResult(receipt),
+  }
+}
+
+export function walletAdvancedActions<
+  transport extends Transport = Transport,
+  chain extends Chain | undefined = Chain | undefined,
+  account extends Account | undefined = Account | undefined,
+>(client: Client<transport, chain, account>): WalletAdvancedActions {
+  return {
+    ...publicAdvancedActions(client),
+    buildMutation: (data: EntityMutationOps, options?: BuildMutationOptions) =>
+      buildMutation(client, data, options),
+    sendMutation: (data: EntityMutationOps, options?: SendMutationOptions) =>
+      sendMutation(client, data, options),
+  }
+}

package/src/clients/decorators/arkivPublic.ts

@@ -1,19 +1,24 @@
-import type { Account, Chain, Client, Hex, PublicActions, Transport } from "viem"
-import { getBlockTiming } from "../../actions/public/getBlockTiming"
+import type { Account, Address, Chain, Client, Hex, PublicActions, Transport } from "viem"
+import { type GetBlockTimingReturnType, getBlockTiming } from "../../actions/public/getBlockTiming"
 import { getEntity } from "../../actions/public/getEntity"
 import { getEntityCount } from "../../actions/public/getEntityCount"
+import { getEntityNonce } from "../../actions/public/getEntityNonce"
+import {
+  type PredictEntityKeysParameters,
+  type PredictEntityKeysReturnType,
+  predictEntityKeys,
+} from "../../actions/public/predictEntityKeys"
 import { type QueryOptions, type QueryReturnType, query } from "../../actions/public/query"
-import { subscribeEntityEvents } from "../../actions/public/subscribeEntityEvents"
-import { QueryBuilder, SelectQueryBuilder } from "../../query/queryBuilder"
+import {
+  type WatchEntityEventsParameters,
+  watchEntityEvents,
+} from "../../actions/public/watchEntityEvents"
+import type { SaltInput } from "../../entity/key"
+import type { Expression } from "../../query/expression"
+import { SelectQueryBuilder } from "../../query/queryBuilder"
 import type { EntitySelection, FullEntity, ProjectedEntity, SelectArg } from "../../query/selection"
 import type { Entity } from "../../types/entity"
-import type {
-  OnEntityCreatedEvent,
-  OnEntityDeletedEvent,
-  OnEntityExpiredEvent,
-  OnEntityExpiresInExtendedEvent,
-  OnEntityUpdatedEvent,
-} from "../../types/events"
+import { type PublicAdvancedActions, publicAdvancedActions } from "./arkivAdvanced"
 
 export type PublicArkivActions<
   transport extends Transport = Transport,
@@ -35,33 +40,42 @@ export type PublicArkivActions<
   /**
    * Returns the entity with the given key.
    *
-   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
+   * - JSON-RPC Methods: `arkiv_query`
    *
    * @param key - The entity key (hex string)
-   * @returns The entity with the given key. {@link Entity}
+   * @returns The entity with the given key, with every field populated. {@link FullEntity}
+   *
+   * @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.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entity = await client.getEntity("0x123")
-   * // {
-   * //   key: "0x123",
-   * //   value: "0x123",
+   * const entity = await client.getEntity(entityKey)
+   * // Entity {
+   * //   key: "0x9f2c…",
+   * //   owner: "0xabc…",
+   * //   contentType: "application/json",
+   * //   payload: Uint8Array,          // entity.toJson() / entity.toText() decode it
+   * //   attributes: { category: { type: "str", value: "docs" } },
+   * //   expiresAt: 1_297_000n,
    * // }
    */
-  getEntity: (key: Hex) => Promise<Entity>
+  getEntity: (key: Hex) => Promise<FullEntity>
 
   /**
    * 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.
    *
-   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   * - JSON-RPC Methods: `arkiv_query`
    *
    * @param selection - 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
@@ -70,12 +84,13 @@ export type PublicArkivActions<
    * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
-   * import { eq } from 'arkiv/query'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { eq } from "@arkiv-network/sdk/query"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * // select everything
@@ -83,7 +98,7 @@ export type PublicArkivActions<
    * await client.select("*").where(eq("category", "docs")).fetch()
    * // only the key
    * await client.select({ key: true }).where(eq("category", "docs")).fetch()
-   * // select specific fields — result typed { owner: Hex; attributes: Attribute[] }
+   * // select specific fields — result typed { owner: Hex; attributes: Attributes }
    * await client.select({ owner: true, attributes: true }).fetch()
    * // a single field — result typed { owner: Hex }
    * await client.select({ owner: true }).fetch()
@@ -95,9 +110,11 @@ export type PublicArkivActions<
      * Pick the entity 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.
      *
-     * Available fields: `key`, `owner`, `creator`, `contentType`, `payload`, `attributes`,
-     * `expiresAtBlock`, `createdAtBlock`, `lastModifiedAtBlock`, `transactionIndexInBlock`,
-     * `operationIndexInTransaction`.
+     * Available fields: `key`, `owner`, `creator`, `createdAt`, `updatedAt`, `expiresAt`,
+     * `creationFlags`, `contentType`, `payload`, `attributeSchema` and `attributes`.
+     *
+     * `attributes` also takes a map of names, to fetch only those:
+     * `select({ key: true, attributes: { projectId: true } })`.
      *
      * Pass the selection inline so its fields stay literal `true`. A selection stored in a `let`/
      * `const` variable widens to `boolean` and the result type can no longer be narrowed — annotate
@@ -105,7 +122,8 @@ export type PublicArkivActions<
      *
      * @example
      * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
-     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     * client.select({ key: true, payload: true })      // includes payload → toText()/toJson() too
+     * client.select({ key: true, attributeSchema: true }) // what shape is the data?
      */
     <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
     /**
@@ -116,90 +134,133 @@ export type PublicArkivActions<
   }
 
   /**
-   * Returns a QueryBuilder instance for building and executing queries.
-   * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
-   *
-   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   * Runs one query and returns one page, with no builder in between.
    *
-   * @deprecated Use {@link select} instead. `buildQuery()` returns only the entity `key` unless
-   * you remember to opt in to data with `withAttributes()`/`withMetadata()`/`withPayload()`, which
-   * is an easy mistake. `select()` makes the selection explicit. This method remains for backwards
-   * compatibility and will be removed in a future release.
+   * Use {@link PublicArkivActions.select} for anything typed — this returns full {@link Entity} objects whatever the
+   * selection, and 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.
    *
-   * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
+   * @param query - An {@link Expression}, or the raw query string.
+   * @param queryOptions - Selection, page size, cursor and block. {@link QueryOptions}
+   * @returns One page of entities. {@link QueryReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { and, eq, gte } from "@arkiv-network/sdk/query"
+   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const query = client.buildQuery()
-   * const entities = await query.where("key", "=", "value").ownedBy("0x123").fetch()
+   * const page = await client.query(and(eq("category", "docs"), gte("level", i32(10))), {
+   *   select: { key: true, attributes: true },
+   *   limit: 100,
+   * })
+   * // { entities: [Entity], cursor: "b64:…", blockNumber: 32223n }
    *
+   * // The raw form, unchecked:
+   * await client.query("category = str('docs') AND level >= i32(10)")
    */
-  buildQuery: () => QueryBuilder
+  query: (query: Expression | string, queryOptions?: QueryOptions) => Promise<QueryReturnType>
 
   /**
-   * Returns a QueryResult instance for fetching the results of a raw query.
-   * If no query options are provided, all payload is included, but no metadata (like owner, expiredAt, etc.) and attributes.
-   * @param query - The raw query string
-   * @param queryOptions - The optional query options - {@link QueryOptions}
-   * @returns A QueryReturnType instance - {@link QueryReturnType}
+   * Returns the total number of entities on the chain.
+   * @returns The number of entities currently stored
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const queryResult = client.query('key = value && $owner = 0x123')
-   * // queryResult = { entities: [{ key: "0x123", value: "0x123" }], cursor: undefined, blockNumber: undefined }
-   * const queryResultWithOptions = client.query('key = value && $owner = 0x123', {
-   *   includeData: {
-   *     attributes: false,
-   *     payload: true,
-   *     metadata: true,
-   *   },
-   *   resultsPerPage: 10,
-   *   cursor: undefined,
-   *   atBlock: undefined,
-   * })
-   * // queryResultWithOptions = { entities: [{ key: "0x123", value: "0x123" }], cursor: "...", blockNumber: 32223n }
+   * const entityCount = await client.getEntityCount()
+   * // entityCount = 0
    */
-  query: (query: string, queryOptions?: QueryOptions) => Promise<QueryReturnType>
+  getEntityCount: () => Promise<number>
 
   /**
-   * Returns the number of entities in the DBChain.
-   * @returns The number of entities in the DBChain
+   * 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.
+   *
+   * @param owner - The account whose nonce to read.
+   * @returns The nonce the account's next create will use.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entityCount = await client.getEntityCount()
-   * // entityCount = 0
+   * const nonce = await client.getEntityNonce("0xabc…")
+   * // 7n — the next entity this account creates is its eighth
    */
-  getEntityCount: () => Promise<number>
+  getEntityNonce: (owner: Address) => Promise<bigint>
+
+  /**
+   * 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.
+   *
+   * @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.executeBatch({
+   *   creates: [
+   *     { payload, contentType, expires, salt: parent.salt },
+   *     {
+   *       payload,
+   *       contentType,
+   *       expires,
+   *       salt: child.salt,
+   *       attributes: { parent: key(parent.key) },
+   *     },
+   *   ],
+   * })
+   */
+  predictEntityKeys: <
+    const TCount extends number = number,
+    const TSalts extends readonly SaltInput[] | undefined = undefined,
+  >(
+    parameters: PredictEntityKeysParameters<TCount, TSalts>,
+  ) => Promise<PredictEntityKeysReturnType<TCount, TSalts>>
 
   /**
    * Returns the current block timing.
    * @returns The current block timing. {@link GetBlockTimingReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * const blockTiming = await client.getBlockTiming()
@@ -209,50 +270,45 @@ export type PublicArkivActions<
    * //   blockDuration: 2, // in seconds
    * // }
    */
-  getBlockTiming: () => Promise<{
-    currentBlock: bigint
-    currentBlockTime: number
-    blockDuration: number
-  }>
+  getBlockTiming: () => Promise<GetBlockTimingReturnType>
 
   /**
-   * Subscribes to entity events.
-   * Takes an object with event handlers: {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
-   * @param pollingInterval - The polling interval in milliseconds
-   * @param fromBlock - The block number to start from
-   * @returns A function to unsubscribe from the events
+   * 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.
+   *
+   * @param parameters - Handlers and options, all optional. {@link WatchEntityEventsParameters}
+   * @returns A function that stops the watcher.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const unsubscribe = await client.subscribeEntityEvents({
-   *   onError: (error) => console.error("subscribeEntityEvents error", error),
+   * const unwatch = client.watchEntityEvents({
+   *   onEntityCreated: ({ entityKey, expiresAt }) => console.log(entityKey, "until", expiresAt),
+   *   onError: (error) => console.error("watchEntityEvents error", error),
    * })
-   * unsubscribe() // unsubscribe from the events
+   * unwatch() // stop watching
+   */
+  watchEntityEvents: (parameters: WatchEntityEventsParameters) => () => void
+
+  /**
+   * The read-only half of the advanced path: check on a transaction and decode its result with at
+   * most one RPC call per action — so a process that holds nothing but a transaction hash can
+   * follow it without a wallet. {@link PublicAdvancedActions}
+   *
+   * @example
+   * const { status } = await client.advanced.pingTransaction(txHash) // 1 eth_getTransactionReceipt
    */
-  subscribeEntityEvents: (
-    {
-      onError,
-      onEntityCreated,
-      onEntityUpdated,
-      onEntityDeleted,
-      onEntityExpiresInExtended,
-    }: {
-      onError?: (error: Error) => void
-      onEntityCreated?: (event: OnEntityCreatedEvent) => void
-      onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
-      onEntityDeleted?: (event: OnEntityDeletedEvent) => void
-      onEntityExpired?: (event: OnEntityExpiredEvent) => void
-      onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
-    },
-    pollingInterval?: number,
-    fromBlock?: bigint,
-  ) => Promise<() => void>
+  advanced: PublicAdvancedActions
 }
 
 export function publicArkivActions<
@@ -262,42 +318,20 @@ export function publicArkivActions<
 >(client: Client<transport, chain, account>) {
   return {
     getEntity: (key: Hex) => getEntity(client, key),
-    query: (rawQuery: string, queryOptions?: QueryOptions) => query(client, rawQuery, queryOptions),
-    buildQuery: () => new QueryBuilder(client),
+    query: (rawQuery: Expression | string, queryOptions?: QueryOptions) =>
+      query(client, rawQuery, queryOptions),
     select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
     getBlockTiming: () => getBlockTiming(client),
     getEntityCount: () => getEntityCount(client),
-    subscribeEntityEvents: (
-      {
-        onError,
-        onEntityCreated,
-        onEntityUpdated,
-        onEntityDeleted,
-        onEntityExpired,
-        onEntityExpiresInExtended,
-      }: {
-        onError?: (error: Error) => void
-        onEntityCreated?: (event: OnEntityCreatedEvent) => void
-        onEntityUpdated?: (event: OnEntityUpdatedEvent) => void
-        onEntityDeleted?: (event: OnEntityDeletedEvent) => void
-        onEntityExpired?: (event: OnEntityExpiredEvent) => void
-        onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void
-      },
-      pollingInterval?: number,
-      fromBlock?: bigint,
-    ) =>
-      subscribeEntityEvents(
-        client,
-        {
-          onError,
-          onEntityCreated,
-          onEntityUpdated,
-          onEntityDeleted,
-          onEntityExpired,
-          onEntityExpiresInExtended,
-        },
-        pollingInterval,
-        fromBlock,
-      ),
+    getEntityNonce: (owner: Address) => getEntityNonce(client, owner),
+    predictEntityKeys: <
+      const TCount extends number = number,
+      const TSalts extends readonly SaltInput[] | undefined = undefined,
+    >(
+      parameters: PredictEntityKeysParameters<TCount, TSalts>,
+    ) => predictEntityKeys(client, parameters),
+    watchEntityEvents: (parameters: WatchEntityEventsParameters) =>
+      watchEntityEvents(client, parameters),
+    advanced: publicAdvancedActions(client),
   }
 }