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

package/src/actions/wallet/{mutateEntities.test.ts → executeBatch.test.ts}

@@ -1,6 +1,6 @@
 import { describe, expect, it, vi } from "bun:test"
 import type { ArkivClient } from "../../clients/baseClient"
-import { mutateEntities } from "./mutateEntities"
+import { executeBatch } from "./executeBatch"
 
 const ENTITY_KEY = `0x${"ab".repeat(32)}` as const
 const NEW_OWNER = "0x2222222222222222222222222222222222222222"
@@ -29,7 +29,7 @@ describe("the empty-batch guard", () => {
     // An ownership-only batch is a batch: it used to be rejected because the guard listed
     // creates/updates/deletes/extensions and forgot ownershipChanges.
     const { client, writeContract } = makeClient()
-    const result = await mutateEntities(client, {
+    const result = await executeBatch(client, {
       ownershipChanges: [{ entityKey: ENTITY_KEY, newOwner: NEW_OWNER }],
     })
     expect(writeContract).toHaveBeenCalledTimes(1)
@@ -38,9 +38,9 @@ describe("the empty-batch guard", () => {
 
   it("rejects a batch with nothing in it", async () => {
     const { client, writeContract } = makeClient()
-    await expect(mutateEntities(client, {})).rejects.toThrow(/No operations/)
+    await expect(executeBatch(client, {})).rejects.toThrow(/No operations/)
     // Present but empty is just as empty — the engine would revert with EmptyBatch().
-    await expect(mutateEntities(client, { deletes: [], ownershipChanges: [] })).rejects.toThrow(
+    await expect(executeBatch(client, { deletes: [], ownershipChanges: [] })).rejects.toThrow(
       /No operations/,
     )
     expect(writeContract).not.toHaveBeenCalled()
@@ -52,10 +52,10 @@ describe("the empty-batch guard", () => {
     // keys would score this batch as non-empty and then drop it on the way to the wire, sending
     // execute([]) — so the guard counts the five kinds that actually reach the transaction.
     const stale = { updates: [{ entityKey: ENTITY_KEY, set: { level: 1 } }] } as never
-    await expect(mutateEntities(client, stale)).rejects.toThrow(/No operations/)
+    await expect(executeBatch(client, stale)).rejects.toThrow(/No operations/)
     // A typo is the same mistake with a different name.
     await expect(
-      mutateEntities(client, { delete: [{ entityKey: ENTITY_KEY }] } as never),
+      executeBatch(client, { delete: [{ entityKey: ENTITY_KEY }] } as never),
     ).rejects.toThrow(/No operations/)
     expect(writeContract).not.toHaveBeenCalled()
   })
@@ -65,7 +65,7 @@ describe("the empty-batch guard", () => {
     // The dangerous shape: the creates apply and the transaction succeeds, so nothing surfaces the
     // fact that the `updates` never happened. The guard cannot catch this one — only the caller's
     // types can — but the result must at least not claim they did.
-    const result = await mutateEntities(client, {
+    const result = await executeBatch(client, {
       deletes: [{ entityKey: ENTITY_KEY }],
       updates: [{ entityKey: ENTITY_KEY, set: { level: 1 } }],
     } as never)

package/src/actions/wallet/{mutateEntities.ts → executeBatch.ts}

@@ -9,15 +9,15 @@ import type { DeleteEntityParameters } from "./deleteEntity"
 import type { ExtendEntityParameters } from "./extendEntity"
 import type { PatchEntityParameters } from "./patchEntity"
 
-const logger = getLogger("actions:wallet:mutate-entities")
+const logger = getLogger("actions:wallet:execute-batch")
 
 /**
- * Parameters for the mutateEntities function.
+ * Parameters for the executeBatch function.
  *
  * At least one operation is required; a batch with nothing in it throws rather than spending gas on
  * an empty transaction.
  */
-export type MutateEntitiesParameters = {
+export type ExecuteBatchParameters = {
   /** The entities to create. */
   creates?: CreateEntityParameters[]
   /** The patches to apply. */
@@ -30,8 +30,8 @@ export type MutateEntitiesParameters = {
   ownershipChanges?: ChangeOwnershipParameters[]
 }
 
-/** Return type for the mutateEntities function. */
-export type MutateEntitiesReturnType = {
+/** Return type for the executeBatch function. */
+export type ExecuteBatchReturnType = {
   /** The transaction hash. */
   txHash: Hash
   /** The keys of the created entities, in batch order. */
@@ -46,14 +46,14 @@ export type MutateEntitiesReturnType = {
   ownershipChanges: Hex[]
 }
 
-export async function mutateEntities(
+export async function executeBatch(
   client: ArkivClient,
-  data: MutateEntitiesParameters,
+  data: ExecuteBatchParameters,
   txParams?: TxParams,
-): Promise<MutateEntitiesReturnType> {
+): Promise<ExecuteBatchReturnType> {
   const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams)
 
-  logger("Receipt from mutateEntities %o", receipt)
+  logger("Receipt from executeBatch %o", receipt)
 
   return {
     txHash: receipt.transactionHash as Hash,

package/src/actions/wallet/extendEntity.ts

@@ -4,6 +4,7 @@ import type { Expiry } from "../../entity"
 import { EntityMutationError } from "../../errors"
 import type { TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
+import type { ExpirationTime } from "../../utils/expirationTime"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:extend-entity")
@@ -61,6 +62,7 @@ export async function extendEntity(
   if (expiresAt === undefined) {
     throw new EntityMutationError(
       `Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity expiry.`,
+      { txHash: receipt.transactionHash },
     )
   }
 

package/src/actions/wallet/patchEntity.ts

@@ -38,9 +38,9 @@ export type PatchEntityParameters = {
    * Attributes to write, keyed by name. An existing attribute is overwritten — including with a
    * different type — and a name the entity does not carry yet is added.
    *
-   * Values are the tagged constructors from `@arkiv-network/sdk/attr` — `i32`, `u256`, `dec`, `str`,
-   * `addr`, `key`, `bytes32`, `bool` — or a bare `boolean`, `number`, `bigint` or `string` where the
-   * type is unambiguous.
+   * Values are the tagged constructors from `@arkiv-network/sdk/attr` — `i32`, `u64`, `u256`,
+   * `dec`, `str`, `addr`, `key`, `bytes32`, `bool` — or a bare `boolean`, `number`, `bigint` or
+   * `string` where the type is unambiguous.
    *
    * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
    * @throws {InvalidValueError} If a value does not fit the type it names or defaults to.

package/src/attr/attributes.ts

@@ -10,6 +10,10 @@ import { str, toValue, type ValueInput } from "./values"
  */
 export const MAX_ATTRIBUTES = 32
 
+/**
+ * The largest payload an entity may carry, in bytes. The payload travels as the `$payload` system
+ * cell, so this is a bound on that one attribute rather than on the operation as a whole.
+ */
 export const MAX_PAYLOAD_BYTES = 128 * 1024
 
 /** The system attribute holding an entity's opaque payload. */
@@ -20,7 +24,7 @@ const CONTENT_TYPE_CELL = "$contentType"
 /**
  * The attributes written on an entity, as a plain object keyed by attribute name.
  *
- * Values may be tagged ({@link ValueInput}) or bare where the type is unambiguous — see
+ * Values may be tagged ({@link ArkivValue}) or bare where the type is unambiguous — see
  * {@link toValue} for the bare-form defaults.
  *
  * @example
@@ -141,8 +145,10 @@ export type MutationInputs = SystemCells & {
  *
  * @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
  * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+ * @throws {MissingValueError} If a value is `undefined` or `null`.
  * @throws {InvalidValueError} If a value does not fit its type.
- * @throws {TooManyAttributesError} If `set` names more than {@link MAX_ATTRIBUTES} attributes.
+ * @throws {TooManyAttributesError} If the mutations exceed {@link MAX_ATTRIBUTES}.
+ * @throws {TypeError} If `unset` is not an array.
  */
 export function encodeMutations({
   set,

package/src/attr/errors.ts

@@ -32,8 +32,8 @@ export class UntypedValueError extends Error {
   constructor(input: unknown) {
     super(
       `Cannot infer an Arkiv type for ${describe(input)}. ` +
-        "Attribute values must be a tagged value (i32, u256, dec, str, addr, key, bytes32, bool) " +
-        "or a bare boolean, number, bigint or string.",
+        "Attribute values must be a tagged value (i32, u64, u256, dec, str, addr, key, bytes32, " +
+        "bool) or a bare boolean, number, bigint or string.",
     )
     this.name = "UntypedValueError"
     this.input = input

package/src/attr/types.ts

@@ -1,4 +1,5 @@
 import type { Address, Hex } from "viem"
+import type { decUnits } from "./values"
 
 /**
  * The protocol's attribute type vocabulary, mapping each short **tag** (the name used by the
@@ -54,8 +55,7 @@ export function isUserSettable(tag: TypeTag): tag is UserTypeTag {
 /**
  * Marks a value as having passed its constructor's validation. The symbol is module-private, so a
  * hand-written object literal is not assignable to {@link ArkivValue} — every value crossing the
- * wire has been range-, length- and format-checked by {@link i32}, {@link u256}, {@link dec}, and
- * friends.
+ * wire has been range-, length- and format-checked by `i32`, `u256`, `dec`, and friends.
  */
 declare const validated: unique symbol
 
@@ -89,7 +89,7 @@ export type U256Value = Value<"u256", bigint>
 export type DecValue = Value<"dec", string>
 /** 32 opaque bytes, as lowercase `0x` hex. */
 export type Bytes32Value = Value<"bytes32", Hex>
-/** A UTF-8 string of at most 128 bytes. */
+/** A UTF-8 string of at most 128 bytes, free of C0 control characters and DEL. */
 export type StrValue = Value<"str", string>
 /** A 20-byte Ethereum address, as EIP-55 checksummed hex. */
 export type AddrValue = Value<"addr", Address>

package/src/attr/values.ts

@@ -271,7 +271,11 @@ export function decFromUnits(units: bigint): DecValue {
  *
  * The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
  *
- * @throws {InvalidValueError} If the string exceeds 128 UTF-8 bytes.
+ * C0 control characters and DEL are rejected: the query language writes a `str` as `str('...')`,
+ * whose only escape is a doubled quote, so a control character could be stored but never queried.
+ *
+ * @throws {InvalidValueError} If the value is not a string, holds a control character, or exceeds
+ * 128 UTF-8 bytes.
  *
  * @example
  * str("Bob")

package/src/chains/localhost.ts

@@ -1,5 +1,8 @@
 import { defineChain } from "viem"
 
+/**
+ * A node running on the local machine
+ */
 export const localhost = defineChain({
   id: 1337,
   name: "Localhost",

package/src/clients/createPublicClient.test.ts

@@ -35,5 +35,5 @@ test("creates", () => {
   expect(client.deleteEntity).not.toBeDefined()
   expect(client.extendEntity).not.toBeDefined()
   expect(client.changeOwnership).not.toBeDefined()
-  expect(client.mutateEntities).not.toBeDefined()
+  expect(client.executeBatch).not.toBeDefined()
 })

package/src/clients/createPublicClient.ts

@@ -23,14 +23,14 @@ export type PublicArkivClient<
 >
 
 /**
- * Creates a Public Client with a given [Transport](https://viem.sh/docs/clients/intro) configured for a [Chain](https://viem.sh/docs/clients/chains).
+ * Creates a Public Client with a given [Transport](https://viem.sh/docs/clients/intro) configured for a [Chain](https://viem.sh/docs/chains/introduction).
  *
- * - Docs: https://docs.arkiv.network/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.arkiv.network/json-rpc/), and [Cheesecake JSON-RPC API](https://rpc.cheesecake.db-chain.devnet.gobas.me) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
+ * A Public Client is an interface to the "public" [Ethereum JSON-RPC API](https://ethereum.org/en/developers/docs/apis/json-rpc/)
+ * and the Arkiv JSON-RPC API — retrieving block numbers and transactions, reading from
+ * contracts, and querying entities — through {@link PublicArkivActions}.
  *
  * @param parameters - Configuration object for the public client (chain, transport, etc.)
- * @returns A Arkiv Public Client. {@link PublicArkivClient}
+ * @returns An Arkiv Public Client. {@link PublicArkivClient}
  *
  * @example
  * import { createPublicClient } from "@arkiv-network/sdk"

package/src/clients/createWalletClient.test.ts

@@ -29,6 +29,6 @@ test("creates", () => {
   expect(typeof client.extendEntity).toBe("function")
   expect(client.changeOwnership).toBeDefined()
   expect(typeof client.changeOwnership).toBe("function")
-  expect(client.mutateEntities).toBeDefined()
-  expect(typeof client.mutateEntities).toBe("function")
+  expect(client.executeBatch).toBeDefined()
+  expect(typeof client.executeBatch).toBe("function")
 })

package/src/clients/createWalletClient.ts

@@ -24,16 +24,14 @@ export type WalletArkivClient<
 
 /**
  * Creates a Wallet Client with a given [Transport](https://viem.sh/docs/clients/intro) configured
- * for a [Chain](https://viem.sh/docs/clients/chains) and an account.
- *
- * - Docs: https://docs.arkiv.network/ts-sdk/clients/wallet
+ * for a [Chain](https://viem.sh/docs/chains/introduction) and an account.
  *
  * A Wallet Client signs and sends transactions, so it carries an `account` and exposes everything
  * that mutates state — `createEntity`, `patchEntity`, `deleteEntity`, `extendEntity`,
- * `changeOwnership` and `mutateEntities` — on top of the read actions a Public Client has.
+ * `changeOwnership` and `executeBatch` — on top of the read actions a Public Client has.
  *
  * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
- * @returns A Arkiv Wallet Client. {@link WalletArkivClient}
+ * @returns An Arkiv Wallet Client. {@link WalletArkivClient}
  *
  * @example
  * import { createWalletClient } from "@arkiv-network/sdk"

package/src/clients/decorators/arkivPublic.ts

@@ -1,5 +1,5 @@
 import type { Account, Address, Chain, Client, Hex, PublicActions, Transport } from "viem"
-import { getBlockTiming } from "../../actions/public/getBlockTiming"
+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"
@@ -13,6 +13,7 @@ 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"
@@ -38,11 +39,15 @@ 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, 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 } from "@arkiv-network/sdk"
    * import { cheesecake } from "@arkiv-network/sdk/chains"
@@ -69,7 +74,7 @@ export type PublicArkivActions<
    * 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
@@ -130,7 +135,7 @@ export type PublicArkivActions<
   /**
    * Runs one query and returns one page, with no builder in between.
    *
-   * Use {@link select} for anything typed — this returns full {@link Entity} objects whatever the
+   * 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.
@@ -224,7 +229,7 @@ export type PublicArkivActions<
    * import { key } from "@arkiv-network/sdk/attr"
    *
    * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
-   * await wallet.mutateEntities({
+   * await wallet.executeBatch({
    *   creates: [
    *     { payload, contentType, expires, salt: parent.salt },
    *     {
@@ -239,7 +244,7 @@ export type PublicArkivActions<
    */
   predictEntityKeys: <
     const TCount extends number = number,
-    const TSalts extends readonly bigint[] | undefined = undefined,
+    const TSalts extends readonly SaltInput[] | undefined = undefined,
   >(
     parameters: PredictEntityKeysParameters<TCount, TSalts>,
   ) => Promise<PredictEntityKeysReturnType<TCount, TSalts>>
@@ -264,11 +269,7 @@ export type PublicArkivActions<
    * //   blockDuration: 2, // in seconds
    * // }
    */
-  getBlockTiming: () => Promise<{
-    currentBlock: bigint
-    currentBlockTime: number
-    blockDuration: number
-  }>
+  getBlockTiming: () => Promise<GetBlockTimingReturnType>
 
   /**
    * Watches entity events, calling the handlers you pass as they arrive.
@@ -314,7 +315,7 @@ export function publicArkivActions<
     getEntityNonce: (owner: Address) => getEntityNonce(client, owner),
     predictEntityKeys: <
       const TCount extends number = number,
-      const TSalts extends readonly bigint[] | undefined = undefined,
+      const TSalts extends readonly SaltInput[] | undefined = undefined,
     >(
       parameters: PredictEntityKeysParameters<TCount, TSalts>,
     ) => predictEntityKeys(client, parameters),

package/src/clients/decorators/arkivWallet.ts

@@ -14,16 +14,16 @@ import type {
   DeleteEntityReturnType,
 } from "../../actions/wallet/deleteEntity"
 import { deleteEntity } from "../../actions/wallet/deleteEntity"
+import type {
+  ExecuteBatchParameters,
+  ExecuteBatchReturnType,
+} from "../../actions/wallet/executeBatch"
+import { executeBatch } from "../../actions/wallet/executeBatch"
 import type {
   ExtendEntityParameters,
   ExtendEntityReturnType,
 } from "../../actions/wallet/extendEntity"
 import { extendEntity } from "../../actions/wallet/extendEntity"
-import type {
-  MutateEntitiesParameters,
-  MutateEntitiesReturnType,
-} from "../../actions/wallet/mutateEntities"
-import { mutateEntities } from "../../actions/wallet/mutateEntities"
 import type { PatchEntityParameters, PatchEntityReturnType } from "../../actions/wallet/patchEntity"
 import { patchEntity } from "../../actions/wallet/patchEntity"
 import type { TxParams } from "../../types"
@@ -50,12 +50,12 @@ export type WalletArkivActions<
     /**
      * Creates a new entity.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/createEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity creation parameters
      * @param txParams - Optional transaction parameters
-     * @returns The created entity with transaction hash
+     * @returns The new entity's key, the transaction hash, and the block it is expected to
+     * expire at. {@link CreateEntityReturnType}
      *
      * @throws {InvalidExpiryError} If the expiry exceeds a protocol bound or would leave the
      * entity dead on arrival.
@@ -67,8 +67,10 @@ export type WalletArkivActions<
      * import { i32 } from "@arkiv-network/sdk/attr"
      * import { cheesecake } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
      *   chain: cheesecake,
      *   transport: http(),
      * })
@@ -88,12 +90,11 @@ export type WalletArkivActions<
      * Applies a patch to the entity with the given key: sets some fields, unsets others, and leaves
      * everything it does not name alone.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/patchEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity key and the mutations to apply
      * @param txParams - Optional transaction parameters
-     * @returns The entity key and the transaction hash
+     * @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`.
@@ -105,8 +106,10 @@ export type WalletArkivActions<
      * import { i32 } from "@arkiv-network/sdk/attr"
      * import { cheesecake } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
      *   chain: cheesecake,
      *   transport: http(),
      * })
@@ -126,19 +129,20 @@ export type WalletArkivActions<
     /**
      * Deletes the entity with the given key.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/deleteEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity deletion parameters
      * @param txParams - Optional transaction parameters
-     * @returns The deleted entity with transaction hash
+     * @returns The deleted entity's key and the transaction hash. {@link DeleteEntityReturnType}
      *
      * @example
      * import { createWalletClient } from "@arkiv-network/sdk"
      * import { cheesecake } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
      *   chain: cheesecake,
      *   transport: http(),
      * })
@@ -157,12 +161,12 @@ export type WalletArkivActions<
      * 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.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/extendEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity key and its new lifetime
      * @param txParams - Optional transaction parameters
-     * @returns The entity key, transaction hash, and the block it is now expected to expire at
+     * @returns The entity's key, the transaction hash, and the block it is now expected to expire
+     * at. {@link ExtendEntityReturnType}
      *
      * @throws {InvalidExpiryError} If the expiry is malformed, exceeds a protocol bound, or would
      * leave the entity dead on arrival.
@@ -171,8 +175,10 @@ export type WalletArkivActions<
      * import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
      * import { cheesecake } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
      *   chain: cheesecake,
      *   transport: http(),
      * })
@@ -187,14 +193,13 @@ export type WalletArkivActions<
     ) => Promise<ExtendEntityReturnType>
 
     /**
-     * Changes the ownership of the entity with the given address.
+     * Hands the entity with the given key to a new owner.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/changeOwnership
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The ownership change parameters
      * @param txParams - Optional transaction parameters
-     * @returns The entity with updated ownership and transaction hash
+     * @returns The entity's key and the transaction hash. {@link ChangeOwnershipReturnType}
      */
     changeOwnership: (
       data: ChangeOwnershipParameters,
@@ -202,17 +207,18 @@ export type WalletArkivActions<
     ) => Promise<ChangeOwnershipReturnType>
 
     /**
-     * Mutates the entities with the given keys.
+     * Applies a batch of entity operations — creates, patches, deletes, extensions and ownership
+     * transfers — in one transaction.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/mutateEntities
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - 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.
      *
-     * @param data - The mutation parameters (creates, patches, deletes, extensions, ownershipChanges)
+     * @param data - The batch parameters (creates, patches, deletes, extensions, ownershipChanges)
      * @param txParams - Optional transaction parameters
-     * @returns The mutation result with transaction hash
+     * @returns The transaction hash, plus the keys touched by each kind of operation.
+     * {@link ExecuteBatchReturnType}
      *
      * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound or would leave the entity
      * dead on arrival.
@@ -222,12 +228,14 @@ export type WalletArkivActions<
      * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
      * import { cheesecake } from "@arkiv-network/sdk/chains"
      * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
      *   chain: cheesecake,
      *   transport: http(),
      * })
-     * const { txHash, createdEntities } = await client.mutateEntities({
+     * const { txHash, createdEntities } = await client.executeBatch({
      *   creates: [{
      *     payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
      *     contentType: "application/json",
@@ -243,10 +251,10 @@ export type WalletArkivActions<
      *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
      * })
      */
-    mutateEntities: (
-      data: MutateEntitiesParameters,
+    executeBatch: (
+      data: ExecuteBatchParameters,
       txParams?: TxParams,
-    ) => Promise<MutateEntitiesReturnType>
+    ) => Promise<ExecuteBatchReturnType>
   }
 
 export function walletArkivActions<
@@ -265,7 +273,7 @@ export function walletArkivActions<
       extendEntity(client, data, txParams),
     changeOwnership: (data: ChangeOwnershipParameters, txParams?: TxParams) =>
       changeOwnership(client, data, txParams),
-    mutateEntities: (data: MutateEntitiesParameters, txParams?: TxParams) =>
-      mutateEntities(client, data, txParams),
+    executeBatch: (data: ExecuteBatchParameters, txParams?: TxParams) =>
+      executeBatch(client, data, txParams),
   }
 }

package/src/entity/create.test.ts

@@ -4,7 +4,7 @@ import { encodeAttributes } from "../attr/attributes"
 import { dec, i32, str, u256 } from "../attr/values"
 import { InvalidCreationFlagsError } from "./errors"
 import { decodeCreationFlags, encodeCreationFlags } from "./flags"
-import { MAX_SALT, predictEntityKey, randomSalt, validateSalt } from "./key"
+import { MAX_SALT, NO_SALT, predictEntityKey, randomSalt, resolveSalt, validateSalt } from "./key"
 import { createOperation } from "./operations"
 import { OperationType } from "./params"
 
@@ -73,6 +73,18 @@ describe("salt", () => {
     expect(() => validateSalt(MAX_SALT + 1n)).toThrow(/uint128/)
     expect(() => validateSalt(-1n)).toThrow(/uint128/)
   })
+
+  it("resolves NO_SALT to the zero, and passes anything else through", () => {
+    expect(resolveSalt(NO_SALT)).toBe(0n)
+    expect(resolveSalt(0n)).toBe(0n)
+    expect(resolveSalt(42n)).toBe(42n)
+    expect(() => resolveSalt(MAX_SALT + 1n)).toThrow(/uint128/)
+  })
+
+  it("reports a salt it cannot use without choking on a symbol", () => {
+    // @ts-expect-error
+    expect(() => validateSalt(Symbol("nope"))).toThrow(/Invalid salt/)
+  })
 })
 
 describe("predictEntityKey", () => {
@@ -86,6 +98,13 @@ describe("predictEntityKey", () => {
     ).not.toBe(predictEntityKey(base))
   })
 
+  it("derives the same key from NO_SALT as from an explicit zero", () => {
+    const base = { owner: OWNER, nonce: 3n, chainId: 1 } as const
+    expect(predictEntityKey({ ...base, salt: NO_SALT })).toBe(
+      predictEntityKey({ ...base, salt: 0n }),
+    )
+  })
+
   it("separates chains through the domain", () => {
     const base = { owner: OWNER, nonce: 0n, salt: 0n } as const
     expect(predictEntityKey({ ...base, chainId: 1 })).not.toBe(

package/src/entity/errors.ts

@@ -16,10 +16,11 @@ export class InvalidCreationFlagsError extends Error {
 
 /** A key salt was outside the `uint128` the wire carries. */
 export class InvalidSaltError extends Error {
-  constructor(salt: bigint) {
+  constructor(salt: unknown) {
     super(
-      `Invalid salt ${salt}. A salt is a uint128, so it must be between 0 and ` +
-        `${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass 0 for a predictable key.`,
+      `Invalid salt ${String(salt)}. A salt is a uint128, so it must be between 0 and ` +
+        `${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass NO_SALT for a key derived ` +
+        `from the owner and nonce alone.`,
     )
     this.name = "InvalidSaltError"
   }

package/src/entity/expiry.ts

@@ -1,4 +1,5 @@
 import { BLOCK_TIME } from "../consts"
+import type { ExpirationTime } from "../utils/expirationTime"
 import { InvalidExpiryError } from "./errors"
 import { MAX_EXPIRES_AT } from "./params"