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

package/dist/entity-BIp_df9u.js

@@ -0,0 +1,67 @@
+import { bytesToString } from "viem";
+
+//#region src/types/entity.ts
+/**
+* An entity as it comes back from a query.
+*
+* Which fields are populated is decided by the query's selection — `select({ key: true })` gives
+* back an entity carrying only its key. The static type of a `select()` result is narrowed to
+* exactly the selected fields, so in typed code the `undefined`s here are not reachable.
+*/
+var Entity = class {
+	key;
+	owner;
+	creator;
+	createdAt;
+	updatedAt;
+	expiresAt;
+	creationFlags;
+	contentType;
+	payload;
+	attributeSchema;
+	attributes;
+	constructor(fields = {}) {
+		this.key = fields.key;
+		this.owner = fields.owner;
+		this.creator = fields.creator;
+		this.createdAt = fields.createdAt;
+		this.updatedAt = fields.updatedAt;
+		this.expiresAt = fields.expiresAt;
+		this.creationFlags = fields.creationFlags;
+		this.contentType = fields.contentType;
+		this.payload = fields.payload;
+		this.attributeSchema = fields.attributeSchema;
+		this.attributes = fields.attributes;
+	}
+	/**
+	* The payload decoded as UTF-8 text.
+	*
+	* @throws If the payload was not selected, or is not valid UTF-8.
+	*/
+	toText() {
+		if (this.payload === void 0) throw new Error("Entity has no payload — the query did not select it. Use select({ payload: true }).");
+		try {
+			return bytesToString(this.payload);
+		} catch (e) {
+			throw new Error(`Failed to convert entity payload to text: ${e instanceof Error ? e.message : String(e)}`, { cause: e });
+		}
+	}
+	/**
+	* The payload parsed as JSON.
+	*
+	* @throws If the payload was not selected, is empty, or is not valid JSON.
+	*/
+	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
+export { Entity as t };
+//# sourceMappingURL=entity-BIp_df9u.js.map

package/dist/entity-BIp_df9u.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-BIp_df9u.js","names":[],"sources":["../src/types/entity.ts"],"sourcesContent":["import { bytesToString, type Hex } from \"viem\"\nimport type { AttributeSchema, Attributes } from \"../attr\"\nimport type { ResolvedCreationFlags } from \"../entity/flags\"\n\n/**\n * The fields an {@link Entity} can carry. Every one is optional: a query returns exactly the parts\n * it selected, and `undefined` means \"not asked for\" rather than \"empty\".\n */\nexport type EntityFields = {\n  key?: Hex | undefined\n  owner?: Hex | undefined\n  creator?: Hex | undefined\n  /** Block the entity was created at. */\n  createdAt?: bigint | undefined\n  /** Block the entity was last patched at. */\n  updatedAt?: bigint | undefined\n  /** Block the entity expires at. */\n  expiresAt?: bigint | undefined\n  /** The immutable properties the entity was created with. */\n  creationFlags?: ResolvedCreationFlags | undefined\n  contentType?: string | undefined\n  payload?: Uint8Array | undefined\n  /** Attribute names and types, with no values. */\n  attributeSchema?: AttributeSchema | undefined\n  /** Attribute names, types and values. */\n  attributes?: Attributes | undefined\n}\n\n/**\n * An entity as it comes back from a query.\n *\n * Which fields are populated is decided by the query's selection — `select({ key: true })` gives\n * back an entity carrying only its key. The static type of a `select()` result is narrowed to\n * exactly the selected fields, so in typed code the `undefined`s here are not reachable.\n */\nexport class Entity implements EntityFields {\n  key: Hex | undefined\n  owner: Hex | undefined\n  creator: Hex | undefined\n  createdAt: bigint | undefined\n  updatedAt: bigint | undefined\n  expiresAt: bigint | undefined\n  creationFlags: ResolvedCreationFlags | undefined\n  contentType: string | undefined\n  payload: Uint8Array | undefined\n  attributeSchema: AttributeSchema | undefined\n  attributes: Attributes | undefined\n\n  constructor(fields: EntityFields = {}) {\n    this.key = fields.key\n    this.owner = fields.owner\n    this.creator = fields.creator\n    this.createdAt = fields.createdAt\n    this.updatedAt = fields.updatedAt\n    this.expiresAt = fields.expiresAt\n    this.creationFlags = fields.creationFlags\n    this.contentType = fields.contentType\n    this.payload = fields.payload\n    this.attributeSchema = fields.attributeSchema\n    this.attributes = fields.attributes\n  }\n\n  /**\n   * The payload decoded as UTF-8 text.\n   *\n   * @throws If the payload was not selected, or is not valid UTF-8.\n   */\n  toText(): string {\n    if (this.payload === undefined) {\n      throw new Error(\n        \"Entity has no payload — the query did not select it. Use select({ payload: true }).\",\n      )\n    }\n    try {\n      return bytesToString(this.payload)\n    } catch (e) {\n      throw new Error(\n        `Failed to convert entity payload to text: ${e instanceof Error ? e.message : String(e)}`,\n        { cause: e },\n      )\n    }\n  }\n\n  /**\n   * The payload parsed as JSON.\n   *\n   * @throws If the payload was not selected, is empty, or is not valid JSON.\n   */\n  // biome-ignore lint/suspicious/noExplicitAny: JSON.parse returns whatever the payload holds.\n  toJson(): any {\n    const text = this.toText()\n    if (!text) {\n      throw new Error(\"Entity has empty payload, cannot parse as JSON\")\n    }\n    try {\n      return JSON.parse(text)\n    } catch (e) {\n      throw new Error(\n        `Failed to parse entity payload as JSON: ${e instanceof Error ? e.message : String(e)}`,\n        { cause: e },\n      )\n    }\n  }\n}\n"],"mappings":";;;;;;;;;;AAmCA,IAAa,SAAb,MAA4C;CAC1C;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CACA;CAEA,YAAY,SAAuB,EAAE,EAAE;AACrC,OAAK,MAAM,OAAO;AAClB,OAAK,QAAQ,OAAO;AACpB,OAAK,UAAU,OAAO;AACtB,OAAK,YAAY,OAAO;AACxB,OAAK,YAAY,OAAO;AACxB,OAAK,YAAY,OAAO;AACxB,OAAK,gBAAgB,OAAO;AAC5B,OAAK,cAAc,OAAO;AAC1B,OAAK,UAAU,OAAO;AACtB,OAAK,kBAAkB,OAAO;AAC9B,OAAK,aAAa,OAAO;;;;;;;CAQ3B,SAAiB;AACf,MAAI,KAAK,YAAY,OACnB,OAAM,IAAI,MACR,sFACD;AAEH,MAAI;AACF,UAAO,cAAc,KAAK,QAAQ;WAC3B,GAAG;AACV,SAAM,IAAI,MACR,6CAA6C,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,IACvF,EAAE,OAAO,GAAG,CACb;;;;;;;;CAUL,SAAc;EACZ,MAAM,OAAO,KAAK,QAAQ;AAC1B,MAAI,CAAC,KACH,OAAM,IAAI,MAAM,iDAAiD;AAEnE,MAAI;AACF,UAAO,KAAK,MAAM,KAAK;WAChB,GAAG;AACV,SAAM,IAAI,MACR,2CAA2C,aAAa,QAAQ,EAAE,UAAU,OAAO,EAAE,IACrF,EAAE,OAAO,GAAG,CACb"}

package/dist/entity-CFhbAv0R.js

@@ -0,0 +1,70 @@
+import { i as NoRandomSourceError, r as InvalidSaltError } from "./errors-DGB8AgT2.js";
+import { o as ARKIV_ADDRESS } from "./expiry-DGRzrSan.js";
+import { encodePacked, keccak256, parseAbi } from "viem";
+
+//#region src/entity/key.ts
+/** The widest salt the `uint128` wire field carries. */
+const MAX_SALT = 2n ** 128n - 1n;
+/**
+* A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
+*
+* The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees
+* distinct keys. Random bits mean only the creator can predict the key of an entity they are about
+* to create, so nobody else can reference or squat it in advance.
+*
+* @throws {NoRandomSourceError} If the runtime has no `crypto.getRandomValues`.
+*/
+function randomSalt() {
+	const source = globalThis.crypto;
+	if (typeof source?.getRandomValues !== "function") throw new NoRandomSourceError();
+	const bytes = source.getRandomValues(new Uint8Array(16));
+	let salt = 0n;
+	for (const byte of bytes) salt = salt << 8n | BigInt(byte);
+	return salt;
+}
+/** Validates a caller-supplied salt against the `uint128` wire field. */
+function validateSalt(salt) {
+	if (typeof salt !== "bigint" || salt < 0n || salt > MAX_SALT) throw new InvalidSaltError(salt);
+	return salt;
+}
+/**
+* The key an entity will be created with, derived exactly as the engine derives it:
+* `keccak256(domain ++ owner ++ nonce ++ salt)`.
+*
+* Deriving it client-side is what lets a batch compose: predict the key of a create, then have a
+* later operation in the same transaction reference it, or store it as a `key` attribute on a
+* sibling entity.
+*/
+function predictEntityKey({ owner, nonce, salt, chainId }) {
+	return keccak256(encodePacked([
+		"uint256",
+		"address",
+		"address",
+		"uint64",
+		"uint128"
+	], [
+		BigInt(chainId),
+		ARKIV_ADDRESS,
+		owner,
+		nonce,
+		validateSalt(salt)
+	]));
+}
+
+//#endregion
+//#region src/entity/events.ts
+/**
+* The events the engine emits: one per applied operation, in application order, so an off-chain
+* replica can replay a transaction operation by operation.
+*/
+const ENTITY_EVENTS_ABI = parseAbi([
+	"event EntityCreated(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt, uint8 creationFlags)",
+	"event EntityPatched(bytes32 indexed entityKey, address indexed owner)",
+	"event ExpiryExtended(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt)",
+	"event OwnershipTransferred(bytes32 indexed entityKey, address indexed previousOwner, address indexed newOwner)",
+	"event EntityDeleted(bytes32 indexed entityKey, address indexed owner)"
+]);
+
+//#endregion
+export { validateSalt as a, randomSalt as i, MAX_SALT as n, predictEntityKey as r, ENTITY_EVENTS_ABI as t };
+//# sourceMappingURL=entity-CFhbAv0R.js.map

package/dist/entity-CFhbAv0R.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"entity-CFhbAv0R.js","names":[],"sources":["../src/entity/key.ts","../src/entity/events.ts"],"sourcesContent":["import { type Address, encodePacked, type Hex, keccak256 } from \"viem\"\nimport { ARKIV_ADDRESS } from \"../consts\"\nimport { InvalidSaltError, NoRandomSourceError } from \"./errors\"\n\n/** The widest salt the `uint128` wire field carries. */\nexport const MAX_SALT = 2n ** 128n - 1n\n\n/**\n * A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.\n *\n * The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees\n * distinct keys. Random bits mean only the creator can predict the key of an entity they are about\n * to create, so nobody else can reference or squat it in advance.\n *\n * @throws {NoRandomSourceError} If the runtime has no `crypto.getRandomValues`.\n */\nexport function randomSalt(): bigint {\n  const source = globalThis.crypto\n  if (typeof source?.getRandomValues !== \"function\") {\n    throw new NoRandomSourceError()\n  }\n  const bytes = source.getRandomValues(new Uint8Array(16))\n  let salt = 0n\n  for (const byte of bytes) salt = (salt << 8n) | BigInt(byte)\n  return salt\n}\n\n/** Validates a caller-supplied salt against the `uint128` wire field. */\nexport function validateSalt(salt: bigint): bigint {\n  if (typeof salt !== \"bigint\" || salt < 0n || salt > MAX_SALT) {\n    throw new InvalidSaltError(salt)\n  }\n  return salt\n}\n\n/**\n * The key an entity will be created with, derived exactly as the engine derives it:\n * `keccak256(domain ++ owner ++ nonce ++ salt)`.\n *\n * Deriving it client-side is what lets a batch compose: predict the key of a create, then have a\n * later operation in the same transaction reference it, or store it as a `key` attribute on a\n * sibling entity.\n */\nexport function predictEntityKey({\n  owner,\n  nonce,\n  salt,\n  chainId,\n}: {\n  /** The account creating the entity. */\n  owner: Address\n  /**\n   * The owner's entity-nonce at creation time. Each create in a batch consumes one, so the *n*th\n   * create in a batch uses `nonce + n`.\n   */\n  nonce: bigint\n  /** The salt the create will carry. */\n  salt: bigint\n  /** The chain the entity is being created on — half of the derivation domain. */\n  chainId: number\n}): Hex {\n  return keccak256(\n    encodePacked(\n      [\"uint256\", \"address\", \"address\", \"uint64\", \"uint128\"],\n      [BigInt(chainId), ARKIV_ADDRESS, owner, nonce, validateSalt(salt)],\n    ),\n  )\n}\n","import { parseAbi } from \"viem\"\n\n/**\n * The events the engine emits: one per applied operation, in application order, so an off-chain\n * replica can replay a transaction operation by operation.\n */\nexport const ENTITY_EVENTS_ABI = parseAbi([\n  \"event EntityCreated(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt, uint8 creationFlags)\",\n  \"event EntityPatched(bytes32 indexed entityKey, address indexed owner)\",\n  \"event ExpiryExtended(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt)\",\n  \"event OwnershipTransferred(bytes32 indexed entityKey, address indexed previousOwner, address indexed newOwner)\",\n  \"event EntityDeleted(bytes32 indexed entityKey, address indexed owner)\",\n])\n\n/** The name of each event in {@link ENTITY_EVENTS_ABI}. */\nexport type EntityEventName = (typeof ENTITY_EVENTS_ABI)[number][\"name\"]\n"],"mappings":";;;;;;AAKA,MAAa,WAAW,MAAM,OAAO;;;;;;;;;;AAWrC,SAAgB,aAAqB;CACnC,MAAM,SAAS,WAAW;AAC1B,KAAI,OAAO,QAAQ,oBAAoB,WACrC,OAAM,IAAI,qBAAqB;CAEjC,MAAM,QAAQ,OAAO,gBAAgB,IAAI,WAAW,GAAG,CAAC;CACxD,IAAI,OAAO;AACX,MAAK,MAAM,QAAQ,MAAO,QAAQ,QAAQ,KAAM,OAAO,KAAK;AAC5D,QAAO;;;AAIT,SAAgB,aAAa,MAAsB;AACjD,KAAI,OAAO,SAAS,YAAY,OAAO,MAAM,OAAO,SAClD,OAAM,IAAI,iBAAiB,KAAK;AAElC,QAAO;;;;;;;;;;AAWT,SAAgB,iBAAiB,EAC/B,OACA,OACA,MACA,WAaM;AACN,QAAO,UACL,aACE;EAAC;EAAW;EAAW;EAAW;EAAU;EAAU,EACtD;EAAC,OAAO,QAAQ;EAAE;EAAe;EAAO;EAAO,aAAa,KAAK;EAAC,CACnE,CACF;;;;;;;;;AC5DH,MAAa,oBAAoB,SAAS;CACxC;CACA;CACA;CACA;CACA;CACD,CAAC"}

package/dist/entity-wfBnZd91.cjs

@@ -0,0 +1,98 @@
+const require_errors = require('./errors-D-eJkGVc.cjs');
+const require_expiry = require('./expiry-BUYIXTGb.cjs');
+let viem = require("viem");
+
+//#region src/entity/key.ts
+/** The widest salt the `uint128` wire field carries. */
+const MAX_SALT = 2n ** 128n - 1n;
+/**
+* A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
+*
+* The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees
+* distinct keys. Random bits mean only the creator can predict the key of an entity they are about
+* to create, so nobody else can reference or squat it in advance.
+*
+* @throws {NoRandomSourceError} If the runtime has no `crypto.getRandomValues`.
+*/
+function randomSalt() {
+	const source = globalThis.crypto;
+	if (typeof source?.getRandomValues !== "function") throw new require_errors.NoRandomSourceError();
+	const bytes = source.getRandomValues(new Uint8Array(16));
+	let salt = 0n;
+	for (const byte of bytes) salt = salt << 8n | BigInt(byte);
+	return salt;
+}
+/** Validates a caller-supplied salt against the `uint128` wire field. */
+function validateSalt(salt) {
+	if (typeof salt !== "bigint" || salt < 0n || salt > MAX_SALT) throw new require_errors.InvalidSaltError(salt);
+	return salt;
+}
+/**
+* The key an entity will be created with, derived exactly as the engine derives it:
+* `keccak256(domain ++ owner ++ nonce ++ salt)`.
+*
+* Deriving it client-side is what lets a batch compose: predict the key of a create, then have a
+* later operation in the same transaction reference it, or store it as a `key` attribute on a
+* sibling entity.
+*/
+function predictEntityKey({ owner, nonce, salt, chainId }) {
+	return (0, viem.keccak256)((0, viem.encodePacked)([
+		"uint256",
+		"address",
+		"address",
+		"uint64",
+		"uint128"
+	], [
+		BigInt(chainId),
+		require_expiry.ARKIV_ADDRESS,
+		owner,
+		nonce,
+		validateSalt(salt)
+	]));
+}
+
+//#endregion
+//#region src/entity/events.ts
+/**
+* The events the engine emits: one per applied operation, in application order, so an off-chain
+* replica can replay a transaction operation by operation.
+*/
+const ENTITY_EVENTS_ABI = (0, viem.parseAbi)([
+	"event EntityCreated(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt, uint8 creationFlags)",
+	"event EntityPatched(bytes32 indexed entityKey, address indexed owner)",
+	"event ExpiryExtended(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt)",
+	"event OwnershipTransferred(bytes32 indexed entityKey, address indexed previousOwner, address indexed newOwner)",
+	"event EntityDeleted(bytes32 indexed entityKey, address indexed owner)"
+]);
+
+//#endregion
+Object.defineProperty(exports, 'ENTITY_EVENTS_ABI', {
+  enumerable: true,
+  get: function () {
+    return ENTITY_EVENTS_ABI;
+  }
+});
+Object.defineProperty(exports, 'MAX_SALT', {
+  enumerable: true,
+  get: function () {
+    return MAX_SALT;
+  }
+});
+Object.defineProperty(exports, 'predictEntityKey', {
+  enumerable: true,
+  get: function () {
+    return predictEntityKey;
+  }
+});
+Object.defineProperty(exports, 'randomSalt', {
+  enumerable: true,
+  get: function () {
+    return randomSalt;
+  }
+});
+Object.defineProperty(exports, 'validateSalt', {
+  enumerable: true,
+  get: function () {
+    return validateSalt;
+  }
+});

package/dist/errors-D-eJkGVc.cjs

@@ -0,0 +1,56 @@
+
+//#region src/entity/errors.ts
+/** An expiry could not be expressed, or would be rejected by the engine. */
+var InvalidExpiryError = class extends Error {
+	constructor(reason) {
+		super(`Invalid expiry: ${reason}`);
+		this.name = "InvalidExpiryError";
+	}
+};
+/** A `creationFlags` byte could not be built or read. */
+var InvalidCreationFlagsError = class extends Error {
+	constructor(reason) {
+		super(`Invalid creation flags: ${reason}`);
+		this.name = "InvalidCreationFlagsError";
+	}
+};
+/** A key salt was outside the `uint128` the wire carries. */
+var InvalidSaltError = class extends Error {
+	constructor(salt) {
+		super(`Invalid salt ${salt}. A salt is a uint128, so it must be between 0 and ${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass 0 for a predictable key.`);
+		this.name = "InvalidSaltError";
+	}
+};
+/** No cryptographic randomness was available to generate a salt. */
+var NoRandomSourceError = class extends Error {
+	constructor() {
+		super("No cryptographic random source is available (globalThis.crypto.getRandomValues is missing), so a key salt cannot be generated. Upgrade to Node 18+ or a modern browser, or pass an explicit salt.");
+		this.name = "NoRandomSourceError";
+	}
+};
+
+//#endregion
+Object.defineProperty(exports, 'InvalidCreationFlagsError', {
+  enumerable: true,
+  get: function () {
+    return InvalidCreationFlagsError;
+  }
+});
+Object.defineProperty(exports, 'InvalidExpiryError', {
+  enumerable: true,
+  get: function () {
+    return InvalidExpiryError;
+  }
+});
+Object.defineProperty(exports, 'InvalidSaltError', {
+  enumerable: true,
+  get: function () {
+    return InvalidSaltError;
+  }
+});
+Object.defineProperty(exports, 'NoRandomSourceError', {
+  enumerable: true,
+  get: function () {
+    return NoRandomSourceError;
+  }
+});

package/dist/errors-DGB8AgT2.js

@@ -0,0 +1,33 @@
+//#region src/entity/errors.ts
+/** An expiry could not be expressed, or would be rejected by the engine. */
+var InvalidExpiryError = class extends Error {
+	constructor(reason) {
+		super(`Invalid expiry: ${reason}`);
+		this.name = "InvalidExpiryError";
+	}
+};
+/** A `creationFlags` byte could not be built or read. */
+var InvalidCreationFlagsError = class extends Error {
+	constructor(reason) {
+		super(`Invalid creation flags: ${reason}`);
+		this.name = "InvalidCreationFlagsError";
+	}
+};
+/** A key salt was outside the `uint128` the wire carries. */
+var InvalidSaltError = class extends Error {
+	constructor(salt) {
+		super(`Invalid salt ${salt}. A salt is a uint128, so it must be between 0 and ${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass 0 for a predictable key.`);
+		this.name = "InvalidSaltError";
+	}
+};
+/** No cryptographic randomness was available to generate a salt. */
+var NoRandomSourceError = class extends Error {
+	constructor() {
+		super("No cryptographic random source is available (globalThis.crypto.getRandomValues is missing), so a key salt cannot be generated. Upgrade to Node 18+ or a modern browser, or pass an explicit salt.");
+		this.name = "NoRandomSourceError";
+	}
+};
+
+//#endregion
+export { NoRandomSourceError as i, InvalidExpiryError as n, InvalidSaltError as r, InvalidCreationFlagsError as t };
+//# sourceMappingURL=errors-DGB8AgT2.js.map

package/dist/errors-DGB8AgT2.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors-DGB8AgT2.js","names":[],"sources":["../src/entity/errors.ts"],"sourcesContent":["/** An expiry could not be expressed, or would be rejected by the engine. */\nexport class InvalidExpiryError extends Error {\n  constructor(reason: string) {\n    super(`Invalid expiry: ${reason}`)\n    this.name = \"InvalidExpiryError\"\n  }\n}\n\n/** A `creationFlags` byte could not be built or read. */\nexport class InvalidCreationFlagsError extends Error {\n  constructor(reason: string) {\n    super(`Invalid creation flags: ${reason}`)\n    this.name = \"InvalidCreationFlagsError\"\n  }\n}\n\n/** A key salt was outside the `uint128` the wire carries. */\nexport class InvalidSaltError extends Error {\n  constructor(salt: bigint) {\n    super(\n      `Invalid salt ${salt}. A salt is a uint128, so it must be between 0 and ` +\n        `${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass 0 for a predictable key.`,\n    )\n    this.name = \"InvalidSaltError\"\n  }\n}\n\n/** No cryptographic randomness was available to generate a salt. */\nexport class NoRandomSourceError extends Error {\n  constructor() {\n    super(\n      \"No cryptographic random source is available (globalThis.crypto.getRandomValues is \" +\n        \"missing), so a key salt cannot be generated. Upgrade to Node 18+ or a modern browser, \" +\n        \"or pass an explicit salt.\",\n    )\n    this.name = \"NoRandomSourceError\"\n  }\n}\n"],"mappings":";;AACA,IAAa,qBAAb,cAAwC,MAAM;CAC5C,YAAY,QAAgB;AAC1B,QAAM,mBAAmB,SAAS;AAClC,OAAK,OAAO;;;;AAKhB,IAAa,4BAAb,cAA+C,MAAM;CACnD,YAAY,QAAgB;AAC1B,QAAM,2BAA2B,SAAS;AAC1C,OAAK,OAAO;;;;AAKhB,IAAa,mBAAb,cAAsC,MAAM;CAC1C,YAAY,MAAc;AACxB,QACE,gBAAgB,KAAK,qDAChB,MAAM,OAAO,GAAG,oEACtB;AACD,OAAK,OAAO;;;;AAKhB,IAAa,sBAAb,cAAyC,MAAM;CAC7C,cAAc;AACZ,QACE,oMAGD;AACD,OAAK,OAAO"}

package/dist/expiry-BUYIXTGb.cjs

@@ -0,0 +1,135 @@
+const require_errors = require('./errors-D-eJkGVc.cjs');
+
+//#region src/consts.ts
+const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044";
+const BLOCK_TIME = 2;
+
+//#endregion
+//#region src/entity/params.ts
+/**
+* Max uint64 value
+*/
+const MAX_EXPIRES_AT = 2n ** 64n - 1n;
+/** The operation tags of the `execute` ABI's tagged union. */
+const OperationType = {
+	Create: 1,
+	Patch: 2,
+	ExtendExpiry: 3,
+	TransferOwnership: 4,
+	Delete: 5
+};
+
+//#endregion
+//#region src/entity/expiry.ts
+/**
+* Builds a branded {@link Expiry}.
+*
+* Internal seam for {@link ExpirationTime}, which is the only thing that should call it — it is not
+* part of the package's public surface.
+*/
+function makeExpiry(minLifetime, expiresAt) {
+	return {
+		minLifetime,
+		expiresAt
+	};
+}
+/**
+* Resolves an expiry into the wire pair and the block the entity will expire at.
+*
+* Durations are converted to blocks at the nominal `BLOCK_TIME` (2 seconds), which makes them
+* **approximate**: block production is not a clock, so a lifetime asked for in days drifts if the
+* chain runs fast or slow. The block it was converted to comes back as
+* {@link ResolvedExpiry.target}, so the approximation is always observable rather than assumed.
+*
+* @throws {InvalidExpiryError} If the expiry is malformed, does not fit the `uint64` the wire
+* carries, or would leave the entity dead on arrival.
+*/
+function resolveExpiry(expiry, context) {
+	const { currentBlock } = context;
+	if (typeof expiry?.minLifetime !== "bigint" || expiry.expiresAt === void 0) throw new require_errors.InvalidExpiryError("expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or ExpirationTime.atBlock(1_200_000n)");
+	const { minLifetime } = expiry;
+	const absolute = typeof expiry.expiresAt === "bigint" ? expiry.expiresAt : blockAtDate(expiry.expiresAt, currentBlock);
+	if (minLifetime === 0n && absolute === 0n) throw new require_errors.InvalidExpiryError("no expiry given. Pass ExpirationTime.fromDays(30) for a lifetime, ExpirationTime.atBlock(n) for an absolute deadline, or a deadline with { atLeast } to take whichever is later.");
+	if (absolute > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`expiresAt resolves to block ${absolute}, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT}). Use ExpirationTime.permanent() for an entity that should not expire.`);
+	if (minLifetime > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`the lifetime is ${minLifetime} blocks, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT})`);
+	const relative = minLifetime === 0n ? 0n : currentBlock + minLifetime;
+	const target = absolute > relative ? absolute : relative;
+	if (target <= currentBlock) throw new require_errors.InvalidExpiryError(`the entity would expire at block ${target}, which is not after the current block ${currentBlock}, so it would be dead on arrival`);
+	if (target > MAX_EXPIRES_AT) throw new require_errors.InvalidExpiryError(`a lifetime of ${minLifetime} blocks from block ${currentBlock} lands at ${target}, past the largest expiry the wire carries (${MAX_EXPIRES_AT})`);
+	return {
+		expiresAt: absolute,
+		minLifetime,
+		target
+	};
+}
+/**
+* A duration in seconds as a whole number of blocks.
+*
+* Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not
+* describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks
+* — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple
+* of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.
+*
+* @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.
+*/
+function toBlocks(seconds) {
+	if (!Number.isInteger(seconds) || seconds <= 0) throw new require_errors.InvalidExpiryError(`a lifetime must be a positive whole number of seconds, got ${seconds}. Use the ExpirationTime helpers, e.g. ExpirationTime.fromDays(30).`);
+	if (seconds % BLOCK_TIME !== 0) throw new require_errors.InvalidExpiryError(`a lifetime must be a multiple of the ${BLOCK_TIME}s block time, got ${seconds}, which is ${seconds / BLOCK_TIME} blocks. Try ${seconds - seconds % BLOCK_TIME} or ${seconds + BLOCK_TIME - seconds % BLOCK_TIME}, or ExpirationTime.fromBlocks(n).`);
+	return BigInt(seconds / BLOCK_TIME);
+}
+/**
+* The block a wall-clock instant lands on.
+*
+* Rounds **up**: a date almost never falls on a block boundary, and unlike a duration — which the
+* caller states and can state exactly — there is nothing here to reject, so the entity lives until
+* at least the instant asked for.
+*/
+function blockAtDate(date, currentBlock) {
+	const secondsAway = (date.getTime() - Date.now()) / 1e3;
+	if (secondsAway <= 0) throw new require_errors.InvalidExpiryError(`the deadline ${date.toISOString()} is in the past, so the entity would be dead on arrival`);
+	return currentBlock + BigInt(Math.ceil(secondsAway / BLOCK_TIME));
+}
+
+//#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;
+  }
+});
+Object.defineProperty(exports, 'MAX_EXPIRES_AT', {
+  enumerable: true,
+  get: function () {
+    return MAX_EXPIRES_AT;
+  }
+});
+Object.defineProperty(exports, 'OperationType', {
+  enumerable: true,
+  get: function () {
+    return OperationType;
+  }
+});
+Object.defineProperty(exports, 'makeExpiry', {
+  enumerable: true,
+  get: function () {
+    return makeExpiry;
+  }
+});
+Object.defineProperty(exports, 'resolveExpiry', {
+  enumerable: true,
+  get: function () {
+    return resolveExpiry;
+  }
+});
+Object.defineProperty(exports, 'toBlocks', {
+  enumerable: true,
+  get: function () {
+    return toBlocks;
+  }
+});

package/dist/expiry-BxOlvVWC.d.ts

@@ -0,0 +1,79 @@
+//#region src/entity/expiry.d.ts
+/**
+ * The brand. Module-private and never exported, so the only way to obtain an {@link Expiry} is to
+ * build one with {@link ExpirationTime} — a hand-written `{ minLifetime, expiresAt }` literal will
+ * not typecheck, and neither will a bare number of seconds.
+ */
+declare const validated: unique symbol;
+/**
+ * How long an entity should live.
+ *
+ * This is the pair the ABI carries, and the engine resolves it as
+ * `max(expiresAt, currentBlock + minLifetime)` — whichever is later. Build one with
+ * {@link ExpirationTime}; there is no other way to make one.
+ *
+ * Which slot a value lands in also decides which rules govern it. `minLifetime` is a duration, so
+ * it must come to a whole number of blocks. `expiresAt` is a block height, which is a whole number
+ * by construction, so a wall-clock date rounds into it rather than being rejected.
+ */
+type Expiry = {
+  /** Lifetime floor in blocks, counted from the block the transaction lands in. `0n` if unset. */
+  readonly minLifetime: bigint;
+  /**
+   * Absolute deadline: a block height, or a `Date` still to be placed against the current block.
+   * `0n` if unset.
+   */
+  readonly expiresAt: bigint | Date;
+  readonly [validated]: true;
+};
+/**
+ * An expiry that is nothing but a duration — what the `ExpirationTime.from*` helpers return.
+ *
+ * Distinguished from a full {@link Expiry} by its `expiresAt` being the literal `0n`, which is what
+ * keeps `atBlock(x, { atLeast: atBlock(y) })` from compiling: a deadline is not a floor.
+ */
+type Lifetime = Expiry & {
+  readonly expiresAt: 0n;
+};
+/** The two `uint256` values the ABI carries, with every `Date` already placed. */
+type EncodedExpiry = {
+  /** Absolute target block height, or `0n` for a purely relative lifetime. */
+  expiresAt: bigint;
+  /** Relative floor in blocks, or `0n` for a purely absolute expiry. */
+  minLifetime: bigint;
+};
+/** What an expiry resolves to, given the chain's current block. */
+type ResolvedExpiry = EncodedExpiry & {
+  /** The block the entity will expire at — `max(expiresAt, currentBlock + minLifetime)`. */
+  target: bigint;
+};
+/** What the SDK needs to know about the chain to resolve an expiry. */
+type ExpiryContext = {
+  currentBlock: bigint;
+};
+/**
+ * Resolves an expiry into the wire pair and the block the entity will expire at.
+ *
+ * Durations are converted to blocks at the nominal `BLOCK_TIME` (2 seconds), which makes them
+ * **approximate**: block production is not a clock, so a lifetime asked for in days drifts if the
+ * chain runs fast or slow. The block it was converted to comes back as
+ * {@link ResolvedExpiry.target}, so the approximation is always observable rather than assumed.
+ *
+ * @throws {InvalidExpiryError} If the expiry is malformed, does not fit the `uint64` the wire
+ * carries, or would leave the entity dead on arrival.
+ */
+declare function resolveExpiry(expiry: Expiry, context: ExpiryContext): ResolvedExpiry;
+/**
+ * A duration in seconds as a whole number of blocks.
+ *
+ * Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not
+ * describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks
+ * — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple
+ * of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.
+ *
+ * @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.
+ */
+declare function toBlocks(seconds: number): bigint;
+//#endregion
+export { ResolvedExpiry as a, Lifetime as i, Expiry as n, resolveExpiry as o, ExpiryContext as r, toBlocks as s, EncodedExpiry as t };
+//# sourceMappingURL=expiry-BxOlvVWC.d.ts.map

package/dist/expiry-BxOlvVWC.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry-BxOlvVWC.d.ts","names":[],"sources":["../src/entity/expiry.ts"],"sourcesContent":[],"mappings":";;;AAsBA;AAiBA;AAaA;AAQA,cAnDc,SAmDY,EAAA,OAAA,MAAG;AAM7B;AAeA;;;;;AAmEA;;;;;KA9HY,MAAA;;;;;;;+BAOmB;YACnB,SAAA;;;;;;;;KASA,QAAA,GAAW;;;;KAaX,aAAA;;;;;;;KAQA,cAAA,GAAiB;;;;;KAMjB,aAAA;;;;;;;;;;;;;;iBAeI,aAAA,SAAsB,iBAAiB,gBAAgB;;;;;;;;;;;iBAmEvD,QAAA"}

package/dist/expiry-DGRzrSan.js

@@ -0,0 +1,95 @@
+import { n as InvalidExpiryError } from "./errors-DGB8AgT2.js";
+
+//#region src/consts.ts
+const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044";
+const BLOCK_TIME = 2;
+
+//#endregion
+//#region src/entity/params.ts
+/**
+* Max uint64 value
+*/
+const MAX_EXPIRES_AT = 2n ** 64n - 1n;
+/** The operation tags of the `execute` ABI's tagged union. */
+const OperationType = {
+	Create: 1,
+	Patch: 2,
+	ExtendExpiry: 3,
+	TransferOwnership: 4,
+	Delete: 5
+};
+
+//#endregion
+//#region src/entity/expiry.ts
+/**
+* Builds a branded {@link Expiry}.
+*
+* Internal seam for {@link ExpirationTime}, which is the only thing that should call it — it is not
+* part of the package's public surface.
+*/
+function makeExpiry(minLifetime, expiresAt) {
+	return {
+		minLifetime,
+		expiresAt
+	};
+}
+/**
+* Resolves an expiry into the wire pair and the block the entity will expire at.
+*
+* Durations are converted to blocks at the nominal `BLOCK_TIME` (2 seconds), which makes them
+* **approximate**: block production is not a clock, so a lifetime asked for in days drifts if the
+* chain runs fast or slow. The block it was converted to comes back as
+* {@link ResolvedExpiry.target}, so the approximation is always observable rather than assumed.
+*
+* @throws {InvalidExpiryError} If the expiry is malformed, does not fit the `uint64` the wire
+* carries, or would leave the entity dead on arrival.
+*/
+function resolveExpiry(expiry, context) {
+	const { currentBlock } = context;
+	if (typeof expiry?.minLifetime !== "bigint" || expiry.expiresAt === void 0) throw new InvalidExpiryError("expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or ExpirationTime.atBlock(1_200_000n)");
+	const { minLifetime } = expiry;
+	const absolute = typeof expiry.expiresAt === "bigint" ? expiry.expiresAt : blockAtDate(expiry.expiresAt, currentBlock);
+	if (minLifetime === 0n && absolute === 0n) throw new InvalidExpiryError("no expiry given. Pass ExpirationTime.fromDays(30) for a lifetime, ExpirationTime.atBlock(n) for an absolute deadline, or a deadline with { atLeast } to take whichever is later.");
+	if (absolute > MAX_EXPIRES_AT) throw new InvalidExpiryError(`expiresAt resolves to block ${absolute}, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT}). Use ExpirationTime.permanent() for an entity that should not expire.`);
+	if (minLifetime > MAX_EXPIRES_AT) throw new InvalidExpiryError(`the lifetime is ${minLifetime} blocks, which does not fit the uint64 the wire carries (max ${MAX_EXPIRES_AT})`);
+	const relative = minLifetime === 0n ? 0n : currentBlock + minLifetime;
+	const target = absolute > relative ? absolute : relative;
+	if (target <= currentBlock) throw new InvalidExpiryError(`the entity would expire at block ${target}, which is not after the current block ${currentBlock}, so it would be dead on arrival`);
+	if (target > MAX_EXPIRES_AT) throw new InvalidExpiryError(`a lifetime of ${minLifetime} blocks from block ${currentBlock} lands at ${target}, past the largest expiry the wire carries (${MAX_EXPIRES_AT})`);
+	return {
+		expiresAt: absolute,
+		minLifetime,
+		target
+	};
+}
+/**
+* A duration in seconds as a whole number of blocks.
+*
+* Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not
+* describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks
+* — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple
+* of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.
+*
+* @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.
+*/
+function toBlocks(seconds) {
+	if (!Number.isInteger(seconds) || seconds <= 0) throw new InvalidExpiryError(`a lifetime must be a positive whole number of seconds, got ${seconds}. Use the ExpirationTime helpers, e.g. ExpirationTime.fromDays(30).`);
+	if (seconds % BLOCK_TIME !== 0) throw new InvalidExpiryError(`a lifetime must be a multiple of the ${BLOCK_TIME}s block time, got ${seconds}, which is ${seconds / BLOCK_TIME} blocks. Try ${seconds - seconds % BLOCK_TIME} or ${seconds + BLOCK_TIME - seconds % BLOCK_TIME}, or ExpirationTime.fromBlocks(n).`);
+	return BigInt(seconds / BLOCK_TIME);
+}
+/**
+* The block a wall-clock instant lands on.
+*
+* Rounds **up**: a date almost never falls on a block boundary, and unlike a duration — which the
+* caller states and can state exactly — there is nothing here to reject, so the entity lives until
+* at least the instant asked for.
+*/
+function blockAtDate(date, currentBlock) {
+	const secondsAway = (date.getTime() - Date.now()) / 1e3;
+	if (secondsAway <= 0) throw new InvalidExpiryError(`the deadline ${date.toISOString()} is in the past, so the entity would be dead on arrival`);
+	return currentBlock + BigInt(Math.ceil(secondsAway / BLOCK_TIME));
+}
+
+//#endregion
+export { OperationType as a, MAX_EXPIRES_AT as i, resolveExpiry as n, ARKIV_ADDRESS as o, toBlocks as r, BLOCK_TIME as s, makeExpiry as t };
+//# sourceMappingURL=expiry-DGRzrSan.js.map