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

package/dist/index.d.ts

@@ -1,8 +1,105 @@
-import { A as RpcEntity, C as QueryOptions, D as GetBlockTimingReturnType, E as QueryReturnType, M as RpcOrderByAttribute, N as RpcQueryOptions, O as ArkivClient, P as MimeType, S as ChangeOwnershipReturnType, T as QueryOptionsOrderBy, _ as DeleteEntityParameters, a as OnEntityDeletedEvent, b as CreateEntityReturnType, c as OnEntityOwnerChangedEvent, d as MutateEntitiesParameters, f as MutateEntitiesReturnType, g as ExtendEntityReturnType, h as ExtendEntityParameters, i as OnEntityCreatedEvent, j as RpcIncludeData, k as ArkivRpcSchema, l as OnEntityUpdatedEvent, m as UpdateEntityReturnType, n as EntityOperationType, o as OnEntityExpiredEvent, p as UpdateEntityParameters, r as TxParams, s as OnEntityExpiresInExtendedEvent, t as Entity, u as Attribute, v as DeleteEntityReturnType, w as QueryOptionsIncludeData, x as ChangeOwnershipParameters, y as CreateEntityParameters } from "./entity-NnEVlePN.js";
-import { c as FullEntity, i as SelectQueryBuilder, l as ProjectedEntity, r as QueryBuilder, s as EntitySelection, u as SelectArg } from "./index-ClkpS6s_.js";
-import { n as stringToPayload, t as jsonToPayload } from "./payload-C2KHOUoj.js";
-import { Account, Address, Chain, Client, Hex, ParseAccount, Prettify, PublicActions, PublicClientConfig, RpcSchema, Transport, WalletActions, WalletClientConfig } from "viem";
+import { F as RpcCreationFlags, I as RpcEntity, L as RpcQueryOptions, M as ArkivRpcSchema, N as RpcAttribute, P as RpcAttributeSchemaEntry, R as RpcSelect, c as EntityFields, i as SelectArg, j as ArkivClient, n as FullEntity, p as Expression, r as ProjectedEntity, s as Entity, t as EntitySelection } from "./selection-C4UhsMOO.js";
+import { a as Bytes32Value, c as I32Value, d as TypeTag, f as U256Value, h as isArkivValue, i as BoolValue, l as KeyValue, m as UserTypeTag, n as AnyArkivValue, o as BytesValue, p as U64Value, r as ArkivValue, s as DecValue, t as AddrValue, u as StrValue } from "./codec-Car3KkFF.js";
+import { a as ResolvedExpiry, i as Lifetime, n as Expiry, o as resolveExpiry, r as ExpiryContext, s as toBlocks, t as EncodedExpiry } from "./expiry-nDbCgZX4.js";
+import { a as randomSalt, c as InvalidCreationFlagsError, d as NoRandomSourceError, f as Operation, i as predictEntityKey, l as InvalidExpiryError, n as OperationType, o as ENTITY_EVENTS_ABI, r as MAX_SALT, s as EntityEventName, t as MAX_EXPIRES_AT, u as InvalidSaltError } from "./index-fX_XyqLp.js";
+import { A as PredictEntityKeysParameters, C as EntityEvent, D as OwnershipTransferredEvent, E as ExpiryExtendedEvent, M as PredictedEntityKey, N as GetBlockTimingReturnType, O as QueryOptions, S as EntityDeletedEvent, T as EntityPatchedEvent, _ as DeleteEntityReturnType, a as mutationNeedsBlockNumber, b as WatchEntityEventsParameters, c as TxParams, d as PatchEntityReturnType, f as MutateEntitiesParameters, g as DeleteEntityParameters, h as ExtendEntityReturnType, i as collectMutationEvents, j as PredictEntityKeysReturnType, k as QueryReturnType, l as MimeType, m as ExtendEntityParameters, n as MutationEvents, o as ChangeOwnershipParameters, p as MutateEntitiesReturnType, r as buildEntityOperations, s as ChangeOwnershipReturnType, t as EntityMutationOps, u as PatchEntityParameters, v as CreateEntityParameters, w as EntityEventContext, x as EntityCreatedEvent, y as CreateEntityReturnType } from "./arkivTransactions-NtGD6uk5.js";
+import { A as i32, C as ValueInput, D as dec, E as bytes32, F as u64, M as str, N as toValue, O as decFromUnits, P as u256, S as U64_MAX, T as bool, _ as MAX_PAYLOAD_BYTES, a as InvalidAttributeNameError, b as MAX_STRING_BYTES, c as TooManyAttributesError, d as DECIMAL_SCALE, f as DECIMAL_UNIT, g as MAX_ATTRIBUTES, h as Attributes, i as ConflictingMutationError, j as key, k as decUnits, l as UnknownAttributeTypeError, m as AttributeSchema, n as isValidAttributeName, o as InvalidValueError, p as AttributeInputs, r as validateAttributeName, s as MissingValueError, t as MAX_NAME_BYTES, u as UntypedValueError, v as I32_MAX, w as addr, x as U256_MAX, y as I32_MIN } from "./index-DvYvrkdk.js";
+import { i as encodeCreationFlags, n as ResolvedCreationFlags, r as decodeCreationFlags, t as CreationFlags } from "./flags-5dTNRnow.js";
+import { a as pingTransaction, c as decodeMutationResult, d as BuildMutationReturnType, f as buildMutation, i as PingTransactionReturnType, l as getMutationResult, n as SendMutationReturnType, o as GetMutationResultReturnType, r as sendMutation, s as MutationResult, t as SendMutationOptions, u as BuildMutationOptions } from "./index-B5j76711.js";
+import { t as SelectQueryBuilder } from "./index-DHDud2hC.js";
+import { i as ExpirationTime, n as stringToPayload, r as DeadlineOptions, t as jsonToPayload } from "./payload-CcUj85ys.js";
+import { Account, Address, Chain, Client, Hash, Hex, ParseAccount, Prettify, PublicActions, PublicClientConfig, RpcSchema, TransactionReceipt, Transport, WalletActions, WalletClientConfig } from "viem";
 
+//#region src/clients/decorators/arkivAdvanced.d.ts
+/**
+ * The read-only half of the advanced path — checking on a transaction and decoding its result —
+ * which needs no account, so a Public Client carries it too.
+ *
+ * Every action here costs at most one RPC call, and says exactly which.
+ */
+type PublicAdvancedActions = {
+  /**
+   * Asks the chain — once — whether a transaction has landed. Exactly one
+   * `eth_getTransactionReceipt`, never a poll: an unmined transaction comes back as
+   * `{ status: "pending" }` and the schedule stays yours.
+   *
+   * @param txHash - The transaction hash returned by `sendMutation` (or any other send)
+   * @returns `{ status: "pending" }`, or `{ status: "success" | "reverted", blockNumber }`
+   *
+   * @example
+   * const { status } = await client.advanced.pingTransaction(txHash)
+   * if (status === "pending") scheduleAnotherPing()
+   */
+  pingTransaction: (txHash: Hash) => Promise<PingTransactionReturnType>;
+  /**
+   * Fetches a transaction's receipt — once — and decodes what the mutation did: created keys and
+   * expiries, plus the keys of everything patched, deleted, extended or handed over. One
+   * `eth_getTransactionReceipt`; `{ status: "pending" }` if not mined yet. No revert diagnosis is
+   * run on a `reverted` result — that extra call is yours to spend or skip.
+   *
+   * @param txHash - The transaction hash
+   * @returns The decoded {@link MutationResult}, or `{ status: "pending" }`
+   *
+   * @example
+   * const result = await client.advanced.getMutationResult(txHash)
+   * if (result.status === "success") console.log(result.createdEntities)
+   */
+  getMutationResult: (txHash: Hash) => Promise<GetMutationResultReturnType>;
+  /**
+   * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls** — for
+   * receipts that reached you through your own `waitForTransactionReceipt`, a block watcher, or a
+   * webhook.
+   *
+   * @param receipt - The transaction receipt
+   * @returns The decoded {@link MutationResult}
+   */
+  decodeMutationResult: (receipt: TransactionReceipt) => MutationResult;
+};
+/**
+ * The advanced path on a Wallet Client: build, send, ping and read results as separate steps, each
+ * costing the minimum number of RPC calls — down to one per transaction when you supply what the
+ * SDK would otherwise look up.
+ *
+ * The everyday actions (`createEntity`, `mutateEntities`, …) bundle send + wait + decode and are
+ * the right default. This namespace unbundles them for callers optimising their RPC budget.
+ *
+ * @example Minimal-call flow: one send, one ping, done.
+ * const { txHash } = await client.advanced.sendMutation(
+ *   { creates: [{ payload, contentType: "application/json", expires }] },
+ *   { currentBlock, txParams: { nonce, gas: 1_000_000n, maxFeePerGas, maxPriorityFeePerGas } },
+ * ) // exactly 1 RPC call: eth_sendRawTransaction
+ * // ... later, on your own schedule:
+ * const result = await client.advanced.getMutationResult(txHash) // 1 RPC call
+ * if (result.status === "success") console.log(result.createdEntities)
+ */
+type WalletAdvancedActions = PublicAdvancedActions & {
+  /**
+   * Encodes a mutation batch without sending anything: zero RPC calls with `currentBlock` supplied
+   * (or when no expiry is relative), at most one `eth_blockNumber` otherwise. Returns the
+   * operations for `writeContract`, and the `{ to, data }` calldata for offline signing.
+   *
+   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
+   * @param options - Optional `currentBlock` to avoid the `eth_blockNumber` lookup
+   */
+  buildMutation: (data: EntityMutationOps, options?: BuildMutationOptions) => Promise<BuildMutationReturnType>;
+  /**
+   * Signs and sends a mutation batch, returning the hash as soon as the transaction is submitted —
+   * no waiting, no polling, no revert diagnosis. With `currentBlock` and full `txParams` (nonce,
+   * gas, fees) supplied this is exactly one `eth_sendRawTransaction`; each omitted piece adds only
+   * the lookup viem needs to fill it.
+   *
+   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
+   * @param options - Optional `currentBlock` and `txParams`
+   * @returns The transaction hash and the batch's per-kind operation counts
+   *
+   * @example
+   * const { txHash } = await client.advanced.sendMutation({
+   *   creates: [{ payload, contentType: "application/json", expires: ExpirationTime.atBlock(1_200_000n) }],
+   * })
+   */
+  sendMutation: (data: EntityMutationOps, options?: SendMutationOptions) => Promise<SendMutationReturnType>;
+};
+//#endregion
 //#region src/clients/decorators/arkivPublic.d.ts
 type PublicArkivActions<transport extends Transport = Transport, chain extends Chain | undefined = Chain | undefined, account extends Account | undefined = Account | undefined> = Pick<PublicActions<transport, chain, account>, "getBalance" | "getBlock" | "getBlockNumber" | "getChainId" | "getLogs" | "getTransaction" | "getTransactionCount" | "getTransactionReceipt" | "waitForTransactionReceipt" | "watchEvent"> & {
   /**
@@ -11,23 +108,28 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/getEntity
    *
    * @param key - The entity key (hex string)
-   * @returns The entity with the given key. {@link Entity}
+   * @returns The entity with the given key, with every field populated. {@link FullEntity}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entity = await client.getEntity("0x123")
-   * // {
-   * //   key: "0x123",
-   * //   value: "0x123",
+   * const entity = await client.getEntity(entityKey)
+   * // Entity {
+   * //   key: "0x9f2c…",
+   * //   owner: "0xabc…",
+   * //   contentType: "application/json",
+   * //   payload: Uint8Array,          // entity.toJson() / entity.toText() decode it
+   * //   attributes: { category: { type: "str", value: "docs" } },
+   * //   expiresAt: 1_297_000n,
    * // }
    */
-  getEntity: (key: Hex) => Promise<Entity>;
+  getEntity: (key: Hex) => Promise<FullEntity>;
   /**
    * Returns a SelectQueryBuilder for building and executing queries — the recommended way to
    * read entities. You declare up front which parts of an entity you want returned, so results
@@ -42,12 +144,13 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
    * @returns A SelectQueryBuilder instance for building and executing queries. {@link SelectQueryBuilder}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
-   * import { eq } from 'arkiv/query'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { eq } from "@arkiv-network/sdk/query"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * // select everything
@@ -55,7 +158,7 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
    * await client.select("*").where(eq("category", "docs")).fetch()
    * // only the key
    * await client.select({ key: true }).where(eq("category", "docs")).fetch()
-   * // select specific fields — result typed { owner: Hex; attributes: Attribute[] }
+   * // select specific fields — result typed { owner: Hex; attributes: Attributes }
    * await client.select({ owner: true, attributes: true }).fetch()
    * // a single field — result typed { owner: Hex }
    * await client.select({ owner: true }).fetch()
@@ -67,9 +170,11 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
      * Pick the entity fields to return. Set the ones you want to `true` (at least one is required);
      * the result is typed to exactly those fields, so reading anything else is a compile error.
      *
-     * Available fields: `key`, `owner`, `creator`, `contentType`, `payload`, `attributes`,
-     * `expiresAtBlock`, `createdAtBlock`, `lastModifiedAtBlock`, `transactionIndexInBlock`,
-     * `operationIndexInTransaction`.
+     * Available fields: `key`, `owner`, `creator`, `createdAt`, `updatedAt`, `expiresAt`,
+     * `creationFlags`, `contentType`, `payload`, `attributeSchema` and `attributes`.
+     *
+     * `attributes` also takes a map of names, to fetch only those:
+     * `select({ key: true, attributes: { projectId: true } })`.
      *
      * Pass the selection inline so its fields stay literal `true`. A selection stored in a `let`/
      * `const` variable widens to `boolean` and the result type can no longer be narrowed — annotate
@@ -77,7 +182,8 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
      *
      * @example
      * client.select({ owner: true, attributes: true }) // entities typed { owner, attributes }
-     * client.select({ key: true, payload: true })       // includes payload → toText()/toJson() too
+     * client.select({ key: true, payload: true })      // includes payload → toText()/toJson() too
+     * client.select({ key: true, attributeSchema: true }) // what shape is the data?
      */
     <const S extends EntitySelection>(selection: S): SelectQueryBuilder<ProjectedEntity<S>>;
     /**
@@ -87,87 +193,124 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
     (selection: SelectArg): SelectQueryBuilder<FullEntity>;
   };
   /**
-   * Returns a QueryBuilder instance for building and executing queries.
-   * The QueryBuilder object follows the Builder pattern, allowing you to chain methods to build a query and then execute it.
-   *
-   * - Docs: https://docs.arkiv.network/ts-sdk/actions/public/query
+   * Runs one query and returns one page, with no builder in between.
    *
-   * @deprecated Use {@link select} instead. `buildQuery()` returns only the entity `key` unless
-   * you remember to opt in to data with `withAttributes()`/`withMetadata()`/`withPayload()`, which
-   * is an easy mistake. `select()` makes the selection explicit. This method remains for backwards
-   * compatibility and will be removed in a future release.
+   * Use {@link select} for anything typed — this returns full {@link Entity} objects whatever the
+   * selection, and takes a raw string as an escape hatch for a query built elsewhere. A raw string
+   * goes to the node exactly as written, with none of the name, type or operator checks the
+   * expression combinators apply.
    *
-   * @returns A QueryBuilder instance for building and executing queries. {@link QueryBuilder}
+   * @param query - An {@link Expression}, or the raw query string.
+   * @param queryOptions - Selection, page size, cursor and block. {@link QueryOptions}
+   * @returns One page of entities. {@link QueryReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { and, eq, gte } from "@arkiv-network/sdk/query"
+   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const query = client.buildQuery()
-   * const entities = await query.where("key", "=", "value").ownedBy("0x123").fetch()
+   * const page = await client.query(and(eq("category", "docs"), gte("level", i32(10))), {
+   *   select: { key: true, attributes: true },
+   *   limit: 100,
+   * })
+   * // { entities: [Entity], cursor: "b64:…", blockNumber: 32223n }
    *
+   * // The raw form, unchecked:
+   * await client.query("category = str('docs') AND level >= i32(10)")
    */
-  buildQuery: () => QueryBuilder;
+  query: (query: Expression | string, queryOptions?: QueryOptions) => Promise<QueryReturnType>;
   /**
-   * Returns a QueryResult instance for fetching the results of a raw query.
-   * If no query options are provided, all payload is included, but no metadata (like owner, expiredAt, etc.) and attributes.
-   * @param query - The raw query string
-   * @param queryOptions - The optional query options - {@link QueryOptions}
-   * @returns A QueryReturnType instance - {@link QueryReturnType}
+   * Returns the total number of entities on the chain.
+   * @returns The number of entities currently stored
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const queryResult = client.query('key = value && $owner = 0x123')
-   * // queryResult = { entities: [{ key: "0x123", value: "0x123" }], cursor: undefined, blockNumber: undefined }
-   * const queryResultWithOptions = client.query('key = value && $owner = 0x123', {
-   *   includeData: {
-   *     attributes: false,
-   *     payload: true,
-   *     metadata: true,
-   *   },
-   *   resultsPerPage: 10,
-   *   cursor: undefined,
-   *   atBlock: undefined,
-   * })
-   * // queryResultWithOptions = { entities: [{ key: "0x123", value: "0x123" }], cursor: "...", blockNumber: 32223n }
+   * const entityCount = await client.getEntityCount()
+   * // entityCount = 0
    */
-  query: (query: string, queryOptions?: QueryOptions) => Promise<QueryReturnType>;
+  getEntityCount: () => Promise<number>;
   /**
-   * Returns the number of entities in the DBChain.
-   * @returns The number of entities in the DBChain
+   * Returns how many entities an account has created — its entity-minting nonce.
+   *
+   * Not the account's transaction nonce: the engine keeps its own counter per creator and mixes it
+   * into every key it mints, which is why two identical creates from one account never collide.
+   *
+   * @param owner - The account whose nonce to read.
+   * @returns The nonce the account's next create will use.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const entityCount = await client.getEntityCount()
-   * // entityCount = 0
+   * const nonce = await client.getEntityNonce("0xabc…")
+   * // 7n — the next entity this account creates is its eighth
    */
-  getEntityCount: () => Promise<number>;
+  getEntityNonce: (owner: Address) => Promise<bigint>;
+  /**
+   * Works out the keys an account's next creates will be given, before sending them.
+   *
+   * The engine derives a key from the chain, the registry, the owner, the owner's nonce and a
+   * salt — everything but the nonce is known to the caller, and the nonce is read here. This is
+   * what lets a batch reference an entity it is about to mint.
+   *
+   * Each key arrives paired with the salt that mints it, because a create defaults to a *random*
+   * salt: a predicted key only holds if the create carries the salt it was predicted with. And the
+   * prediction holds only while nothing else from this owner is in flight — for a key you can rely
+   * on unconditionally, read it back from the create instead.
+   *
+   * A literal `count` comes back as a fixed-length tuple, so the pairs destructure into names.
+   *
+   * @param parameters - Owner, and either a count or the salts. {@link PredictEntityKeysParameters}
+   * @returns One `{ key, salt }` pair per create, in batch order.
+   *   {@link PredictEntityKeysReturnType}
+   *
+   * @example A batch whose second entity points at its first.
+   * import { key } from "@arkiv-network/sdk/attr"
+   *
+   * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
+   * await wallet.mutateEntities({
+   *   creates: [
+   *     { payload, contentType, expires, salt: parent.salt },
+   *     {
+   *       payload,
+   *       contentType,
+   *       expires,
+   *       salt: child.salt,
+   *       attributes: { parent: key(parent.key) },
+   *     },
+   *   ],
+   * })
+   */
+  predictEntityKeys: <const TCount extends number = number, const TSalts extends readonly bigint[] | undefined = undefined>(parameters: PredictEntityKeysParameters<TCount, TSalts>) => Promise<PredictEntityKeysReturnType<TCount, TSalts>>;
   /**
    * Returns the current block timing.
    * @returns The current block timing. {@link GetBlockTimingReturnType}
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
    * const blockTiming = await client.getBlockTiming()
@@ -183,39 +326,41 @@ type PublicArkivActions<transport extends Transport = Transport, chain extends C
     blockDuration: number;
   }>;
   /**
-   * Subscribes to entity events.
-   * Takes an object with event handlers: {onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpiresInExtended}
-   * @param pollingInterval - The polling interval in milliseconds
-   * @param fromBlock - The block number to start from
-   * @returns A function to unsubscribe from the events
+   * Watches entity events, calling the handlers you pass as they arrive.
+   *
+   * All five are decoded from logs — `onEntityCreated`, `onEntityPatched`, `onExpiryExtended`,
+   * `onOwnershipTransferred`, `onEntityDeleted` — and each carries the block, transaction and log
+   * index it came from, which is the order the operations were applied in. `onEvent` receives all
+   * of them, whatever their type.
+   *
+   * @param parameters - Handlers and options, all optional. {@link WatchEntityEventsParameters}
+   * @returns A function that stops the watcher.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createPublicClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createPublicClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const unsubscribe = await client.subscribeEntityEvents({
-   *   onError: (error) => console.error("subscribeEntityEvents error", error),
+   * const unwatch = client.watchEntityEvents({
+   *   onEntityCreated: ({ entityKey, expiresAt }) => console.log(entityKey, "until", expiresAt),
+   *   onError: (error) => console.error("watchEntityEvents error", error),
    * })
-   * unsubscribe() // unsubscribe from the events
+   * unwatch() // stop watching
    */
-  subscribeEntityEvents: ({
-    onError,
-    onEntityCreated,
-    onEntityUpdated,
-    onEntityDeleted,
-    onEntityExpiresInExtended
-  }: {
-    onError?: (error: Error) => void;
-    onEntityCreated?: (event: OnEntityCreatedEvent) => void;
-    onEntityUpdated?: (event: OnEntityUpdatedEvent) => void;
-    onEntityDeleted?: (event: OnEntityDeletedEvent) => void;
-    onEntityExpired?: (event: OnEntityExpiredEvent) => void;
-    onEntityExpiresInExtended?: (event: OnEntityExpiresInExtendedEvent) => void;
-  }, pollingInterval?: number, fromBlock?: bigint) => Promise<() => void>;
+  watchEntityEvents: (parameters: WatchEntityEventsParameters) => () => void;
+  /**
+   * The read-only half of the advanced path: check on a transaction and decode its result with at
+   * most one RPC call per action — so a process that holds nothing but a transaction hash can
+   * follow it without a wallet. {@link PublicAdvancedActions}
+   *
+   * @example
+   * const { status } = await client.advanced.pingTransaction(txHash) // 1 eth_getTransactionReceipt
+   */
+  advanced: PublicAdvancedActions;
 };
 //#endregion
 //#region src/clients/createPublicClient.d.ts
@@ -225,17 +370,18 @@ type PublicArkivClient<transport extends Transport = Transport, chain extends Ch
  *
  * - 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 [Braga JSON-RPC API](https://braga.holesky.arkiv.network/rpc) 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 "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).
  *
  * @param parameters - Configuration object for the public client (chain, transport, etc.)
  * @returns A Arkiv Public Client. {@link PublicArkivClient}
  *
  * @example
- * import { createPublicClient, http } from 'arkiv'
- * import { braga } from 'arkiv/chains'
+ * import { createPublicClient } from "@arkiv-network/sdk"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { http } from "viem"
  *
  * const client = createPublicClient({
- *   chain: braga,
+ *   chain: cheesecake,
  *   transport: http(),
  * })
  */
@@ -253,57 +399,64 @@ type WalletArkivActions<transport extends Transport = Transport, chain extends C
    * @param txParams - Optional transaction parameters
    * @returns The created entity with transaction hash
    *
-   * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-   * that is a multiple of the block time (2 seconds).
-   * @throws {InvalidAttributeError} If a numeric attribute value is not an
-   * integer.
+   * @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.
    *
    * @example
-   * import { createPublicClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
+   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
-   * const client = createPublicClient({
-   *   chain: braga,
+   * const client = createWalletClient({
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const { entityKey, txHash } = await client.createEntity({
-   *   payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-   *   attributes: [{ key: "testKey", value: "testValue" }],
-   *   expiresIn: 1000,
+   * 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),
    * })
-   * console.log("entityKey", entityKey)
-   * console.log("txHash", txHash)
-   * // {
-   * //   entityKey: "0x123",
-   * //   txHash: "0x123",
-   * // }
    */
   createEntity: (data: CreateEntityParameters, txParams?: TxParams) => Promise<CreateEntityReturnType>;
   /**
-   * Updates the entity with the given key.
+   * 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/updateEntity
+   * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/patchEntity
    * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
    *
-   * @param data - The entity update parameters
+   * @param data - The entity key and the mutations to apply
    * @param txParams - Optional transaction parameters
-   * @returns The updated entity with transaction hash
+   * @returns The entity key and the transaction hash
    *
-   * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-   * that is a multiple of the block time (2 seconds).
-   * @throws {InvalidAttributeError} If a numeric attribute value is not an
-   * integer.
+   * @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.
    *
    * @example
-   * import { createWalletClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createWalletClient, jsonToPayload } from "@arkiv-network/sdk"
+   * import { i32 } from "@arkiv-network/sdk/attr"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createWalletClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   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" }),
+   * })
    */
-  updateEntity: (data: UpdateEntityParameters, txParams?: TxParams) => Promise<UpdateEntityReturnType>;
+  patchEntity: (data: PatchEntityParameters, txParams?: TxParams) => Promise<PatchEntityReturnType>;
   /**
    * Deletes the entity with the given key.
    *
@@ -315,52 +468,48 @@ type WalletArkivActions<transport extends Transport = Transport, chain extends C
    * @returns The deleted entity with transaction hash
    *
    * @example
-   * import { createWalletClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createWalletClient } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createWalletClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const { entityKey, txHash } = await client.deleteEntity({ entityKey: "0x123" })
-   * console.log("entityKey", entityKey)
-   * console.log("txHash", txHash)
-   * // {
-   * //   entityKey: "0x123",
-   * //   txHash: "0x123",
-   * // }
+   * // entityKey is the bytes32 key returned by createEntity.
+   * const { txHash } = await client.deleteEntity({ entityKey })
    */
   deleteEntity: (data: DeleteEntityParameters, txParams?: TxParams) => Promise<DeleteEntityReturnType>;
   /**
-   * Extends the entity with the given key.
+   * Sets a new expiry on the entity with the given key.
+   *
+   * 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.
    *
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/extendEntity
    * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
    *
-   * @param data - The entity update parameters
+   * @param data - The entity key and its new lifetime
    * @param txParams - Optional transaction parameters
-   * @returns The updated entity with transaction hash
+   * @returns The entity key, transaction hash, and the block it is now expected to expire at
    *
-   * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-   * that is a multiple of the block time (2 seconds).
+   * @throws {InvalidExpiryError} If the expiry is malformed, exceeds a protocol bound, or would
+   * leave the entity dead on arrival.
    *
    * @example
-   * import { createWalletClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createWalletClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const { entityKey, txHash } = await client.extendEntity("0x123", {
-   *   expiresIn: 1000,
+   * const { txHash, expiresAt } = await client.extendEntity({
+   *   entityKey,
+   *   expires: ExpirationTime.fromDays(30),
    * })
-   * console.log("entityKey", entityKey)
-   * console.log("txHash", txHash)
-   * // {
-   * //   entityKey: "0x123",
-   * //   txHash: "0x123",
-   * // }
    */
   extendEntity: (data: ExtendEntityParameters, txParams?: TxParams) => Promise<ExtendEntityReturnType>;
   /**
@@ -380,100 +529,103 @@ type WalletArkivActions<transport extends Transport = Transport, chain extends C
    * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/mutateEntities
    * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
    *
-   * @param data - The mutation parameters (creates, updates, deletes, extensions)
+   * 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 txParams - Optional transaction parameters
    * @returns The mutation result with transaction hash
    *
-   * @throws {InvalidExpirationError} If any create/update/extension `expiresIn`
-   * is not a positive integer that is a multiple of the block time (2 seconds).
-   * @throws {InvalidAttributeError} If a numeric attribute value is not an
-   * integer.
+   * @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.
    *
    * @example
-   * import { createWalletClient, http } from 'arkiv'
-   * import { braga } from 'arkiv/chains'
+   * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
+   * import { cheesecake } from "@arkiv-network/sdk/chains"
+   * import { http } from "viem"
    *
    * const client = createWalletClient({
-   *   chain: braga,
+   *   chain: cheesecake,
    *   transport: http(),
    * })
-   * const { entityKey, txHash } = await client.mutateEntities({
+   * const { txHash, createdEntities } = await client.mutateEntities({
    *   creates: [{
-   *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-   *     attriubutes: [{ key: "testKey", value: "testValue" }],
-   *     expiresIn: 1000,
-   *   }],
-   *   updates: [{
-   *     entityKey: "0x123",
-   *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-   *     attributes: [{ key: "testKey", value: "testValue" }],
-   *     expiresIn: 1000,
-   *   }],
-   *   deletes: [{
-   *     entityKey: "0x321",
+   *     payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
+   *     contentType: "application/json",
+   *     attributes: { testKey: "testValue" },
+   *     expires: ExpirationTime.fromDays(30),
    *   }],
+   *   patches: [{ entityKey: keyToRevise, set: { status: "archived" }, unset: ["draft"] }],
+   *   deletes: [{ entityKey: staleKey }],
    *   extensions: [{
-   *     entityKey: "0x1234",
-   *     expiresIn: 1000,
+   *     entityKey: keyToKeepAlive,
+   *     expires: ExpirationTime.atBlock(1_200_000n),
    *   }],
+   *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
    * })
-   * console.log("entityKey", entityKey)
-   * console.log("txHash", txHash)
-   * // {
-   * //   entityKey: "0x123",
-   * //   txHash: "0x123",
-   * // }
    */
   mutateEntities: (data: MutateEntitiesParameters, 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;
 };
 //#endregion
 //#region src/clients/createWalletClient.d.ts
 type WalletArkivClient<transport extends Transport = Transport, chain extends Chain | undefined = Chain | undefined, account extends Account | undefined = Account | undefined, rpcSchema extends RpcSchema | undefined = ArkivRpcSchema> = Prettify<Client<transport, chain, account, rpcSchema, WalletArkivActions<transport, chain, account>>>;
 /**
- * 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 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/public
+ * - Docs: https://docs.arkiv.network/ts-sdk/clients/wallet
  *
- * 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 [Braga JSON-RPC API](https://braga.holesky.arkiv.network/rpc) methods such as retrieving block numbers, transactions, reading from smart contracts, etc through [Public Actions](/docs/actions/public/introduction).
+ * 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.
  *
  * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
  * @returns A Arkiv Wallet Client. {@link WalletArkivClient}
  *
  * @example
- * import { createPublicClient, http } from 'arkiv'
- * import { braga } from 'arkiv/chains'
+ * import { createWalletClient } from "@arkiv-network/sdk"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { http } from "viem"
+ * import { privateKeyToAccount } from "viem/accounts"
  *
- * const client = createPublicClient({
- *   chain: braga,
+ * const client = createWalletClient({
+ *   chain: cheesecake,
  *   transport: http(),
+ *   account: privateKeyToAccount("0x..."),
  * })
  */
 declare function createWalletClient<transport extends Transport, chain extends Chain | undefined = undefined, accountOrAddress extends Account | Address | undefined = undefined, rpcSchema extends RpcSchema | undefined = ArkivRpcSchema>(parameters: WalletClientConfig<transport, chain, accountOrAddress, rpcSchema>): WalletArkivClient<transport, chain, ParseAccount<accountOrAddress>, rpcSchema>;
 //#endregion
 //#region src/errors.d.ts
 declare class EntityMutationError extends Error {
-  constructor(message: string);
-}
-declare class InvalidExpirationError extends Error {
-  constructor(expiresIn: unknown);
-}
-declare class InvalidAttributeError extends Error {
-  constructor(key: string, value: number);
-}
-declare class InvalidAttributeKeyError extends Error {
-  constructor(key: string, reason: string);
-}
-declare class DuplicateAttributeError extends Error {
-  constructor(key: string);
+  constructor(message: string, options?: {
+    cause?: unknown;
+  });
 }
 declare class NoMoreResultsError extends Error {
   constructor();
 }
-declare class NoCursorOrLimitError extends Error {
-  constructor();
-}
 declare class NoEntityFoundError extends Error {
-  constructor();
+  /** The key that matched nothing, when the lookup was by key. */
+  readonly entityKey: string | undefined;
+  constructor(entityKey?: string);
+}
+declare class EmptyPatchError extends Error {
+  readonly entityKey: string;
+  constructor(entityKey: string);
 }
 declare class InvalidContentTypeError extends Error {
   constructor(contentType: string);
@@ -488,5 +640,5 @@ declare class InvalidContentTypeError extends Error {
  */
 declare function chainFromName(name: string): Chain;
 //#endregion
-export { type ArkivClient, ArkivRpcSchema, Attribute, ChangeOwnershipParameters, ChangeOwnershipReturnType, CreateEntityParameters, CreateEntityReturnType, DeleteEntityParameters, DeleteEntityReturnType, DuplicateAttributeError, Entity, EntityMutationError, EntityOperationType, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, InvalidAttributeError, InvalidAttributeKeyError, InvalidContentTypeError, InvalidExpirationError, MimeType, MutateEntitiesParameters, MutateEntitiesReturnType, NoCursorOrLimitError, NoEntityFoundError, NoMoreResultsError, OnEntityCreatedEvent, OnEntityDeletedEvent, OnEntityExpiredEvent, OnEntityExpiresInExtendedEvent, OnEntityOwnerChangedEvent, OnEntityUpdatedEvent, type PublicArkivActions, type PublicArkivClient, QueryOptions, QueryOptionsIncludeData, QueryOptionsOrderBy, QueryReturnType, RpcEntity, RpcIncludeData, RpcOrderByAttribute, RpcQueryOptions, TxParams, UpdateEntityParameters, UpdateEntityReturnType, type WalletArkivActions, type WalletArkivClient, chainFromName, createPublicClient, createWalletClient, jsonToPayload, stringToPayload };
+export { AddrValue, AnyArkivValue, type ArkivClient, ArkivRpcSchema, ArkivValue, AttributeInputs, AttributeSchema, Attributes, BoolValue, BuildMutationOptions, BuildMutationReturnType, Bytes32Value, BytesValue, ChangeOwnershipParameters, ChangeOwnershipReturnType, ConflictingMutationError, CreateEntityParameters, CreateEntityReturnType, CreationFlags, DECIMAL_SCALE, DECIMAL_UNIT, type DeadlineOptions, DecValue, DeleteEntityParameters, DeleteEntityReturnType, ENTITY_EVENTS_ABI, EmptyPatchError, EncodedExpiry, Entity, EntityCreatedEvent, EntityDeletedEvent, EntityEvent, EntityEventContext, EntityEventName, EntityFields, EntityMutationError, type EntityMutationOps, EntityPatchedEvent, ExpirationTime, Expiry, ExpiryContext, ExpiryExtendedEvent, ExtendEntityParameters, ExtendEntityReturnType, GetBlockTimingReturnType, GetMutationResultReturnType, I32Value, I32_MAX, I32_MIN, InvalidAttributeNameError, InvalidContentTypeError, InvalidCreationFlagsError, InvalidExpiryError, InvalidSaltError, InvalidValueError, KeyValue, Lifetime, MAX_ATTRIBUTES, MAX_EXPIRES_AT, MAX_NAME_BYTES, MAX_PAYLOAD_BYTES, MAX_SALT, MAX_STRING_BYTES, MimeType, MissingValueError, MutateEntitiesParameters, MutateEntitiesReturnType, type MutationEvents, MutationResult, NoEntityFoundError, NoMoreResultsError, NoRandomSourceError, Operation, OperationType, OwnershipTransferredEvent, PatchEntityParameters, PatchEntityReturnType, PingTransactionReturnType, PredictEntityKeysParameters, PredictEntityKeysReturnType, PredictedEntityKey, type PublicAdvancedActions, type PublicArkivActions, type PublicArkivClient, QueryOptions, QueryReturnType, ResolvedCreationFlags, ResolvedExpiry, RpcAttribute, RpcAttributeSchemaEntry, RpcCreationFlags, RpcEntity, RpcQueryOptions, RpcSelect, SendMutationOptions, SendMutationReturnType, StrValue, TooManyAttributesError, TxParams, TypeTag, U256Value, U256_MAX, U64Value, U64_MAX, UnknownAttributeTypeError, UntypedValueError, UserTypeTag, ValueInput, type WalletAdvancedActions, type WalletArkivActions, type WalletArkivClient, WatchEntityEventsParameters, addr, bool, buildEntityOperations, buildMutation, bytes32, chainFromName, collectMutationEvents, createPublicClient, createWalletClient, dec, decFromUnits, decUnits, decodeCreationFlags, decodeMutationResult, encodeCreationFlags, getMutationResult, i32, isArkivValue, isValidAttributeName, jsonToPayload, key, mutationNeedsBlockNumber, pingTransaction, predictEntityKey, randomSalt, resolveExpiry, sendMutation, str, stringToPayload, toBlocks, toValue, u256, u64, validateAttributeName };
 //# sourceMappingURL=index.d.ts.map