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

package/dist/attr-BvxHN99W.cjs

@@ -0,0 +1,1029 @@
+let viem = require("viem");
+
+//#region src/attr/errors.ts
+/**
+* A value was rejected by its tagged constructor — out of range, wrong length, bad checksum, too
+* much precision, and so on.
+*
+* The message names the offending value and, where there is one, the type that *would* hold it, so
+* the fix is in the error rather than in the docs.
+*/
+var InvalidValueError = class extends Error {
+	/** The type tag whose constructor rejected the value. */
+	tag;
+	/** The rejected input, as given. */
+	input;
+	constructor(tag, input, reason, hint) {
+		super(`Invalid ${tag} value ${describe(input)}: ${reason}.${hint ? ` ${hint}` : ""}`);
+		this.name = "InvalidValueError";
+		this.tag = tag;
+		this.input = input;
+	}
+};
+/**
+* A bare JavaScript value could not be given a type. Raised when an attribute or predicate is
+* handed something that is neither a tagged value nor one of the four bare forms
+* (`boolean`, `number`, `bigint`, `string`).
+*/
+var UntypedValueError = class extends Error {
+	input;
+	constructor(input) {
+		super(`Cannot infer an Arkiv type for ${describe(input)}. Attribute values must be a tagged value (i32, u256, dec, str, addr, key, bytes32, bool) or a bare boolean, number, bigint or string.`);
+		this.name = "UntypedValueError";
+		this.input = input;
+	}
+};
+/**
+* An attribute was given `undefined` or `null` as its value.
+*
+* There is no such thing as an attribute with no value: an attribute either exists with a type, or
+* is not set. The fix is always to leave the name out of the map rather than to write an empty
+* value, so this is called out separately from {@link UntypedValueError} — the remedy is different.
+*/
+var MissingValueError = class extends Error {
+	/** The attribute whose value was missing, when raised from an attribute map. */
+	attributeName;
+	constructor(input, attributeName) {
+		const subject = attributeName ? `attribute "${attributeName}"` : "attribute value";
+		super(`The ${subject} is ${input === null ? "null" : "undefined"}. An attribute is either set with a value and a type or not set at all, so there is nothing to write here. ` + (attributeName ? `Omit "${attributeName}" from the attributes instead — e.g. build the map conditionally, or drop the key when the value is absent.` : "Omit the attribute instead of giving it an empty value."));
+		this.name = "MissingValueError";
+		this.attributeName = attributeName;
+	}
+};
+/** An attribute name violated the on-chain name grammar. */
+var InvalidAttributeNameError = class extends Error {
+	attributeName;
+	constructor(attributeName, reason) {
+		super(`Invalid attribute name "${attributeName}": ${reason}. Names must be 1-32 bytes, start with a letter, and contain only A-Z, a-z, 0-9, ".", "-" or "_". Names are case-sensitive.`);
+		this.name = "InvalidAttributeNameError";
+		this.attributeName = attributeName;
+	}
+};
+/**
+* One patch tried to both write and remove the same attribute.
+*/
+var ConflictingMutationError = class extends Error {
+	attributeName;
+	constructor(attributeName) {
+		super(`The patch both sets and unsets "${attributeName}". A patch applies one mutation per attribute, so say which you mean: drop it from "unset" to write the value, or from "set" to remove the attribute.`);
+		this.name = "ConflictingMutationError";
+		this.attributeName = attributeName;
+	}
+};
+/** More attributes were supplied than an entity operation can carry. */
+var TooManyAttributesError = class extends Error {
+	constructor(count, max) {
+		super(`An entity may carry at most ${max} attributes, got ${count}.`);
+		this.name = "TooManyAttributesError";
+	}
+};
+/** The node sent back an attribute this SDK cannot decode. */
+var UnknownAttributeTypeError = class extends Error {
+	/** The type as the node named it — a tag over JSON-RPC, a typeId on the wire. */
+	type;
+	constructor(type) {
+		super(`Unknown attribute type ${describe(type)}. The node is using a type this SDK version does not know about — upgrade @arkiv-network/sdk.`);
+		this.name = "UnknownAttributeTypeError";
+		this.type = type;
+	}
+};
+/** Renders an arbitrary input for an error message, without ever throwing. */
+function describe(input) {
+	switch (typeof input) {
+		case "string": return JSON.stringify(input.length > 64 ? `${input.slice(0, 61)}...` : input);
+		case "bigint": return `${input}n`;
+		case "object": return input === null ? "null" : safeJson(input);
+		case "undefined": return "undefined";
+		default: return String(input);
+	}
+}
+function safeJson(input) {
+	try {
+		return JSON.stringify(input) ?? String(input);
+	} catch {
+		return Object.prototype.toString.call(input);
+	}
+}
+
+//#endregion
+//#region src/attr/decimal.ts
+/**
+* Decimal places a `dec` value is scaled by. Fixed by the protocol, so any two decimals are
+* directly comparable — and range-indexable — as plain integers.
+*/
+const DECIMAL_SCALE = 18;
+/** 10 ** {@link DECIMAL_SCALE} — the scaling factor between a `dec` and its integer units. */
+const DECIMAL_UNIT = 10n ** BigInt(DECIMAL_SCALE);
+/** The widest scaled value an `int256` holds. */
+const INT256_MAX = 2n ** 255n - 1n;
+/** The narrowest scaled value an `int256` holds. */
+const INT256_MIN = -(2n ** 255n);
+/**
+* A decimal literal: an optional sign, at least one integer digit, and an optional fraction of at
+* most {@link DECIMAL_SCALE} digits. Exponents are not part of the grammar — `1e18` is a parse
+* error rather than a silent reinterpretation.
+*/
+const DECIMAL_RE = /^([+-]?)(\d+)(?:\.(\d+))?$/;
+/**
+* Parses a decimal literal into its scaled integer units.
+*
+* Excess fractional precision is an **error, never a rounding**: the protocol stores exactly 18
+* decimal places, and silently dropping the 19th digit would make a stored value differ from the
+* one that was written.
+*
+* @param input - The decimal literal, e.g. `"3.5"` or `"-0.000001"`.
+* @returns The value scaled by 10 ** 18.
+* @throws {InvalidValueError} If the literal is malformed, too precise, or out of `int256` range.
+*/
+function decimalToUnits(input) {
+	const match = DECIMAL_RE.exec(input);
+	if (!match) throw new InvalidValueError("dec", input, "not a decimal literal", "Write it as sign, digits, and an optional \".\" with up to 18 fractional digits — e.g. dec(\"3.5\") or dec(\"-0.25\"). Exponents such as \"1e18\" are not accepted.");
+	const [, sign, whole, fraction = ""] = match;
+	if (fraction.length > DECIMAL_SCALE) throw new InvalidValueError("dec", input, `${fraction.length} fractional digits exceeds the ${DECIMAL_SCALE} the protocol stores`, "Round it yourself before storing — a dec is never rounded for you, so that what you write is exactly what is stored.");
+	const digits = BigInt(whole + fraction.padEnd(DECIMAL_SCALE, "0"));
+	const units = sign === "-" ? -digits : digits;
+	if (units > INT256_MAX || units < INT256_MIN) throw new InvalidValueError("dec", input, "exceeds the int256 range a dec is stored in");
+	return units;
+}
+/**
+* Renders scaled integer units back as a canonical decimal string: no leading zeros, no trailing
+* fractional zeros, no `-0`. Parsing the result yields the same units, so this is the inverse of
+* {@link decimalToUnits} on every value it accepts.
+*
+* @param units - The value scaled by 10 ** 18.
+* @returns The canonical decimal string, e.g. `"3.5"`.
+* @throws {InvalidValueError} If the units are outside the `int256` range.
+*/
+function unitsToDecimal(units) {
+	if (units > INT256_MAX || units < INT256_MIN) throw new InvalidValueError("dec", units, "exceeds the int256 range a dec is stored in");
+	const negative = units < 0n;
+	const magnitude = negative ? -units : units;
+	const whole = magnitude / DECIMAL_UNIT;
+	const trimmed = (magnitude % DECIMAL_UNIT).toString().padStart(DECIMAL_SCALE, "0").replace(/0+$/, "");
+	const sign = negative ? "-" : "";
+	return trimmed ? `${sign}${whole}.${trimmed}` : `${sign}${whole}`;
+}
+
+//#endregion
+//#region src/attr/types.ts
+/**
+* The protocol's attribute type vocabulary, mapping each short **tag** (the name used by the
+* client, the query language and this SDK) to its **typeId** (the byte carried on the wire and in
+* the entity record).
+*
+* The typeIds are consensus-critical: they are written into entity records and mixed into index
+* keys, so this table must never drift from the node's `AttributeType`.
+*
+* | tag       | typeId | ABI wire type       | indexing          |
+* | --------- | ------ | ------------------- | ----------------- |
+* | `bool`    | 1      | `bool`              | equality          |
+* | `i32`     | 2      | `int32`             | equality + range  |
+* | `u64`     | 3      | `uint64`            | equality + range  |
+* | `u256`    | 4      | `uint256`           | equality + range  |
+* | `dec`     | 5      | `int256` (18 dp)    | equality + range  |
+* | `bytes32` | 6      | `bytes32`           | equality          |
+* | `bytes`   | 7      | `bytes`             | none — system-only |
+* | `str`     | 8      | `string` (<= 128 B) | equality + prefix |
+* | `addr`    | 9      | `address`           | equality          |
+* | `key`     | 10     | `bytes32`           | equality          |
+*/
+const TYPE_IDS = {
+	bool: 1,
+	i32: 2,
+	u64: 3,
+	u256: 4,
+	dec: 5,
+	bytes32: 6,
+	bytes: 7,
+	str: 8,
+	addr: 9,
+	key: 10
+};
+/**
+* Builds a validated value. Module-internal: the constructors in `values.ts` call this **after**
+* validating, which is what makes the {@link validated} brand meaningful.
+*/
+function makeValue(type, value) {
+	return {
+		type,
+		value
+	};
+}
+/**
+* Whether `input` has the *shape* of an {@link ArkivValue} — a known type tag and a value.
+*/
+function isArkivValue(input) {
+	return typeof input === "object" && input !== null && "type" in input && "value" in input && typeof input.type === "string" && Object.hasOwn(TYPE_IDS, input.type);
+}
+
+//#endregion
+//#region src/attr/values.ts
+/** The widest `i32`. */
+const I32_MAX = 2147483647;
+/** The narrowest `i32`. */
+const I32_MIN = -2147483648;
+/** The widest `u64`. */
+const U64_MAX = 2n ** 64n - 1n;
+/** The widest `u256`. */
+const U256_MAX = 2n ** 256n - 1n;
+/**
+* The longest `str`, in UTF-8 bytes
+*/
+const MAX_STRING_BYTES = 128;
+/**
+* Finds the first C0 control or DEL — the characters a `str` may not contain.
+*/
+function findControlChar(value) {
+	for (let index = 0; index < value.length; index++) {
+		const code = value.charCodeAt(index);
+		if (code <= 31 || code === 127) return {
+			index,
+			code
+		};
+	}
+}
+/**
+* A boolean.
+*
+* `bool` is the one type that may also be written bare — `{ flagged: true }` and
+* `{ flagged: bool(true) }` are the same attribute.
+*
+* @example
+* bool(true) // { type: "bool", value: true }
+*/
+function bool(value) {
+	if (typeof value !== "boolean") throw new InvalidValueError("bool", value, "not a boolean");
+	return makeValue("bool", value);
+}
+/**
+* A 32-bit signed integer, indexed for equality and range queries. This is the default type for a
+* bare number, so `{ level: 10 }` and `{ level: i32(10) }` are the same attribute.
+*
+* @param value - An integer in [-2147483648, 2147483647].
+* @throws {InvalidValueError} If the value is not an integer, or does not fit an `i32`.
+*
+* @example
+* i32(10)   // { type: "i32", value: 10 }
+* i32(-42)  // negative values are fine — i32 is the signed integer
+*/
+function i32(value) {
+	if (typeof value === "bigint") {
+		if (value > BigInt(I32_MAX) || value < BigInt(I32_MIN)) throw new InvalidValueError("i32", value, outOfI32Range(value >= 0n));
+		return makeValue("i32", Number(value));
+	}
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new InvalidValueError("i32", value, "not a number");
+	if (!Number.isInteger(value)) throw new InvalidValueError("i32", value, "not an integer", `Use dec(${JSON.stringify(String(value))}) for a fixed-point decimal.`);
+	if (value > I32_MAX || value < I32_MIN) throw new InvalidValueError("i32", value, outOfI32Range(value >= 0));
+	return makeValue("i32", value);
+}
+function outOfI32Range(nonNegative) {
+	const range = `outside the i32 range [${I32_MIN}, ${I32_MAX}]`;
+	return nonNegative ? `${range} — use u64(...) for large counters, timestamps and block heights (Date.now() does not fit an i32), or u256(...) beyond 2**64 - 1` : `${range} — use dec(...) for values that need more range than an i32`;
+}
+/**
+* A 256-bit unsigned integer, indexed for equality and range queries. The type for token amounts
+* and anything else that can outgrow 2⁶⁴ — reach for {@link u64} first for counters, timestamps
+* and block heights.
+*
+* @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
+* string.
+* @throws {InvalidValueError} If the value is negative, non-integral, or wider than 256 bits.
+*
+* @example
+* u256(1_000_000n)
+* u256(Date.now())        // safe integers are accepted
+* u256("0xf4240")         // hex, as it comes back over JSON-RPC
+*/
+function u256(value) {
+	return makeValue("u256", toUnsigned("u256", value, U256_MAX));
+}
+/**
+* A 64-bit unsigned integer, indexed for equality and range queries.
+*
+* This is the width the protocol counts in: block heights, `$expiresAt` and the entity-nonce are
+* all `u64`, so it is the type to reach for when a value has to line up with one of them. Use
+* {@link u256} for token amounts and anything else that can exceed 2⁶⁴.
+*
+* @param value - A non-negative integer, as a `bigint`, a safe `number`, or a decimal or `0x` hex
+* string.
+* @throws {InvalidValueError} If the value is negative, non-integral, or wider than 64 bits.
+*
+* @example
+* u64(1_200_000n)     // a block height
+* u64(Date.now())     // safe integers are accepted
+* u64("0x124f80")     // hex, as it comes back over JSON-RPC
+*/
+function u64(value) {
+	return makeValue("u64", toUnsigned("u64", value, U64_MAX));
+}
+/**
+* Parses and range-checks an unsigned integer for `tag`, whose widest value is `max`.
+*
+* Shared by {@link u64} and {@link u256} so the two differ in exactly one thing — their width —
+* rather than in how they read a string or how they explain a failure.
+*/
+function toUnsigned(tag, value, max) {
+	const parsed = toUnsignedBigint(tag, value);
+	if (parsed < 0n) throw new InvalidValueError(tag, value, `negative — ${tag} is unsigned`, "Use i32(...) for small signed integers, or dec(...) for a signed fixed-point value.");
+	if (parsed > max) throw new InvalidValueError(tag, value, `wider than ${tag === "u64" ? 64 : 256} bits`, tag === "u64" ? "Use u256(...) for values beyond 2**64 - 1." : void 0);
+	return parsed;
+}
+function toUnsignedBigint(tag, value) {
+	if (typeof value === "bigint") return value;
+	if (typeof value === "number") {
+		if (!Number.isInteger(value)) throw new InvalidValueError(tag, value, "not an integer", `Use dec(${JSON.stringify(String(value))}) for a fixed-point decimal.`);
+		if (!Number.isSafeInteger(value)) throw new InvalidValueError(tag, value, "beyond the safe integer range, so it may already have lost precision", "Pass it as a bigint literal (e.g. 12345678901234567890n) or a string instead.");
+		return BigInt(value);
+	}
+	if (typeof value === "string") {
+		if (!/^(0x[0-9a-fA-F]+|\d+)$/.test(value)) throw new InvalidValueError(tag, value, "not a decimal or 0x-hex integer");
+		return BigInt(value);
+	}
+	throw new InvalidValueError(tag, value, "not a bigint, number or string");
+}
+/**
+* A signed fixed-point decimal with exactly 18 decimal places, indexed for equality and range
+* queries.
+*
+* Pass fractional values as **strings**. A JavaScript number cannot represent most decimals
+* exactly, so accepting `dec(0.1 + 0.2)` would quietly store `0.30000000000000004`; requiring the
+* string keeps what you write and what is stored the same thing. Excess precision is likewise an
+* error rather than a rounding.
+*
+* @param value - A decimal string, or an integral `number` / `bigint`.
+* @throws {InvalidValueError} If the value is malformed, has more than 18 fractional digits, or
+* falls outside the `int256` range.
+*
+* @example
+* dec("3.5")
+* dec("-0.000000000000000001")  // the smallest step
+* dec(5)                        // integers may be passed bare
+*/
+function dec(value) {
+	if (typeof value === "string") return makeValue("dec", unitsToDecimal(decimalToUnits(value)));
+	if (typeof value === "bigint") return decFromUnits(value * DECIMAL_UNIT);
+	if (typeof value !== "number" || !Number.isFinite(value)) throw new InvalidValueError("dec", value, "not a number");
+	if (!Number.isInteger(value)) throw new InvalidValueError("dec", value, "a fractional number cannot be represented exactly in binary floating point", `Pass it as a string instead: dec(${JSON.stringify(String(value))}).`);
+	return decFromUnits(BigInt(value) * DECIMAL_UNIT);
+}
+/**
+* The exact scaled integer behind a `dec` — the value multiplied by 10 ** 18, which is what the
+* protocol stores and compares. Use it when you need exact arithmetic; JavaScript has no native
+* decimal type, so the SDK carries the canonical string and leaves the maths to you.
+*
+* @example
+* decUnits(dec("3.5"))  // 3500000000000000000n
+*/
+function decUnits(value) {
+	return decimalToUnits(value.value);
+}
+/**
+* A `dec` built from its scaled integer units — the inverse of {@link decUnits}.
+*
+* @example
+* decFromUnits(3_500_000_000_000_000_000n)  // dec("3.5")
+*/
+function decFromUnits(units) {
+	return makeValue("dec", unitsToDecimal(units));
+}
+/**
+* A UTF-8 string of at most 128 bytes, indexed for equality and prefix (`STARTSWITH`) matching.
+*
+* The limit is on **bytes**, not characters: a string of 128 emoji does not fit.
+*
+* @throws {InvalidValueError} If the string exceeds 128 UTF-8 bytes.
+*
+* @example
+* str("Bob")
+*/
+function str(value) {
+	if (typeof value !== "string") throw new InvalidValueError("str", value, "not a string");
+	const control = findControlChar(value);
+	if (control !== void 0) throw new InvalidValueError("str", value, `contains the control character U+${control.code.toString(16).padStart(4, "0").toUpperCase()} at index ${control.index}`, "A str is written into a query as str('...'), whose only escape is a doubled quote — there is no spelling for a control character, so this value could be stored but never queried. Free-form text belongs in the entity payload; keep a short, printable key here.");
+	const bytes = (0, viem.stringToBytes)(value).length;
+	if (bytes > MAX_STRING_BYTES) throw new InvalidValueError("str", value, `${bytes} UTF-8 bytes exceeds the ${MAX_STRING_BYTES}-byte limit on a str`, "Store the long form in the entity payload and keep a short, queryable key here.");
+	return makeValue("str", value);
+}
+/**
+* A 20-byte Ethereum address, indexed for equality.
+*
+* All-lowercase and all-uppercase input carries no checksum and is accepted as-is; mixed-case
+* input is checked against its EIP-55 checksum, so a mistyped address is caught here rather than
+* being written to a wrong account. The stored value is always EIP-55 checksummed.
+*
+* @throws {InvalidValueError} If the value is not 20 hex bytes, or fails its EIP-55 checksum.
+*
+* @example
+* addr("0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045")
+*/
+function addr(value) {
+	if (typeof value !== "string" || !/^0x[0-9a-fA-F]{40}$/.test(value)) throw new InvalidValueError("addr", value, "not a 20-byte 0x-prefixed hex address");
+	const body = value.slice(2);
+	if (body !== body.toLowerCase() && body !== body.toUpperCase() && !(0, viem.isAddress)(value, { strict: true })) throw new InvalidValueError("addr", value, "fails its EIP-55 checksum, so a digit is probably mistyped", `If those hex digits are right, the correctly checksummed form is ${(0, viem.checksumAddress)(value)}.`);
+	return makeValue("addr", (0, viem.checksumAddress)(value));
+}
+/**
+* A reference to another entity, indexed for equality.
+*
+* References are **weak**: nothing checks that the target exists when you write it, and a
+* reference to a deleted or expired entity is allowed to dangle.
+*
+* @param value - A 32-byte entity key, as `0x` hex or raw bytes.
+* @throws {InvalidValueError} If the value is not exactly 32 bytes.
+*
+* @example
+* key(parentEntityKey)
+*/
+function key(value) {
+	return makeValue("key", asFixedHex("key", value, 32));
+}
+/**
+* 32 opaque bytes — a hash, a digest, an identifier from another system — indexed for equality.
+*
+* Use {@link key} instead when the bytes are an Arkiv entity key: same wire width, but the
+* distinct type makes the reference visible to readers and to the query language.
+*
+* @param value - 32 bytes, as `0x` hex or raw bytes.
+* @throws {InvalidValueError} If the value is not exactly 32 bytes.
+*
+* @example
+* bytes32(keccak256(toBytes("hello")))
+*/
+function bytes32(value) {
+	return makeValue("bytes32", asFixedHex("bytes32", value, 32));
+}
+/** Normalizes hex-or-bytes input of a known width into lowercase `0x` hex. */
+function asFixedHex(tag, value, size$1) {
+	if (value instanceof Uint8Array) {
+		if (value.length !== size$1) throw new InvalidValueError(tag, `<${value.length} bytes>`, `not exactly ${size$1} bytes`);
+		return (0, viem.toHex)(value);
+	}
+	if (typeof value !== "string" || !(0, viem.isHex)(value, { strict: true })) throw new InvalidValueError(tag, value, "not 0x-prefixed hex");
+	if (value.length !== 2 + size$1 * 2) throw new InvalidValueError(tag, value, `${(value.length - 2) / 2} bytes, not exactly ${size$1} bytes`);
+	return value.toLowerCase();
+}
+/**
+* Resolves a {@link ValueInput} to a typed value, applying the bare-form defaults above. Tagged
+* values pass through untouched.
+*
+* @param input - The value to resolve.
+* @param attributeName - The attribute this value belongs to, used to make errors name it.
+*
+* @throws {MissingValueError} If the input is `undefined` or `null` — an attribute is either set
+* with a value and a type, or not set at all.
+* @throws {UntypedValueError} If the input is not a tagged value or a bare boolean, number, bigint
+* or string.
+* @throws {InvalidValueError} If a bare value does not fit the type it defaults to.
+*
+* @example
+* toValue(10)          // i32(10)
+* toValue(10n)         // u256(10n)
+* toValue("hello")     // str("hello")
+* toValue(dec("3.5"))  // unchanged
+*/
+function toValue(input, attributeName) {
+	if (input === void 0 || input === null) throw new MissingValueError(input, attributeName);
+	switch (typeof input) {
+		case "boolean": return bool(input);
+		case "number": return i32(input);
+		case "bigint": return u256(input);
+		case "string": return str(input);
+		default: {
+			const candidate = input;
+			if (isArkivValue(candidate)) {
+				if (candidate.type === "bytes") throw new InvalidValueError("bytes", candidate.value, "system-only — bytes backs the entity payload and cannot be set as an attribute", "Pass the bytes as the entity payload instead.");
+				return revalidate(candidate);
+			}
+			throw new UntypedValueError(input);
+		}
+	}
+}
+/**
+* Re-runs a tagged value through its own constructor.
+*
+* {@link isArkivValue} can only check shape — the `validated` brand is a type-level construct with
+* no runtime existence, so a hand-written `{ type: "u256", value: "1000" }` (from `JSON.parse`, a
+* config file, an `as any` boundary) is indistinguishable from a real `u256(1000n)`. Passing it
+* through unchecked was silent corruption rather than an error: the ABI encoder would take the
+* *string* "1000" and write its UTF-8 bytes into the word, storing 2.27e76 on chain.
+*
+* Running the constructor again is what makes the brand's promise — "every value crossing the wire
+* has been range-, length- and format-checked" — true at runtime. For a value that really did come
+* from a constructor it is a no-op that returns an equal value.
+*/
+function revalidate(value) {
+	switch (value.type) {
+		case "bool": return bool(value.value);
+		case "i32": return i32(value.value);
+		case "u64": return u64(value.value);
+		case "u256": return u256(value.value);
+		case "dec": return dec(value.value);
+		case "bytes32": return bytes32(value.value);
+		case "str": return str(value.value);
+		case "addr": return addr(value.value);
+		case "key": return key(value.value);
+	}
+}
+
+//#endregion
+//#region src/attr/codec.ts
+function strFromChain(value) {
+	return makeValue("str", value);
+}
+/**
+* The `typeId` marking a tombstone — an attribute being unset. It carries a zero-length value and
+* is legal only in a patch's mutation list, never in a create.
+*/
+const TOMBSTONE_TYPE_ID = 0;
+/**
+* Encodes a typed value into the `bytes` the ABI carries for it.
+*
+* This and {@link decodeValueBytes} are the only place the value/wire mapping is written down.
+*
+* - Word types (`bool`, `i32`, `u64`, `u256`, `dec`, `bytes32`, `addr`, `key`) become exactly 32
+*   bytes, in the encoding Solidity would use — right-aligned, and sign-extended for `i32`.
+* - `str` becomes its raw UTF-8 bytes, and `bytes` its raw bytes: variable length, no padding.
+*/
+function encodeValueBytes(value) {
+	switch (value.type) {
+		case "bool": return (0, viem.pad)(value.value ? "0x01" : "0x00", { size: 32 });
+		case "i32": return (0, viem.toHex)(BigInt.asUintN(256, BigInt(value.value)), { size: 32 });
+		case "u64":
+		case "u256": return (0, viem.toHex)(value.value, { size: 32 });
+		case "dec": return (0, viem.toHex)(BigInt.asUintN(256, decUnits(value)), { size: 32 });
+		case "bytes32":
+		case "key": return value.value;
+		case "addr": return (0, viem.pad)(value.value.toLowerCase(), { size: 32 });
+		case "str": return (0, viem.toHex)((0, viem.stringToBytes)(value.value));
+		case "bytes": return value.value;
+	}
+}
+/**
+* Encodes a named, typed attribute into its ABI form.
+*
+* @param name - The attribute name. Assumed already validated, or a system (`$`) name the SDK sets
+* itself.
+*/
+function encodeAbiAttribute(name, value) {
+	return {
+		name: (0, viem.toHex)(name, { size: 32 }),
+		typeId: TYPE_IDS[value.type],
+		value: encodeValueBytes(value)
+	};
+}
+/** Encodes a tombstone — the mutation that unsets `name`. Legal only in a patch. */
+function encodeTombstone(name) {
+	return {
+		name: (0, viem.toHex)(name, { size: 32 }),
+		typeId: TOMBSTONE_TYPE_ID,
+		value: "0x"
+	};
+}
+/**
+* Decodes an attribute value as it comes back over JSON-RPC.
+*
+* The JSON encoding follows the value's **declared type**, never its magnitude: `bool` is a JSON
+* boolean, `i32` a JSON number, `u64`/`u256` a `0x` QUANTITY, `dec` a decimal string, `str` a
+* string, and
+* the byte-shaped types `0x` DATA. Decimal strings are also accepted for the integer types, so this
+* keeps working against a node that renders them that way.
+*
+* @param type - The type tag the response declared, e.g. `"u256"`.
+* @param value - The JSON value.
+* @throws {UnknownAttributeTypeError} If the tag names no known type.
+* @throws {InvalidValueError} If the value does not parse as that type.
+*/
+function decodeRpcValue(type, value) {
+	switch (asTypeTag(type)) {
+		case "bool": return bool(asBoolean(value));
+		case "i32": return i32(Number(asIntegerish("i32", value)));
+		case "u64": return u64(asIntegerish("u64", value));
+		case "u256": return u256(asIntegerish("u256", value));
+		case "dec": return dec(asString("dec", value));
+		case "bytes32": return bytes32(asString("bytes32", value));
+		case "key": return key(asString("key", value));
+		case "addr": return addr(asString("addr", value));
+		case "str": return strFromChain(asString("str", value));
+		case "bytes": return makeValue("bytes", asString("bytes", value).toLowerCase());
+	}
+}
+/**
+* Narrows a type tag as the node spelled it.
+*
+* @throws {UnknownAttributeTypeError} If it names no type this SDK knows.
+*/
+function asTypeTag(type) {
+	if (typeof type !== "string" || !Object.hasOwn(TYPE_IDS, type)) throw new UnknownAttributeTypeError(type);
+	return type;
+}
+function asBoolean(value) {
+	if (typeof value === "boolean") return value;
+	if (value === "true" || value === "false") return value === "true";
+	throw new InvalidValueError("bool", value, "not a boolean");
+}
+function asString(tag, value) {
+	if (typeof value !== "string") throw new InvalidValueError(tag, value, `expected a string, got ${typeof value}`);
+	return value;
+}
+/** A `0x` QUANTITY, a JSON number, or a decimal string — all of which name one integer. */
+function asIntegerish(tag, value) {
+	if (typeof value === "number") {
+		if (!Number.isInteger(value)) throw new InvalidValueError(tag, value, "not an integer");
+		return BigInt(value);
+	}
+	if (typeof value === "bigint") return value;
+	if (typeof value === "string") {
+		if (/^0x[0-9a-fA-F]+$/.test(value)) return BigInt(value);
+		if (/^-?\d+$/.test(value)) return BigInt(value);
+	}
+	throw new InvalidValueError(tag, value, "not an integer");
+}
+
+//#endregion
+//#region src/attr/names.ts
+/** The longest attribute name, in bytes — the width of the on-chain `Ident32` name cell. */
+const MAX_NAME_BYTES = 32;
+/**
+* The attribute-name grammar (`Ident32`): a leading letter, then letters, digits, `.`, `-` or `_`.
+*
+* Names are **case-sensitive** — `Level` and `level` are two different attributes.
+*
+* The charset is ASCII-only, so a name's length in characters is also its length in bytes.
+*/
+const NAME_RE = /^[A-Za-z][A-Za-z0-9._-]*$/;
+/**
+* Words the query language reserves. They are rejected as attribute names because an attribute
+* named `not` or `str` could be written but never queried — the parser would read the name as an
+* operator or a type tag.
+*
+* Matched **case-insensitively**: query keywords are case-insensitive, so `NOT` and `not` are the
+* same operator, and the type tags are held to the same rule so that what is reserved does not
+* depend on how you happen to capitalise it.
+*/
+const RESERVED = new Set([
+	"and",
+	"or",
+	"not",
+	"true",
+	"false",
+	"startswith",
+	"exists",
+	"typeof",
+	"bool",
+	"i32",
+	"u64",
+	"u256",
+	"dec",
+	"bytes32",
+	"bytes",
+	"str",
+	"addr",
+	"key"
+]);
+/**
+* Validates an attribute name against the engine's `Ident32` grammar and the query language's
+* reserved words.
+*
+* @param name - The attribute name.
+* @throws {InvalidAttributeNameError} If the name is empty, too long, uses characters outside the
+* grammar, or collides with a reserved word.
+*/
+function validateAttributeName(name) {
+	if (typeof name !== "string" || name.length === 0) throw new InvalidAttributeNameError(String(name), "the name is empty");
+	if (name.startsWith("$")) throw new InvalidAttributeNameError(name, "\"$\" is reserved for system attributes, which the engine sets and you cannot write");
+	if (!NAME_RE.test(name)) {
+		const chars = [...name];
+		const at = chars.findIndex((char, index) => !(index === 0 ? /[A-Za-z]/ : /[A-Za-z0-9._-]/).test(char));
+		throw new InvalidAttributeNameError(name, at === 0 ? `it starts with "${chars[0]}" rather than a letter` : `it contains "${chars[at]}" at position ${at}`);
+	}
+	if (name.length > MAX_NAME_BYTES) throw new InvalidAttributeNameError(name, `the name is ${name.length} bytes long`);
+	if (name.includes("--")) throw new InvalidAttributeNameError(name, "\"--\" opens a comment in the query language, so everything after it in a query would be discarded — an attribute with this name could be written but never safely queried");
+	if (RESERVED.has(name.toLowerCase())) throw new InvalidAttributeNameError(name, `"${name}" is reserved by the query language, so an attribute with this name could never be queried`);
+}
+/** Whether `name` is a valid attribute name — the non-throwing form of {@link validateAttributeName}. */
+function isValidAttributeName(name) {
+	try {
+		validateAttributeName(name);
+		return true;
+	} catch {
+		return false;
+	}
+}
+
+//#endregion
+//#region src/attr/attributes.ts
+/**
+* The most attribute cells one operation may carry.
+*/
+const MAX_ATTRIBUTES = 32;
+const MAX_PAYLOAD_BYTES = 128 * 1024;
+/** The system attribute holding an entity's opaque payload. */
+const PAYLOAD_CELL = "$payload";
+/** The system attribute holding an entity's content type. */
+const CONTENT_TYPE_CELL = "$contentType";
+/**
+* The typed form of an attribute map: names validated, bare values resolved to their default type.
+*
+* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+* @throws {MissingValueError} If a value is `undefined` or `null` — omit the name instead.
+* @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
+* @throws {TooManyAttributesError} If there are more than {@link MAX_ATTRIBUTES} attributes.
+*
+* @example
+* resolveAttributes({ level: 10, name: "Bob" })
+* // { level: { type: "i32", value: 10 }, name: { type: "str", value: "Bob" } }
+*/
+function resolveAttributes(attributes) {
+	const entries = Object.entries(attributes);
+	if (entries.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(entries.length, MAX_ATTRIBUTES);
+	const resolved = {};
+	for (const [name, input] of entries) {
+		validateAttributeName(name);
+		resolved[name] = toValue(input, name);
+	}
+	return resolved;
+}
+/**
+* Encodes an attribute map, plus the payload and content-type system cells, into the ABI attribute
+* array an operation carries.
+*
+* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+* @throws {MissingValueError} If a value is `undefined` or `null`.
+* @throws {InvalidValueError} If a value does not fit its type.
+* @throws {TooManyAttributesError} If there are more than {@link MAX_ATTRIBUTES} attributes.
+*/
+function encodeAttributes(attributes = {}, system = {}) {
+	const cells = Object.entries(resolveAttributes(attributes));
+	if (system.payload !== void 0) {
+		if (system.payload.length > MAX_PAYLOAD_BYTES) throw new InvalidValueError("bytes", `<${system.payload.length} bytes>`, `${system.payload.length} bytes exceeds the ${MAX_PAYLOAD_BYTES}-byte payload limit`, "Store the bulk elsewhere and keep a reference to it on the entity.");
+		cells.push([PAYLOAD_CELL, makeValue("bytes", toHexBytes(system.payload))]);
+	}
+	if (system.contentType !== void 0) cells.push([CONTENT_TYPE_CELL, str(system.contentType)]);
+	if (cells.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(cells.length, MAX_ATTRIBUTES);
+	return cells.map(([name, value]) => encodeAbiAttribute(name, value)).sort(byName);
+}
+/**
+* Encodes a patch's mutations into the ABI attribute array the operation carries.
+*
+* @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
+* @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
+* @throws {InvalidValueError} If a value does not fit its type.
+* @throws {TooManyAttributesError} If `set` names more than {@link MAX_ATTRIBUTES} attributes.
+*/
+function encodeMutations({ set, unset, payload, contentType }) {
+	const written = encodeAttributes(set, {
+		payload,
+		contentType
+	});
+	const tombstones = resolveUnset(unset, set).map(encodeTombstone);
+	const mutations = [...written, ...tombstones];
+	if (mutations.length > MAX_ATTRIBUTES) throw new TooManyAttributesError(mutations.length, MAX_ATTRIBUTES);
+	return mutations.sort(byName);
+}
+function resolveUnset(unset = [], set = {}) {
+	if (!Array.isArray(unset)) throw new TypeError(`"unset" must be an array of attribute names`);
+	const names = new Set(unset);
+	for (const name of names) {
+		validateAttributeName(name);
+		if (Object.hasOwn(set, name)) throw new ConflictingMutationError(name);
+	}
+	return [...names];
+}
+/**
+* The engine requires attributes **strictly ascending by their `bytes32` name**: that ordering is
+* what the canonical serialization hashes into the state root, and it doubles as the uniqueness
+* check.
+*/
+function byName(a, b) {
+	return a.name < b.name ? -1 : a.name > b.name ? 1 : 0;
+}
+/** Raw bytes as lowercase `0x` hex, without viem's hex-string ambiguity. */
+function toHexBytes(bytes) {
+	let out = "0x";
+	for (const byte of bytes) out += byte.toString(16).padStart(2, "0");
+	return out;
+}
+
+//#endregion
+Object.defineProperty(exports, 'ConflictingMutationError', {
+  enumerable: true,
+  get: function () {
+    return ConflictingMutationError;
+  }
+});
+Object.defineProperty(exports, 'DECIMAL_SCALE', {
+  enumerable: true,
+  get: function () {
+    return DECIMAL_SCALE;
+  }
+});
+Object.defineProperty(exports, 'DECIMAL_UNIT', {
+  enumerable: true,
+  get: function () {
+    return DECIMAL_UNIT;
+  }
+});
+Object.defineProperty(exports, 'I32_MAX', {
+  enumerable: true,
+  get: function () {
+    return I32_MAX;
+  }
+});
+Object.defineProperty(exports, 'I32_MIN', {
+  enumerable: true,
+  get: function () {
+    return I32_MIN;
+  }
+});
+Object.defineProperty(exports, 'InvalidAttributeNameError', {
+  enumerable: true,
+  get: function () {
+    return InvalidAttributeNameError;
+  }
+});
+Object.defineProperty(exports, 'InvalidValueError', {
+  enumerable: true,
+  get: function () {
+    return InvalidValueError;
+  }
+});
+Object.defineProperty(exports, 'MAX_ATTRIBUTES', {
+  enumerable: true,
+  get: function () {
+    return MAX_ATTRIBUTES;
+  }
+});
+Object.defineProperty(exports, 'MAX_NAME_BYTES', {
+  enumerable: true,
+  get: function () {
+    return MAX_NAME_BYTES;
+  }
+});
+Object.defineProperty(exports, 'MAX_PAYLOAD_BYTES', {
+  enumerable: true,
+  get: function () {
+    return MAX_PAYLOAD_BYTES;
+  }
+});
+Object.defineProperty(exports, 'MAX_STRING_BYTES', {
+  enumerable: true,
+  get: function () {
+    return MAX_STRING_BYTES;
+  }
+});
+Object.defineProperty(exports, 'MissingValueError', {
+  enumerable: true,
+  get: function () {
+    return MissingValueError;
+  }
+});
+Object.defineProperty(exports, 'TYPE_IDS', {
+  enumerable: true,
+  get: function () {
+    return TYPE_IDS;
+  }
+});
+Object.defineProperty(exports, 'TooManyAttributesError', {
+  enumerable: true,
+  get: function () {
+    return TooManyAttributesError;
+  }
+});
+Object.defineProperty(exports, 'U256_MAX', {
+  enumerable: true,
+  get: function () {
+    return U256_MAX;
+  }
+});
+Object.defineProperty(exports, 'U64_MAX', {
+  enumerable: true,
+  get: function () {
+    return U64_MAX;
+  }
+});
+Object.defineProperty(exports, 'UnknownAttributeTypeError', {
+  enumerable: true,
+  get: function () {
+    return UnknownAttributeTypeError;
+  }
+});
+Object.defineProperty(exports, 'UntypedValueError', {
+  enumerable: true,
+  get: function () {
+    return UntypedValueError;
+  }
+});
+Object.defineProperty(exports, 'addr', {
+  enumerable: true,
+  get: function () {
+    return addr;
+  }
+});
+Object.defineProperty(exports, 'asTypeTag', {
+  enumerable: true,
+  get: function () {
+    return asTypeTag;
+  }
+});
+Object.defineProperty(exports, 'bool', {
+  enumerable: true,
+  get: function () {
+    return bool;
+  }
+});
+Object.defineProperty(exports, 'bytes32', {
+  enumerable: true,
+  get: function () {
+    return bytes32;
+  }
+});
+Object.defineProperty(exports, 'dec', {
+  enumerable: true,
+  get: function () {
+    return dec;
+  }
+});
+Object.defineProperty(exports, 'decFromUnits', {
+  enumerable: true,
+  get: function () {
+    return decFromUnits;
+  }
+});
+Object.defineProperty(exports, 'decUnits', {
+  enumerable: true,
+  get: function () {
+    return decUnits;
+  }
+});
+Object.defineProperty(exports, 'decodeRpcValue', {
+  enumerable: true,
+  get: function () {
+    return decodeRpcValue;
+  }
+});
+Object.defineProperty(exports, 'encodeAttributes', {
+  enumerable: true,
+  get: function () {
+    return encodeAttributes;
+  }
+});
+Object.defineProperty(exports, 'encodeMutations', {
+  enumerable: true,
+  get: function () {
+    return encodeMutations;
+  }
+});
+Object.defineProperty(exports, 'i32', {
+  enumerable: true,
+  get: function () {
+    return i32;
+  }
+});
+Object.defineProperty(exports, 'isArkivValue', {
+  enumerable: true,
+  get: function () {
+    return isArkivValue;
+  }
+});
+Object.defineProperty(exports, 'isValidAttributeName', {
+  enumerable: true,
+  get: function () {
+    return isValidAttributeName;
+  }
+});
+Object.defineProperty(exports, 'key', {
+  enumerable: true,
+  get: function () {
+    return key;
+  }
+});
+Object.defineProperty(exports, 'str', {
+  enumerable: true,
+  get: function () {
+    return str;
+  }
+});
+Object.defineProperty(exports, 'toValue', {
+  enumerable: true,
+  get: function () {
+    return toValue;
+  }
+});
+Object.defineProperty(exports, 'u256', {
+  enumerable: true,
+  get: function () {
+    return u256;
+  }
+});
+Object.defineProperty(exports, 'u64', {
+  enumerable: true,
+  get: function () {
+    return u64;
+  }
+});
+Object.defineProperty(exports, 'validateAttributeName', {
+  enumerable: true,
+  get: function () {
+    return validateAttributeName;
+  }
+});