@arkiv-network/sdk 0.8.0-advanced.2 → 0.8.0-dev.2

package/src/clients/decorators/arkivWallet.ts

@@ -14,20 +14,19 @@ 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"
-import { type WalletAdvancedActions, walletAdvancedActions } from "./arkivAdvanced"
 
 export type WalletArkivActions<
   transport extends Transport = Transport,
@@ -51,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.
@@ -68,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(),
      * })
@@ -89,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`.
@@ -106,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(),
      * })
@@ -127,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(),
      * })
@@ -158,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.
@@ -172,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(),
      * })
@@ -188,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,
@@ -203,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.
@@ -223,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",
@@ -244,23 +251,10 @@ export type WalletArkivActions<
      *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
      * })
      */
-    mutateEntities: (
-      data: MutateEntitiesParameters,
+    executeBatch: (
+      data: ExecuteBatchParameters,
       txParams?: TxParams,
-    ) => Promise<MutateEntitiesReturnType>
-
-    /**
-     * The advanced path: build, send, ping and read mutation results as separate steps, each
-     * costing the minimum number of RPC calls. Use it when you are optimising your RPC budget;
-     * the everyday actions above remain the right default. {@link WalletAdvancedActions}
-     *
-     * @example
-     * const { txHash } = await client.advanced.sendMutation({ creates: [entity] }) // no waiting
-     * // ... later, one eth_getTransactionReceipt on your own schedule:
-     * const result = await client.advanced.getMutationResult(txHash)
-     * if (result.status === "success") console.log(result.createdEntities)
-     */
-    advanced: WalletAdvancedActions
+    ) => Promise<ExecuteBatchReturnType>
   }
 
 export function walletArkivActions<
@@ -279,8 +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),
-    advanced: walletAdvancedActions(client),
+    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"
 

package/src/entity/index.ts

@@ -10,6 +10,6 @@ export type { EncodedExpiry, Expiry, ExpiryContext, Lifetime, ResolvedExpiry } f
 export { resolveExpiry, toBlocks } from "./expiry"
 export type { CreationFlags, ResolvedCreationFlags } from "./flags"
 export { decodeCreationFlags, encodeCreationFlags } from "./flags"
-export { MAX_SALT, predictEntityKey, randomSalt } from "./key"
-export type { Operation } from "./operations"
+export type { SaltInput } from "./key"
+export { MAX_SALT, NO_SALT, predictEntityKey, randomSalt } from "./key"
 export { MAX_EXPIRES_AT, OperationType } from "./params"

package/src/entity/key.ts

@@ -1,10 +1,23 @@
 import { type Address, encodePacked, type Hex, keccak256 } from "viem"
+import type { CreateEntityParameters } from "../actions/wallet/createEntity"
 import { ARKIV_ADDRESS } from "../consts"
 import { InvalidSaltError, NoRandomSourceError } from "./errors"
 
 /** The widest salt the `uint128` wire field carries. */
 export const MAX_SALT = 2n ** 128n - 1n
 
+/**
+ * Opts a create out of salting, as {@link CreateEntityParameters.salt}: the key is then derived
+ * from the owner and its nonce alone, so anyone who knows both can work it out before the create
+ * lands.
+ */
+export const NO_SALT = Symbol("NO_SALT")
+
+/**
+ * A salt as a caller expresses it: an explicit `uint128`, or {@link NO_SALT} to opt out of salting.
+ */
+export type SaltInput = bigint | typeof NO_SALT
+
 /**
  * A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
  *
@@ -25,6 +38,13 @@ export function randomSalt(): bigint {
   return salt
 }
 
+/**
+ * Resolves a caller-supplied salt to a `uint128`.
+ */
+export function resolveSalt(salt: SaltInput): bigint {
+  return salt === NO_SALT ? 0n : validateSalt(salt)
+}
+
 /** Validates a caller-supplied salt against the `uint128` wire field. */
 export function validateSalt(salt: bigint): bigint {
   if (typeof salt !== "bigint" || salt < 0n || salt > MAX_SALT) {
@@ -54,15 +74,15 @@ export function predictEntityKey({
    * create in a batch uses `nonce + n`.
    */
   nonce: bigint
-  /** The salt the create will carry. */
-  salt: bigint
+  /** The salt the create will carry, or {@link NO_SALT} if it carries none. */
+  salt: SaltInput
   /** The chain the entity is being created on — half of the derivation domain. */
   chainId: number
 }): Hex {
   return keccak256(
     encodePacked(
       ["uint256", "address", "address", "uint64", "uint128"],
-      [BigInt(chainId), ARKIV_ADDRESS, owner, nonce, validateSalt(salt)],
+      [BigInt(chainId), ARKIV_ADDRESS, owner, nonce, resolveSalt(salt)],
     ),
   )
 }

package/src/entity/operations.ts

@@ -1,6 +1,7 @@
 import { type Address, encodeAbiParameters, type Hex, parseAbi, parseAbiParameters } from "viem"
 import type { AbiAttribute } from "../attr/codec"
 import type { EncodedExpiry } from "./expiry"
+import type { predictEntityKey } from "./key"
 import { OperationType } from "./params"
 
 /**

package/src/index.ts

@@ -2,8 +2,6 @@
  * @module main
  */
 
-// the advanced path: build, send, ping and read mutation results as separate minimal-RPC steps
-export * from "./actions/advanced"
 // the attribute type system
 export * from "./attr"
 // export main arkiv stuff
@@ -12,10 +10,6 @@ export type { PublicArkivClient } from "./clients/createPublicClient"
 export { createPublicClient } from "./clients/createPublicClient"
 export type { WalletArkivClient } from "./clients/createWalletClient"
 export { createWalletClient } from "./clients/createWalletClient"
-export type {
-  PublicAdvancedActions,
-  WalletAdvancedActions,
-} from "./clients/decorators/arkivAdvanced"
 export type { PublicArkivActions } from "./clients/decorators/arkivPublic"
 export type { WalletArkivActions } from "./clients/decorators/arkivWallet"
 // entity lifetimes, flags, keys and the protocol parameters behind them
@@ -24,13 +18,6 @@ export * from "./entity"
 export * from "./errors"
 // re-export arkiv types in main index file
 export * from "./types"
-// the building blocks behind the advanced path, for callers that go even lower
-export type { EntityMutationOps, MutationEvents } from "./utils/arkivTransactions"
-export {
-  buildEntityOperations,
-  collectMutationEvents,
-  mutationNeedsBlockNumber,
-} from "./utils/arkivTransactions"
 // re-export chosen utils
 export { chainFromName } from "./utils/chains"
 // every create needs an expiry, and this is the only way to build one

package/src/query/engine.ts

@@ -41,17 +41,6 @@ export type QueryResponse = {
 export async function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse> {
   const { query, select, limit, cursor, atBlock } = request
 
-  // A cursor is bound to the block it was issued at; without a block the node reads at the head,
-  // and the resume breaks whenever a block has landed in between — an intermittent failure this
-  // turns into a deterministic one. (Pages chained through `QueryResult.next` inherit the block
-  // automatically; this catches a cursor resumed by hand.)
-  if (cursor !== undefined && atBlock === undefined) {
-    throw new Error(
-      "a cursor must be resumed with `atBlock` set to the `blockNumber` of the page it came " +
-        "from — persist the two together.",
-    )
-  }
-
   if (limit !== undefined) {
     if (!Number.isInteger(limit) || limit < 1) {
       throw new Error(`limit must be a positive integer, got ${limit}.`)

package/src/query/errors.ts

@@ -10,7 +10,7 @@ import type { TypeTag } from "../attr"
  * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
  * | --- | --- | --- | --- |
  * | `bool` | yes | no | no |
- * | `i32` `u256` `dec` | yes | yes | no |
+ * | `i32` `u64` `u256` `dec` | yes | yes | no |
  * | `str` | yes | no | yes |
  * | `addr` `key` `bytes32` | yes | no | no |
  */

package/src/query/expression.ts

@@ -12,6 +12,10 @@ import {
 import { TYPE_IDS } from "../attr/types"
 import { InvalidPredicateError, UnsupportedOperatorError } from "./errors"
 
+/**
+ * The comparison operators the query language defines. `<` `<=` `>` `>=` need an ordered type —
+ * `i32`, `u64`, `u256` or `dec`; every type accepts `=` and `!=`.
+ */
 export type ComparisonOperator = "=" | "!=" | "<" | "<=" | ">" | ">="
 
 /** A comparison between an attribute and a typed literal. */
@@ -216,7 +220,7 @@ export function ne(name: string, value: ValueInput): ComparisonNode {
 }
 
 /**
- * Attribute is greater than value. Ordered types only (`i32`, `u256`, `dec`).
+ * Attribute is greater than value. Ordered types only (`i32`, `u64`, `u256`, `dec`).
  *
  * @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
  *
@@ -229,7 +233,7 @@ export function gt(name: string, value: ValueInput): ComparisonNode {
 }
 
 /**
- * Attribute is greater than or equal to value. Ordered types only (`i32`, `u256`, `dec`).
+ * Attribute is greater than or equal to value. Ordered types only (`i32`, `u64`, `u256`, `dec`).
  *
  * @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
  *
@@ -241,7 +245,7 @@ export function gte(name: string, value: ValueInput): ComparisonNode {
 }
 
 /**
- * Attribute is less than value. Ordered types only (`i32`, `u256`, `dec`).
+ * Attribute is less than value. Ordered types only (`i32`, `u64`, `u256`, `dec`).
  *
  * @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
  *
@@ -253,7 +257,7 @@ export function lt(name: string, value: ValueInput): ComparisonNode {
 }
 
 /**
- * Attribute is less than or equal to value. Ordered types only (`i32`, `u256`, `dec`).
+ * Attribute is less than or equal to value. Ordered types only (`i32`, `u64`, `u256`, `dec`).
  *
  * @throws {UnsupportedOperatorError} If the value's type carries no ordered index.
  *
@@ -271,7 +275,9 @@ export function lte(name: string, value: ValueInput): ComparisonNode {
  * `startsWith("name", "é")` matches only the same byte sequence, not another normal form of it.
  *
  * @param prefix - The prefix, as a bare string or a `str` value.
- * @throws {UnsupportedOperatorError} If given a value that is not a `str`.
+ * @throws {InvalidPredicateError} If the name is not a queryable attribute.
+ * @throws {UnsupportedOperatorError} If given a value that is not a `str`, or a system attribute
+ * (none of which is a `str`).
  *
  * @example
  * startsWith("desc", "ab") // desc STARTSWITH str('ab')
@@ -325,7 +331,8 @@ export function exists(name: string): ExistsNode {
  * Useful when the same name is written with different types across entities — a comparison already
  * asserts the type, so this is for asking about the type alone.
  *
- * @param tag - The type tag: `bool`, `i32`, `u256`, `dec`, `bytes32`, `str`, `addr` or `key`.
+ * @param tag - The type tag: `bool`, `i32`, `u64`, `u256`, `dec`, `bytes32`, `str`, `addr` or
+ * `key`.
  * @throws {InvalidPredicateError} If the tag is not a settable type, or the name is a system
  * attribute (whose type is fixed).
  *
@@ -344,7 +351,7 @@ export function hasType(name: string, tag: UserTypeTag): TypeOfNode {
   if (!isUserTypeTag(tag)) {
     throw new InvalidPredicateError(
       `"${tag}" is not a settable attribute type. Use one of ` +
-        "bool, i32, u256, dec, bytes32, str, addr, key.",
+        "bool, i32, u64, u256, dec, bytes32, str, addr, key.",
       name,
     )
   }

package/src/query/queryBuilder.test.ts

@@ -242,27 +242,7 @@ describe("pagination", () => {
 
     expect(sent(request, 1).query).toBe("a = i32(1)")
     expect(sent(request, 1).options).not.toHaveProperty("limit")
-    // The block page 2 reads at is the one page 1 was served from, not the builder's later edit.
-    expect(sent(request, 1).options).toMatchObject({ atBlock: "0x8e1ff" })
-  })
-
-  it("pins the rest of the walk to the block the first page was read at", async () => {
-    const { client, request } = makeClient(
-      page("b64:1", "0x1"),
-      page("b64:2", "0x2"),
-      page(undefined, "0x3"),
-    )
-    // No atBlock on the builder: the first page reads at the head, and every page after it reads
-    // at the block that page came back with. Otherwise a block mined mid-walk moves the head on
-    // and the node rejects a cursor bound to the earlier one.
-    const first = await new SelectQueryBuilder(client, { key: true }).where(eq("a", 1)).fetch()
-    expect(sent(request, 0).options).not.toHaveProperty("atBlock")
-
-    const second = await first.next()
-    expect(sent(request, 1).options).toMatchObject({ cursor: "b64:1", atBlock: "0x8e1ff" })
-
-    await second.next()
-    expect(sent(request, 2).options).toMatchObject({ cursor: "b64:2", atBlock: "0x8e1ff" })
+    expect(sent(request, 1).options).not.toHaveProperty("atBlock")
   })
 
   it("walks every page through the async iterator", async () => {

package/src/query/queryBuilder.ts

@@ -5,7 +5,7 @@ import type { Entity } from "../types/entity"
 import type { RpcSelect } from "../types/rpcSchema"
 import { type QueryRequest, runQuery } from "./engine"
 import { InvalidPredicateError } from "./errors"
-import { and, type Expression, eq } from "./expression"
+import { and, type Expression, eq, type or } from "./expression"
 import { QueryResult } from "./queryResult"
 import { type SelectArg, toRpcSelect } from "./selection"
 
@@ -110,9 +110,7 @@ export class SelectQueryBuilder<TEntity = Entity> {
    *
    * Pagination normally goes through {@link QueryResult.next}, which carries the cursor for you;
    * this is for resuming a walk in a later process. A cursor is bound to the query, block and
-   * selection it came from, so it must be used with an identically-built query — {@link atBlock}
-   * set to the `blockNumber` of the page the cursor came from is required (persist the two
-   * together), and a fetch with a cursor but no block rejects locally.
+   * selection it came from, so it must be used with an identically-built query.
    */
   cursor(cursor: string): this {
     this._cursor = cursor
@@ -205,17 +203,12 @@ async function fetchPage<TEntity>(
 ): Promise<QueryResult<TEntity>> {
   const response = await runQuery(client, { ...request, cursor })
 
-  // Pin the rest of the walk to the block this page was read at. Without a block the node reads
-  // at the head, and a block mined between two pages would leave the cursor bound to the previous
-  // one — a `kind: "cursor"` rejection mid-walk on an otherwise valid page-through.
-  const pinned = Object.freeze({ ...request, atBlock: response.blockNumber })
-
   return new QueryResult<TEntity>(
     // Every row decodes to a full Entity; the static narrowing to the selected fields comes from
     // `client.select()`'s inference and nothing at runtime depends on it.
     response.entities as unknown as TEntity[],
     response.blockNumber,
     response.cursor,
-    (next) => fetchPage<TEntity>(client, pinned, next),
+    (next) => fetchPage<TEntity>(client, request, next),
   )
 }

package/src/types/index.ts

@@ -12,11 +12,11 @@ export type {
 } from "../actions/wallet/changeOwnership"
 export type { CreateEntityParameters, CreateEntityReturnType } from "../actions/wallet/createEntity"
 export type { DeleteEntityParameters, DeleteEntityReturnType } from "../actions/wallet/deleteEntity"
-export type { ExtendEntityParameters, ExtendEntityReturnType } from "../actions/wallet/extendEntity"
 export type {
-  MutateEntitiesParameters,
-  MutateEntitiesReturnType,
-} from "../actions/wallet/mutateEntities"
+  ExecuteBatchParameters,
+  ExecuteBatchReturnType,
+} from "../actions/wallet/executeBatch"
+export type { ExtendEntityParameters, ExtendEntityReturnType } from "../actions/wallet/extendEntity"
 export type { PatchEntityParameters, PatchEntityReturnType } from "../actions/wallet/patchEntity"
 export type { EntityFields } from "./entity"
 export { Entity } from "./entity"

package/src/types/rpcSchema.ts

@@ -69,6 +69,7 @@ export type RpcSelect = {
   attributes?: boolean | Record<string, boolean>
 }
 
+/** The second parameter of `arkiv_query` — what to return, and where in the results to start. */
 export type RpcQueryOptions = {
   /** Block height to read at, as a hex quantity. Defaults to the head, and must be within the node's retained range. */
   atBlock?: Hex

package/src/types/txParams.ts

@@ -1,3 +1,11 @@
+/**
+ * Transaction fields a write action passes through to the wallet, for the cases where the defaults
+ * are not what you want.
+ *
+ * Fee style is either/or: give `gasPrice` for a legacy transaction, or `maxFeePerGas` /
+ * `maxPriorityFeePerGas` for an EIP-1559 one. Mixing the two does not typecheck. Anything left out
+ * is estimated.
+ */
 export type TxParams =
   | {
       gas?: bigint

package/src/utils/arkivTransactions.test.ts

@@ -23,7 +23,7 @@ import {
 } from "../attr"
 import type { ArkivClient } from "../clients/baseClient"
 import { ARKIV_ADDRESS } from "../consts"
-import { InvalidExpiryError } from "../entity"
+import { InvalidExpiryError, NO_SALT } from "../entity"
 import { ENTITY_EVENTS_ABI, type EntityEventName } from "../entity/events"
 import { MAX_EXPIRES_AT, OperationType } from "../entity/params"
 import { EmptyPatchError, EntityMutationError } from "../errors"
@@ -304,6 +304,12 @@ describe("creation flags and salt", () => {
     expect(sentCreate(w2).salt).toBe(0n)
   })
 
+  it("sends a zero salt for a create that opts out with NO_SALT", async () => {
+    const { client, writeContract } = makeClient()
+    await sendArkivTransaction(client, { creates: [{ ...validCreate, salt: NO_SALT }] })
+    expect(sentCreate(writeContract).salt).toBe(0n)
+  })
+
   it("rejects a salt wider than the uint128 field", async () => {
     const { client } = makeClient()
     await expect(