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

package/dist/expiry-DGRzrSan.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry-DGRzrSan.js","names":[],"sources":["../src/consts.ts","../src/entity/params.ts","../src/entity/expiry.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","/**\n * Max uint64 value\n */\nexport const MAX_EXPIRES_AT = 2n ** 64n - 1n\n\n/** The operation tags of the `execute` ABI's tagged union. */\nexport const OperationType = {\n  Create: 1,\n  Patch: 2,\n  ExtendExpiry: 3,\n  TransferOwnership: 4,\n  Delete: 5,\n} as const\n\nexport type OperationType = (typeof OperationType)[keyof typeof OperationType]\n","import { BLOCK_TIME } from \"../consts\"\nimport { InvalidExpiryError } from \"./errors\"\nimport { MAX_EXPIRES_AT } from \"./params\"\n\n/**\n * The brand. Module-private and never exported, so the only way to obtain an {@link Expiry} is to\n * build one with {@link ExpirationTime} — a hand-written `{ minLifetime, expiresAt }` literal will\n * not typecheck, and neither will a bare number of seconds.\n */\ndeclare const validated: unique symbol\n\n/**\n * How long an entity should live.\n *\n * This is the pair the ABI carries, and the engine resolves it as\n * `max(expiresAt, currentBlock + minLifetime)` — whichever is later. Build one with\n * {@link ExpirationTime}; there is no other way to make one.\n *\n * Which slot a value lands in also decides which rules govern it. `minLifetime` is a duration, so\n * it must come to a whole number of blocks. `expiresAt` is a block height, which is a whole number\n * by construction, so a wall-clock date rounds into it rather than being rejected.\n */\nexport type Expiry = {\n  /** Lifetime floor in blocks, counted from the block the transaction lands in. `0n` if unset. */\n  readonly minLifetime: bigint\n  /**\n   * Absolute deadline: a block height, or a `Date` still to be placed against the current block.\n   * `0n` if unset.\n   */\n  readonly expiresAt: bigint | Date\n  readonly [validated]: true\n}\n\n/**\n * An expiry that is nothing but a duration — what the `ExpirationTime.from*` helpers return.\n *\n * Distinguished from a full {@link Expiry} by its `expiresAt` being the literal `0n`, which is what\n * keeps `atBlock(x, { atLeast: atBlock(y) })` from compiling: a deadline is not a floor.\n */\nexport type Lifetime = Expiry & { readonly expiresAt: 0n }\n\n/**\n * Builds a branded {@link Expiry}.\n *\n * Internal seam for {@link ExpirationTime}, which is the only thing that should call it — it is not\n * part of the package's public surface.\n */\nexport function makeExpiry(minLifetime: bigint, expiresAt: bigint | Date): Expiry {\n  return { minLifetime, expiresAt } as Expiry\n}\n\n/** The two `uint256` values the ABI carries, with every `Date` already placed. */\nexport type EncodedExpiry = {\n  /** Absolute target block height, or `0n` for a purely relative lifetime. */\n  expiresAt: bigint\n  /** Relative floor in blocks, or `0n` for a purely absolute expiry. */\n  minLifetime: bigint\n}\n\n/** What an expiry resolves to, given the chain's current block. */\nexport type ResolvedExpiry = EncodedExpiry & {\n  /** The block the entity will expire at — `max(expiresAt, currentBlock + minLifetime)`. */\n  target: bigint\n}\n\n/** What the SDK needs to know about the chain to resolve an expiry. */\nexport type ExpiryContext = {\n  currentBlock: bigint\n}\n\n/**\n * Resolves an expiry into the wire pair and the block the entity will expire at.\n *\n * Durations are converted to blocks at the nominal `BLOCK_TIME` (2 seconds), which makes them\n * **approximate**: block production is not a clock, so a lifetime asked for in days drifts if the\n * chain runs fast or slow. The block it was converted to comes back as\n * {@link ResolvedExpiry.target}, so the approximation is always observable rather than assumed.\n *\n * @throws {InvalidExpiryError} If the expiry is malformed, does not fit the `uint64` the wire\n * carries, or would leave the entity dead on arrival.\n */\nexport function resolveExpiry(expiry: Expiry, context: ExpiryContext): ResolvedExpiry {\n  const { currentBlock } = context\n\n  if (typeof expiry?.minLifetime !== \"bigint\" || expiry.expiresAt === undefined) {\n    throw new InvalidExpiryError(\n      \"expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or \" +\n        \"ExpirationTime.atBlock(1_200_000n)\",\n    )\n  }\n\n  const { minLifetime } = expiry\n  const absolute =\n    typeof expiry.expiresAt === \"bigint\"\n      ? expiry.expiresAt\n      : blockAtDate(expiry.expiresAt, currentBlock)\n\n  if (minLifetime === 0n && absolute === 0n) {\n    throw new InvalidExpiryError(\n      \"no expiry given. Pass ExpirationTime.fromDays(30) for a lifetime, \" +\n        \"ExpirationTime.atBlock(n) for an absolute deadline, or a deadline with \" +\n        \"{ atLeast } to take whichever is later.\",\n    )\n  }\n\n  if (absolute > MAX_EXPIRES_AT) {\n    throw new InvalidExpiryError(\n      `expiresAt resolves to block ${absolute}, which does not fit the uint64 the wire carries ` +\n        `(max ${MAX_EXPIRES_AT}). Use ExpirationTime.permanent() for an entity that should not ` +\n        \"expire.\",\n    )\n  }\n  if (minLifetime > MAX_EXPIRES_AT) {\n    throw new InvalidExpiryError(\n      `the lifetime is ${minLifetime} blocks, which does not fit the uint64 the wire carries ` +\n        `(max ${MAX_EXPIRES_AT})`,\n    )\n  }\n\n  const relative = minLifetime === 0n ? 0n : currentBlock + minLifetime\n  const target = absolute > relative ? absolute : relative\n\n  if (target <= currentBlock) {\n    throw new InvalidExpiryError(\n      `the entity would expire at block ${target}, which is not after the current block ` +\n        `${currentBlock}, so it would be dead on arrival`,\n    )\n  }\n  if (target > MAX_EXPIRES_AT) {\n    throw new InvalidExpiryError(\n      `a lifetime of ${minLifetime} blocks from block ${currentBlock} lands at ${target}, past ` +\n        `the largest expiry the wire carries (${MAX_EXPIRES_AT})`,\n    )\n  }\n\n  return { expiresAt: absolute, minLifetime, target }\n}\n\n/**\n * A duration in seconds as a whole number of blocks.\n *\n * Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not\n * describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks\n * — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple\n * of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.\n *\n * @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.\n */\nexport function toBlocks(seconds: number): bigint {\n  if (!Number.isInteger(seconds) || seconds <= 0) {\n    throw new InvalidExpiryError(\n      `a lifetime must be a positive whole number of seconds, got ${seconds}. Use the ` +\n        \"ExpirationTime helpers, e.g. ExpirationTime.fromDays(30).\",\n    )\n  }\n  if (seconds % BLOCK_TIME !== 0) {\n    throw new InvalidExpiryError(\n      `a lifetime must be a multiple of the ${BLOCK_TIME}s block time, got ${seconds}, which is ` +\n        `${seconds / BLOCK_TIME} blocks. Try ${seconds - (seconds % BLOCK_TIME)} or ` +\n        `${seconds + BLOCK_TIME - (seconds % BLOCK_TIME)}, or ExpirationTime.fromBlocks(n).`,\n    )\n  }\n  return BigInt(seconds / BLOCK_TIME)\n}\n\n/**\n * The block a wall-clock instant lands on.\n *\n * Rounds **up**: a date almost never falls on a block boundary, and unlike a duration — which the\n * caller states and can state exactly — there is nothing here to reject, so the entity lives until\n * at least the instant asked for.\n */\nfunction blockAtDate(date: Date, currentBlock: bigint): bigint {\n  const secondsAway = (date.getTime() - Date.now()) / 1000\n  if (secondsAway <= 0) {\n    throw new InvalidExpiryError(\n      `the deadline ${date.toISOString()} is in the past, so the entity would be dead on arrival`,\n    )\n  }\n  return currentBlock + BigInt(Math.ceil(secondsAway / BLOCK_TIME))\n}\n"],"mappings":";;;AACA,MAAa,gBAAgB;AAC7B,MAAa,aAAa;;;;;;;ACC1B,MAAa,iBAAiB,MAAM,MAAM;;AAG1C,MAAa,gBAAgB;CAC3B,QAAQ;CACR,OAAO;CACP,cAAc;CACd,mBAAmB;CACnB,QAAQ;CACT;;;;;;;;;;ACmCD,SAAgB,WAAW,aAAqB,WAAkC;AAChF,QAAO;EAAE;EAAa;EAAW;;;;;;;;;;;;;AAiCnC,SAAgB,cAAc,QAAgB,SAAwC;CACpF,MAAM,EAAE,iBAAiB;AAEzB,KAAI,OAAO,QAAQ,gBAAgB,YAAY,OAAO,cAAc,OAClE,OAAM,IAAI,mBACR,oHAED;CAGH,MAAM,EAAE,gBAAgB;CACxB,MAAM,WACJ,OAAO,OAAO,cAAc,WACxB,OAAO,YACP,YAAY,OAAO,WAAW,aAAa;AAEjD,KAAI,gBAAgB,MAAM,aAAa,GACrC,OAAM,IAAI,mBACR,mLAGD;AAGH,KAAI,WAAW,eACb,OAAM,IAAI,mBACR,+BAA+B,SAAS,wDAC9B,eAAe,yEAE1B;AAEH,KAAI,cAAc,eAChB,OAAM,IAAI,mBACR,mBAAmB,YAAY,+DACrB,eAAe,GAC1B;CAGH,MAAM,WAAW,gBAAgB,KAAK,KAAK,eAAe;CAC1D,MAAM,SAAS,WAAW,WAAW,WAAW;AAEhD,KAAI,UAAU,aACZ,OAAM,IAAI,mBACR,oCAAoC,OAAO,yCACtC,aAAa,kCACnB;AAEH,KAAI,SAAS,eACX,OAAM,IAAI,mBACR,iBAAiB,YAAY,qBAAqB,aAAa,YAAY,OAAO,8CACxC,eAAe,GAC1D;AAGH,QAAO;EAAE,WAAW;EAAU;EAAa;EAAQ;;;;;;;;;;;;AAarD,SAAgB,SAAS,SAAyB;AAChD,KAAI,CAAC,OAAO,UAAU,QAAQ,IAAI,WAAW,EAC3C,OAAM,IAAI,mBACR,8DAA8D,QAAQ,qEAEvE;AAEH,KAAI,UAAU,eAAe,EAC3B,OAAM,IAAI,mBACR,wCAAwC,WAAW,oBAAoB,QAAQ,aAC1E,UAAU,WAAW,eAAe,UAAW,UAAU,WAAY,MACrE,UAAU,aAAc,UAAU,WAAY,oCACpD;AAEH,QAAO,OAAO,UAAU,WAAW;;;;;;;;;AAUrC,SAAS,YAAY,MAAY,cAA8B;CAC7D,MAAM,eAAe,KAAK,SAAS,GAAG,KAAK,KAAK,IAAI;AACpD,KAAI,eAAe,EACjB,OAAM,IAAI,mBACR,gBAAgB,KAAK,aAAa,CAAC,yDACpC;AAEH,QAAO,eAAe,OAAO,KAAK,KAAK,cAAc,WAAW,CAAC"}

package/dist/expiry-DRV29F1r.d.cts

@@ -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-DRV29F1r.d.cts.map

package/dist/expiry-DRV29F1r.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"expiry-DRV29F1r.d.cts","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/flags-0Vl5rrHq.d.cts

@@ -0,0 +1,41 @@
+//#region src/entity/flags.d.ts
+/**
+ * The immutable properties an entity is created with. Both default to `false`.
+ *
+ * Creation flags are fixed at creation: there is no operation that changes them, so an entity is
+ * whatever it was created as for its whole life.
+ */
+type CreationFlags = {
+  /**
+   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * ownership transferred, and the entity deleted.
+   */
+  readonly?: boolean;
+  /**
+   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something
+   * alive without being able to change it.
+   */
+  permissionlessExtension?: boolean;
+};
+/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */
+type ResolvedCreationFlags = {
+  readonly: boolean;
+  permissionlessExtension: boolean;
+  raw: number;
+};
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+declare function encodeCreationFlags(flags?: CreationFlags): number;
+/**
+ * Reads the `creationFlags` byte back.
+ *
+ * @param raw - The `creationFlags` byte.
+ * @throws {InvalidCreationFlagsError} Malformed input
+ */
+declare function decodeCreationFlags(raw: number): ResolvedCreationFlags;
+//#endregion
+export { encodeCreationFlags as i, ResolvedCreationFlags as n, decodeCreationFlags as r, CreationFlags as t };
+//# sourceMappingURL=flags-0Vl5rrHq.d.cts.map

package/dist/flags-0Vl5rrHq.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-0Vl5rrHq.d.cts","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":[],"mappings":";;AAYA;AAcA;AAWA;AAkBA;;KA3CY,aAAA;;;;;;;;;;;;;KAcA,qBAAA;;;;;;;;;;iBAWI,mBAAA,SAA2B;;;;;;;iBAkB3B,mBAAA,eAAkC"}

package/dist/flags-Ct8k0gpB.cjs

@@ -0,0 +1,43 @@
+const require_errors = require('./errors-D-eJkGVc.cjs');
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new require_errors.InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new require_errors.InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+Object.defineProperty(exports, 'decodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return decodeCreationFlags;
+  }
+});
+Object.defineProperty(exports, 'encodeCreationFlags', {
+  enumerable: true,
+  get: function () {
+    return encodeCreationFlags;
+  }
+});

package/dist/flags-ZtlvOIIk.js

@@ -0,0 +1,33 @@
+import { t as InvalidCreationFlagsError } from "./errors-DGB8AgT2.js";
+
+//#region src/entity/flags.ts
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 1;
+const PERMISSIONLESS_EXTENSION_BIT = 2;
+/**
+* Packs creation flags into the `creationFlags` byte.
+*
+* @throws {InvalidCreationFlagsError} If a value is not a boolean.
+*/
+function encodeCreationFlags(flags = {}) {
+	for (const [name, value] of Object.entries(flags)) if (value !== void 0 && typeof value !== "boolean") throw new InvalidCreationFlagsError(`"${name}" must be a boolean, got ${typeof value}`);
+	return (flags.readonly ? READONLY_BIT : 0) | (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0);
+}
+/**
+* Reads the `creationFlags` byte back.
+*
+* @param raw - The `creationFlags` byte.
+* @throws {InvalidCreationFlagsError} Malformed input
+*/
+function decodeCreationFlags(raw) {
+	if (!Number.isInteger(raw) || raw < 0 || raw > 255) throw new InvalidCreationFlagsError(`${raw} is not a byte`);
+	return {
+		readonly: (raw & READONLY_BIT) !== 0,
+		permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+		raw
+	};
+}
+
+//#endregion
+export { encodeCreationFlags as n, decodeCreationFlags as t };
+//# sourceMappingURL=flags-ZtlvOIIk.js.map

package/dist/flags-ZtlvOIIk.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-ZtlvOIIk.js","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":["import { InvalidCreationFlagsError } from \"./errors\"\n\n/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */\nconst READONLY_BIT = 0b0000_0001\nconst PERMISSIONLESS_EXTENSION_BIT = 0b0000_0010\n\n/**\n * The immutable properties an entity is created with. Both default to `false`.\n *\n * Creation flags are fixed at creation: there is no operation that changes them, so an entity is\n * whatever it was created as for its whole life.\n */\nexport type CreationFlags = {\n  /**\n   * The entity's attributes and payload can never be changed — only its expiry extended, its\n   * ownership transferred, and the entity deleted.\n   */\n  readonly?: boolean\n  /**\n   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something\n   * alive without being able to change it.\n   */\n  permissionlessExtension?: boolean\n}\n\n/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */\nexport type ResolvedCreationFlags = {\n  readonly: boolean\n  permissionlessExtension: boolean\n  raw: number\n}\n\n/**\n * Packs creation flags into the `creationFlags` byte.\n *\n * @throws {InvalidCreationFlagsError} If a value is not a boolean.\n */\nexport function encodeCreationFlags(flags: CreationFlags = {}): number {\n  for (const [name, value] of Object.entries(flags)) {\n    if (value !== undefined && typeof value !== \"boolean\") {\n      throw new InvalidCreationFlagsError(`\"${name}\" must be a boolean, got ${typeof value}`)\n    }\n  }\n  return (\n    (flags.readonly ? READONLY_BIT : 0) |\n    (flags.permissionlessExtension ? PERMISSIONLESS_EXTENSION_BIT : 0)\n  )\n}\n\n/**\n * Reads the `creationFlags` byte back.\n *\n * @param raw - The `creationFlags` byte.\n * @throws {InvalidCreationFlagsError} Malformed input\n */\nexport function decodeCreationFlags(raw: number): ResolvedCreationFlags {\n  if (!Number.isInteger(raw) || raw < 0 || raw > 0xff) {\n    throw new InvalidCreationFlagsError(`${raw} is not a byte`)\n  }\n  return {\n    readonly: (raw & READONLY_BIT) !== 0,\n    permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,\n    raw,\n  }\n}\n"],"mappings":";;;;AAGA,MAAM,eAAe;AACrB,MAAM,+BAA+B;;;;;;AAiCrC,SAAgB,oBAAoB,QAAuB,EAAE,EAAU;AACrE,MAAK,MAAM,CAAC,MAAM,UAAU,OAAO,QAAQ,MAAM,CAC/C,KAAI,UAAU,UAAa,OAAO,UAAU,UAC1C,OAAM,IAAI,0BAA0B,IAAI,KAAK,2BAA2B,OAAO,QAAQ;AAG3F,SACG,MAAM,WAAW,eAAe,MAChC,MAAM,0BAA0B,+BAA+B;;;;;;;;AAUpE,SAAgB,oBAAoB,KAAoC;AACtE,KAAI,CAAC,OAAO,UAAU,IAAI,IAAI,MAAM,KAAK,MAAM,IAC7C,OAAM,IAAI,0BAA0B,GAAG,IAAI,gBAAgB;AAE7D,QAAO;EACL,WAAW,MAAM,kBAAkB;EACnC,0BAA0B,MAAM,kCAAkC;EAClE;EACD"}

package/dist/flags-wmcMoAnN.d.ts

@@ -0,0 +1,41 @@
+//#region src/entity/flags.d.ts
+/**
+ * The immutable properties an entity is created with. Both default to `false`.
+ *
+ * Creation flags are fixed at creation: there is no operation that changes them, so an entity is
+ * whatever it was created as for its whole life.
+ */
+type CreationFlags = {
+  /**
+   * The entity's attributes and payload can never be changed — only its expiry extended, its
+   * ownership transferred, and the entity deleted.
+   */
+  readonly?: boolean;
+  /**
+   * Anyone, not just the owner, may extend the entity's expiry. Lets a third party keep something
+   * alive without being able to change it.
+   */
+  permissionlessExtension?: boolean;
+};
+/** {@link CreationFlags} as read back, with every flag resolved and the raw byte alongside. */
+type ResolvedCreationFlags = {
+  readonly: boolean;
+  permissionlessExtension: boolean;
+  raw: number;
+};
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+declare function encodeCreationFlags(flags?: CreationFlags): number;
+/**
+ * Reads the `creationFlags` byte back.
+ *
+ * @param raw - The `creationFlags` byte.
+ * @throws {InvalidCreationFlagsError} Malformed input
+ */
+declare function decodeCreationFlags(raw: number): ResolvedCreationFlags;
+//#endregion
+export { encodeCreationFlags as i, ResolvedCreationFlags as n, decodeCreationFlags as r, CreationFlags as t };
+//# sourceMappingURL=flags-wmcMoAnN.d.ts.map

package/dist/flags-wmcMoAnN.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"flags-wmcMoAnN.d.ts","names":[],"sources":["../src/entity/flags.ts"],"sourcesContent":[],"mappings":";;AAYA;AAcA;AAWA;AAkBA;;KA3CY,aAAA;;;;;;;;;;;;;KAcA,qBAAA;;;;;;;;;;iBAWI,mBAAA,SAA2B;;;;;;;iBAkB3B,mBAAA,eAAkC"}

package/dist/index-Cgw1u5aY.d.cts

@@ -0,0 +1,278 @@
+import { K as TypeTag } from "./index-D8LZt-3J.cjs";
+import { R as RpcSelect, d as Expression, i as SelectArg, j as ArkivClient, k as Entity } from "./selection-BvK6yX0g.cjs";
+import { Hex } from "viem";
+
+//#region src/query/engine.d.ts
+declare const MAX_LIMIT = 200;
+/** One `arkiv_query` call. */
+type QueryRequest = {
+  /** The query expression, already rendered. */
+  query: string;
+  /** What to return. */
+  select: RpcSelect;
+  /** Page size, up to {@link MAX_LIMIT}. Defaults to the node's own page size. */
+  limit?: number | undefined;
+  /** Cursor from a previous page. */
+  cursor?: string | undefined;
+  /** Block height to read at. Defaults to the head. */
+  atBlock?: bigint | undefined;
+};
+/** One page of results. */
+type QueryResponse = {
+  entities: Entity[];
+  /** The block the page was read at — the same for every page of a paginated query. */
+  blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  cursor: string | undefined;
+};
+/**
+ * Runs one query and decodes the page it returns.
+ *
+ * @throws {QueryError} If the node rejects the query.
+ */
+declare function runQuery(client: ArkivClient, request: QueryRequest): Promise<QueryResponse>;
+//#endregion
+//#region src/query/errors.d.ts
+/**
+ * A predicate asked for an operator the query language does not define for that type.
+ *
+ * The operator × type matrix is part of the language, not a policy: a range comparison on an
+ * equality-only type is a **parse error** at the node, not an empty result. Catching it here turns
+ * a round trip and an RPC error code into a stack trace pointing at the call site.
+ *
+ * | | `=` `!=` | `<` `<=` `>` `>=` | `STARTSWITH` |
+ * | --- | --- | --- | --- |
+ * | `bool` | yes | no | no |
+ * | `i32` `u256` `dec` | yes | yes | no |
+ * | `str` | yes | no | yes |
+ * | `addr` `key` `bytes32` | yes | no | no |
+ */
+declare class UnsupportedOperatorError extends Error {
+  /** The attribute the predicate names. */
+  readonly attributeName: string;
+  /** The operator, as it would have been written in the query. */
+  readonly operator: string;
+  /** The type of the value it was applied to. */
+  readonly tag: TypeTag;
+  constructor(attributeName: string, operator: string, tag: TypeTag, hint?: string);
+}
+/**
+ * A predicate could not be expressed in the query language for a reason other than its operator —
+ * a system attribute that is returned in results but cannot be filtered on, a system attribute
+ * compared against the wrong type, or a combinator with nothing to combine.
+ */
+declare class InvalidPredicateError extends Error {
+  /** The attribute the predicate names, where there is one. */
+  readonly attributeName: string | undefined;
+  constructor(message: string, attributeName?: string);
+}
+/**
+ * What a node rejected a query for. Part of the frozen RPC surface, so it is safe to branch on —
+ * a `"cursor"` failure means start the query again, a `"block"` failure means the node no longer
+ * retains that height, and the rest mean the query itself needs fixing.
+ */
+type QueryErrorKind = /** The query string does not parse. `data` locates it: `{ position, expected, got }`. */
+"parse"
+/** A predicate is well-formed but ill-typed — a range operator on an equality-only type, an unknown tag. */ | "type"
+/** A literal failed validation — an `i32` out of range, a bad EIP-55 checksum, more than 18 decimal places. */ | "literal"
+/** A node budget was exceeded — query length, predicate count, nesting depth, bitmap operations. */ | "limits"
+/** The cursor expired, is malformed, or belongs to a different query, block or selection. */ | "cursor"
+/** `atBlock` is outside the range the node retains. */ | "block";
+/**
+ * The node rejected a query.
+ *
+ * These codes are part of the frozen `arkiv_query` surface, so {@link kind} and {@link data} are
+ * stable enough to branch on — which the underlying JSON-RPC error is not, because the codes
+ * overlap Ethereum's own EIP-1474 numbering and get wrapped accordingly on the way up.
+ *
+ * @example
+ * try {
+ *   await result.next()
+ * } catch (error) {
+ *   if (error instanceof QueryError && error.kind === "cursor") {
+ *     // The page is gone — start the query over.
+ *   }
+ * }
+ */
+declare class QueryError extends Error {
+  /** Which failure this is. */
+  readonly kind: QueryErrorKind;
+  /** The JSON-RPC error code. */
+  readonly code: number;
+  /** The machine-readable detail the node sent, if any — e.g. `{ position, expected, got }`. */
+  readonly data: unknown;
+  /** The query string that was rejected. */
+  readonly query: string;
+  constructor(kind: QueryErrorKind, code: number, query: string, data: unknown, detail?: string);
+}
+//#endregion
+//#region src/query/queryResult.d.ts
+/** Fetches the page a cursor points at. */
+type FetchPage<TEntity> = (cursor: string) => Promise<QueryResult<TEntity>>;
+/**
+ * One page of query results.
+ *
+ * A page is immutable: {@link next} returns the following page rather than mutating this one, so a
+ * page that has been read stays readable.
+ *
+ * @typeParam TEntity - The shape of each entity, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * let page = await client.select({ key: true }).where(eq("category", "docs")).limit(100).fetch()
+ * while (page.hasNextPage()) {
+ *   page = await page.next()
+ * }
+ */
+declare class QueryResult<TEntity = Entity> {
+  /** The entities on this page. */
+  readonly entities: readonly TEntity[];
+  /**
+   * The block this page was read at.
+   *
+   * Every page of one walk reads the same block — the cursor is bound to it — so results cannot
+   * shift under a paginating reader.
+   */
+  readonly blockNumber: bigint;
+  /** The cursor for the next page, or `undefined` when this was the last one. */
+  readonly cursor: string | undefined;
+  private readonly fetchPage;
+  constructor(entities: readonly TEntity[], blockNumber: bigint, cursor: string | undefined, fetchPage: FetchPage<TEntity>);
+  /**
+   * Whether another page follows.
+   *
+   * The node omits the cursor once nothing remains, so this is an answer rather than the guess a
+   * short final page would be — a full last page is reported correctly.
+   */
+  hasNextPage(): boolean;
+  /**
+   * Fetches the next page.
+   *
+   * @throws {NoMoreResultsError} If this was the last page — check {@link hasNextPage} first.
+   * @throws {QueryError} If the node rejects the request; `kind === "cursor"` means the cursor
+   * expired and the walk has to start again.
+   */
+  next(): Promise<QueryResult<TEntity>>;
+}
+//#endregion
+//#region src/query/queryBuilder.d.ts
+/**
+ * Builds and runs a query.
+ *
+ * The selection is fixed when the builder is created and the filter is added by chaining, so the
+ * result type is known before a single predicate is written. Create one with `client.select(...)`
+ * rather than constructing it directly — that is what infers the entity shape from the selection.
+ *
+ * Every filter added with {@link where}, {@link ownedBy} and {@link createdBy} must hold; use
+ * {@link or} for alternatives inside one call.
+ *
+ * @typeParam TEntity - The projected entity shape, inferred from the selection by `client.select()`.
+ *
+ * @example
+ * import { createPublicClient } from "@arkiv-network/sdk"
+ * import { i32 } from "@arkiv-network/sdk/attr"
+ * import { cheesecake } from "@arkiv-network/sdk/chains"
+ * import { eq, gte, or } from "@arkiv-network/sdk/query"
+ * import { http } from "viem"
+ *
+ * const client = createPublicClient({ chain: cheesecake, transport: http() })
+ *
+ * const page = await client
+ *   .select({ key: true, attributes: true })
+ *   .where(gte("level", i32(10)), or(eq("status", "open"), eq("status", "review")))
+ *   .ownedBy(owner)
+ *   .limit(100)
+ *   .fetch()
+ *
+ * for (const entity of page.entities) console.log(entity.key, entity.attributes)
+ */
+declare class SelectQueryBuilder<TEntity = Entity> {
+  private readonly _client;
+  private readonly _select;
+  private readonly _filters;
+  private _ownedBy;
+  private _createdBy;
+  private _limit;
+  private _cursor;
+  private _atBlock;
+  constructor(client: ArkivClient, selection?: SelectArg);
+  /**
+   * Adds filters. Everything passed here, and across repeated calls, must hold.
+   *
+   * @param expressions - The expressions, as separate arguments or one array.
+   *
+   * @example
+   * builder.where(eq("category", "docs"))
+   * builder.where(gte("level", i32(10)), lt("level", i32(20)))
+   * builder.where(or(eq("status", "open"), not(exists("closedAt"))))
+   */
+  where(expressions: readonly Expression[]): this;
+  where(...expressions: Expression[]): this;
+  /**
+   * Restricts the results to entities this account owns — shorthand for
+   * `where(eq("$owner", addr(owner)))`. Calling it again replaces the filter.
+   *
+   * @example
+   * builder.ownedBy("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+   */
+  ownedBy(owner: Hex): this;
+  /**
+   * Restricts the results to entities this account created — shorthand for
+   * `where(eq("$creator", addr(creator)))`. Calling it again replaces the filter.
+   *
+   * The creator never changes; the owner does, so these differ after a transfer.
+   */
+  createdBy(creator: Hex): this;
+  /**
+   * Sets the page size, up to the node maximum of 200. Without it the node picks the page size.
+   *
+   * @example
+   * builder.limit(100)
+   */
+  limit(limit: number): this;
+  /**
+   * Starts from a cursor returned by an earlier page.
+   *
+   * Pagination normally goes through {@link QueryResult.next}, which carries the cursor for you;
+   * this is for resuming a walk in a later process. A cursor is bound to the query, block and
+   * selection it came from, so it must be used with an identically-built query.
+   */
+  cursor(cursor: string): this;
+  /**
+   * Reads the state as of a given block rather than the head. The block must be within the range
+   * the node retains.
+   *
+   * @example
+   * builder.atBlock(1_297_000n)
+   */
+  atBlock(block: bigint): this;
+  /**
+   * The query string this builder will send — the same text the node parses.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   */
+  toString(): string;
+  /**
+   * Runs the query and returns the first page.
+   *
+   * @throws {InvalidPredicateError} If no filter has been added.
+   * @throws {QueryError} If the node rejects the query.
+   *
+   * @example
+   * const page = await client.select({ key: true }).where(eq("category", "docs")).fetch()
+   * page.entities        // this page
+   * await page.next()    // the next one
+   */
+  fetch(): Promise<QueryResult<TEntity>>;
+  /**
+   * Walks every page, yielding one entity at a time.
+   *
+   * @example
+   * for await (const entity of client.select({ key: true }).where(eq("category", "docs"))) {
+   *   console.log(entity.key)
+   * }
+   */
+  [Symbol.asyncIterator](): AsyncGenerator<TEntity>;
+}
+//#endregion
+export { QueryErrorKind as a, QueryRequest as c, QueryError as i, QueryResponse as l, QueryResult as n, UnsupportedOperatorError as o, InvalidPredicateError as r, MAX_LIMIT as s, SelectQueryBuilder as t, runQuery as u };
+//# sourceMappingURL=index-Cgw1u5aY.d.cts.map

package/dist/index-Cgw1u5aY.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-Cgw1u5aY.d.cts","names":[],"sources":["../src/query/engine.ts","../src/query/errors.ts","../src/query/queryResult.ts","../src/query/queryBuilder.ts"],"sourcesContent":[],"mappings":";;;;;cAUa,SAAA;;AAAA,KAGD,YAAA,GAHU;EAGV;EAcA,KAAA,EAAA,MAAA;EAaU;EAAiB,MAAA,EAvB7B,SAuB6B;EAAsB;EAAuB,KAAA,CAAA,EAAA,MAAA,GAAA,SAAA;EAAR;EAAO,MAAA,CAAA,EAAA,MAAA,GAAA,SAAA;;;;ACxBnF;AAMgB,KDKJ,aAAA,GCLI;EAE4C,QAAA,EDIhD,MCJgD,EAAA;EARd;EAAK,WAAA,EAAA,MAAA;EAyBtC;EAgBD,MAAA,EAAA,MAAA,GAAc,SAAA;AAwC1B,CAAA;;;;;;iBDzDsB,QAAA,SAAiB,sBAAsB,eAAe,QAAQ;;;;;;;AA9BpF;AAGA;AAcA;AAaA;;;;;;;cCxBa,wBAAA,SAAiC,KAAA;;EAAjC,SAAA,aAAA,EAAA,MAAyB;EAMtB;EAE4C,SAAA,QAAA,EAAA,MAAA;EARd;EAAK,SAAA,GAAA,EAMnC,OANmC;EAyBtC,WAAA,CAAA,aAAsB,EAAA,MAAA,EAAA,QAAa,EAAA,MAAA,EAAA,GAAA,EAjBY,OAiBZ,EAAA,IAAA,CAAA,EAAA,MAAA;AAgBhD;AAwCA;;;;;cAxDa,qBAAA,SAA8B,KAAA;;;ECrCtC,WAAA,CAAS,OAAA,EAAA,MAAA,EAAA,aAAA,CAAA,EAAA,MAAA;;;;;AAgBd;;AAE8B,KDmClB,cAAA;;+GCSwB;kHAApB;;;ACzBhB,0DAA0C,OAAA;;;;;;;;;;;;;;;;;cFwD7B,UAAA,SAAmB,KAAA;;iBAEf;;;;;;;oBAQG;;;;;KCvGf,yCAAyC,QAAQ,YAAY;;;AFMlE;AAGA;AAcA;AAaA;;;;;;;;;ACxBa,cCIA,WDJyB,CAAA,UCIH,MDJG,CAAA,CAAA;EAMtB;EAE4C,SAAA,QAAA,EAAA,SCF9B,ODE8B,EAAA;EARd;;AAyB9C;AAgBA;AAwCA;;EAUoB,SAAA,WAAA,EAAA,MAAA;EAVY;EAAK,SAAA,MAAA,EAAA,MAAA,GAAA,SAAA;;iCC7Dd,uEAGR,UAAU;;AAtCoB;;;;;EAmBhC,WAAA,CAAA,CAAA,EAAW,OAAA;EAAW;;;;;;;EA8CnB,IAAA,CAAA,CAAA,EAAA,OAAA,CAAQ,WAAR,CAAoB,OAApB,CAAA,CAAA;;;;AFrDhB;AAcA;AAaA;;;;;;;;;ACxBA;;;;;AAyBA;AAgBA;AAwCA;;;;;;;;AChG6C;;;;AAGQ,cCqCxC,kBDrCwC,CAAA,UCqCX,MDrCW,CAAA,CAAA;EAgBxC,iBAAW,OAAA;EAAW,iBAAA,OAAA;EAEL,iBAAA,QAAA;EAcP,QAAA,QAAA;EAGE,QAAA,UAAA;EAAV,QAAA,MAAA;EA2BqB,QAAA,OAAA;EAAZ,QAAA,QAAA;EAAR,WAAA,CAAA,MAAA,ECfM,WDeN,EAAA,SAAA,CAAA,ECf+B,SDe/B;EAAO;;;;ACzBvB;;;;;;EAuCiB,KAAA,CAAA,WAAA,EAAA,SAda,UAcb,EAAA,CAAA,EAAA,IAAA;EAWI,KAAA,CAAA,GAAA,WAAA,EAxBG,UAwBH,EAAA,CAAA,EAAA,IAAA;EAuEgB;;;;;;;iBAlFpB;;;;;;;qBAWI;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;WAuEJ,QAAQ,YAAY;;;;;;;;;GAqB3B,MAAA,CAAO,aAAA,KAAkB,eAAe"}