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

package/dist/index.js

@@ -1,10 +1,19 @@
-import { t as chains_exports } from "./chains-CrtkVbBh.js";
-import { S as getLogger, _ as InvalidContentTypeError, b as NoEntityFoundError, c as isEntityKey, d as entityFromRpcResult, f as RpcAttributeValueType, g as InvalidAttributeKeyError, h as InvalidAttributeError, l as validateAttribute, m as EntityMutationError, n as QueryBuilder, p as DuplicateAttributeError, r as SelectQueryBuilder, u as validateExpiresIn, v as InvalidExpirationError, x as NoMoreResultsError, y as NoCursorOrLimitError } from "./queryBuilder-BE_XhLLa.js";
-import { n as BLOCK_TIME, t as ARKIV_ADDRESS } from "./consts-Bz0LZQZY.js";
-import { n as EntityOperationType } from "./entity-DGfVyB-a.js";
-import "./types-Ci4BRClw.js";
-import { n as stringToPayload, t as jsonToPayload } from "./payload-BpNUPOnY.js";
-import { ContractFunctionExecutionError, ContractFunctionRevertedError, TransactionExecutionError, bytesToHex, createClient, decodeEventLog, encodePacked, hexToBytes, keccak256, numberToHex, parseAbi, publicActions, stringToBytes, toBytes, toHex, walletActions } from "viem";
+import { t as chains_exports } from "./chains-BJrZs6sG.js";
+import { a as OperationType, i as MAX_EXPIRES_AT, n as resolveExpiry, o as ARKIV_ADDRESS, r as toBlocks, s as BLOCK_TIME } from "./expiry-BjpxZZQU.js";
+import { a as buildMutation, c as mutationNeedsBlockNumber, i as getMutationResult, l as sendArkivTransaction, n as pingTransaction, o as buildEntityOperations, r as decodeMutationResult, s as collectMutationEvents, t as sendMutation, u as ENTITY_NONCE_ABI } from "./advanced-8ZPTmmaN.js";
+import { A as DECIMAL_UNIT, C as str, E as u64, F as TooManyAttributesError, I as UnknownAttributeTypeError, L as UntypedValueError, M as InvalidAttributeNameError, N as InvalidValueError, O as isArkivValue, P as MissingValueError, S as key, T as u256, _ as bytes32, a as MAX_NAME_BYTES, b as decUnits, d as I32_MIN, f as MAX_STRING_BYTES, g as bool, h as addr, j as ConflictingMutationError, k as DECIMAL_SCALE, m as U64_MAX, n as MAX_PAYLOAD_BYTES, o as isValidAttributeName, p as U256_MAX, s as validateAttributeName, t as MAX_ATTRIBUTES, u as I32_MAX, v as dec, w as toValue, x as i32, y as decFromUnits } from "./attributes-BhY5DwJp.js";
+import { a as ENTITY_EVENTS_ABI, i as validateSalt, n as predictEntityKey, r as randomSalt, t as MAX_SALT } from "./key-D1Bh7MF0.js";
+import { i as NoRandomSourceError, n as InvalidExpiryError, r as InvalidSaltError, t as InvalidCreationFlagsError } from "./errors-LTe7bOYS.js";
+import { n as encodeCreationFlags, t as decodeCreationFlags } from "./flags-DFBs2J94.js";
+import { a as NoEntityFoundError, i as InvalidContentTypeError, n as EmptyPatchError, o as NoMoreResultsError, r as EntityMutationError, t as getLogger } from "./logger-CVpvU8ik.js";
+import "./attr-GcQKatub.js";
+import { t as Entity } from "./entity-BYQR1uoe.js";
+import { a as eq, r as toRpcSelect, t as SelectQueryBuilder, v as runQuery } from "./queryBuilder-DM6AWCBa.js";
+import "./entity-CD_qFF2M.js";
+import "./types-Bu_ZwMbZ.js";
+import { n as stringToPayload, r as ExpirationTime, t as jsonToPayload } from "./payload-Bz6651ax.js";
+import { createClient, decodeEventLog, publicActions, walletActions } from "viem";
+import { getChainId, readContract } from "viem/actions";
 
 //#region src/actions/public/getBlockTiming.ts
 const logger$8 = getLogger("actions:public:get-block-timing");
@@ -23,33 +32,26 @@ async function getBlockTiming(client) {
 
 //#endregion
 //#region src/actions/public/getEntity.ts
-async function getEntity(client, key) {
-	let bytes;
-	try {
-		bytes = hexToBytes(key);
-	} catch {
-		throw new Error(`Invalid key format: ${key}. Key must be a valid hex string.`);
-	}
-	if (bytes.length !== 32) throw new Error(`Invalid key length: ${bytes.length} bytes. Key must be 32 bytes (64 hex characters) long.`);
-	const hexKey = bytesToHex(bytes);
-	const result = await client.request({
-		method: "arkiv_query",
-		params: [`$key = ${hexKey}`, { includeData: {
-			key: true,
-			attributes: true,
-			payload: true,
-			contentType: true,
-			expiration: true,
-			owner: true,
-			creator: true,
-			createdAtBlock: true,
-			lastModifiedAtBlock: true,
-			transactionIndexInBlock: true,
-			operationIndexInTransaction: true
-		} }]
+/**
+* Reads one entity by key, with every field selected.
+*
+* Returns a {@link FullEntity} rather than an {@link Entity}: the selection is fixed at `"*"`, so
+* every field is populated and none of them needs a `?` at the call site. The bare `Entity` type
+* has every field optional because a `select()` result carries only what it asked for.
+*
+* @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.
+*/
+async function getEntity(client, entityKey) {
+	const { entities } = await runQuery(client, {
+		query: eq("$key", key(entityKey)).toString(),
+		select: toRpcSelect("*"),
+		limit: 1
 	});
-	if (!result.data.length) throw new NoEntityFoundError();
-	return await entityFromRpcResult(result.data[0]);
+	const entity = entities[0];
+	if (entity === void 0) throw new NoEntityFoundError(entityKey);
+	return entity;
 }
 
 //#endregion
@@ -62,355 +64,294 @@ async function getEntityCount(client) {
 }
 
 //#endregion
-//#region src/actions/public/query.ts
-async function query(client, query$1, queryOptions) {
-	const rpcQueryOptions = {
-		includeData: {
-			key: true,
-			payload: queryOptions?.includeData?.payload ?? true,
-			attributes: queryOptions?.includeData?.attributes ?? false,
-			contentType: queryOptions?.includeData?.metadata ?? false,
-			expiration: queryOptions?.includeData?.metadata ?? false,
-			owner: queryOptions?.includeData?.metadata ?? false,
-			creator: queryOptions?.includeData?.metadata ?? false,
-			createdAtBlock: queryOptions?.includeData?.metadata ?? false,
-			lastModifiedAtBlock: queryOptions?.includeData?.metadata ?? false,
-			transactionIndexInBlock: queryOptions?.includeData?.metadata ?? false,
-			operationIndexInTransaction: queryOptions?.includeData?.metadata ?? false
-		},
-		...queryOptions?.atBlock !== void 0 && { atBlock: numberToHex(queryOptions.atBlock) },
-		...queryOptions?.orderBy && { orderBy: queryOptions?.orderBy.map((order) => ({
-			name: order.name,
-			type: order.type,
-			desc: order.desc === "desc"
-		})) },
-		...queryOptions?.resultsPerPage !== void 0 && { resultsPerPage: numberToHex(queryOptions.resultsPerPage) },
-		...queryOptions?.cursor !== void 0 && { cursor: queryOptions?.cursor }
-	};
-	const result = await client.request({
-		method: "arkiv_query",
-		params: [query$1, rpcQueryOptions]
+//#region src/actions/public/getEntityNonce.ts
+const logger$7 = getLogger("actions:public:get-entity-nonce");
+/**
+* Reads an owner's entity-minting nonce — how many entities that account has created.
+*
+* This is not the account's transaction nonce. The engine keeps a separate counter per creator and
+* mixes it into every key it mints, which is what makes two identical creates from one account land
+* on different keys.
+*
+* @param owner - The account whose nonce to read.
+* @returns The number of entities `owner` has created so far, which is the nonce its next create
+* will use.
+*/
+async function getEntityNonce(client, owner) {
+	const nonce = await readContract(client, {
+		address: ARKIV_ADDRESS,
+		abi: ENTITY_NONCE_ABI,
+		functionName: "entityNonce",
+		args: [owner]
 	});
-	return {
-		entities: await Promise.all(result.data.map((entity) => entityFromRpcResult(entity))),
-		cursor: result.cursor,
-		blockNumber: BigInt(result.blockNumber)
-	};
+	logger$7("entity nonce of %s is %s", owner, nonce);
+	return nonce;
 }
 
 //#endregion
-//#region src/utils/arkivTransactions.ts
-const logger$7 = getLogger("utils:arkiv-transactions");
-const MIME_REGEX = /^[a-z][a-z0-9!#$&\-^_]*\/[a-z0-9][a-z0-9!#$&\-^_.+]*$/;
-function validateContentType(contentType) {
-	if (!MIME_REGEX.test(contentType)) throw new InvalidContentTypeError(contentType);
-}
-const ENTITY_EXECUTE_ABI = parseAbi(["function execute((uint8 operationType, bytes32 entityKey, bytes payload, (bytes32[4] data) contentType, (bytes32 name, uint8 valueType, bytes32[4] value)[] attributes, uint32 expiresIn, address newOwner)[] ops) external"]);
-const ENTITY_OPERATION_EVENT_ABI = parseAbi(["event EntityOperation(bytes32 indexed entityKey, uint8 indexed operationType, address indexed owner, uint32 expiresAt, bytes32 entityHash)"]);
-const ENTITY_ERRORS_ABI = parseAbi([
-	"error EmptyBatch()",
-	"error AttributesNotSorted()",
-	"error InvalidValueType(bytes32 name, uint8 valueType)",
-	"error InvalidOpType(uint8 operationType)",
-	"error ExpiryInPast(uint32 expiresAt, uint32 currentBlock)",
-	"error TooManyAttributes(uint256 count, uint256 maxCount)",
-	"error EntityNotFound(bytes32 entityKey)",
-	"error NotOwner(bytes32 entityKey, address caller, address owner)",
-	"error EntityExpired(bytes32 entityKey, uint32 expiresAt)",
-	"error ExpiryNotExtended(bytes32 entityKey, uint32 newExpiresAt, uint32 currentExpiresAt)",
-	"error TransferToZeroAddress(bytes32 entityKey)",
-	"error TransferToSelf(bytes32 entityKey)",
-	"error EntityNotExpired(bytes32 entityKey, uint32 expiresAt)",
-	"error Ident32Empty()",
-	"error Ident32TooLong(uint256 length)",
-	"error Ident32InvalidByte(uint256 position, bytes1 value)",
-	"error MimeEmpty()",
-	"error MimeTooLong(uint256 length, uint256 maxLength)",
-	"error MimeInvalidByte(uint256 position, bytes1 value)",
-	"error MimeIncomplete()"
-]);
-const EXECUTE_ABI = [...ENTITY_EXECUTE_ABI, ...ENTITY_ERRORS_ABI];
-const ENTITY_NONCE_ABI = parseAbi(["function nonces(address owner) view returns (uint32)"]);
-const ZERO_ADDRESS = "0x0000000000000000000000000000000000000000";
-const ZERO_32 = `0x${"00".repeat(32)}`;
-const EMPTY_BYTES128 = [
-	ZERO_32,
-	ZERO_32,
-	ZERO_32,
-	ZERO_32
-];
-function encodeBytes128(data) {
-	const padded = new Uint8Array(128);
-	padded.set(data.slice(0, 128));
-	return [
-		toHex(padded.slice(0, 32)),
-		toHex(padded.slice(32, 64)),
-		toHex(padded.slice(64, 96)),
-		toHex(padded.slice(96, 128))
-	];
-}
-function encodeMime128(contentType) {
-	return { data: contentType ? encodeBytes128(stringToBytes(contentType)) : EMPTY_BYTES128 };
+//#region src/actions/public/predictEntityKeys.ts
+/**
+* Works out the keys an account's next creates will be given, before sending them.
+*
+* A key is `keccak256(chainId ++ registry ++ owner ++ nonce ++ salt)`. Everything but the nonce is
+* known to the caller, and the nonce is read here — so a batch can reference a key it is about to
+* mint, storing it as a `key` attribute on a sibling entity created in the same transaction.
+*
+* Each key arrives paired with its salt, and the create must be given that salt: a create left to
+* pick its own salt picks a random one, which mints a different key.
+*
+* The prediction is valid only while nothing else from this owner is in flight. Every create that
+* lands first takes the nonce with it and moves these keys. For a key you can rely on
+* unconditionally, read it back from the create instead — `createEntity` and `mutateEntities`
+* report the keys the engine actually minted.
+*
+* @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) },
+*     },
+*   ],
+* })
+*/
+async function predictEntityKeys(client, { owner, count, salts }) {
+	const resolvedSalts = resolveSalts(count, salts);
+	const chainId = client.chain?.id ?? await getChainId(client);
+	const nonce = await getEntityNonce(client, owner);
+	return resolvedSalts.map((salt, index) => ({
+		key: predictEntityKey({
+			owner,
+			nonce: nonce + BigInt(index),
+			salt,
+			chainId
+		}),
+		salt
+	}));
 }
-function encodeAttribute(attr) {
-	validateAttribute(attr);
-	const name = toHex(attr.key, { size: 32 });
-	if (typeof attr.value === "string") {
-		if (isEntityKey(attr.value)) return {
-			name,
-			valueType: RpcAttributeValueType.EntityKey,
-			value: [
-				toHex(toBytes(attr.value), { size: 32 }),
-				ZERO_32,
-				ZERO_32,
-				ZERO_32
-			]
-		};
-		return {
-			name,
-			valueType: RpcAttributeValueType.String,
-			value: encodeBytes128(stringToBytes(attr.value))
-		};
+/** The salts to derive from: the ones given, or `count` fresh random ones. */
+function resolveSalts(count, salts) {
+	if (salts !== void 0) {
+		if (salts.length === 0) throw new Error("predictEntityKeys: `salts` is empty — there is nothing to predict");
+		return salts.map(validateSalt);
 	}
-	return {
-		name,
-		valueType: RpcAttributeValueType.Uint,
-		value: [
-			toHex(BigInt(attr.value), { size: 32 }),
-			ZERO_32,
-			ZERO_32,
-			ZERO_32
-		]
-	};
-}
-function encodeAttributes(attrs) {
-	const encoded = attrs.map((attr) => ({
-		key: attr.key,
-		...encodeAttribute(attr)
-	})).sort((a, b) => a.name < b.name ? -1 : a.name > b.name ? 1 : 0);
-	for (let i = 1; i < encoded.length; i++) if (encoded[i].name === encoded[i - 1].name) throw new DuplicateAttributeError(encoded[i].key);
-	return encoded.map(({ key: _,...attr }) => attr);
+	if (count === void 0) throw new Error("predictEntityKeys: pass either `count` or `salts`");
+	if (!Number.isInteger(count) || count <= 0) throw new Error(`predictEntityKeys: \`count\` must be a positive whole number, got ${count}`);
+	return Array.from({ length: count }, () => randomSalt());
 }
-function toBTL(expiresIn) {
-	validateExpiresIn(expiresIn);
-	return Math.ceil(expiresIn / BLOCK_TIME);
-}
-function deriveEntityKey(chainId, owner, nonce) {
-	return keccak256(encodePacked([
-		"uint256",
-		"address",
-		"address",
-		"uint32"
-	], [
-		BigInt(chainId),
-		ARKIV_ADDRESS,
-		owner,
-		Number(nonce)
-	]));
-}
-async function sendArkivTransaction(client, ops, txParams) {
-	if (!client.account) throw new Error("Account required");
-	if (!client.chain) throw new Error("Chain required");
-	const walletClient = client;
-	const { creates, updates, deletes, extensions, ownershipChanges } = ops;
-	const owner = client.account.address;
-	const ownerNonce = creates?.length ? BigInt(await walletClient.readContract({
-		address: ARKIV_ADDRESS,
-		abi: ENTITY_NONCE_ABI,
-		functionName: "nonces",
-		args: [owner]
-	})) : 0n;
-	const createdEntityKeys = (creates ?? []).map((_, i) => deriveEntityKey(client.chain.id, owner, ownerNonce + BigInt(i)));
-	for (const item of creates ?? []) validateContentType(item.contentType);
-	for (const item of updates ?? []) validateContentType(item.contentType);
-	const operations = [
-		...(creates ?? []).map((item, i) => ({
-			operationType: EntityOperationType.Create,
-			entityKey: createdEntityKeys[i],
-			payload: toHex(item.payload),
-			contentType: encodeMime128(item.contentType),
-			attributes: encodeAttributes(item.attributes),
-			expiresIn: toBTL(item.expiresIn),
-			newOwner: ZERO_ADDRESS
-		})),
-		...(updates ?? []).map((item) => ({
-			operationType: EntityOperationType.Update,
-			entityKey: item.entityKey,
-			payload: toHex(item.payload),
-			contentType: encodeMime128(item.contentType),
-			attributes: encodeAttributes(item.attributes),
-			expiresIn: 0,
-			newOwner: ZERO_ADDRESS
-		})),
-		...(deletes ?? []).map((item) => ({
-			operationType: EntityOperationType.Delete,
-			entityKey: item.entityKey,
-			payload: "0x",
-			contentType: encodeMime128(""),
-			attributes: [],
-			expiresIn: 0,
-			newOwner: ZERO_ADDRESS
-		})),
-		...(extensions ?? []).map((item) => ({
-			operationType: EntityOperationType.Extend,
-			entityKey: item.entityKey,
-			payload: "0x",
-			contentType: encodeMime128(""),
-			attributes: [],
-			expiresIn: toBTL(item.expiresIn),
-			newOwner: ZERO_ADDRESS
-		})),
-		...(ownershipChanges ?? []).map((item) => ({
-			operationType: EntityOperationType.Transfer,
-			entityKey: item.entityKey,
-			payload: "0x",
-			contentType: encodeMime128(""),
-			attributes: [],
-			expiresIn: 0,
-			newOwner: item.newOwner
-		}))
-	];
-	logger$7("Sending execute with %d operations %s", operations.length, JSON.stringify(operations));
-	try {
-		const txHash = await walletClient.writeContract({
-			address: ARKIV_ADDRESS,
-			abi: EXECUTE_ABI,
-			functionName: "execute",
-			args: [operations],
-			account: client.account,
-			chain: client.chain,
-			...txParams
-		});
-		const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash });
-		logger$7("Tx receipt %o", receipt);
-		if (receipt.status === "reverted") {
-			try {
-				await walletClient.simulateContract({
-					address: ARKIV_ADDRESS,
-					abi: EXECUTE_ABI,
-					functionName: "execute",
-					args: [operations],
-					account: client.account,
-					chain: client.chain
-				});
-			} catch (err) {
-				const error = err;
-				const reason = error.shortMessage ?? error.cause?.details ?? "No reason provided by backend.";
-				throw new EntityMutationError(`Transaction ${receipt.transactionHash} reverted. Reason: ${reason}`);
-			}
-			throw new EntityMutationError(`Transaction ${receipt.transactionHash} reverted. No reason provided by backend.`);
-		}
-		return {
-			receipt,
-			createdEntityKeys
-		};
-	} catch (error) {
-		let message = "Transaction failed";
-		if (error instanceof TransactionExecutionError) message += `: ${error.details}`;
-		else if (error instanceof ContractFunctionExecutionError) {
-			logger$7("Contract function execution error data:", error.shortMessage);
-			if (error.cause instanceof ContractFunctionRevertedError) message += `: ${error.cause.message}`;
-			else message += ": Execution error without revert data";
-		} else if (error instanceof EntityMutationError) throw error;
-		throw new EntityMutationError(message);
-	}
+
+//#endregion
+//#region src/actions/public/query.ts
+/**
+* Runs a single query and returns one page, with no builder in between.
+*
+* Takes either an {@link Expression} or a raw query string. The string form is an escape hatch for
+* a query built elsewhere — it goes to the node exactly as written, with none of the name, type or
+* operator checks the expression combinators apply.
+*
+* @throws {QueryError} If the node rejects the query.
+*/
+function query(client, query$1, options = {}) {
+	return runQuery(client, {
+		query: query$1.toString(),
+		select: toRpcSelect(options.select),
+		limit: options.limit,
+		cursor: options.cursor,
+		atBlock: options.atBlock
+	});
 }
 
 //#endregion
-//#region src/actions/public/subscribeEntityEvents.ts
-const logger$6 = getLogger("actions:public:subscribe-entity-events");
-const arkivABI = ENTITY_OPERATION_EVENT_ABI;
-async function subscribeEntityEvents(client, { onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpired, onEntityExpiresInExtended, onEntityOwnerChanged }, pollingInterval, fromBlock) {
-	return client.watchEvent({
-		pollingInterval: pollingInterval ?? 1e3,
-		fromBlock,
-		events: arkivABI,
+//#region src/actions/public/watchEntityEvents.ts
+const logger$6 = getLogger("actions:public:watch-entity-events");
+/**
+* How often to poll, when the caller does not say.
+*
+* Half a block: fast enough that an event is never a whole block stale, slow enough not to hammer
+* the node. viem's own default is derived from a 12-second Ethereum block and is far too slow here.
+*/
+const DEFAULT_POLLING_INTERVAL = BLOCK_TIME * 1e3 / 2;
+/**
+* Watches entity events, calling the handlers you pass as they arrive.
+*
+* Every event here is decoded from a log the Arkiv operation address emitted, and carries the
+* block, transaction and log index it came from — so consuming them in order replays exactly what
+* the engine did.
+*
+* @param parameters - Handlers and options. {@link WatchEntityEventsParameters}
+* @returns A function that stops the watcher.
+*
+*
+* @example
+* import { createPublicClient } from "@arkiv-network/sdk"
+* import { cheesecake } from "@arkiv-network/sdk/chains"
+* import { http } from "viem"
+*
+* const client = createPublicClient({ chain: cheesecake, transport: http() })
+*
+* const unwatch = client.watchEntityEvents({
+*   onEntityCreated: ({ entityKey, owner, expiresAt }) =>
+*     console.log("created", entityKey, "by", owner, "until block", expiresAt),
+*   onEntityDeleted: ({ entityKey }) => console.log("deleted", entityKey),
+*   onError: (error) => console.error(error),
+* })
+*
+* unwatch()
+*/
+function watchEntityEvents(client, parameters) {
+	const { onEntityCreated, onEntityPatched, onExpiryExtended, onOwnershipTransferred, onEntityDeleted, onEvent, onError, fromBlock, pollingInterval = DEFAULT_POLLING_INTERVAL } = parameters;
+	const publicClient = client;
+	const reportError = onError ?? logToConsole;
+	function emit(event) {
+		deliver(onEvent, event);
+		switch (event.type) {
+			case "EntityCreated":
+				deliver(onEntityCreated, event);
+				break;
+			case "EntityPatched":
+				deliver(onEntityPatched, event);
+				break;
+			case "ExpiryExtended":
+				deliver(onExpiryExtended, event);
+				break;
+			case "OwnershipTransferred":
+				deliver(onOwnershipTransferred, event);
+				break;
+			case "EntityDeleted":
+				deliver(onEntityDeleted, event);
+				break;
+		}
+	}
+	/**
+	* Runs one handler, keeping its failure to itself.
+	*
+	* A handler that throws is the consumer's problem, not the watcher's: letting it escape would
+	* reject the poll, drop the rest of the batch, and take down every other handler with it.
+	*/
+	function deliver(handler, event) {
+		if (handler === void 0) return;
+		try {
+			handler(event);
+		} catch (error) {
+			reportError(asError(error));
+		}
+	}
+	return publicClient.watchEvent({
+		address: ARKIV_ADDRESS,
+		events: ENTITY_EVENTS_ABI,
+		pollingInterval,
+		...fromBlock !== void 0 && { fromBlock },
 		onLogs: (logs) => {
-			logger$6("logs from subscribeEntityEvents %o", logs);
+			logger$6("logs %o", logs);
 			for (const log of logs) {
-				const event = decodeEventLog({
-					abi: arkivABI,
-					topics: log.topics,
-					data: log.data
-				});
-				logger$6("event from subscribeEntityEvents %o", event);
-				if (event.eventName !== "EntityOperation") continue;
-				const entityKey = event.args.entityKey;
-				const owner = event.args.owner;
-				const expiresAt = event.args.expiresAt;
-				const entityHash = event.args.entityHash;
-				switch (Number(event.args.operationType)) {
-					case EntityOperationType.Create:
-						onEntityCreated?.({
-							entityKey,
-							owner,
-							expiresAt,
-							entityHash
-						});
-						break;
-					case EntityOperationType.Update:
-						onEntityUpdated?.({
-							entityKey,
-							owner,
-							expiresAt,
-							entityHash
-						});
-						break;
-					case EntityOperationType.Extend:
-						onEntityExpiresInExtended?.({
-							entityKey,
-							owner,
-							expiresAt,
-							entityHash
-						});
-						break;
-					case EntityOperationType.Transfer:
-						onEntityOwnerChanged?.({
-							entityKey,
-							owner,
-							entityHash
-						});
-						break;
-					case EntityOperationType.Delete:
-						onEntityDeleted?.({
-							entityKey,
-							owner
-						});
-						break;
-					default:
-						onEntityExpired?.({
-							entityKey,
-							owner
-						});
-						break;
+				if (log.blockNumber === null || log.transactionHash === null || log.logIndex === null) continue;
+				const context = {
+					blockNumber: log.blockNumber,
+					transactionHash: log.transactionHash,
+					logIndex: log.logIndex
+				};
+				let event;
+				try {
+					event = toEntityEvent(log.topics, log.data, context);
+				} catch (error) {
+					reportError(asError(error));
+					continue;
 				}
+				emit(event);
 			}
 		},
-		onError: (error) => {
-			console.error("error from subscribeEntityEvents", error);
-			onError?.(error);
-		}
+		onError: (error) => reportError(error)
 	});
 }
+/** The fallback when no `onError` was given — see {@link WatchEntityEventsParameters.onError}. */
+function logToConsole(error) {
+	console.error("watchEntityEvents error", error);
+}
+/** Handlers take an `Error`, and a `throw` can be anything. */
+function asError(error) {
+	return error instanceof Error ? error : new Error(String(error));
+}
+/**
+* Decodes one log into the {@link EntityEvent} it carries.
+*
+* @throws If the log does not decode against {@link ENTITY_EVENTS_ABI}.
+*/
+function toEntityEvent(topics, data, context) {
+	const decoded = decodeEventLog({
+		abi: ENTITY_EVENTS_ABI,
+		topics,
+		data
+	});
+	switch (decoded.eventName) {
+		case "EntityCreated": return {
+			type: "EntityCreated",
+			...context,
+			...decoded.args,
+			creationFlags: decodeCreationFlags(decoded.args.creationFlags)
+		};
+		case "EntityPatched": return {
+			type: "EntityPatched",
+			...context,
+			...decoded.args
+		};
+		case "ExpiryExtended": return {
+			type: "ExpiryExtended",
+			...context,
+			...decoded.args
+		};
+		case "OwnershipTransferred": return {
+			type: "OwnershipTransferred",
+			...context,
+			...decoded.args
+		};
+		case "EntityDeleted": return {
+			type: "EntityDeleted",
+			...context,
+			...decoded.args
+		};
+	}
+}
+
+//#endregion
+//#region src/clients/decorators/arkivAdvanced.ts
+function publicAdvancedActions(client) {
+	return {
+		pingTransaction: (txHash) => pingTransaction(client, txHash),
+		getMutationResult: (txHash) => getMutationResult(client, txHash),
+		decodeMutationResult: (receipt) => decodeMutationResult(receipt)
+	};
+}
+function walletAdvancedActions(client) {
+	return {
+		...publicAdvancedActions(client),
+		buildMutation: (data, options) => buildMutation(client, data, options),
+		sendMutation: (data, options) => sendMutation(client, data, options)
+	};
+}
 
 //#endregion
 //#region src/clients/decorators/arkivPublic.ts
 function publicArkivActions(client) {
 	return {
-		getEntity: (key) => getEntity(client, key),
+		getEntity: (key$1) => getEntity(client, key$1),
 		query: (rawQuery, queryOptions) => query(client, rawQuery, queryOptions),
-		buildQuery: () => new QueryBuilder(client),
 		select: (selection) => new SelectQueryBuilder(client, selection),
 		getBlockTiming: () => getBlockTiming(client),
 		getEntityCount: () => getEntityCount(client),
-		subscribeEntityEvents: ({ onError, onEntityCreated, onEntityUpdated, onEntityDeleted, onEntityExpired, onEntityExpiresInExtended }, pollingInterval, fromBlock) => subscribeEntityEvents(client, {
-			onError,
-			onEntityCreated,
-			onEntityUpdated,
-			onEntityDeleted,
-			onEntityExpired,
-			onEntityExpiresInExtended
-		}, pollingInterval, fromBlock)
+		getEntityNonce: (owner) => getEntityNonce(client, owner),
+		predictEntityKeys: (parameters) => predictEntityKeys(client, parameters),
+		watchEntityEvents: (parameters) => watchEntityEvents(client, parameters),
+		advanced: publicAdvancedActions(client)
 	};
 }
 
@@ -421,25 +362,26 @@ function publicArkivActions(client) {
 *
 * - 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(),
 * })
 */
 function createPublicClient(parameters) {
-	const { key = "public", name = "Public Client" } = parameters;
+	const { key: key$1 = "public", name = "Public Client" } = parameters;
 	return createClient({
 		...parameters,
-		key,
+		key: key$1,
 		name
 	}).extend(publicActions).extend(publicArkivActions);
 }
@@ -462,11 +404,15 @@ async function changeOwnership(client, data, txParams) {
 const logger$4 = getLogger("actions:wallet:create-entity");
 async function createEntity(client, data, txParams) {
 	logger$4("createEntity %o", data);
-	const { receipt, createdEntityKeys } = await sendArkivTransaction(client, { creates: [data] }, txParams);
+	const { receipt, createdEntityKeys, createdExpiries } = await sendArkivTransaction(client, { creates: [data] }, txParams);
 	logger$4("Receipt from createEntity %o", receipt);
+	const [entityKey] = createdEntityKeys;
+	const [expiresAt] = createdExpiries;
+	if (entityKey === void 0 || expiresAt === void 0) throw new EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity key or expiry.`);
 	return {
 		txHash: receipt.transactionHash,
-		entityKey: createdEntityKeys[0]
+		entityKey,
+		expiresAt
 	};
 }
 
@@ -488,11 +434,14 @@ async function deleteEntity(client, data, txParams) {
 const logger$2 = getLogger("actions:wallet:extend-entity");
 async function extendEntity(client, data, txParams) {
 	logger$2("extendEntity %o", data);
-	const { receipt } = await sendArkivTransaction(client, { extensions: [data] }, txParams);
+	const { receipt, extendedExpiries } = await sendArkivTransaction(client, { extensions: [data] }, txParams);
 	logger$2("Receipt from extendEntity %o", receipt);
+	const [expiresAt] = extendedExpiries;
+	if (expiresAt === void 0) throw new EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity expiry.`);
 	return {
 		txHash: receipt.transactionHash,
-		entityKey: data.entityKey
+		entityKey: data.entityKey,
+		expiresAt
 	};
 }
 
@@ -500,13 +449,12 @@ async function extendEntity(client, data, txParams) {
 //#region src/actions/wallet/mutateEntities.ts
 const logger$1 = getLogger("actions:wallet:mutate-entities");
 async function mutateEntities(client, data, txParams) {
-	if (!data.creates && !data.updates && !data.deletes && !data.extensions) throw new Error("No operations to perform");
 	const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams);
 	logger$1("Receipt from mutateEntities %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
 		createdEntities: createdEntityKeys,
-		updatedEntities: (data.updates ?? []).map((u) => u.entityKey),
+		patchedEntities: (data.patches ?? []).map((p) => p.entityKey),
 		deletedEntities: (data.deletes ?? []).map((d) => d.entityKey),
 		extendedEntities: (data.extensions ?? []).map((e) => e.entityKey),
 		ownershipChanges: (data.ownershipChanges ?? []).map((o) => o.entityKey)
@@ -514,12 +462,12 @@ async function mutateEntities(client, data, txParams) {
 }
 
 //#endregion
-//#region src/actions/wallet/updateEntity.ts
-const logger = getLogger("actions:wallet:update-entity");
-async function updateEntity(client, data, txParams) {
-	logger("updateEntity %o", data);
-	const { receipt } = await sendArkivTransaction(client, { updates: [data] }, txParams);
-	logger("Receipt from updateEntity %o", receipt);
+//#region src/actions/wallet/patchEntity.ts
+const logger = getLogger("actions:wallet:patch-entity");
+async function patchEntity(client, data, txParams) {
+	logger("patchEntity %o", data);
+	const { receipt } = await sendArkivTransaction(client, { patches: [data] }, txParams);
+	logger("Receipt from patchEntity %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
 		entityKey: data.entityKey
@@ -531,47 +479,54 @@ async function updateEntity(client, data, txParams) {
 function walletArkivActions(client) {
 	return {
 		createEntity: (data, txParams) => createEntity(client, data, txParams),
-		updateEntity: (data, txParams) => updateEntity(client, data, txParams),
+		patchEntity: (data, txParams) => patchEntity(client, data, txParams),
 		deleteEntity: (data, txParams) => deleteEntity(client, data, txParams),
 		extendEntity: (data, txParams) => extendEntity(client, data, txParams),
 		changeOwnership: (data, txParams) => changeOwnership(client, data, txParams),
-		mutateEntities: (data, txParams) => mutateEntities(client, data, txParams)
+		mutateEntities: (data, txParams) => mutateEntities(client, data, txParams),
+		advanced: walletAdvancedActions(client)
 	};
 }
 
 //#endregion
 //#region src/clients/createWalletClient.ts
 /**
-* 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..."),
 * })
 */
 function createWalletClient(parameters) {
-	const { key = "wallet", name = "Wallet Client" } = parameters;
+	const { key: key$1 = "wallet", name = "Wallet Client" } = parameters;
 	return createClient({
 		...parameters,
-		key,
+		key: key$1,
 		name
 	}).extend(publicActions).extend(walletActions).extend(walletArkivActions);
 }
 
 //#endregion
 //#region src/utils/chains.ts
-const chainMap = new Map(Object.entries(chains_exports).map(([key, value]) => [key.toLowerCase(), value]));
+const chainMap = new Map(Object.entries(chains_exports).map(([key$1, value]) => [key$1.toLowerCase(), value]));
 /**
 * Get a chain from its name
 * @param name - The name of the chain, case insensitive
@@ -585,5 +540,5 @@ function chainFromName(name) {
 }
 
 //#endregion
-export { DuplicateAttributeError, EntityMutationError, EntityOperationType, InvalidAttributeError, InvalidAttributeKeyError, InvalidContentTypeError, InvalidExpirationError, NoCursorOrLimitError, NoEntityFoundError, NoMoreResultsError, chainFromName, createPublicClient, createWalletClient, jsonToPayload, stringToPayload };
+export { ConflictingMutationError, DECIMAL_SCALE, DECIMAL_UNIT, ENTITY_EVENTS_ABI, EmptyPatchError, Entity, EntityMutationError, ExpirationTime, I32_MAX, I32_MIN, InvalidAttributeNameError, InvalidContentTypeError, InvalidCreationFlagsError, InvalidExpiryError, InvalidSaltError, InvalidValueError, MAX_ATTRIBUTES, MAX_EXPIRES_AT, MAX_NAME_BYTES, MAX_PAYLOAD_BYTES, MAX_SALT, MAX_STRING_BYTES, MissingValueError, NoEntityFoundError, NoMoreResultsError, NoRandomSourceError, OperationType, TooManyAttributesError, U256_MAX, U64_MAX, UnknownAttributeTypeError, UntypedValueError, 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.js.map