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

package/src/attr/attributes.ts

@@ -0,0 +1,190 @@
+import { type AbiAttribute, encodeAbiAttribute, encodeTombstone } from "./codec"
+import { ConflictingMutationError, InvalidValueError, TooManyAttributesError } from "./errors"
+import { validateAttributeName } from "./names"
+import type { AnyArkivValue, ArkivValue, TypeTag } from "./types"
+import { makeValue } from "./types"
+import { str, toValue, type ValueInput } from "./values"
+
+/**
+ * The most attribute cells one operation may carry.
+ */
+export const MAX_ATTRIBUTES = 32
+
+export 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 attributes written on an entity, as a plain object keyed by attribute name.
+ *
+ * Values may be tagged ({@link ValueInput}) or bare where the type is unambiguous — see
+ * {@link toValue} for the bare-form defaults.
+ *
+ * @example
+ * const attributes = {
+ *   level:   i32(10),
+ *   balance: u256(1_000_000n),
+ *   score:   dec("3.5"),
+ *   parent:  key(parentKey),
+ *   name:    "Bob",   // bare string -> str
+ *   flagged: true,    // bare boolean -> bool
+ * } satisfies AttributeInputs
+ */
+export type AttributeInputs = Readonly<Record<string, ValueInput>>
+
+/**
+ * The attributes read back from an entity: the same shape, with every value typed.
+ *
+ * A value read from here drops straight back into an {@link AttributeInputs} — the vocabulary is the
+ * same in both directions.
+ */
+export type Attributes = Readonly<Record<string, AnyArkivValue>>
+
+/**
+ * The names and types of an entity's attributes, with no values — what the `attributeSchema`
+ * projection returns.
+ *
+ * Useful for asking what shape the data has without paying to transfer it, and for telling apart
+ * two entities that use the same name with different types.
+ */
+export type AttributeSchema = Readonly<Record<string, TypeTag>>
+
+/**
+ * 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" } }
+ */
+export function resolveAttributes(attributes: AttributeInputs): Record<string, ArkivValue> {
+  const entries = Object.entries(attributes)
+  if (entries.length > MAX_ATTRIBUTES) {
+    throw new TooManyAttributesError(entries.length, MAX_ATTRIBUTES)
+  }
+  const resolved: Record<string, ArkivValue> = {}
+  for (const [name, input] of entries) {
+    validateAttributeName(name)
+    resolved[name] = toValue(input, name)
+  }
+  return resolved
+}
+
+/**
+ * The payload and content type, which travel to the engine as system attributes.
+ *
+ * They are separate fields on the SDK's surface because that is what they are to an application —
+ * an entity's contents and its type — but on the wire an operation carries no dedicated field for
+ * either: `$payload` is the one `bytes`-typed cell, and `$contentType` is a `str`.
+ */
+export type SystemCells = {
+  payload?: Uint8Array | undefined
+  contentType?: string | undefined
+}
+
+/**
+ * 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.
+ */
+export function encodeAttributes(
+  attributes: AttributeInputs = {},
+  system: SystemCells = {},
+): AbiAttribute[] {
+  const cells: [string, AnyArkivValue][] = Object.entries(resolveAttributes(attributes))
+
+  // Written whenever the field is given, empty or not: an empty payload is a payload, and dropping
+  // it would mean the entity does not hold what the caller passed. Absence is for the operations
+  // that genuinely leave a cell alone, not for a value that happens to be empty.
+  if (system.payload !== undefined) {
+    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 !== undefined) {
+    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)
+}
+
+export type MutationInputs = SystemCells & {
+  /** Attributes to write. Existing ones are overwritten; new ones are added. */
+  set?: AttributeInputs | undefined
+  /** Attribute names to remove. Each becomes a tombstone on the wire. */
+  unset?: readonly string[] | undefined
+}
+
+/**
+ * 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.
+ */
+export function encodeMutations({
+  set,
+  unset,
+  payload,
+  contentType,
+}: MutationInputs): AbiAttribute[] {
+  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: readonly string[] = [], set: AttributeInputs = {}): string[] {
+  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: AbiAttribute, b: AbiAttribute): number {
+  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: Uint8Array): `0x${string}` {
+  let out = "0x"
+  for (const byte of bytes) out += byte.toString(16).padStart(2, "0")
+  return out as `0x${string}`
+}

package/src/attr/codec.test.ts

@@ -0,0 +1,162 @@
+import { describe, expect, it } from "bun:test"
+import type { Hex } from "viem"
+import {
+  decodeRpcValue,
+  decodeValueBytes,
+  encodeAbiAttribute,
+  encodeTombstone,
+  encodeValueBytes,
+} from "./codec"
+import { InvalidValueError, UnknownAttributeTypeError } from "./errors"
+import type { ArkivValue } from "./types"
+import { addr, bool, bytes32, dec, i32, key, str, u64, u256 } from "./values"
+
+const ZERO = `0x${"00".repeat(32)}` as Hex
+const KEY = `0x${"ab".repeat(32)}` as Hex
+const VITALIK = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+
+/** One value of every user-settable type, including the awkward edges of each. */
+const SAMPLES: ArkivValue[] = [
+  bool(true),
+  bool(false),
+  i32(0),
+  i32(-42),
+  i32(2147483647),
+  i32(-2147483648),
+  u64(0n),
+  u64(2n ** 64n - 1n),
+  u256(0n),
+  u256(2n ** 256n - 1n),
+  dec("0"),
+  dec("3.5"),
+  dec("-3.5"),
+  dec("-0.000000000000000001"),
+  bytes32(KEY),
+  key(KEY),
+  addr(VITALIK),
+  str(""),
+  str("hello"),
+  str("é".repeat(64)),
+]
+
+describe("ABI value encoding", () => {
+  it("round-trips every type", () => {
+    for (const value of SAMPLES) {
+      const back = decodeValueBytes(value.type, encodeValueBytes(value))
+      expect(back.type).toBe(value.type)
+      expect(back.value).toEqual(value.value)
+    }
+  })
+
+  it("gives every word type exactly 32 bytes", () => {
+    for (const value of SAMPLES) {
+      if (value.type === "str") continue
+      expect(encodeValueBytes(value)).toHaveLength(2 + 64)
+    }
+  })
+
+  it("sign-extends a negative i32 across the whole word, as Solidity does", () => {
+    expect(encodeValueBytes(i32(-1))).toBe(`0x${"ff".repeat(32)}`)
+    expect(encodeValueBytes(i32(-42))).toBe(`0x${"ff".repeat(31)}d6`)
+    expect(encodeValueBytes(i32(42))).toBe(`0x${"00".repeat(31)}2a`)
+  })
+
+  it("stores a dec as its two's-complement scaled int256", () => {
+    const scaled = (value: string) => BigInt.asIntN(256, BigInt(encodeValueBytes(dec(value))))
+    expect(scaled("1.5")).toBe(1_500_000_000_000_000_000n)
+    expect(scaled("-1.5")).toBe(-1_500_000_000_000_000_000n)
+    expect(scaled("0")).toBe(0n)
+  })
+
+  it("right-aligns an address and a bool", () => {
+    expect(encodeValueBytes(addr(VITALIK))).toBe(
+      `0x${"00".repeat(12)}${VITALIK.slice(2).toLowerCase()}`,
+    )
+    expect(encodeValueBytes(bool(true))).toBe(`0x${"00".repeat(31)}01`)
+    expect(encodeValueBytes(bool(false))).toBe(ZERO)
+  })
+
+  it("gives a str its raw UTF-8 bytes, with no padding", () => {
+    expect(encodeValueBytes(str("hi"))).toBe("0x6869")
+    expect(encodeValueBytes(str(""))).toBe("0x")
+    // Two bytes per "é", so no relationship to a 32-byte word.
+    expect(encodeValueBytes(str("é"))).toBe("0xc3a9")
+  })
+
+  it("rejects a word a well-formed encoder would not have produced", () => {
+    expect(() => decodeValueBytes("bool", `0x${"00".repeat(31)}02`)).toThrow(/exactly 0 or 1/)
+    expect(() => decodeValueBytes("u256", "0x2a")).toThrow(/must be 32 bytes, got 1/)
+    // An i32 whose upper bytes contradict its sign bit.
+    expect(() => decodeValueBytes("i32", `0xff${"00".repeat(31)}`)).toThrow(/sign-extended/)
+    // An address with junk above its 20 bytes.
+    expect(() => decodeValueBytes("addr", `0x${"ab".repeat(32)}`)).toThrow(/zero-padded/)
+    // A u64 with junk above its 8 bytes — truncating it would invent a plausible block height.
+    expect(() => decodeValueBytes("u64", `0x${"ab".repeat(32)}`)).toThrow(/zero-padded/)
+  })
+})
+
+describe("encodeAbiAttribute", () => {
+  it("packs the name left-aligned into its bytes32 cell", () => {
+    const attribute = encodeAbiAttribute("level", i32(10))
+    // "level" is 6c6576656c, null-padded to 32 bytes.
+    expect(attribute.name).toBe(`0x6c6576656c${"00".repeat(27)}`)
+    expect(attribute.typeId).toBe(2)
+  })
+
+  it("encodes a tombstone as a zero-length value under typeId 0", () => {
+    expect(encodeTombstone("flagged")).toEqual({
+      name: `0x666c6167676564${"00".repeat(25)}`,
+      typeId: 0,
+      value: "0x",
+    })
+  })
+})
+
+describe("decodeRpcValue", () => {
+  it("reads the JSON encoding each type declares", () => {
+    expect(decodeRpcValue("bool", true).value).toBe(true)
+    expect(decodeRpcValue("i32", -42).value).toBe(-42)
+    expect(decodeRpcValue("u256", "0xf4240").value).toBe(1_000_000n)
+    expect(decodeRpcValue("dec", "3.5").value).toBe("3.5")
+    expect(decodeRpcValue("dec", "-0.25").value).toBe("-0.25")
+    expect(decodeRpcValue("bytes32", KEY).value).toBe(KEY)
+    expect(decodeRpcValue("str", "hello").value).toBe("hello")
+    expect(decodeRpcValue("addr", VITALIK.toLowerCase()).value).toBe(VITALIK)
+    expect(decodeRpcValue("key", KEY).value).toBe(KEY)
+  })
+
+  it("takes an integer however it is rendered", () => {
+    // QUANTITY is the spec's encoding; decimal strings and numbers are tolerated.
+    expect(decodeRpcValue("u256", "0x2a").value).toBe(42n)
+    expect(decodeRpcValue("u256", "42").value).toBe(42n)
+    expect(decodeRpcValue("u256", 42).value).toBe(42n)
+    expect(decodeRpcValue("i32", "-42").value).toBe(-42)
+  })
+
+  it("decodes the system-only bytes type, which only ever arrives as a payload", () => {
+    expect(decodeRpcValue("bytes", "0xDEADBEEF").value).toBe("0xdeadbeef")
+  })
+
+  it("names the type it does not recognise, and says to upgrade", () => {
+    expect(() => decodeRpcValue("int", "x")).toThrow(UnknownAttributeTypeError)
+    expect(() => decodeRpcValue("int", "x")).toThrow(/upgrade @arkiv-network\/sdk/)
+    // The pre-spec wire form: a typeId where the JSON-RPC surface names a tag.
+    expect(() => decodeRpcValue(3 as unknown as string, "0x2a")).toThrow(UnknownAttributeTypeError)
+  })
+
+  it("does not mistake an inherited Object key for a type tag", () => {
+    // `type in TYPE_IDS` walks the prototype chain, so these passed the check and then fell off
+    // the end of the exhaustive switch, returning `undefined` — the caller got a TypeError from
+    // `entity.attributes.foo.value` instead of "upgrade the SDK".
+    for (const inherited of ["constructor", "toString", "valueOf", "hasOwnProperty"]) {
+      expect(() => decodeRpcValue(inherited, 1)).toThrow(UnknownAttributeTypeError)
+    }
+  })
+
+  it("rejects a value whose JSON shape contradicts its declared type", () => {
+    expect(() => decodeRpcValue("u256", "not a number")).toThrow(InvalidValueError)
+    expect(() => decodeRpcValue("str", 42)).toThrow(/expected a string/)
+    expect(() => decodeRpcValue("bool", "yes")).toThrow(/not a boolean/)
+    expect(() => decodeRpcValue("i32", 1.5)).toThrow(/not an integer/)
+  })
+})

package/src/attr/codec.ts

@@ -0,0 +1,220 @@
+import { bytesToString, type Hex, hexToBytes, pad, size, stringToBytes, toHex } from "viem"
+import { unitsToDecimal } from "./decimal"
+import { InvalidValueError, UnknownAttributeTypeError } from "./errors"
+import { type AnyArkivValue, makeValue, type StrValue, TYPE_IDS, type TypeTag } from "./types"
+import { addr, bool, bytes32, dec, decUnits, i32, key, u64, u256 } from "./values"
+
+function strFromChain(value: string): StrValue {
+  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.
+ */
+export const TOMBSTONE_TYPE_ID = 0
+
+/**
+ * An attribute in its ABI form: `(Ident32 name, uint8 typeId, bytes value)`.
+ *
+ * The `value` encoding is selected by `typeId`: an exact 32-byte word for the word types, the raw
+ * bytes for `str` and `bytes`, and zero-length for a tombstone.
+ */
+export type AbiAttribute = {
+  name: Hex
+  typeId: number
+  value: Hex
+}
+
+/**
+ * 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.
+ */
+export function encodeValueBytes(value: AnyArkivValue): Hex {
+  switch (value.type) {
+    case "bool":
+      return pad(value.value ? "0x01" : "0x00", { size: 32 })
+    case "i32":
+      // int32 is sign-extended across the whole word, as Solidity encodes it.
+      return toHex(BigInt.asUintN(256, BigInt(value.value)), { size: 32 })
+    case "u64":
+    case "u256":
+      return toHex(value.value, { size: 32 })
+    case "dec":
+      return toHex(BigInt.asUintN(256, decUnits(value)), { size: 32 })
+    case "bytes32":
+    case "key":
+      return value.value
+    case "addr":
+      return pad(value.value.toLowerCase() as Hex, { size: 32 })
+    case "str":
+      return toHex(stringToBytes(value.value))
+    case "bytes":
+      return value.value
+  }
+}
+
+/**
+ * Decodes the ABI `bytes` of an attribute of type `tag`.
+ *
+ * Rejects anything a well-formed encoder would not have produced — a word type whose value is not
+ * 32 bytes, an `i32` that is not sign-extended, a `bool` that is neither 0 nor 1 — rather than
+ * silently truncating it.
+ */
+export function decodeValueBytes(tag: TypeTag, value: Hex): AnyArkivValue {
+  if (tag === "str") return strFromChain(bytesToString(hexToBytes(value)))
+  if (tag === "bytes") return makeValue("bytes", value.toLowerCase() as Hex)
+
+  const width = size(value)
+  if (width !== 32) {
+    throw new InvalidValueError(tag, value, `a ${tag} value must be 32 bytes, got ${width}`)
+  }
+  const raw = BigInt(value)
+
+  switch (tag) {
+    case "bool":
+      if (raw !== 0n && raw !== 1n) {
+        throw new InvalidValueError("bool", value, "a bool word must hold exactly 0 or 1")
+      }
+      return bool(raw === 1n)
+    case "i32": {
+      const narrowed = BigInt.asIntN(32, raw)
+      if (BigInt.asUintN(256, narrowed) !== raw) {
+        throw new InvalidValueError("i32", value, "an i32 word must be sign-extended")
+      }
+      return i32(narrowed)
+    }
+    case "u64":
+      if (raw >> 64n !== 0n) {
+        throw new InvalidValueError("u64", value, "a u64 word must be zero-padded to 8 bytes")
+      }
+      return u64(raw)
+    case "u256":
+      return u256(raw)
+    case "dec":
+      return dec(unitsToDecimal(BigInt.asIntN(256, raw)))
+    case "bytes32":
+      return bytes32(value)
+    case "key":
+      return key(value)
+    case "addr": {
+      if (raw >> 160n !== 0n) {
+        throw new InvalidValueError(
+          "addr",
+          value,
+          "an address word must be zero-padded to 20 bytes",
+        )
+      }
+      return addr(`0x${value.slice(-40)}`)
+    }
+  }
+}
+
+/**
+ * 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.
+ */
+export function encodeAbiAttribute(name: string, value: AnyArkivValue): AbiAttribute {
+  return {
+    // Ident32 is left-aligned and null-padded, which is what `toHex` does for a string.
+    name: 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. */
+export function encodeTombstone(name: string): AbiAttribute {
+  return { name: 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.
+ */
+export function decodeRpcValue(type: string, value: unknown): AnyArkivValue {
+  const tag = asTypeTag(type)
+  switch (tag) {
+    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) as Hex)
+    case "key":
+      return key(asString("key", value) as Hex)
+    case "addr":
+      return addr(asString("addr", value))
+    case "str":
+      return strFromChain(asString("str", value))
+    case "bytes":
+      return makeValue("bytes", asString("bytes", value).toLowerCase() as Hex)
+  }
+}
+
+/**
+ * Narrows a type tag as the node spelled it.
+ *
+ * @throws {UnknownAttributeTypeError} If it names no type this SDK knows.
+ */
+export function asTypeTag(type: string): TypeTag {
+  // `Object.hasOwn`, not `in`: `in` walks the prototype chain, so "constructor" and "toString"
+  // would pass as type tags and then fall off the end of the exhaustive switch below as `undefined`.
+  if (typeof type !== "string" || !Object.hasOwn(TYPE_IDS, type)) {
+    throw new UnknownAttributeTypeError(type)
+  }
+  return type as TypeTag
+}
+
+function asBoolean(value: unknown): boolean {
+  if (typeof value === "boolean") return value
+  // Tolerated because a node may render it as text; anything else is a protocol error.
+  if (value === "true" || value === "false") return value === "true"
+  throw new InvalidValueError("bool", value, "not a boolean")
+}
+
+function asString(tag: TypeTag, value: unknown): string {
+  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: TypeTag, value: unknown): bigint {
+  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")
+}

package/src/attr/decimal.ts

@@ -0,0 +1,86 @@
+import { InvalidValueError } from "./errors"
+
+/**
+ * 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.
+ */
+export const DECIMAL_SCALE = 18
+
+/** 10 ** {@link DECIMAL_SCALE} — the scaling factor between a `dec` and its integer units. */
+export 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.
+ */
+export function decimalToUnits(input: string): bigint {
+  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.
+ */
+export function unitsToDecimal(units: bigint): string {
+  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 fraction = (magnitude % DECIMAL_UNIT).toString().padStart(DECIMAL_SCALE, "0")
+  const trimmed = fraction.replace(/0+$/, "")
+  const sign = negative ? "-" : ""
+  return trimmed ? `${sign}${whole}.${trimmed}` : `${sign}${whole}`
+}