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

package/src/utils/revert.ts

@@ -0,0 +1,145 @@
+import { BaseError, ContractFunctionRevertedError, type Hex, hexToString } from "viem"
+
+/**
+ * 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.
+ */
+export function describeEntityRevert(error: unknown): string | undefined {
+  if (!(error instanceof BaseError)) return undefined
+  const reverted = error.walk((e) => e instanceof ContractFunctionRevertedError)
+  if (!(reverted instanceof ContractFunctionRevertedError)) return undefined
+
+  const name = reverted.data?.errorName
+  if (name === undefined) return undefined
+  const args = (reverted.data?.args ?? []) as readonly unknown[]
+
+  return explain(name, 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: string, args: readonly unknown[]): string | undefined {
+  switch (name) {
+    // ── attribute names ──────────────────────────────────────────────────────
+    case "Ident32InvalidByte": {
+      const position = Number(args[0] ?? 0)
+      const char = printable(String(args[1] ?? "0x00"))
+      return (
+        `an attribute name holds ${char} at byte ${position}, which is outside the ` +
+        `name charset (${CHARSET})`
+      )
+    }
+    case "Ident32Empty":
+      return "an attribute name is empty"
+
+    // ── the attribute list ───────────────────────────────────────────────────
+    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`
+
+    // ── entity state and authorisation ───────────────────────────────────────
+    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"
+      )
+
+    // ── expiry ───────────────────────────────────────────────────────────────
+    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`
+      )
+
+    // ── ownership ────────────────────────────────────────────────────────────
+    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`
+
+    // ── batch framing ────────────────────────────────────────────────────────
+    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 undefined
+  }
+}
+
+/** A `bytes32` Ident32 cell as the name it holds — left-aligned, null-padded. */
+function identName(raw: unknown): string {
+  if (typeof raw !== "string") return String(raw)
+  try {
+    // Cut at the first null rather than trimming with a regex: the padding is whatever follows
+    // the name, so everything before it is the name and nothing after it is. Written as an escape
+    // because a literal NUL byte in source is invisible to every reader after you.
+    return hexToString(raw as Hex).split("\u0000")[0] ?? ""
+  } catch {
+    return raw
+  }
+}
+
+/** An entity key, abbreviated */
+function short(raw: unknown): string {
+  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: string): string {
+  const code = Number.parseInt(byte.replace(/^0x/, ""), 16)
+  if (!Number.isFinite(code)) return `byte ${byte}`
+  const char = String.fromCharCode(code)
+  return code >= 0x21 && code <= 0x7e ? `"${char}" (${byte})` : `byte ${byte}`
+}

package/dist/chains-BifaY04V.cjs

@@ -1,108 +0,0 @@
-//#region rolldown:runtime
-var __defProp = Object.defineProperty;
-var __export = (all) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	return target;
-};
-
-//#endregion
-let viem = require("viem");
-
-//#region src/chains/braga.ts
-const braga = (0, viem.defineChain)({
-	id: 60138453102,
-	name: "Braga",
-	network: "braga",
-	nativeCurrency: {
-		name: "Golem",
-		symbol: "GLM",
-		decimals: 18
-	},
-	rpcUrls: { default: {
-		http: ["https://braga.hoodi.arkiv.network/rpc"],
-		webSocket: ["wss://braga.hoodi.arkiv.network/rpc/ws"]
-	} },
-	blockExplorers: { default: {
-		name: "Braga Arkiv Explorer",
-		url: "https://explorer.braga.hoodi.arkiv.network",
-		apiUrl: "https://explorer.braga.hoodi.arkiv.network/api"
-	} },
-	testnet: true
-});
-
-//#endregion
-//#region src/chains/kaolin.ts
-/**
-* @deprecated The kaolin network is getting removed on may 15th 2026. Migration guide: https://docs.arkiv.network/networks/migrate-from-kaolin/
-*/
-const kaolin = (0, viem.defineChain)({
-	id: 60138453025,
-	name: "Kaolin",
-	network: "kaolin",
-	nativeCurrency: {
-		name: "Ethereum",
-		symbol: "ETH",
-		decimals: 18
-	},
-	rpcUrls: { default: {
-		http: ["https://kaolin.hoodi.arkiv.network/rpc"],
-		webSocket: ["wss://kaolin.hoodi.arkiv.network/rpc/ws"]
-	} },
-	blockExplorers: { default: {
-		name: "Kaolin Arkiv Explorer",
-		url: "https://explorer.kaolin.hoodi.arkiv.network",
-		apiUrl: "https://explorer.kaolin.hoodi.arkiv.network/api"
-	} },
-	testnet: true
-});
-
-//#endregion
-//#region src/chains/localhost.ts
-const localhost = (0, viem.defineChain)({
-	id: 1337,
-	name: "Localhost",
-	nativeCurrency: {
-		decimals: 18,
-		name: "Ether",
-		symbol: "ETH"
-	},
-	rpcUrls: { default: { http: ["http://127.0.0.1:8545"] } }
-});
-
-//#endregion
-//#region src/chains/index.ts
-var chains_exports = /* @__PURE__ */ __export({
-	braga: () => braga,
-	kaolin: () => kaolin,
-	localhost: () => localhost
-});
-
-//#endregion
-Object.defineProperty(exports, 'braga', {
-  enumerable: true,
-  get: function () {
-    return braga;
-  }
-});
-Object.defineProperty(exports, 'chains_exports', {
-  enumerable: true,
-  get: function () {
-    return chains_exports;
-  }
-});
-Object.defineProperty(exports, 'kaolin', {
-  enumerable: true,
-  get: function () {
-    return kaolin;
-  }
-});
-Object.defineProperty(exports, 'localhost', {
-  enumerable: true,
-  get: function () {
-    return localhost;
-  }
-});

package/dist/chains-CrtkVbBh.js

@@ -1,86 +0,0 @@
-import { defineChain } from "viem";
-
-//#region rolldown:runtime
-var __defProp = Object.defineProperty;
-var __export = (all) => {
-	let target = {};
-	for (var name in all) __defProp(target, name, {
-		get: all[name],
-		enumerable: true
-	});
-	return target;
-};
-
-//#endregion
-//#region src/chains/braga.ts
-const braga = defineChain({
-	id: 60138453102,
-	name: "Braga",
-	network: "braga",
-	nativeCurrency: {
-		name: "Golem",
-		symbol: "GLM",
-		decimals: 18
-	},
-	rpcUrls: { default: {
-		http: ["https://braga.hoodi.arkiv.network/rpc"],
-		webSocket: ["wss://braga.hoodi.arkiv.network/rpc/ws"]
-	} },
-	blockExplorers: { default: {
-		name: "Braga Arkiv Explorer",
-		url: "https://explorer.braga.hoodi.arkiv.network",
-		apiUrl: "https://explorer.braga.hoodi.arkiv.network/api"
-	} },
-	testnet: true
-});
-
-//#endregion
-//#region src/chains/kaolin.ts
-/**
-* @deprecated The kaolin network is getting removed on may 15th 2026. Migration guide: https://docs.arkiv.network/networks/migrate-from-kaolin/
-*/
-const kaolin = defineChain({
-	id: 60138453025,
-	name: "Kaolin",
-	network: "kaolin",
-	nativeCurrency: {
-		name: "Ethereum",
-		symbol: "ETH",
-		decimals: 18
-	},
-	rpcUrls: { default: {
-		http: ["https://kaolin.hoodi.arkiv.network/rpc"],
-		webSocket: ["wss://kaolin.hoodi.arkiv.network/rpc/ws"]
-	} },
-	blockExplorers: { default: {
-		name: "Kaolin Arkiv Explorer",
-		url: "https://explorer.kaolin.hoodi.arkiv.network",
-		apiUrl: "https://explorer.kaolin.hoodi.arkiv.network/api"
-	} },
-	testnet: true
-});
-
-//#endregion
-//#region src/chains/localhost.ts
-const localhost = defineChain({
-	id: 1337,
-	name: "Localhost",
-	nativeCurrency: {
-		decimals: 18,
-		name: "Ether",
-		symbol: "ETH"
-	},
-	rpcUrls: { default: { http: ["http://127.0.0.1:8545"] } }
-});
-
-//#endregion
-//#region src/chains/index.ts
-var chains_exports = /* @__PURE__ */ __export({
-	braga: () => braga,
-	kaolin: () => kaolin,
-	localhost: () => localhost
-});
-
-//#endregion
-export { braga as i, localhost as n, kaolin as r, chains_exports as t };
-//# sourceMappingURL=chains-CrtkVbBh.js.map

package/dist/chains-CrtkVbBh.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"chains-CrtkVbBh.js","names":[],"sources":["../src/chains/braga.ts","../src/chains/kaolin.ts","../src/chains/localhost.ts","../src/chains/index.ts"],"sourcesContent":["import { defineChain } from \"viem\"\n\nexport const braga = defineChain({\n  id: 60138453102,\n  name: \"Braga\",\n  network: \"braga\",\n  nativeCurrency: {\n    name: \"Golem\",\n    symbol: \"GLM\",\n    decimals: 18,\n  },\n  rpcUrls: {\n    default: {\n      http: [\"https://braga.hoodi.arkiv.network/rpc\"],\n      webSocket: [\"wss://braga.hoodi.arkiv.network/rpc/ws\"],\n    },\n  },\n  blockExplorers: {\n    default: {\n      name: \"Braga Arkiv Explorer\",\n      url: \"https://explorer.braga.hoodi.arkiv.network\",\n      apiUrl: \"https://explorer.braga.hoodi.arkiv.network/api\",\n    },\n  },\n  testnet: true,\n})\n","import { defineChain } from \"viem\"\n\n/**\n * @deprecated The kaolin network is getting removed on may 15th 2026. Migration guide: https://docs.arkiv.network/networks/migrate-from-kaolin/\n */\nexport const kaolin = defineChain({\n  id: 60138453025,\n  name: \"Kaolin\",\n  network: \"kaolin\",\n  nativeCurrency: {\n    name: \"Ethereum\",\n    symbol: \"ETH\",\n    decimals: 18,\n  },\n  rpcUrls: {\n    default: {\n      http: [\"https://kaolin.hoodi.arkiv.network/rpc\"],\n      webSocket: [\"wss://kaolin.hoodi.arkiv.network/rpc/ws\"],\n    },\n  },\n  blockExplorers: {\n    default: {\n      name: \"Kaolin Arkiv Explorer\",\n      url: \"https://explorer.kaolin.hoodi.arkiv.network\",\n      apiUrl: \"https://explorer.kaolin.hoodi.arkiv.network/api\",\n    },\n  },\n  testnet: true,\n})\n","import { defineChain } from \"viem\"\n\nexport const localhost = defineChain({\n  id: 1337,\n  name: \"Localhost\",\n  nativeCurrency: {\n    decimals: 18,\n    name: \"Ether\",\n    symbol: \"ETH\",\n  },\n  rpcUrls: {\n    default: { http: [\"http://127.0.0.1:8545\"] },\n  },\n})\n","export { braga } from \"./braga\"\nexport { kaolin } from \"./kaolin\"\nexport { localhost } from \"./localhost\"\n"],"mappings":";;;;;;;;;;;;;;;AAEA,MAAa,QAAQ,YAAY;CAC/B,IAAI;CACJ,MAAM;CACN,SAAS;CACT,gBAAgB;EACd,MAAM;EACN,QAAQ;EACR,UAAU;EACX;CACD,SAAS,EACP,SAAS;EACP,MAAM,CAAC,wCAAwC;EAC/C,WAAW,CAAC,yCAAyC;EACtD,EACF;CACD,gBAAgB,EACd,SAAS;EACP,MAAM;EACN,KAAK;EACL,QAAQ;EACT,EACF;CACD,SAAS;CACV,CAAC;;;;;;;ACpBF,MAAa,SAAS,YAAY;CAChC,IAAI;CACJ,MAAM;CACN,SAAS;CACT,gBAAgB;EACd,MAAM;EACN,QAAQ;EACR,UAAU;EACX;CACD,SAAS,EACP,SAAS;EACP,MAAM,CAAC,yCAAyC;EAChD,WAAW,CAAC,0CAA0C;EACvD,EACF;CACD,gBAAgB,EACd,SAAS;EACP,MAAM;EACN,KAAK;EACL,QAAQ;EACT,EACF;CACD,SAAS;CACV,CAAC;;;;AC1BF,MAAa,YAAY,YAAY;CACnC,IAAI;CACJ,MAAM;CACN,gBAAgB;EACd,UAAU;EACV,MAAM;EACN,QAAQ;EACT;CACD,SAAS,EACP,SAAS,EAAE,MAAM,CAAC,wBAAwB,EAAE,EAC7C;CACF,CAAC"}

package/dist/consts-Bz0LZQZY.js

@@ -1,7 +0,0 @@
-//#region src/consts.ts
-const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044";
-const BLOCK_TIME = 2;
-
-//#endregion
-export { BLOCK_TIME as n, ARKIV_ADDRESS as t };
-//# sourceMappingURL=consts-Bz0LZQZY.js.map

package/dist/consts-Bz0LZQZY.js.map

@@ -1 +0,0 @@
-{"version":3,"file":"consts-Bz0LZQZY.js","names":[],"sources":["../src/consts.ts"],"sourcesContent":["//export const ARKIV_ADDRESS = \"0x00000000000000000000000000000061726b6976\" as `0x${string}`\nexport const ARKIV_ADDRESS = \"0x4400000000000000000000000000000000000044\" as `0x${string}`\nexport const BLOCK_TIME = 2 // 2 seconds\n"],"mappings":";AACA,MAAa,gBAAgB;AAC7B,MAAa,aAAa"}

package/dist/consts-CxT1-RXU.cjs

@@ -1,18 +0,0 @@
-
-//#region src/consts.ts
-const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044";
-const BLOCK_TIME = 2;
-
-//#endregion
-Object.defineProperty(exports, 'ARKIV_ADDRESS', {
-  enumerable: true,
-  get: function () {
-    return ARKIV_ADDRESS;
-  }
-});
-Object.defineProperty(exports, 'BLOCK_TIME', {
-  enumerable: true,
-  get: function () {
-    return BLOCK_TIME;
-  }
-});

package/dist/entity-BhSXaB23.cjs

@@ -1,81 +0,0 @@
-let viem = require("viem");
-
-//#region src/types/entity.ts
-let EntityOperationType = /* @__PURE__ */ function(EntityOperationType$1) {
-	EntityOperationType$1[EntityOperationType$1["Create"] = 1] = "Create";
-	EntityOperationType$1[EntityOperationType$1["Update"] = 2] = "Update";
-	EntityOperationType$1[EntityOperationType$1["Extend"] = 3] = "Extend";
-	EntityOperationType$1[EntityOperationType$1["Transfer"] = 4] = "Transfer";
-	EntityOperationType$1[EntityOperationType$1["Delete"] = 5] = "Delete";
-	EntityOperationType$1[EntityOperationType$1["Expire"] = 6] = "Expire";
-	return EntityOperationType$1;
-}({});
-var Entity = class {
-	key;
-	contentType;
-	owner;
-	creator;
-	expiresAtBlock;
-	createdAtBlock;
-	lastModifiedAtBlock;
-	transactionIndexInBlock;
-	operationIndexInTransaction;
-	payload;
-	attributes;
-	constructor(key, contentType = void 0, owner = void 0, creator = void 0, expiresAtBlock = void 0, createdAtBlock = void 0, lastModifiedAtBlock = void 0, transactionIndexInBlock = void 0, operationIndexInTransaction = void 0, payload = void 0, attributes) {
-		this.key = key;
-		this.owner = owner;
-		this.creator = creator;
-		this.expiresAtBlock = expiresAtBlock;
-		this.createdAtBlock = createdAtBlock;
-		this.lastModifiedAtBlock = lastModifiedAtBlock;
-		this.transactionIndexInBlock = transactionIndexInBlock;
-		this.operationIndexInTransaction = operationIndexInTransaction;
-		this.payload = payload;
-		this.attributes = attributes;
-		this.contentType = contentType;
-	}
-	/**
-	* Converts the entity payload from bytes to a string and returns it.
-	* Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-	* Throws an error if the conversion from bytes to string fails.
-	* @returns The entity payload as a string.
-	*/
-	toText() {
-		if (this.payload === void 0) throw new Error("Entity has no payload – it was probably queried without withPayload(true) via QueryBuilder");
-		try {
-			return (0, viem.bytesToString)(this.payload);
-		} catch (e) {
-			throw new Error(`Failed to convert entity payload to text: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
-		}
-	}
-	/**
-	* Parses the entity payload as JSON and returns the resulting object.
-	* Throws an error if the payload is undefined, which may occur if the entity was not queried with the withPayload option.
-	* Throws an error if the payload is empty or cannot be parsed as JSON.
-	* @returns The parsed JSON object from the entity payload.
-	*/
-	toJson() {
-		const text = this.toText();
-		if (!text) throw new Error("Entity has empty payload, cannot parse as JSON");
-		try {
-			return JSON.parse(text);
-		} catch (e) {
-			throw new Error(`Failed to parse entity payload as JSON: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
-		}
-	}
-};
-
-//#endregion
-Object.defineProperty(exports, 'Entity', {
-  enumerable: true,
-  get: function () {
-    return Entity;
-  }
-});
-Object.defineProperty(exports, 'EntityOperationType', {
-  enumerable: true,
-  get: function () {
-    return EntityOperationType;
-  }
-});