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

package/dist/advanced-8ZPTmmaN.js

@@ -0,0 +1,598 @@
+import { a as OperationType, n as resolveExpiry, o as ARKIV_ADDRESS } from "./expiry-BjpxZZQU.js";
+import { i as encodeMutations, r as encodeAttributes } from "./attributes-BhY5DwJp.js";
+import { a as ENTITY_EVENTS_ABI, i as validateSalt, r as randomSalt } from "./key-D1Bh7MF0.js";
+import { n as encodeCreationFlags } from "./flags-DFBs2J94.js";
+import { i as InvalidContentTypeError, n as EmptyPatchError, r as EntityMutationError, t as getLogger } from "./logger-CVpvU8ik.js";
+import { BaseError, ContractFunctionExecutionError, ContractFunctionRevertedError, TransactionExecutionError, TransactionReceiptNotFoundError, decodeEventLog, encodeAbiParameters, encodeFunctionData, hexToString, parseAbi, parseAbiParameters } from "viem";
+
+//#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 = 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 = 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 = {
+	[OperationType.Create]: parseAbiParameters(`(uint128 salt, uint64 expiresAt, uint64 minLifetime, uint8 creationFlags, ${ATTRIBUTE_TUPLE} attributes)`),
+	[OperationType.Patch]: parseAbiParameters(`(bytes32 entityKey, ${ATTRIBUTE_TUPLE} mutations)`),
+	[OperationType.ExtendExpiry]: parseAbiParameters("(bytes32 entityKey, uint64 expiresAt, uint64 minLifetime)"),
+	[OperationType.TransferOwnership]: parseAbiParameters("(bytes32 entityKey, address newOwner)"),
+	[OperationType.Delete]: 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: OperationType.Create,
+		operationData: encodeAbiParameters(PAYLOAD_PARAMS[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: OperationType.Patch,
+		operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.Patch], [{
+			entityKey,
+			mutations
+		}])
+	};
+}
+/** Pushes an entity's expiry further out. Extending is allowed; shortening reverts. */
+function extendExpiryOperation({ entityKey, expiry }) {
+	return {
+		operation: OperationType.ExtendExpiry,
+		operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.ExtendExpiry], [{
+			entityKey,
+			expiresAt: expiry.expiresAt,
+			minLifetime: expiry.minLifetime
+		}])
+	};
+}
+/** Hands an entity to a new owner. */
+function transferOwnershipOperation({ entityKey, newOwner }) {
+	return {
+		operation: OperationType.TransferOwnership,
+		operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.TransferOwnership], [{
+			entityKey,
+			newOwner
+		}])
+	};
+}
+/** Deletes an entity before its expiry. */
+function deleteOperation({ entityKey }) {
+	return {
+		operation: OperationType.Delete,
+		operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.Delete], [{ entityKey }])
+	};
+}
+
+//#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 BaseError)) return void 0;
+	const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError);
+	if (!(reverted instanceof 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 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$4 = 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_ERRORS_ABI = 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, extensions } = ops;
+	const operations = buildEntityOperations(ops, { currentBlock: creates?.length || extensions?.length ? await walletClient.getBlockNumber() : 0n });
+	logger$4("Sending execute with %d operations %o", operations.length, operations);
+	const txHash = await submitMutation(client, operations, txParams);
+	try {
+		const receipt = await walletClient.waitForTransactionReceipt({ hash: txHash });
+		logger$4("Tx receipt %o", receipt);
+		if (receipt.status === "reverted") {
+			try {
+				await walletClient.simulateContract({
+					address: 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 EntityMutationError(`Transaction ${receipt.transactionHash} reverted. Reason: ${reason}`);
+			}
+			throw new EntityMutationError(`Transaction ${receipt.transactionHash} reverted. No reason provided by backend.`);
+		}
+		return {
+			receipt,
+			...readAppliedOperations(receipt, {
+				creates: creates?.length ?? 0,
+				extensions: extensions?.length ?? 0
+			})
+		};
+	} catch (error) {
+		throw asEntityMutationError(error);
+	}
+}
+/**
+* Wraps whatever a write step threw into an {@link EntityMutationError} — engine terms when the
+* revert data decodes, the node's own message otherwise. An {@link EntityMutationError} passes
+* through unchanged, so wrapped steps compose without double-wrapping.
+*/
+function asEntityMutationError(error) {
+	if (error instanceof EntityMutationError) return error;
+	const described = describeEntityRevert(error);
+	if (described !== void 0) return new EntityMutationError(`Transaction failed: ${described}`, { cause: error });
+	let message = "Transaction failed";
+	if (error instanceof TransactionExecutionError) message += `: ${error.details}`;
+	else if (error instanceof ContractFunctionExecutionError) {
+		logger$4("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 Error) message += `: ${error.message}`;
+	return new EntityMutationError(message, { cause: error });
+}
+/**
+* The keys and expiries the engine recorded, read back from the events the batch emitted.
+*/
+function readAppliedOperations(receipt, expected) {
+	const events = collectMutationEvents(receipt.logs);
+	const createdEntityKeys = events.created.map((e) => e.entityKey);
+	const createdExpiries = events.created.map((e) => e.expiresAt);
+	const extendedExpiries = events.extended.map((e) => e.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 decodeEventLog({
+			abi: ENTITY_EVENTS_ABI,
+			topics: log.topics,
+			data: log.data
+		});
+	} catch {
+		return;
+	}
+}
+function assertCount(receipt, what, got, want) {
+	if (got === want) return;
+	throw new 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.`);
+}
+/**
+* Whether encoding the batch actually requires the chain head.
+*
+* Only a relative lifetime (`minLifetime > 0`) or a wall-clock deadline (a `Date`) is measured
+* from the current block. A purely absolute `atBlock(n)` expiry encodes the same bytes whatever
+* the head is, so a batch of those — or one with no expiries at all — needs no `eth_blockNumber`.
+*/
+function mutationNeedsBlockNumber(ops) {
+	return [...ops.creates ?? [], ...ops.extensions ?? []].some((item) => {
+		const expires = item.expires;
+		if (expires === void 0 || typeof expires.minLifetime !== "bigint") return false;
+		return expires.minLifetime !== 0n || expires.expiresAt instanceof Date;
+	});
+}
+/**
+* Encodes a batch into the `execute` operations, in the order the engine applies them: creates,
+* patches, deletes, extensions, ownership transfers.
+*
+* Pure — every check here is local (content types, salts, expiry bounds, non-empty patches and a
+* non-empty batch), so the only chain input is `context.currentBlock`. Callers that carry no
+* relative expiry (see {@link mutationNeedsBlockNumber}) can pass `0n`, which disables the
+* dead-on-arrival pre-check and leaves that to the engine.
+*/
+function buildEntityOperations(ops, context) {
+	const { creates, patches, deletes, extensions, ownershipChanges } = ops;
+	const createOps = (creates ?? []).map((item) => {
+		validateContentType(item.contentType);
+		return createOperation({
+			salt: item.salt === void 0 ? randomSalt() : validateSalt(item.salt),
+			expiry: resolveExpiry(item.expires, context),
+			creationFlags: encodeCreationFlags(item.flags),
+			attributes: encodeAttributes(item.attributes, {
+				payload: item.payload,
+				contentType: item.contentType
+			})
+		});
+	});
+	const patchOps = (patches ?? []).map((item) => {
+		if (item.contentType !== void 0) validateContentType(item.contentType);
+		const mutations = encodeMutations(item);
+		if (mutations.length === 0) throw new EmptyPatchError(item.entityKey);
+		return patchOperation({
+			entityKey: item.entityKey,
+			mutations
+		});
+	});
+	const extendOps = (extensions ?? []).map((item) => {
+		const expiry = resolveExpiry(item.expires, context);
+		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");
+	return operations;
+}
+/**
+* Signs and sends an encoded batch, wrapping any node rejection in {@link EntityMutationError}.
+*
+* The submission half both write paths share: one `writeContract` — an `eth_sendRawTransaction`,
+* plus only the lookups viem needs for whatever `txParams` leaves out — with no waiting and no
+* polling. A rejection is reported in engine terms when the node returned decodable revert data,
+* and with the node's own message otherwise; either way the caller sees an
+* {@link EntityMutationError}.
+*
+* Internal seam shared with `actions/advanced/sendMutation`; not part of the package's public
+* surface.
+*/
+async function submitMutation(client, operations, txParams) {
+	if (!client.account) throw new Error("Account required");
+	if (!client.chain) throw new Error("Chain required");
+	const walletClient = client;
+	try {
+		return await walletClient.writeContract({
+			address: ARKIV_ADDRESS,
+			abi: EXECUTE_ABI$1,
+			functionName: "execute",
+			args: [operations],
+			account: client.account,
+			chain: client.chain,
+			...txParams
+		});
+	} catch (error) {
+		throw asEntityMutationError(error);
+	}
+}
+/**
+* Reads the entity events out of a receipt's logs, exactly as they were emitted.
+*
+* Lenient by design: it reports what the events say and nothing else — no counting against what
+* was asked for (the caller may not have the request at hand) and no error for a receipt with no
+* entity events at all. Logs from other contracts and events this SDK has no name for are skipped.
+*/
+function collectMutationEvents(logs) {
+	const events = {
+		created: [],
+		patched: [],
+		deleted: [],
+		extended: [],
+		ownershipTransferred: []
+	};
+	for (const log of logs ?? []) {
+		if (log.address.toLowerCase() !== ARKIV_ADDRESS.toLowerCase()) continue;
+		const decoded = decodeEntityLog(log);
+		if (decoded === void 0) continue;
+		switch (decoded.eventName) {
+			case "EntityCreated":
+				events.created.push({
+					entityKey: decoded.args.entityKey,
+					owner: decoded.args.owner,
+					expiresAt: decoded.args.expiresAt
+				});
+				break;
+			case "EntityPatched":
+				events.patched.push({
+					entityKey: decoded.args.entityKey,
+					owner: decoded.args.owner
+				});
+				break;
+			case "EntityDeleted":
+				events.deleted.push({
+					entityKey: decoded.args.entityKey,
+					owner: decoded.args.owner
+				});
+				break;
+			case "ExpiryExtended":
+				events.extended.push({
+					entityKey: decoded.args.entityKey,
+					owner: decoded.args.owner,
+					expiresAt: decoded.args.expiresAt
+				});
+				break;
+			case "OwnershipTransferred":
+				events.ownershipTransferred.push({
+					entityKey: decoded.args.entityKey,
+					previousOwner: decoded.args.previousOwner,
+					newOwner: decoded.args.newOwner
+				});
+				break;
+		}
+	}
+	return events;
+}
+
+//#endregion
+//#region src/actions/advanced/buildMutation.ts
+const logger$3 = getLogger("actions:advanced:build-mutation");
+/**
+* Encodes a mutation batch without sending anything.
+*
+* This is the first step of the advanced path: it performs only local validation and encoding, so
+* it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
+* and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
+* to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
+*
+* One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
+* locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
+* expiry encodes cleanly and the engine reverts it on-chain — see
+* {@link BuildMutationOptions.currentBlock}.
+*
+* @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
+* @throws {InvalidValueError} If an attribute value does not fit the type it names.
+* @throws {EmptyPatchError} If a patch has nothing to apply.
+*/
+async function buildMutation(client, data, options = {}) {
+	const currentBlock = options.currentBlock ?? (mutationNeedsBlockNumber(data) ? await client.getBlockNumber() : 0n);
+	const operations = buildEntityOperations(data, { currentBlock });
+	logger$3("Built %d operations at block %d", operations.length, currentBlock);
+	return {
+		operations,
+		to: ARKIV_ADDRESS,
+		data: encodeFunctionData({
+			abi: EXECUTE_ABI,
+			functionName: "execute",
+			args: [operations]
+		}),
+		expected: {
+			creates: data.creates?.length ?? 0,
+			patches: data.patches?.length ?? 0,
+			deletes: data.deletes?.length ?? 0,
+			extensions: data.extensions?.length ?? 0,
+			ownershipChanges: data.ownershipChanges?.length ?? 0
+		}
+	};
+}
+
+//#endregion
+//#region src/actions/advanced/getMutationResult.ts
+const logger$2 = getLogger("actions:advanced:get-mutation-result");
+/**
+* Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
+*
+* The pure tail of the advanced path: if a receipt reached you some other way — your own
+* `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
+* expiries without touching the network. Lenient by design: it reports what the events say,
+* without counting them against a request it never saw.
+*/
+function decodeMutationResult(receipt) {
+	const events = collectMutationEvents(receipt.logs);
+	return {
+		status: receipt.status,
+		txHash: receipt.transactionHash,
+		blockNumber: receipt.blockNumber,
+		createdEntities: events.created.map((e) => e.entityKey),
+		createdExpiries: events.created.map((e) => e.expiresAt),
+		patchedEntities: events.patched.map((e) => e.entityKey),
+		deletedEntities: events.deleted.map((e) => e.entityKey),
+		extendedEntities: events.extended.map((e) => e.entityKey),
+		extendedExpiries: events.extended.map((e) => e.expiresAt),
+		ownershipChanges: events.ownershipTransferred.map((e) => e.entityKey),
+		receipt
+	};
+}
+/**
+* Fetches a transaction's receipt — once — and decodes what the mutation did.
+*
+* Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
+* decoded entity events as well: created keys, recorded expiries, and the keys of everything
+* patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
+* `{ status: "pending" }` — check `status` before reading the rest.
+*
+* No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
+* spending a `simulateContract` on the why is your call, not the SDK's.
+*/
+async function getMutationResult(client, txHash) {
+	const receipt = await fetchReceipt(client, txHash);
+	if (receipt === void 0) {
+		logger$2("Tx %s still pending", txHash);
+		return { status: "pending" };
+	}
+	return decodeMutationResult(receipt);
+}
+/**
+* One `eth_getTransactionReceipt`, with "not there yet" as a value instead of an exception.
+*
+* Internal seam shared with `pingTransaction`; not part of the package's public surface.
+*/
+async function fetchReceipt(client, txHash) {
+	const reader = client;
+	try {
+		return await reader.getTransactionReceipt({ hash: txHash });
+	} catch (error) {
+		if (error instanceof TransactionReceiptNotFoundError) return void 0;
+		throw error;
+	}
+}
+
+//#endregion
+//#region src/actions/advanced/pingTransaction.ts
+const logger$1 = getLogger("actions:advanced:ping-transaction");
+/**
+* Asks the chain — once — whether a transaction has landed.
+*
+* Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
+* back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
+* path — you own the schedule, the SDK owns nothing.
+*
+* When it reports `success` and you need the created keys or recorded expiries, spend the next
+* call on `getMutationResult` — or none at all, if you predicted the keys up front with
+* `predictEntityKeys`.
+*/
+async function pingTransaction(client, txHash) {
+	const receipt = await fetchReceipt(client, txHash);
+	if (receipt === void 0) {
+		logger$1("Tx %s still pending", txHash);
+		return { status: "pending" };
+	}
+	return {
+		status: receipt.status,
+		blockNumber: receipt.blockNumber
+	};
+}
+
+//#endregion
+//#region src/actions/advanced/sendMutation.ts
+const logger = getLogger("actions:advanced:send-mutation");
+/**
+* Signs and sends a mutation batch, returning as soon as the transaction is submitted.
+*
+* The fire-and-forget half of the advanced path. Unlike `mutateEntities`, this does **not** wait
+* for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
+* costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
+* RPC call; each omitted piece adds only the lookup viem needs to fill it.
+*
+* Follow up separately, on your own schedule:
+* - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
+* - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
+*
+* @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
+* the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
+* Anything after that — inclusion, success — is yours to check.
+*/
+async function sendMutation(client, data, options = {}) {
+	const { operations, expected } = await buildMutation(client, data, options);
+	logger("Sending execute with %d operations (no wait)", operations.length);
+	return {
+		txHash: await submitMutation(client, operations, options.txParams),
+		expected
+	};
+}
+
+//#endregion
+export { buildMutation as a, mutationNeedsBlockNumber as c, getMutationResult as i, sendArkivTransaction as l, pingTransaction as n, buildEntityOperations as o, decodeMutationResult as r, collectMutationEvents as s, sendMutation as t, ENTITY_NONCE_ABI as u };
+//# sourceMappingURL=advanced-8ZPTmmaN.js.map