@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/clients/decorators/arkivPublic.ts

@@ -1,23 +1,36 @@
 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 {
+  type QueryOptions,
+  type QueryReturnType,
+  type QueryRow,
+  query,
+} from "../../actions/public/query"
 import {
   type WatchEntityEventsParameters,
   watchEntityEvents,
 } from "../../actions/public/watchEntityEvents"
 import type { SaltInput } from "../../entity/key"
+import { CountQueryBuilder } from "../../query/countBuilder"
 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 {
+  FullEntity,
+  FullRow,
+  KnownSystemFields,
+  NonEmptySelection,
+  PartialRow,
+  SelectArg,
+  SelectionOf,
+} from "../../query/selection"
+import type { Schema } from "../../schema"
 
 export type PublicArkivActions<
   transport extends Transport = Transport,
@@ -39,14 +52,21 @@ export type PublicArkivActions<
   /**
    * Returns the entity with the given key.
    *
-   * - JSON-RPC Methods: `arkiv_query`
+   * 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`
    *
    * @param key - The entity key (hex string)
-   * @returns The entity with the given key, with every field populated. {@link FullEntity}
+   * @param schema - Optionally, the schema to read the entity through.
+   * @returns The entity with the given key, with every field populated — a {@link FullEntity}, or
+   * a {@link FullRow} through a schema.
    *
    * @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.
+   * @throws {SchemaMismatchError} If, given a schema, the entity does not fit it.
+   * @throws {SchemaDefinitionError} If the schema given was not built with `defineSchema`.
    *
    * @example
    * import { createPublicClient } from "@arkiv-network/sdk"
@@ -58,85 +78,120 @@ export type PublicArkivActions<
    *   transport: http(),
    * })
    * 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,
+   * // {
+   * //   $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" }, ... }
    */
-  getEntity: (key: Hex) => Promise<FullEntity>
+  getEntity: {
+    (key: Hex): Promise<FullEntity>
+    <S extends Schema>(key: Hex, schema: S): Promise<FullRow<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`
    *
    * @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
-   *   opt-in, including the `key`. The selection is flat — each field maps to an entity field.
+   *   opt-in, including the `$key`. The selection is flat — each field maps to a field of the result.
    *   {@link SelectArg}
    * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
    *
    * @example
    * import { createPublicClient } from "@arkiv-network/sdk"
    * import { tiramisu } from "@arkiv-network/sdk/chains"
-   * import { eq } from "@arkiv-network/sdk/query"
+   * import { and, eq, gt } from "@arkiv-network/sdk/query"
+   * import { dec } from "@arkiv-network/sdk/schema"
    * import { http } from "viem"
    *
    * const client = createPublicClient({
    *   chain: tiramisu,
    *   transport: http(),
    * })
-   * // select everything
-   * await client.select().where(eq("category", "docs")).fetch()
-   * 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: Attributes }
-   * await client.select({ owner: true, attributes: true }).fetch()
-   * // a single field — result typed { owner: Hex }
-   * await client.select({ owner: true }).fetch()
+   * // 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()
    */
   select: {
-    /** Select every field. Pass nothing or `"*"`; the returned entities contain all fields. */
-    (selection?: "*"): SelectQueryBuilder<FullEntity>
     /**
-     * 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`, `createdAt`, `updatedAt`, `expiresAt`,
-     * `creationFlags`, `contentType`, `payload`, `attributeSchema` and `attributes`.
+     * 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.
+     */
+    (selection?: "*"): SelectQueryBuilder<"*">
+    /**
+     * 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.
      *
-     * `attributes` also takes a map of names, to fetch only those:
-     * `select({ key: true, attributes: { projectId: true } })`.
+     * 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 the result type can no longer be narrowed — annotate
-     * it `as const` (e.g. `const sel = { owner: true } as const`) in that case.
+     * `const` variable widens to `boolean`, and one typed {@link SelectArg} is only known at
+     * runtime: which fields come back is then decided at runtime, so every field of the result is
+     * optional — a {@link PartialRow}. Annotate a stored selection `as const` to keep it narrow.
      *
      * @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, attributeSchema: true }) // what shape is the data?
-     */
-    <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>
-    /**
-     * Dynamic selection: accepts a value typed {@link SelectArg} (e.g. built at runtime). The
-     * result cannot be narrowed in this case, so the entities are typed as the full entity.
+     * 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
      */
-    (selection: SelectArg): SelectQueryBuilder<FullEntity>
+    <const S extends SelectArg>(
+      selection: S & NonEmptySelection<S> & KnownSystemFields<S>,
+    ): SelectQueryBuilder<SelectionOf<S>>
   }
 
+  /**
+   * Returns a CountQueryBuilder: counts the entities a query matches, without fetching any of them.
+   *
+   * It filters exactly as {@link select} does — `.from(schema)`, `.where(...)`, `.ownedBy(...)`,
+   * `.createdBy(...)` and `.atBlock(...)` — 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
+   *
+   * @example
+   * const total = await client.count().from(Posts).ownedBy(account.address).fetch()
+   * const news = await client.count().from(Posts).where(eq("category", "news")).fetch()
+   */
+  count: () => CountQueryBuilder
+
   /**
    * Runs one query and returns one page, with no builder in between.
    *
-   * 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
+   * The selection means what it does in {@link 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.
    *
@@ -148,7 +203,7 @@ export type PublicArkivActions<
    * import { createPublicClient } from "@arkiv-network/sdk"
    * import { tiramisu } from "@arkiv-network/sdk/chains"
    * import { and, eq, gte } from "@arkiv-network/sdk/query"
-   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { i32 } from "@arkiv-network/sdk/schema"
    * import { http } from "viem"
    *
    * const client = createPublicClient({
@@ -156,33 +211,18 @@ export type PublicArkivActions<
    *   transport: http(),
    * })
    * const page = await client.query(and(eq("category", "docs"), gte("level", i32(10))), {
-   *   select: { key: true, attributes: true },
+   *   select: { $key: true, title: true },
    *   limit: 100,
    * })
-   * // { entities: [Entity], cursor: "b64:…", blockNumber: 32223n }
+   * // { entities: [{ $key: Hex; title: ArkivValue | undefined }], cursor: "b64:…", blockNumber: 32223n }
    *
    * // The raw form, unchecked:
    * await client.query("category = str('docs') AND level >= i32(10)")
    */
-  query: (query: Expression | string, queryOptions?: QueryOptions) => Promise<QueryReturnType>
-
-  /**
-   * Returns the total number of entities on the chain.
-   * @returns The number of entities currently stored
-   *
-   * @example
-   * import { createPublicClient } from "@arkiv-network/sdk"
-   * import { tiramisu } from "@arkiv-network/sdk/chains"
-   * import { http } from "viem"
-   *
-   * const client = createPublicClient({
-   *   chain: tiramisu,
-   *   transport: http(),
-   * })
-   * const entityCount = await client.getEntityCount()
-   * // entityCount = 0
-   */
-  getEntityCount: () => Promise<number>
+  query: <const S extends SelectArg = "*">(
+    query: Expression | string,
+    queryOptions?: QueryOptions<S>,
+  ) => Promise<QueryReturnType<QueryRow<S>>>
 
   /**
    * Returns how many entities an account has created — its entity-minting nonce.
@@ -226,18 +266,19 @@ export type PublicArkivActions<
    *   {@link PredictEntityKeysReturnType}
    *
    * @example A batch whose second entity points at its first.
-   * import { key } from "@arkiv-network/sdk/attr"
+   * 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: [
-   *     { payload, contentType, expires, salt: parent.salt },
+   *     { schema: Nodes, values: { name: "root" }, expiration, salt: parent.salt },
    *     {
-   *       payload,
-   *       contentType,
-   *       expires,
+   *       schema: Nodes,
+   *       values: { name: "leaf", parent: key(parent.key) },
+   *       expiration,
    *       salt: child.salt,
-   *       attributes: { parent: key(parent.key) },
    *     },
    *   ],
    * })
@@ -306,12 +347,14 @@ export function publicArkivActions<
   account extends Account | undefined = Account | undefined,
 >(client: Client<transport, chain, account>) {
   return {
-    getEntity: (key: Hex) => getEntity(client, key),
-    query: (rawQuery: Expression | string, queryOptions?: QueryOptions) =>
-      query(client, rawQuery, queryOptions),
-    select: (selection?: SelectArg) => new SelectQueryBuilder(client, selection),
+    getEntity: ((key: Hex, schema?: Schema) =>
+      getEntity(client, key, schema as Schema)) as PublicArkivActions["getEntity"],
+    query: ((rawQuery: Expression | string, queryOptions?: QueryOptions) =>
+      query(client, rawQuery, queryOptions)) as PublicArkivActions["query"],
+    select: ((selection?: SelectArg) =>
+      new SelectQueryBuilder(client, selection)) as PublicArkivActions["select"],
+    count: () => new CountQueryBuilder(client),
     getBlockTiming: () => getBlockTiming(client),
-    getEntityCount: () => getEntityCount(client),
     getEntityNonce: (owner: Address) => getEntityNonce(client, owner),
     predictEntityKeys: <
       const TCount extends number = number,

package/src/clients/decorators/arkivWallet.ts

@@ -1,11 +1,11 @@
-import type { Account, Chain, Client, PublicActions, Transport, WalletActions } from "viem"
+import type { Account, Chain, Client, Hex, PublicActions, Transport, WalletActions } from "viem"
 import type {
   ChangeOwnershipParameters,
   ChangeOwnershipReturnType,
 } from "../../actions/wallet/changeOwnership"
 import { changeOwnership } from "../../actions/wallet/changeOwnership"
 import {
-  type CreateEntityParameters,
+  type CreateEntityOptions,
   type CreateEntityReturnType,
   createEntity,
 } from "../../actions/wallet/createEntity"
@@ -24,8 +24,12 @@ import type {
   ExtendEntityReturnType,
 } from "../../actions/wallet/extendEntity"
 import { extendEntity } from "../../actions/wallet/extendEntity"
-import type { PatchEntityParameters, PatchEntityReturnType } from "../../actions/wallet/patchEntity"
-import { patchEntity } from "../../actions/wallet/patchEntity"
+import {
+  type PatchEntityChanges,
+  type PatchEntityReturnType,
+  patchEntity,
+} from "../../actions/wallet/patchEntity"
+import type { CreateEntityValues, Schema } from "../../schema"
 import type { TxParams } from "../../types"
 
 export type WalletArkivActions<
@@ -48,81 +52,99 @@ export type WalletArkivActions<
     | "writeContract"
   > & {
     /**
-     * Creates a new entity.
+     * Creates a new entity through a schema: each column becomes an attribute, written with the
+     * type and indexed flag the schema declares.
      *
      * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
-     * @param data - The entity creation parameters
+     * @param schema - The schema the entity is written through, built with `defineSchema`.
+     * @param values - The entity's values, keyed by column. Required columns must be given;
+     * defaulted ones left out are written with their default. {@link CreateEntityValues}
+     * @param options - The entity's lifetime, plus its flags and salt. {@link CreateEntityOptions}
      * @param txParams - Optional transaction parameters
-     * @returns The new entity's key, the transaction hash, and the block it is expected to
-     * expire at. {@link CreateEntityReturnType}
+     * @returns The new entity's key, the transaction hash, and the block it expires at, as the
+     * engine recorded it. {@link CreateEntityReturnType}
      *
      * @throws {InvalidExpiryError} If the expiry exceeds a protocol bound or would leave the
      * entity dead on arrival.
-     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
-     * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+     * @throws {SchemaMismatchError} If the values do not fit the schema.
+     * @throws {InvalidValueError} If a value does not fit its type.
+     * @throws {EntityTooLargeError} If the `bytes` values add up to more than `MAX_ENTITY_BYTES`.
+     * @throws {EntityMutationError} If the transaction fails or reverts.
      *
      * @example
-     * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
-     * import { i32 } from "@arkiv-network/sdk/attr"
+     * import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
+     * import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
      * import { tiramisu } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
      * import { privateKeyToAccount } from "viem/accounts"
      *
+     * const Posts = defineSchema("posts", {
+     *   author:    addr().indexed(),
+     *   category:  str().indexed(),
+     *   score:     dec().indexed(),
+     *   title:     str(),
+     *   body:      bytes(),
+     *   thumbnail: bytes().optional(),
+     *   mimeType:  str().default("text/markdown"),
+     * })
+     *
      * const client = createWalletClient({
      *   account: privateKeyToAccount("0x..."),
      *   chain: tiramisu,
      *   transport: http(),
      * })
-     * const { entityKey, txHash, expiresAt } = await client.createEntity({
-     *   payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
-     *   contentType: "application/json",
-     *   attributes: { testKey: "testValue", level: i32(3) },
-     *   expires: ExpirationTime.fromDays(30),
-     * })
+     * const { entityKey, txHash, expiresAt } = await client.createEntity(
+     *   Posts,
+     *   {
+     *     author: addr(client.account.address),
+     *     category: "docs",
+     *     score: dec("4.1"),
+     *     title: "Cells, not entities",
+     *     body: new TextEncoder().encode("# Hello"),
+     *   },
+     *   { expiration: ExpirationTime.fromDays(30) },
+     * )
      */
-    createEntity: (
-      data: CreateEntityParameters,
+    createEntity: <S extends Schema>(
+      schema: S,
+      values: CreateEntityValues<S>,
+      options: CreateEntityOptions,
       txParams?: TxParams,
     ) => Promise<CreateEntityReturnType>
 
     /**
-     * Applies a patch to the entity with the given key: sets some fields, unsets others, and leaves
-     * everything it does not name alone.
+     * Patches the entity with the given key through a schema: sets some columns, unsets optional
+     * ones, and leaves everything it does not name alone.
      *
      * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
-     * @param data - The entity key and the mutations to apply
+     * @param schema - The schema the changes are typed by.
+     * @param entityKey - The entity to patch.
+     * @param changes - The columns to set and the optional columns to unset. {@link PatchEntityChanges}
      * @param txParams - Optional transaction parameters
      * @returns The patched entity's key and the transaction hash. {@link PatchEntityReturnType}
      *
      * @throws {EmptyPatchError} If the patch has nothing to apply.
      * @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
-     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
-     * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+     * @throws {SchemaMismatchError} If the changes do not fit the schema.
+     * @throws {InvalidValueError} If a value does not fit its type.
+     * @throws {EntityTooLargeError} If the `bytes` values in `set` add up to more than
+     * `MAX_ENTITY_BYTES`.
+     * @throws {EntityMutationError} If the transaction fails or reverts.
      *
      * @example
-     * import { createWalletClient, jsonToPayload } from "@arkiv-network/sdk"
-     * import { i32 } from "@arkiv-network/sdk/attr"
-     * import { tiramisu } from "@arkiv-network/sdk/chains"
-     * import { http } from "viem"
-     * import { privateKeyToAccount } from "viem/accounts"
-     *
-     * const client = createWalletClient({
-     *   account: privateKeyToAccount("0x..."),
-     *   chain: tiramisu,
-     *   transport: http(),
-     * })
-     * // Publish the entity: one attribute changes, one goes away, the payload is replaced.
-     * const { txHash } = await client.patchEntity({
-     *   entityKey,
-     *   set: { status: "published", revision: i32(2) },
-     *   unset: ["draft"],
-     *   payload: jsonToPayload({ title: "Hello" }),
+     * // Posts is the schema from the createEntity example.
+     * // One column changes, an optional one goes away.
+     * const { txHash } = await client.patchEntity(Posts, entityKey, {
+     *   set: { score: dec("4.5") },
+     *   unset: ["thumbnail"],
      * })
      */
-    patchEntity: (
-      data: PatchEntityParameters,
+    patchEntity: <S extends Schema>(
+      schema: S,
+      entityKey: Hex,
+      changes: PatchEntityChanges<S>,
       txParams?: TxParams,
     ) => Promise<PatchEntityReturnType>
 
@@ -159,14 +181,15 @@ export type WalletArkivActions<
      *
      * The new lifetime is resolved the same way a create's is: a duration counts from now rather
      * than adding to what the entity has left, and `atBlock` / `atDate` pin an absolute deadline.
-     * The engine rejects an extension that would not move the expiry later.
+     * The engine rejects an extension that would move the expiry earlier; one that resolves to the
+     * current expiry changes nothing.
      *
      * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity key and its new lifetime
      * @param txParams - Optional transaction parameters
-     * @returns The entity's key, the transaction hash, and the block it is now expected to expire
-     * at. {@link ExtendEntityReturnType}
+     * @returns The entity's key, the transaction hash, and the block it now expires at, as the
+     * engine recorded it. {@link ExtendEntityReturnType}
      *
      * @throws {InvalidExpiryError} If the expiry is malformed, exceeds a protocol bound, or would
      * leave the entity dead on arrival.
@@ -184,7 +207,7 @@ export type WalletArkivActions<
      * })
      * const { txHash, expiresAt } = await client.extendEntity({
      *   entityKey,
-     *   expires: ExpirationTime.fromDays(30),
+     *   expiration: ExpirationTime.fromDays(30),
      * })
      */
     extendEntity: (
@@ -213,19 +236,28 @@ export type WalletArkivActions<
      * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * Every operation lands in one transaction, so the whole batch applies or none of it does.
-     * At least one operation is required.
+     * At least one operation is required. Each create and patch names its own schema and is typed
+     * by it, so one batch can write entities of several schemas.
      *
      * @param data - The batch parameters (creates, patches, deletes, extensions, ownershipChanges)
      * @param txParams - Optional transaction parameters
      * @returns The transaction hash, plus the keys touched by each kind of operation.
      * {@link ExecuteBatchReturnType}
      *
+     * @throws {Error} If the batch has no operations.
      * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound or would leave the entity
      * dead on arrival.
-     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+     * @throws {SchemaMismatchError} If a create's or patch's values do not fit its schema.
+     * @throws {InvalidValueError} If a value does not fit its type.
+     * @throws {EmptyPatchError} If a patch has nothing to apply.
+     * @throws {ConflictingMutationError} If a patch names a column in both `set` and `unset`.
+     * @throws {EntityTooLargeError} If the `bytes` values of one create or patch add up to more
+     * than `MAX_ENTITY_BYTES`.
+     * @throws {EntityMutationError} If the transaction fails or reverts.
      *
      * @example
-     * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
+     * import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
+     * import { dec } from "@arkiv-network/sdk/schema"
      * import { tiramisu } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
      * import { privateKeyToAccount } from "viem/accounts"
@@ -235,24 +267,27 @@ export type WalletArkivActions<
      *   chain: tiramisu,
      *   transport: http(),
      * })
+     * // Posts is the schema from the createEntity example.
      * const { txHash, createdEntities } = await client.executeBatch({
      *   creates: [{
-     *     payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
-     *     contentType: "application/json",
-     *     attributes: { testKey: "testValue" },
-     *     expires: ExpirationTime.fromDays(30),
+     *     schema: Posts,
+     *     values: { author, category: "docs", score: dec("4.1"), title: "Hi", body: new Uint8Array() },
+     *     expiration: ExpirationTime.fromDays(30),
      *   }],
-     *   patches: [{ entityKey: keyToRevise, set: { status: "archived" }, unset: ["draft"] }],
+     *   patches: [{ schema: Posts, entityKey: keyToRevise, set: { category: "archive" } }],
      *   deletes: [{ entityKey: staleKey }],
      *   extensions: [{
      *     entityKey: keyToKeepAlive,
-     *     expires: ExpirationTime.atBlock(1_200_000n),
+     *     expiration: ExpirationTime.atBlock(1_200_000n),
      *   }],
      *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
      * })
      */
-    executeBatch: (
-      data: ExecuteBatchParameters,
+    executeBatch: <
+      const TCreates extends readonly Schema[] = [],
+      const TPatches extends readonly Schema[] = [],
+    >(
+      data: ExecuteBatchParameters<TCreates, TPatches>,
       txParams?: TxParams,
     ) => Promise<ExecuteBatchReturnType>
   }
@@ -263,17 +298,30 @@ export function walletArkivActions<
   account extends Account | undefined = Account | undefined,
 >(client: Client<transport, chain, account>) {
   return {
-    createEntity: (data: CreateEntityParameters, txParams?: TxParams) =>
-      createEntity(client, data, txParams),
-    patchEntity: (data: PatchEntityParameters, txParams?: TxParams) =>
-      patchEntity(client, data, txParams),
+    createEntity: <S extends Schema>(
+      schema: S,
+      values: CreateEntityValues<S>,
+      options: CreateEntityOptions,
+      txParams?: TxParams,
+    ) => createEntity(client, schema, values, options, txParams),
+    patchEntity: <S extends Schema>(
+      schema: S,
+      entityKey: Hex,
+      changes: PatchEntityChanges<S>,
+      txParams?: TxParams,
+    ) => patchEntity(client, schema, entityKey, changes, txParams),
     deleteEntity: (data: DeleteEntityParameters, txParams?: TxParams) =>
       deleteEntity(client, data, txParams),
     extendEntity: (data: ExtendEntityParameters, txParams?: TxParams) =>
       extendEntity(client, data, txParams),
     changeOwnership: (data: ChangeOwnershipParameters, txParams?: TxParams) =>
       changeOwnership(client, data, txParams),
-    executeBatch: (data: ExecuteBatchParameters, txParams?: TxParams) =>
-      executeBatch(client, data, txParams),
+    executeBatch: <
+      const TCreates extends readonly Schema[] = [],
+      const TPatches extends readonly Schema[] = [],
+    >(
+      data: ExecuteBatchParameters<TCreates, TPatches>,
+      txParams?: TxParams,
+    ) => executeBatch(client, data, txParams),
   }
 }