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

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/arkivAdvanced.ts

@@ -70,7 +70,7 @@ export type PublicAdvancedActions = {
  * 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`, `mutateEntities`, …) bundle send + wait + decode and are
+ * 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.

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"
@@ -39,11 +40,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"
@@ -70,7 +75,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
@@ -131,7 +136,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.
@@ -225,7 +230,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 },
    *     {
@@ -240,7 +245,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>>
@@ -265,11 +270,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.
@@ -325,7 +326,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"
@@ -51,12 +51,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 +68,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 +91,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 +107,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 +130,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 +162,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 +176,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 +194,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 +208,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 +229,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,10 +252,10 @@ export type WalletArkivActions<
      *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
      * })
      */
-    mutateEntities: (
-      data: MutateEntitiesParameters,
+    executeBatch: (
+      data: ExecuteBatchParameters,
       txParams?: TxParams,
-    ) => Promise<MutateEntitiesReturnType>
+    ) => Promise<ExecuteBatchReturnType>
 
     /**
      * The advanced path: build, send, ping and read mutation results as separate steps, each
@@ -279,8 +287,8 @@ 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),
     advanced: walletAdvancedActions(client),
   }
 }

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,7 @@ 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 { SaltInput } from "./key"
+export { MAX_SALT, NO_SALT, predictEntityKey, randomSalt } from "./key"
 export type { Operation } from "./operations"
 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/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 |
  */