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

package/dist/index.cjs

@@ -1,28 +1,24 @@
-const require_chains = require('./chains-BYRTTipa.cjs');
-const require_expiry = require('./expiry-BELY2Kpw.cjs');
-const require_advanced = require('./advanced-fPImL6lW.cjs');
-const require_attributes = require('./attributes-Df9IsCVs.cjs');
-const require_key = require('./key-WKhXnXuU.cjs');
-const require_errors = require('./errors-BVbjKVMN.cjs');
-const require_flags = require('./flags-kr276q6i.cjs');
-const require_logger = require('./logger-Cr15lPAQ.cjs');
-require('./attr-DlmErkvR.cjs');
-const require_entity = require('./entity-B00Li04j.cjs');
-const require_queryBuilder = require('./queryBuilder-DbUMEZln.cjs');
-require('./entity-B7G8q_Eo.cjs');
-require('./types-NRqymi6S.cjs');
-const require_payload = require('./payload-KC14SDlN.cjs');
+const require_chains = require('./chains-BfNQliHU.cjs');
+const require_attr = require('./attr-BXTkpnoc.cjs');
+const require_queryBuilder = require('./queryBuilder-zHGhDmaG.cjs');
+const require_errors = require('./errors-DhV00966.cjs');
+const require_flags = require('./flags-DCD26uhe.cjs');
+const require_entity = require('./entity-B0t6sN7F.cjs');
+const require_expiry = require('./expiry-CG9GhVXv.cjs');
+const require_entity$1 = require('./entity-DJ0Gml9c.cjs');
+require('./types-CKPddlfS.cjs');
+const require_payload = require('./payload-DqFweqiO.cjs');
 let viem = require("viem");
 let viem_actions = require("viem/actions");
 
 //#region src/actions/public/getBlockTiming.ts
-const logger$8 = require_logger.getLogger("actions:public:get-block-timing");
+const logger$9 = require_queryBuilder.getLogger("actions:public:get-block-timing");
 async function getBlockTiming(client) {
 	const blockTiming = await client.request({
 		method: "arkiv_getBlockTiming",
 		params: []
 	});
-	logger$8("Block timing %o", blockTiming);
+	logger$9("Block timing %o", blockTiming);
 	return {
 		currentBlock: BigInt(blockTiming.current_block),
 		currentBlockTime: blockTiming.current_block_time,
@@ -45,12 +41,12 @@ async function getBlockTiming(client) {
 */
 async function getEntity(client, entityKey) {
 	const { entities } = await require_queryBuilder.runQuery(client, {
-		query: require_queryBuilder.eq("$key", require_attributes.key(entityKey)).toString(),
+		query: require_queryBuilder.eq("$key", require_attr.key(entityKey)).toString(),
 		select: require_queryBuilder.toRpcSelect("*"),
 		limit: 1
 	});
 	const entity = entities[0];
-	if (entity === void 0) throw new require_logger.NoEntityFoundError(entityKey);
+	if (entity === void 0) throw new require_queryBuilder.NoEntityFoundError(entityKey);
 	return entity;
 }
 
@@ -63,9 +59,93 @@ async function getEntityCount(client) {
 	});
 }
 
+//#endregion
+//#region src/entity/operations.ts
+/**
+* The one external entry point. A transaction is an ordered, **atomic** batch of entity operations:
+* all of them apply or none do, operation *n+1* observes operation *n*'s effects, and each applied
+* operation emits one event.
+*/
+const EXECUTE_ABI = (0, viem.parseAbi)(["function execute((uint8 operation, bytes operationData)[] ops) external returns (bytes32[] keys)"]);
+/**
+* The engine's one read-only view: an owner's entity-minting nonce, which is the input
+* {@link predictEntityKey} needs and the only part of the derivation the caller cannot know.
+*
+* It is a `view` on the same address `execute` is called on, so it answers over `eth_call` without
+* a transaction.
+*/
+const ENTITY_NONCE_ABI = (0, viem.parseAbi)(["function entityNonce(address owner) external view returns (uint64)"]);
+/**
+* The shared attribute shape, used by `create` (attributes) and `patch` (mutations). Written out
+* once and reused by every payload that carries attributes.
+*/
+const ATTRIBUTE_TUPLE = "(bytes32 name, uint8 typeId, bytes value)[]";
+/**
+* The payload struct for each operation tag. `operationData` is `abi.encode` of the struct the tag
+* selects — a tagged union, so a new operation is additive rather than a change to `execute`.
+*/
+const PAYLOAD_PARAMS = {
+	[require_expiry.OperationType.Create]: (0, viem.parseAbiParameters)(`(uint128 salt, uint64 expiresAt, uint64 minLifetime, uint8 creationFlags, ${ATTRIBUTE_TUPLE} attributes)`),
+	[require_expiry.OperationType.Patch]: (0, viem.parseAbiParameters)(`(bytes32 entityKey, ${ATTRIBUTE_TUPLE} mutations)`),
+	[require_expiry.OperationType.ExtendExpiry]: (0, viem.parseAbiParameters)("(bytes32 entityKey, uint64 expiresAt, uint64 minLifetime)"),
+	[require_expiry.OperationType.TransferOwnership]: (0, viem.parseAbiParameters)("(bytes32 entityKey, address newOwner)"),
+	[require_expiry.OperationType.Delete]: (0, viem.parseAbiParameters)("(bytes32 entityKey)")
+};
+/** Creates an entity. The key is derived by the engine; predict it with `predictEntityKey`. */
+function createOperation({ salt, expiry, creationFlags, attributes }) {
+	return {
+		operation: require_expiry.OperationType.Create,
+		operationData: (0, viem.encodeAbiParameters)(PAYLOAD_PARAMS[require_expiry.OperationType.Create], [{
+			salt,
+			expiresAt: expiry.expiresAt,
+			minLifetime: expiry.minLifetime,
+			creationFlags,
+			attributes
+		}])
+	};
+}
+/** Applies a set of mutations to an existing entity. Tombstones unset attributes. */
+function patchOperation({ entityKey, mutations }) {
+	return {
+		operation: require_expiry.OperationType.Patch,
+		operationData: (0, viem.encodeAbiParameters)(PAYLOAD_PARAMS[require_expiry.OperationType.Patch], [{
+			entityKey,
+			mutations
+		}])
+	};
+}
+/** Pushes an entity's expiry further out. Extending is allowed; shortening reverts. */
+function extendExpiryOperation({ entityKey, expiry }) {
+	return {
+		operation: require_expiry.OperationType.ExtendExpiry,
+		operationData: (0, viem.encodeAbiParameters)(PAYLOAD_PARAMS[require_expiry.OperationType.ExtendExpiry], [{
+			entityKey,
+			expiresAt: expiry.expiresAt,
+			minLifetime: expiry.minLifetime
+		}])
+	};
+}
+/** Hands an entity to a new owner. */
+function transferOwnershipOperation({ entityKey, newOwner }) {
+	return {
+		operation: require_expiry.OperationType.TransferOwnership,
+		operationData: (0, viem.encodeAbiParameters)(PAYLOAD_PARAMS[require_expiry.OperationType.TransferOwnership], [{
+			entityKey,
+			newOwner
+		}])
+	};
+}
+/** Deletes an entity before its expiry. */
+function deleteOperation({ entityKey }) {
+	return {
+		operation: require_expiry.OperationType.Delete,
+		operationData: (0, viem.encodeAbiParameters)(PAYLOAD_PARAMS[require_expiry.OperationType.Delete], [{ entityKey }])
+	};
+}
+
 //#endregion
 //#region src/actions/public/getEntityNonce.ts
-const logger$7 = require_logger.getLogger("actions:public:get-entity-nonce");
+const logger$8 = require_queryBuilder.getLogger("actions:public:get-entity-nonce");
 /**
 * Reads an owner's entity-minting nonce — how many entities that account has created.
 *
@@ -80,11 +160,11 @@ const logger$7 = require_logger.getLogger("actions:public:get-entity-nonce");
 async function getEntityNonce(client, owner) {
 	const nonce = await (0, viem_actions.readContract)(client, {
 		address: require_expiry.ARKIV_ADDRESS,
-		abi: require_advanced.ENTITY_NONCE_ABI,
+		abi: ENTITY_NONCE_ABI,
 		functionName: "entityNonce",
 		args: [owner]
 	});
-	logger$7("entity nonce of %s is %s", owner, nonce);
+	logger$8("entity nonce of %s is %s", owner, nonce);
 	return nonce;
 }
 
@@ -102,7 +182,7 @@ async function getEntityNonce(client, owner) {
 *
 * 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`
+* unconditionally, read it back from the create instead — `createEntity` and `executeBatch`
 * report the keys the engine actually minted.
 *
 * @param parameters - Owner, and either a count or the salts. {@link PredictEntityKeysParameters}
@@ -112,7 +192,7 @@ async function getEntityNonce(client, owner) {
 * import { key } from "@arkiv-network/sdk/attr"
 *
 * const [parent, child] = await client.predictEntityKeys({ owner: account.address, count: 2 })
-* await wallet.mutateEntities({
+* await client.executeBatch({
 *   creates: [
 *     { payload, contentType, expires, salt: parent.salt },
 *     {
@@ -130,7 +210,7 @@ async function predictEntityKeys(client, { owner, count, salts }) {
 	const chainId = client.chain?.id ?? await (0, viem_actions.getChainId)(client);
 	const nonce = await getEntityNonce(client, owner);
 	return resolvedSalts.map((salt, index) => ({
-		key: require_key.predictEntityKey({
+		key: require_entity$1.predictEntityKey({
 			owner,
 			nonce: nonce + BigInt(index),
 			salt,
@@ -143,11 +223,11 @@ async function predictEntityKeys(client, { owner, count, salts }) {
 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(require_key.validateSalt);
+		return salts.map(require_entity$1.resolveSalt);
 	}
 	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 }, () => require_key.randomSalt());
+	return Array.from({ length: count }, () => require_entity$1.randomSalt());
 }
 
 //#endregion
@@ -173,7 +253,7 @@ function query(client, query$1, options = {}) {
 
 //#endregion
 //#region src/actions/public/watchEntityEvents.ts
-const logger$6 = require_logger.getLogger("actions:public:watch-entity-events");
+const logger$7 = require_queryBuilder.getLogger("actions:public:watch-entity-events");
 /**
 * How often to poll, when the caller does not say.
 *
@@ -248,11 +328,11 @@ function watchEntityEvents(client, parameters) {
 	}
 	return publicClient.watchEvent({
 		address: require_expiry.ARKIV_ADDRESS,
-		events: require_key.ENTITY_EVENTS_ABI,
+		events: require_entity$1.ENTITY_EVENTS_ABI,
 		pollingInterval,
 		...fromBlock !== void 0 && { fromBlock },
 		onLogs: (logs) => {
-			logger$6("logs %o", logs);
+			logger$7("logs %o", logs);
 			for (const log of logs) {
 				if (log.blockNumber === null || log.transactionHash === null || log.logIndex === null) continue;
 				const context = {
@@ -288,7 +368,7 @@ function asError(error) {
 */
 function toEntityEvent(topics, data, context) {
 	const decoded = (0, viem.decodeEventLog)({
-		abi: require_key.ENTITY_EVENTS_ABI,
+		abi: require_entity$1.ENTITY_EVENTS_ABI,
 		topics,
 		data
 	});
@@ -322,23 +402,6 @@ function toEntityEvent(topics, data, context) {
 	}
 }
 
-//#endregion
-//#region src/clients/decorators/arkivAdvanced.ts
-function publicAdvancedActions(client) {
-	return {
-		pingTransaction: (txHash) => require_advanced.pingTransaction(client, txHash),
-		getMutationResult: (txHash) => require_advanced.getMutationResult(client, txHash),
-		decodeMutationResult: (receipt) => require_advanced.decodeMutationResult(receipt)
-	};
-}
-function walletAdvancedActions(client) {
-	return {
-		...publicAdvancedActions(client),
-		buildMutation: (data, options) => require_advanced.buildMutation(client, data, options),
-		sendMutation: (data, options) => require_advanced.sendMutation(client, data, options)
-	};
-}
-
 //#endregion
 //#region src/clients/decorators/arkivPublic.ts
 function publicArkivActions(client) {
@@ -350,22 +413,21 @@ function publicArkivActions(client) {
 		getEntityCount: () => getEntityCount(client),
 		getEntityNonce: (owner) => getEntityNonce(client, owner),
 		predictEntityKeys: (parameters) => predictEntityKeys(client, parameters),
-		watchEntityEvents: (parameters) => watchEntityEvents(client, parameters),
-		advanced: publicAdvancedActions(client)
+		watchEntityEvents: (parameters) => watchEntityEvents(client, parameters)
 	};
 }
 
 //#endregion
 //#region src/clients/createPublicClient.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 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"
@@ -386,12 +448,254 @@ function createPublicClient(parameters) {
 	}).extend(viem.publicActions).extend(publicArkivActions);
 }
 
+//#endregion
+//#region src/utils/revert.ts
+/**
+* Turns a decoded engine revert into a sentence that says what to change.
+*
+* viem decodes the error and then renders it positionally — `Ident32InvalidByte(uint256 position,
+* bytes1 value)` arrives as `(5, 0x41)`, which is the right data and no help at all. The engine's
+* errors carry enough to name the actual problem, so this spends the args rather than printing
+* them.
+*
+* @param error - Anything thrown by a write action.
+* @returns The explanation, or `undefined` if this was not a decodable engine revert — in which
+* case the caller should fall back to whatever the transport said.
+*/
+function describeEntityRevert(error) {
+	if (!(error instanceof viem.BaseError)) return void 0;
+	const reverted = error.walk((e) => e instanceof viem.ContractFunctionRevertedError);
+	if (!(reverted instanceof viem.ContractFunctionRevertedError)) return void 0;
+	const name = reverted.data?.errorName;
+	if (name === void 0) return void 0;
+	return explain(name, reverted.data?.args ?? []) ?? `the engine rejected the batch with ${name}`;
+}
+/** The attribute-name charset, quoted the way an error message should read. */
+const CHARSET = "\"A\"-\"Z\", \"a\"-\"z\", \"0\"-\"9\", \".\", \"-\" and \"_\", with a letter first";
+function explain(name, args) {
+	switch (name) {
+		case "Ident32InvalidByte": {
+			const position = Number(args[0] ?? 0);
+			return `an attribute name holds ${printable(String(args[1] ?? "0x00"))} at byte ${position}, which is outside the name charset (${CHARSET})`;
+		}
+		case "Ident32Empty": return "an attribute name is empty";
+		case "SystemAttributeNotWritable": return `"${identName(args[0])}" is owned by the engine and cannot be written. Only $payload and \$contentType are yours to set`;
+		case "TombstoneInCreate": return `a create cannot unset "${identName(args[0])}" — nothing exists yet, so leave the name out instead`;
+		case "TombstoneValueNotEmpty": return `the tombstone for "${identName(args[0])}" carries a value; unsetting takes no value`;
+		case "InvalidValueType": return `"${identName(args[0])}" names type id ${String(args[1])}, which is not a known type`;
+		case "AttributesNotSorted": return "attributes must be strictly ascending by name, which also makes each name unique";
+		case "TooManyAttributes": return `${String(args[0])} attributes exceeds the limit of ${String(args[1])}`;
+		case "EmptyMutations": return `the patch of ${short(args[0])} has no mutations, so it would do nothing`;
+		case "EntityNotFound": return `no entity ${short(args[0])} — it may have been deleted, or have expired`;
+		case "EntityExpired": return `entity ${short(args[0])} expired at block ${String(args[1])}`;
+		case "NotOwner": return `entity ${short(args[0])} is owned by ${String(args[2])}, not ${String(args[1])}`;
+		case "ReadOnlyEntity": return `entity ${short(args[0])} was created readonly, so its contents can never change. Its expiry can still be extended, and it can be transferred or deleted`;
+		case "ReservedCreationFlags": return `creation flags 0b${Number(args[0] ?? 0).toString(2).padStart(8, "0")} set a reserved bit; only readonly and permissionlessExtension are defined`;
+		case "ExpiryDeadOnArrival": return `the expiry resolves to block ${String(args[0])}, which is not after the current block ${String(args[1])}`;
+		case "ExpiryNotExtended": return `entity ${short(args[0])} already expires at block ${String(args[2])}, so extending it to ${String(args[1])} would shorten its life`;
+		case "TransferToZeroAddress": return `entity ${short(args[0])} cannot be transferred to the zero address`;
+		case "TransferToSelf": return `entity ${short(args[0])} is already owned by that account`;
+		case "EmptyBatch": return "the batch has no operations";
+		case "InvalidOpType": return `operation tag ${String(args[0])} is not one the engine knows`;
+		case "NonCanonicalOperationData": return `the payload for operation tag ${String(args[0])} is not its canonical encoding, so the engine refused it rather than accept a second spelling of the same operation`;
+		default: return;
+	}
+}
+/** A `bytes32` Ident32 cell as the name it holds — left-aligned, null-padded. */
+function identName(raw) {
+	if (typeof raw !== "string") return String(raw);
+	try {
+		return (0, viem.hexToString)(raw).split("\0")[0] ?? "";
+	} catch {
+		return raw;
+	}
+}
+/** An entity key, abbreviated */
+function short(raw) {
+	const text = String(raw);
+	return text.length > 18 ? `${text.slice(0, 10)}…${text.slice(-6)}` : text;
+}
+/** A `bytes1` as something readable: the character it is, plus the byte it was. */
+function printable(byte) {
+	const code = Number.parseInt(byte.replace(/^0x/, ""), 16);
+	if (!Number.isFinite(code)) return `byte ${byte}`;
+	return code >= 33 && code <= 126 ? `"${String.fromCharCode(code)}" (${byte})` : `byte ${byte}`;
+}
+
+//#endregion
+//#region src/utils/arkivTransactions.ts
+const logger$6 = require_queryBuilder.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 require_queryBuilder.InvalidContentTypeError(contentType);
+}
+const ENTITY_ERRORS_ABI = (0, viem.parseAbi)([
+	"error EmptyBatch()",
+	"error InvalidOpType(uint8 operation)",
+	"error NonCanonicalOperationData(uint8 operation)",
+	"error AttributesNotSorted()",
+	"error TooManyAttributes(uint256 count, uint256 maxCount)",
+	"error EmptyMutations(bytes32 entityKey)",
+	"error TombstoneInCreate(bytes32 name)",
+	"error TombstoneValueNotEmpty(bytes32 name)",
+	"error SystemAttributeNotWritable(bytes32 name)",
+	"error InvalidValueType(bytes32 name, uint8 typeId)",
+	"error Ident32Empty()",
+	"error Ident32InvalidByte(uint256 position, bytes1 value)",
+	"error EntityNotFound(bytes32 entityKey)",
+	"error EntityExpired(bytes32 entityKey, uint64 expiresAt)",
+	"error NotOwner(bytes32 entityKey, address caller, address owner)",
+	"error ReadOnlyEntity(bytes32 entityKey)",
+	"error ReservedCreationFlags(uint8 creationFlags)",
+	"error ExpiryDeadOnArrival(uint64 target, uint64 currentBlock)",
+	"error ExpiryNotExtended(bytes32 entityKey, uint64 newExpiresAt, uint64 currentExpiresAt)",
+	"error TransferToZeroAddress(bytes32 entityKey)",
+	"error TransferToSelf(bytes32 entityKey)"
+]);
+const EXECUTE_ABI$1 = [...EXECUTE_ABI, ...ENTITY_ERRORS_ABI];
+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, patches, deletes, extensions, ownershipChanges } = ops;
+	const expiryContext = { currentBlock: creates?.length || extensions?.length ? await walletClient.getBlockNumber() : 0n };
+	const createOps = (creates ?? []).map((item) => {
+		validateContentType(item.contentType);
+		return createOperation({
+			salt: item.salt === void 0 ? require_entity$1.randomSalt() : require_entity$1.resolveSalt(item.salt),
+			expiry: require_expiry.resolveExpiry(item.expires, expiryContext),
+			creationFlags: require_flags.encodeCreationFlags(item.flags),
+			attributes: require_attr.encodeAttributes(item.attributes, {
+				payload: item.payload,
+				contentType: item.contentType
+			})
+		});
+	});
+	const patchOps = (patches ?? []).map((item) => {
+		if (item.contentType !== void 0) validateContentType(item.contentType);
+		const mutations = require_attr.encodeMutations(item);
+		if (mutations.length === 0) throw new require_queryBuilder.EmptyPatchError(item.entityKey);
+		return patchOperation({
+			entityKey: item.entityKey,
+			mutations
+		});
+	});
+	const extendOps = (extensions ?? []).map((item) => {
+		const expiry = require_expiry.resolveExpiry(item.expires, expiryContext);
+		return extendExpiryOperation({
+			entityKey: item.entityKey,
+			expiry
+		});
+	});
+	const operations = [
+		...createOps,
+		...patchOps,
+		...(deletes ?? []).map((item) => deleteOperation({ entityKey: item.entityKey })),
+		...extendOps,
+		...(ownershipChanges ?? []).map((item) => transferOwnershipOperation({
+			entityKey: item.entityKey,
+			newOwner: item.newOwner
+		}))
+	];
+	if (operations.length === 0) throw new Error("No operations to perform");
+	logger$6("Sending execute with %d operations %o", operations.length, operations);
+	try {
+		const txHash = await walletClient.writeContract({
+			address: require_expiry.ARKIV_ADDRESS,
+			abi: EXECUTE_ABI$1,
+			functionName: "execute",
+			args: [operations],
+			account: client.account,
+			chain: client.chain,
+			...txParams
+		});
+		const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash });
+		logger$6("Tx receipt %o", receipt);
+		if (receipt.status === "reverted") {
+			try {
+				await walletClient.simulateContract({
+					address: require_expiry.ARKIV_ADDRESS,
+					abi: EXECUTE_ABI$1,
+					functionName: "execute",
+					args: [operations],
+					account: client.account,
+					chain: client.chain
+				});
+			} catch (err) {
+				const error = err;
+				const reason = describeEntityRevert(err) ?? error.shortMessage ?? error.cause?.details ?? "No reason provided by backend.";
+				throw new require_queryBuilder.EntityMutationError(`Transaction ${receipt.transactionHash} reverted. Reason: ${reason}`);
+			}
+			throw new require_queryBuilder.EntityMutationError(`Transaction ${receipt.transactionHash} reverted. No reason provided by backend.`);
+		}
+		return {
+			receipt,
+			...readAppliedOperations(receipt, {
+				creates: createOps.length,
+				extensions: extendOps.length
+			})
+		};
+	} catch (error) {
+		const described = error instanceof require_queryBuilder.EntityMutationError ? void 0 : describeEntityRevert(error);
+		if (described !== void 0) throw new require_queryBuilder.EntityMutationError(`Transaction failed: ${described}`, { cause: error });
+		let message = "Transaction failed";
+		if (error instanceof viem.TransactionExecutionError) message += `: ${error.details}`;
+		else if (error instanceof viem.ContractFunctionExecutionError) {
+			logger$6("Contract function execution error data:", error.shortMessage);
+			if (error.cause instanceof viem.ContractFunctionRevertedError) message += `: ${error.cause.message}`;
+			else message += ": Execution error without revert data";
+		} else if (error instanceof require_queryBuilder.EntityMutationError) throw error;
+		else if (error instanceof Error) message += `: ${error.message}`;
+		throw new require_queryBuilder.EntityMutationError(message, { cause: error });
+	}
+}
+/**
+* The keys and expiries the engine recorded, read back from the events the batch emitted.
+*/
+function readAppliedOperations(receipt, expected) {
+	const createdEntityKeys = [];
+	const createdExpiries = [];
+	const extendedExpiries = [];
+	for (const log of receipt.logs ?? []) {
+		if (log.address.toLowerCase() !== require_expiry.ARKIV_ADDRESS.toLowerCase()) continue;
+		const decoded = decodeEntityLog(log);
+		if (decoded === void 0) continue;
+		if (decoded.eventName === "EntityCreated") {
+			createdEntityKeys.push(decoded.args.entityKey);
+			createdExpiries.push(decoded.args.expiresAt);
+		} else if (decoded.eventName === "ExpiryExtended") extendedExpiries.push(decoded.args.expiresAt);
+	}
+	assertCount(receipt, "create", createdEntityKeys.length, expected.creates);
+	assertCount(receipt, "extension", extendedExpiries.length, expected.extensions);
+	return {
+		createdEntityKeys,
+		createdExpiries,
+		extendedExpiries
+	};
+}
+/** One log as an entity event, or `undefined` for anything this SDK has no name for. */
+function decodeEntityLog(log) {
+	try {
+		return (0, viem.decodeEventLog)({
+			abi: require_entity$1.ENTITY_EVENTS_ABI,
+			topics: log.topics,
+			data: log.data
+		});
+	} catch {
+		return;
+	}
+}
+function assertCount(receipt, what, got, want) {
+	if (got === want) return;
+	throw new require_queryBuilder.EntityMutationError(`Transaction ${receipt.transactionHash} succeeded — do not retry it — but emitted ${got} ${what} event(s) for ${want} ${what} operation(s). The batch was applied; the SDK cannot say which entity each operation produced, so read them back to find them.`);
+}
+
 //#endregion
 //#region src/actions/wallet/changeOwnership.ts
-const logger$5 = require_logger.getLogger("actions:wallet:change-ownership");
+const logger$5 = require_queryBuilder.getLogger("actions:wallet:change-ownership");
 async function changeOwnership(client, data, txParams) {
 	logger$5("changeOwnership %o", data);
-	const { receipt } = await require_advanced.sendArkivTransaction(client, { ownershipChanges: [data] }, txParams);
+	const { receipt } = await sendArkivTransaction(client, { ownershipChanges: [data] }, txParams);
 	logger$5("Receipt from changeOwnership %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
@@ -401,14 +705,14 @@ async function changeOwnership(client, data, txParams) {
 
 //#endregion
 //#region src/actions/wallet/createEntity.ts
-const logger$4 = require_logger.getLogger("actions:wallet:create-entity");
+const logger$4 = require_queryBuilder.getLogger("actions:wallet:create-entity");
 async function createEntity(client, data, txParams) {
 	logger$4("createEntity %o", data);
-	const { receipt, createdEntityKeys, createdExpiries } = await require_advanced.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 require_logger.EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity key or expiry.`);
+	if (entityKey === void 0 || expiresAt === void 0) throw new require_queryBuilder.EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity key or expiry.`);
 	return {
 		txHash: receipt.transactionHash,
 		entityKey,
@@ -418,10 +722,10 @@ async function createEntity(client, data, txParams) {
 
 //#endregion
 //#region src/actions/wallet/deleteEntity.ts
-const logger$3 = require_logger.getLogger("actions:wallet:delete-entity");
+const logger$3 = require_queryBuilder.getLogger("actions:wallet:delete-entity");
 async function deleteEntity(client, data, txParams) {
 	logger$3("deleteEntity %o", data);
-	const { receipt } = await require_advanced.sendArkivTransaction(client, { deletes: [data] }, txParams);
+	const { receipt } = await sendArkivTransaction(client, { deletes: [data] }, txParams);
 	logger$3("Receipt from deleteEntity %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
@@ -430,43 +734,43 @@ async function deleteEntity(client, data, txParams) {
 }
 
 //#endregion
-//#region src/actions/wallet/extendEntity.ts
-const logger$2 = require_logger.getLogger("actions:wallet:extend-entity");
-async function extendEntity(client, data, txParams) {
-	logger$2("extendEntity %o", data);
-	const { receipt, extendedExpiries } = await require_advanced.sendArkivTransaction(client, { extensions: [data] }, txParams);
-	logger$2("Receipt from extendEntity %o", receipt);
-	const [expiresAt] = extendedExpiries;
-	if (expiresAt === void 0) throw new require_logger.EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity expiry.`);
+//#region src/actions/wallet/executeBatch.ts
+const logger$2 = require_queryBuilder.getLogger("actions:wallet:execute-batch");
+async function executeBatch(client, data, txParams) {
+	const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams);
+	logger$2("Receipt from executeBatch %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
-		entityKey: data.entityKey,
-		expiresAt
+		createdEntities: createdEntityKeys,
+		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)
 	};
 }
 
 //#endregion
-//#region src/actions/wallet/mutateEntities.ts
-const logger$1 = require_logger.getLogger("actions:wallet:mutate-entities");
-async function mutateEntities(client, data, txParams) {
-	const { receipt, createdEntityKeys } = await require_advanced.sendArkivTransaction(client, data, txParams);
-	logger$1("Receipt from mutateEntities %o", receipt);
+//#region src/actions/wallet/extendEntity.ts
+const logger$1 = require_queryBuilder.getLogger("actions:wallet:extend-entity");
+async function extendEntity(client, data, txParams) {
+	logger$1("extendEntity %o", data);
+	const { receipt, extendedExpiries } = await sendArkivTransaction(client, { extensions: [data] }, txParams);
+	logger$1("Receipt from extendEntity %o", receipt);
+	const [expiresAt] = extendedExpiries;
+	if (expiresAt === void 0) throw new require_queryBuilder.EntityMutationError(`Transaction ${receipt.transactionHash} succeeded, but the receipt did not carry the expected entity expiry.`);
 	return {
 		txHash: receipt.transactionHash,
-		createdEntities: createdEntityKeys,
-		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)
+		entityKey: data.entityKey,
+		expiresAt
 	};
 }
 
 //#endregion
 //#region src/actions/wallet/patchEntity.ts
-const logger = require_logger.getLogger("actions:wallet:patch-entity");
+const logger = require_queryBuilder.getLogger("actions:wallet:patch-entity");
 async function patchEntity(client, data, txParams) {
 	logger("patchEntity %o", data);
-	const { receipt } = await require_advanced.sendArkivTransaction(client, { patches: [data] }, txParams);
+	const { receipt } = await sendArkivTransaction(client, { patches: [data] }, txParams);
 	logger("Receipt from patchEntity %o", receipt);
 	return {
 		txHash: receipt.transactionHash,
@@ -483,8 +787,7 @@ function walletArkivActions(client) {
 		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),
-		advanced: walletAdvancedActions(client)
+		executeBatch: (data, txParams) => executeBatch(client, data, txParams)
 	};
 }
 
@@ -492,16 +795,14 @@ function walletArkivActions(client) {
 //#region src/clients/createWalletClient.ts
 /**
 * 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"
@@ -540,69 +841,62 @@ function chainFromName(name) {
 }
 
 //#endregion
-exports.ConflictingMutationError = require_attributes.ConflictingMutationError;
-exports.DECIMAL_SCALE = require_attributes.DECIMAL_SCALE;
-exports.DECIMAL_UNIT = require_attributes.DECIMAL_UNIT;
-exports.ENTITY_EVENTS_ABI = require_key.ENTITY_EVENTS_ABI;
-exports.EmptyPatchError = require_logger.EmptyPatchError;
+exports.ConflictingMutationError = require_attr.ConflictingMutationError;
+exports.DECIMAL_SCALE = require_attr.DECIMAL_SCALE;
+exports.DECIMAL_UNIT = require_attr.DECIMAL_UNIT;
+exports.ENTITY_EVENTS_ABI = require_entity$1.ENTITY_EVENTS_ABI;
+exports.EmptyPatchError = require_queryBuilder.EmptyPatchError;
 exports.Entity = require_entity.Entity;
-exports.EntityMutationError = require_logger.EntityMutationError;
+exports.EntityMutationError = require_queryBuilder.EntityMutationError;
 exports.ExpirationTime = require_payload.ExpirationTime;
-exports.I32_MAX = require_attributes.I32_MAX;
-exports.I32_MIN = require_attributes.I32_MIN;
-exports.InvalidAttributeNameError = require_attributes.InvalidAttributeNameError;
-exports.InvalidContentTypeError = require_logger.InvalidContentTypeError;
+exports.I32_MAX = require_attr.I32_MAX;
+exports.I32_MIN = require_attr.I32_MIN;
+exports.InvalidAttributeNameError = require_attr.InvalidAttributeNameError;
+exports.InvalidContentTypeError = require_queryBuilder.InvalidContentTypeError;
 exports.InvalidCreationFlagsError = require_errors.InvalidCreationFlagsError;
 exports.InvalidExpiryError = require_errors.InvalidExpiryError;
 exports.InvalidSaltError = require_errors.InvalidSaltError;
-exports.InvalidValueError = require_attributes.InvalidValueError;
-exports.MAX_ATTRIBUTES = require_attributes.MAX_ATTRIBUTES;
+exports.InvalidValueError = require_attr.InvalidValueError;
+exports.MAX_ATTRIBUTES = require_attr.MAX_ATTRIBUTES;
 exports.MAX_EXPIRES_AT = require_expiry.MAX_EXPIRES_AT;
-exports.MAX_NAME_BYTES = require_attributes.MAX_NAME_BYTES;
-exports.MAX_PAYLOAD_BYTES = require_attributes.MAX_PAYLOAD_BYTES;
-exports.MAX_SALT = require_key.MAX_SALT;
-exports.MAX_STRING_BYTES = require_attributes.MAX_STRING_BYTES;
-exports.MissingValueError = require_attributes.MissingValueError;
-exports.NoEntityFoundError = require_logger.NoEntityFoundError;
-exports.NoMoreResultsError = require_logger.NoMoreResultsError;
+exports.MAX_NAME_BYTES = require_attr.MAX_NAME_BYTES;
+exports.MAX_PAYLOAD_BYTES = require_attr.MAX_PAYLOAD_BYTES;
+exports.MAX_SALT = require_entity$1.MAX_SALT;
+exports.MAX_STRING_BYTES = require_attr.MAX_STRING_BYTES;
+exports.MissingValueError = require_attr.MissingValueError;
+exports.NO_SALT = require_entity$1.NO_SALT;
+exports.NoEntityFoundError = require_queryBuilder.NoEntityFoundError;
+exports.NoMoreResultsError = require_queryBuilder.NoMoreResultsError;
 exports.NoRandomSourceError = require_errors.NoRandomSourceError;
 exports.OperationType = require_expiry.OperationType;
-exports.TooManyAttributesError = require_attributes.TooManyAttributesError;
-exports.U256_MAX = require_attributes.U256_MAX;
-exports.U64_MAX = require_attributes.U64_MAX;
-exports.UnknownAttributeTypeError = require_attributes.UnknownAttributeTypeError;
-exports.UntypedValueError = require_attributes.UntypedValueError;
-exports.addr = require_attributes.addr;
-exports.bool = require_attributes.bool;
-exports.buildEntityOperations = require_advanced.buildEntityOperations;
-exports.buildMutation = require_advanced.buildMutation;
-exports.bytes32 = require_attributes.bytes32;
+exports.TooManyAttributesError = require_attr.TooManyAttributesError;
+exports.U256_MAX = require_attr.U256_MAX;
+exports.U64_MAX = require_attr.U64_MAX;
+exports.UnknownAttributeTypeError = require_attr.UnknownAttributeTypeError;
+exports.UntypedValueError = require_attr.UntypedValueError;
+exports.addr = require_attr.addr;
+exports.bool = require_attr.bool;
+exports.bytes32 = require_attr.bytes32;
 exports.chainFromName = chainFromName;
-exports.collectMutationEvents = require_advanced.collectMutationEvents;
 exports.createPublicClient = createPublicClient;
 exports.createWalletClient = createWalletClient;
-exports.dec = require_attributes.dec;
-exports.decFromUnits = require_attributes.decFromUnits;
-exports.decUnits = require_attributes.decUnits;
+exports.dec = require_attr.dec;
+exports.decFromUnits = require_attr.decFromUnits;
+exports.decUnits = require_attr.decUnits;
 exports.decodeCreationFlags = require_flags.decodeCreationFlags;
-exports.decodeMutationResult = require_advanced.decodeMutationResult;
 exports.encodeCreationFlags = require_flags.encodeCreationFlags;
-exports.getMutationResult = require_advanced.getMutationResult;
-exports.i32 = require_attributes.i32;
-exports.isArkivValue = require_attributes.isArkivValue;
-exports.isValidAttributeName = require_attributes.isValidAttributeName;
+exports.i32 = require_attr.i32;
+exports.isArkivValue = require_attr.isArkivValue;
+exports.isValidAttributeName = require_attr.isValidAttributeName;
 exports.jsonToPayload = require_payload.jsonToPayload;
-exports.key = require_attributes.key;
-exports.mutationNeedsBlockNumber = require_advanced.mutationNeedsBlockNumber;
-exports.pingTransaction = require_advanced.pingTransaction;
-exports.predictEntityKey = require_key.predictEntityKey;
-exports.randomSalt = require_key.randomSalt;
+exports.key = require_attr.key;
+exports.predictEntityKey = require_entity$1.predictEntityKey;
+exports.randomSalt = require_entity$1.randomSalt;
 exports.resolveExpiry = require_expiry.resolveExpiry;
-exports.sendMutation = require_advanced.sendMutation;
-exports.str = require_attributes.str;
+exports.str = require_attr.str;
 exports.stringToPayload = require_payload.stringToPayload;
 exports.toBlocks = require_expiry.toBlocks;
-exports.toValue = require_attributes.toValue;
-exports.u256 = require_attributes.u256;
-exports.u64 = require_attributes.u64;
-exports.validateAttributeName = require_attributes.validateAttributeName;
+exports.toValue = require_attr.toValue;
+exports.u256 = require_attr.u256;
+exports.u64 = require_attr.u64;
+exports.validateAttributeName = require_attr.validateAttributeName;