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

package/src/entity/expiry.test.ts

@@ -0,0 +1,195 @@
+import { describe, expect, it } from "bun:test"
+import { ExpirationTime } from "../utils/expirationTime"
+import { InvalidExpiryError } from "./errors"
+import { type Expiry, type ExpiryContext, resolveExpiry, toBlocks } from "./expiry"
+import { MAX_EXPIRES_AT } from "./params"
+
+const CURRENT_BLOCK = 1000n
+const ctx: ExpiryContext = { currentBlock: CURRENT_BLOCK }
+
+describe("what ExpirationTime builds", () => {
+  it("is the wire pair itself, so what you write is what is sent", () => {
+    expect(ExpirationTime.fromDays(30)).toEqual({ minLifetime: 1_296_000n, expiresAt: 0n } as never)
+    expect(ExpirationTime.atBlock(1_200_000n)).toEqual({
+      minLifetime: 0n,
+      expiresAt: 1_200_000n,
+    } as never)
+  })
+
+  it("is plain data — no prototype, no methods to lose", () => {
+    const expiry = ExpirationTime.fromDays(1)
+    expect(Object.getPrototypeOf(expiry)).toBe(Object.prototype)
+    expect(structuredClone(expiry)).toEqual(expiry as never)
+  })
+
+  it("puts a duration in minLifetime and a deadline in expiresAt, never the other way round", () => {
+    // Which slot a value lands in is what decides the rules that govern it.
+    for (const lifetime of [
+      ExpirationTime.fromSeconds(120),
+      ExpirationTime.fromMinutes(1),
+      ExpirationTime.fromHours(1),
+      ExpirationTime.fromDays(1),
+      ExpirationTime.fromWeeks(1),
+      ExpirationTime.fromMonths(1),
+      ExpirationTime.fromYears(1),
+      ExpirationTime.fromBlocks(3),
+    ]) {
+      expect(lifetime.expiresAt).toBe(0n)
+      expect(lifetime.minLifetime > 0n).toBe(true)
+    }
+    expect(ExpirationTime.atBlock(5n).minLifetime).toBe(0n)
+    expect(ExpirationTime.atDate(new Date(Date.now() + 60_000)).minLifetime).toBe(0n)
+  })
+})
+
+describe("durations — the everyday case", () => {
+  it("turns a duration into a lifetime, with no block arithmetic at the call site", () => {
+    const resolved = resolveExpiry(ExpirationTime.fromDays(30), ctx)
+    // 30 days at 2s/block.
+    expect(resolved.minLifetime).toBe(1_296_000n)
+    expect(resolved.expiresAt).toBe(0n)
+    expect(resolved.target).toBe(CURRENT_BLOCK + 1_296_000n)
+  })
+
+  it("counts blocks exactly, with no conversion to be approximate about", () => {
+    expect(resolveExpiry(ExpirationTime.fromBlocks(7), ctx).minLifetime).toBe(7n)
+    expect(() => ExpirationTime.fromBlocks(0)).toThrow(/positive whole number of blocks/)
+    expect(() => ExpirationTime.fromBlocks(1.5)).toThrow(InvalidExpiryError)
+  })
+
+  it("refuses a duration that is not a whole number of blocks, at the call site", () => {
+    // 3s is a block and a half. Rounding it would silently grant 4s, so it is rejected instead —
+    // and it throws where it is written, not later where it is sent.
+    expect(() => ExpirationTime.fromSeconds(3)).toThrow(/multiple of the 2s block time/)
+    expect(() => ExpirationTime.fromSeconds(999)).toThrow(/Try 998 or 1000/)
+    expect(() => ExpirationTime.fromSeconds(0)).toThrow(/positive whole number of seconds/)
+    expect(() => ExpirationTime.fromSeconds(-2)).toThrow(InvalidExpiryError)
+    expect(() => ExpirationTime.fromSeconds(1.5)).toThrow(InvalidExpiryError)
+  })
+})
+
+describe("deadlines — the absolute case", () => {
+  it("takes a block height as given", () => {
+    const resolved = resolveExpiry(ExpirationTime.atBlock(5_000n), ctx)
+    expect(resolved.expiresAt).toBe(5_000n)
+    expect(resolved.minLifetime).toBe(0n)
+    expect(resolved.target).toBe(5_000n)
+  })
+
+  it("places a Date against the block the transaction is built on", () => {
+    const inAnHour = ExpirationTime.atDate(new Date(Date.now() + 3600_000))
+    const resolved = resolveExpiry(inAnHour, ctx)
+    // 3600s at 2s/block, counted from the current block.
+    expect(resolved.expiresAt).toBe(CURRENT_BLOCK + 1800n)
+    expect(resolved.target).toBe(CURRENT_BLOCK + 1800n)
+  })
+
+  it("rounds a Date up rather than rejecting it, unlike a duration", () => {
+    // A wall-clock instant becomes a block HEIGHT, which is whole by construction — there is no
+    // divisibility question to fail. `fromSeconds(3)` would have thrown; this cannot.
+    const odd = ExpirationTime.atDate(new Date(Date.now() + 3_000))
+    expect(resolveExpiry(odd, ctx).target).toBe(CURRENT_BLOCK + 2n)
+  })
+
+  it("holds the Date until it is resolved, so the value does not depend on when it was built", () => {
+    const date = new Date(Date.now() + 3600_000)
+    const expiry = ExpirationTime.atDate(date)
+    expect(expiry.expiresAt).toEqual(date)
+    // The same value resolves against whatever block it is later sent with.
+    expect(resolveExpiry(expiry, { ...ctx, currentBlock: 9_000n }).target).toBe(9_000n + 1800n)
+  })
+
+  it("rejects a deadline already gone", () => {
+    expect(() => resolveExpiry(ExpirationTime.atDate(new Date(Date.now() - 1000)), ctx)).toThrow(
+      /in the past/,
+    )
+    expect(() => resolveExpiry(ExpirationTime.atBlock(CURRENT_BLOCK - 1n), ctx)).toThrow(
+      /dead on arrival/,
+    )
+    expect(() => resolveExpiry(ExpirationTime.atBlock(CURRENT_BLOCK), ctx)).toThrow(
+      /dead on arrival/,
+    )
+  })
+
+  it("rejects something that is neither a block height nor a Date", () => {
+    expect(() => ExpirationTime.atBlock(-1n)).toThrow(/non-negative block height/)
+    expect(() => ExpirationTime.atDate(new Date("nonsense"))).toThrow(/valid Date/)
+    expect(() => ExpirationTime.atBlock(5 as never)).toThrow(/non-negative block height/)
+  })
+})
+
+describe("a deadline with a floor", () => {
+  it("lives until whichever is later", () => {
+    // The deadline is further out than the floor.
+    const deadlineWins = ExpirationTime.atBlock(5_000n, {
+      atLeast: ExpirationTime.fromSeconds(400),
+    })
+    expect(resolveExpiry(deadlineWins, ctx).target).toBe(5_000n)
+
+    // The floor is further out than the deadline.
+    const floorWins = ExpirationTime.atBlock(1_100n, { atLeast: ExpirationTime.fromDays(1) })
+    expect(resolveExpiry(floorWins, ctx).target).toBe(CURRENT_BLOCK + 43_200n)
+  })
+
+  it("puts both on the wire, leaving the engine to resolve them the same way", () => {
+    const resolved = resolveExpiry(
+      ExpirationTime.atBlock(5_000n, { atLeast: ExpirationTime.fromSeconds(200) }),
+      ctx,
+    )
+    expect(resolved.expiresAt).toBe(5_000n)
+    expect(resolved.minLifetime).toBe(100n)
+  })
+
+  it("works the same on a date deadline", () => {
+    const expiry = ExpirationTime.atDate(new Date(Date.now() + 2_000), {
+      atLeast: ExpirationTime.fromDays(1),
+    })
+    // The date is only a second or two out, so the floor is what keeps the entity alive.
+    expect(resolveExpiry(expiry, ctx).target).toBe(CURRENT_BLOCK + 43_200n)
+  })
+
+  it("treats an omitted floor as no floor", () => {
+    expect(ExpirationTime.atBlock(5_000n, {}).minLifetime).toBe(0n)
+    expect(ExpirationTime.atBlock(5_000n, { atLeast: undefined }).minLifetime).toBe(0n)
+  })
+})
+
+describe("bounds and misuse", () => {
+  it("refuses an expiry that says nothing", () => {
+    // Only reachable from JS, or by hand-building the pair — the type requires ExpirationTime.
+    const nothing = { minLifetime: 0n, expiresAt: 0n } as unknown as Expiry
+    expect(() => resolveExpiry(nothing, ctx)).toThrow(/no expiry given/)
+  })
+
+  it("names ExpirationTime when handed something it did not build", () => {
+    expect(() => resolveExpiry(2_592_000 as unknown as Expiry, ctx)).toThrow(
+      /must be built with ExpirationTime/,
+    )
+    expect(() => resolveExpiry(undefined as unknown as Expiry, ctx)).toThrow(
+      /must be built with ExpirationTime/,
+    )
+  })
+
+  it("bounds an expiry only by the width of the wire field", () => {
+    expect(() => resolveExpiry(ExpirationTime.atBlock(MAX_EXPIRES_AT + 1n), ctx)).toThrow(
+      /does not fit the uint64/,
+    )
+    expect(() => resolveExpiry(ExpirationTime.atBlock(MAX_EXPIRES_AT + 1n), ctx)).toThrow(
+      /ExpirationTime\.permanent\(\)/,
+    )
+  })
+})
+
+describe("toBlocks", () => {
+  it("converts whole blocks' worth of seconds", () => {
+    expect(toBlocks(2)).toBe(1n)
+    expect(toBlocks(4)).toBe(2n)
+    expect(toBlocks(86_400)).toBe(43_200n)
+  })
+
+  it("rejects anything that is not a positive multiple of the block time", () => {
+    for (const bad of [1, 3, 999, 0, -2, 1.5, Number.NaN, Number.POSITIVE_INFINITY]) {
+      expect(() => toBlocks(bad)).toThrow(InvalidExpiryError)
+    }
+  })
+})

package/src/entity/expiry.ts

@@ -0,0 +1,181 @@
+import { BLOCK_TIME } from "../consts"
+import { InvalidExpiryError } from "./errors"
+import { MAX_EXPIRES_AT } from "./params"
+
+/**
+ * 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.
+ */
+export 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.
+ */
+export type Lifetime = Expiry & { readonly expiresAt: 0n }
+
+/**
+ * Builds a branded {@link Expiry}.
+ *
+ * Internal seam for {@link ExpirationTime}, which is the only thing that should call it — it is not
+ * part of the package's public surface.
+ */
+export function makeExpiry(minLifetime: bigint, expiresAt: bigint | Date): Expiry {
+  return { minLifetime, expiresAt } as Expiry
+}
+
+/** The two `uint256` values the ABI carries, with every `Date` already placed. */
+export 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. */
+export 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. */
+export 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.
+ */
+export function resolveExpiry(expiry: Expiry, context: ExpiryContext): ResolvedExpiry {
+  const { currentBlock } = context
+
+  if (typeof expiry?.minLifetime !== "bigint" || expiry.expiresAt === undefined) {
+    throw new InvalidExpiryError(
+      "expires must be built with ExpirationTime, e.g. ExpirationTime.fromDays(30) or " +
+        "ExpirationTime.atBlock(1_200_000n)",
+    )
+  }
+
+  const { minLifetime } = expiry
+  const absolute =
+    typeof expiry.expiresAt === "bigint"
+      ? expiry.expiresAt
+      : blockAtDate(expiry.expiresAt, currentBlock)
+
+  if (minLifetime === 0n && absolute === 0n) {
+    throw new InvalidExpiryError(
+      "no expiry given. Pass ExpirationTime.fromDays(30) for a lifetime, " +
+        "ExpirationTime.atBlock(n) for an absolute deadline, or a deadline with " +
+        "{ atLeast } to take whichever is later.",
+    )
+  }
+
+  if (absolute > MAX_EXPIRES_AT) {
+    throw new InvalidExpiryError(
+      `expiresAt resolves to block ${absolute}, which does not fit the uint64 the wire carries ` +
+        `(max ${MAX_EXPIRES_AT}). Use ExpirationTime.permanent() for an entity that should not ` +
+        "expire.",
+    )
+  }
+  if (minLifetime > MAX_EXPIRES_AT) {
+    throw new InvalidExpiryError(
+      `the lifetime is ${minLifetime} blocks, which does not fit the uint64 the wire carries ` +
+        `(max ${MAX_EXPIRES_AT})`,
+    )
+  }
+
+  const relative = minLifetime === 0n ? 0n : currentBlock + minLifetime
+  const target = absolute > relative ? absolute : relative
+
+  if (target <= currentBlock) {
+    throw new InvalidExpiryError(
+      `the entity would expire at block ${target}, which is not after the current block ` +
+        `${currentBlock}, so it would be dead on arrival`,
+    )
+  }
+  if (target > MAX_EXPIRES_AT) {
+    throw new InvalidExpiryError(
+      `a lifetime of ${minLifetime} blocks from block ${currentBlock} lands at ${target}, past ` +
+        `the largest expiry the wire carries (${MAX_EXPIRES_AT})`,
+    )
+  }
+
+  return { expiresAt: absolute, minLifetime, target }
+}
+
+/**
+ * A duration in seconds as a whole number of blocks.
+ *
+ * Arkiv counts lifetimes in blocks, so a duration that is not a whole number of them does not
+ * describe anything the chain can store. Rather than silently round a caller's `3` up to two blocks
+ * — four seconds, not what they asked for — this rejects it: a duration must be a positive multiple
+ * of `BLOCK_TIME` (2 seconds). The {@link ExpirationTime} helpers all produce such multiples.
+ *
+ * @throws {InvalidExpiryError} If the duration is not a positive whole number of blocks' seconds.
+ */
+export function toBlocks(seconds: number): bigint {
+  if (!Number.isInteger(seconds) || seconds <= 0) {
+    throw new InvalidExpiryError(
+      `a lifetime must be a positive whole number of seconds, got ${seconds}. Use the ` +
+        "ExpirationTime helpers, e.g. ExpirationTime.fromDays(30).",
+    )
+  }
+  if (seconds % BLOCK_TIME !== 0) {
+    throw new InvalidExpiryError(
+      `a lifetime must be a multiple of the ${BLOCK_TIME}s block time, got ${seconds}, which is ` +
+        `${seconds / BLOCK_TIME} blocks. Try ${seconds - (seconds % BLOCK_TIME)} or ` +
+        `${seconds + BLOCK_TIME - (seconds % BLOCK_TIME)}, or ExpirationTime.fromBlocks(n).`,
+    )
+  }
+  return BigInt(seconds / BLOCK_TIME)
+}
+
+/**
+ * The block a wall-clock instant lands on.
+ *
+ * Rounds **up**: a date almost never falls on a block boundary, and unlike a duration — which the
+ * caller states and can state exactly — there is nothing here to reject, so the entity lives until
+ * at least the instant asked for.
+ */
+function blockAtDate(date: Date, currentBlock: bigint): bigint {
+  const secondsAway = (date.getTime() - Date.now()) / 1000
+  if (secondsAway <= 0) {
+    throw new InvalidExpiryError(
+      `the deadline ${date.toISOString()} is in the past, so the entity would be dead on arrival`,
+    )
+  }
+  return currentBlock + BigInt(Math.ceil(secondsAway / BLOCK_TIME))
+}

package/src/entity/flags.ts

@@ -0,0 +1,65 @@
+import { InvalidCreationFlagsError } from "./errors"
+
+/** Bit positions in the `creationFlags` byte. Bits 2-7 are reserved and must be zero. */
+const READONLY_BIT = 0b0000_0001
+const PERMISSIONLESS_EXTENSION_BIT = 0b0000_0010
+
+/**
+ * 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.
+ */
+export 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. */
+export type ResolvedCreationFlags = {
+  readonly: boolean
+  permissionlessExtension: boolean
+  raw: number
+}
+
+/**
+ * Packs creation flags into the `creationFlags` byte.
+ *
+ * @throws {InvalidCreationFlagsError} If a value is not a boolean.
+ */
+export function encodeCreationFlags(flags: CreationFlags = {}): number {
+  for (const [name, value] of Object.entries(flags)) {
+    if (value !== undefined && 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
+ */
+export function decodeCreationFlags(raw: number): ResolvedCreationFlags {
+  if (!Number.isInteger(raw) || raw < 0 || raw > 0xff) {
+    throw new InvalidCreationFlagsError(`${raw} is not a byte`)
+  }
+  return {
+    readonly: (raw & READONLY_BIT) !== 0,
+    permissionlessExtension: (raw & PERMISSIONLESS_EXTENSION_BIT) !== 0,
+    raw,
+  }
+}

package/src/entity/index.ts

@@ -0,0 +1,14 @@
+export {
+  InvalidCreationFlagsError,
+  InvalidExpiryError,
+  InvalidSaltError,
+  NoRandomSourceError,
+} from "./errors"
+export type { EntityEventName } from "./events"
+export { ENTITY_EVENTS_ABI } from "./events"
+export type { EncodedExpiry, Expiry, ExpiryContext, Lifetime, ResolvedExpiry } from "./expiry"
+export { resolveExpiry, toBlocks } from "./expiry"
+export type { CreationFlags, ResolvedCreationFlags } from "./flags"
+export { decodeCreationFlags, encodeCreationFlags } from "./flags"
+export { MAX_SALT, predictEntityKey, randomSalt } from "./key"
+export { MAX_EXPIRES_AT, OperationType } from "./params"

package/src/entity/key.ts

@@ -0,0 +1,68 @@
+import { type Address, encodePacked, type Hex, keccak256 } from "viem"
+import { ARKIV_ADDRESS } from "../consts"
+import { InvalidSaltError, NoRandomSourceError } from "./errors"
+
+/** The widest salt the `uint128` wire field carries. */
+export const MAX_SALT = 2n ** 128n - 1n
+
+/**
+ * A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
+ *
+ * The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees
+ * distinct keys. Random bits mean only the creator can predict the key of an entity they are about
+ * to create, so nobody else can reference or squat it in advance.
+ *
+ * @throws {NoRandomSourceError} If the runtime has no `crypto.getRandomValues`.
+ */
+export function randomSalt(): bigint {
+  const source = globalThis.crypto
+  if (typeof source?.getRandomValues !== "function") {
+    throw new NoRandomSourceError()
+  }
+  const bytes = source.getRandomValues(new Uint8Array(16))
+  let salt = 0n
+  for (const byte of bytes) salt = (salt << 8n) | BigInt(byte)
+  return salt
+}
+
+/** Validates a caller-supplied salt against the `uint128` wire field. */
+export function validateSalt(salt: bigint): bigint {
+  if (typeof salt !== "bigint" || salt < 0n || salt > MAX_SALT) {
+    throw new InvalidSaltError(salt)
+  }
+  return salt
+}
+
+/**
+ * The key an entity will be created with, derived exactly as the engine derives it:
+ * `keccak256(domain ++ owner ++ nonce ++ salt)`.
+ *
+ * Deriving it client-side is what lets a batch compose: predict the key of a create, then have a
+ * later operation in the same transaction reference it, or store it as a `key` attribute on a
+ * sibling entity.
+ */
+export function predictEntityKey({
+  owner,
+  nonce,
+  salt,
+  chainId,
+}: {
+  /** The account creating the entity. */
+  owner: Address
+  /**
+   * The owner's entity-nonce at creation time. Each create in a batch consumes one, so the *n*th
+   * create in a batch uses `nonce + n`.
+   */
+  nonce: bigint
+  /** The salt the create will carry. */
+  salt: bigint
+  /** The chain the entity is being created on — half of the derivation domain. */
+  chainId: number
+}): Hex {
+  return keccak256(
+    encodePacked(
+      ["uint256", "address", "address", "uint64", "uint128"],
+      [BigInt(chainId), ARKIV_ADDRESS, owner, nonce, validateSalt(salt)],
+    ),
+  )
+}

package/src/entity/operations.ts

@@ -0,0 +1,134 @@
+import { type Address, encodeAbiParameters, type Hex, parseAbi, parseAbiParameters } from "viem"
+import type { AbiAttribute } from "../attr/codec"
+import type { EncodedExpiry } from "./expiry"
+import { OperationType } from "./params"
+
+/**
+ * The one external entry point. A transaction is an ordered, **atomic** batch of entity operations:
+ * all of them apply or none do, operation *n+1* observes operation *n*'s effects, and each applied
+ * operation emits one event.
+ */
+export const EXECUTE_ABI = parseAbi([
+  "function execute((uint8 operation, bytes operationData)[] ops) external returns (bytes32[] keys)",
+])
+
+/**
+ * The engine's one read-only view: an owner's entity-minting nonce, which is the input
+ * {@link predictEntityKey} needs and the only part of the derivation the caller cannot know.
+ *
+ * It is a `view` on the same address `execute` is called on, so it answers over `eth_call` without
+ * a transaction.
+ */
+export const ENTITY_NONCE_ABI = parseAbi([
+  "function entityNonce(address owner) external view returns (uint64)",
+])
+
+/**
+ * The shared attribute shape, used by `create` (attributes) and `patch` (mutations). Written out
+ * once and reused by every payload that carries attributes.
+ */
+const ATTRIBUTE_TUPLE = "(bytes32 name, uint8 typeId, bytes value)[]"
+
+/**
+ * The payload struct for each operation tag. `operationData` is `abi.encode` of the struct the tag
+ * selects — a tagged union, so a new operation is additive rather than a change to `execute`.
+ */
+const PAYLOAD_PARAMS = {
+  [OperationType.Create]: parseAbiParameters(
+    `(uint128 salt, uint64 expiresAt, uint64 minLifetime, uint8 creationFlags, ${ATTRIBUTE_TUPLE} attributes)`,
+  ),
+  [OperationType.Patch]: parseAbiParameters(`(bytes32 entityKey, ${ATTRIBUTE_TUPLE} mutations)`),
+  [OperationType.ExtendExpiry]: parseAbiParameters(
+    "(bytes32 entityKey, uint64 expiresAt, uint64 minLifetime)",
+  ),
+  [OperationType.TransferOwnership]: parseAbiParameters("(bytes32 entityKey, address newOwner)"),
+  [OperationType.Delete]: parseAbiParameters("(bytes32 entityKey)"),
+} as const
+
+/** One entry of the `execute` batch: the operation tag and its ABI-encoded payload. */
+export type Operation = {
+  operation: number
+  operationData: Hex
+}
+
+/** Creates an entity. The key is derived by the engine; predict it with `predictEntityKey`. */
+export function createOperation({
+  salt,
+  expiry,
+  creationFlags,
+  attributes,
+}: {
+  salt: bigint
+  expiry: EncodedExpiry
+  creationFlags: number
+  attributes: AbiAttribute[]
+}): Operation {
+  return {
+    operation: OperationType.Create,
+    operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.Create], [
+      {
+        salt,
+        expiresAt: expiry.expiresAt,
+        minLifetime: expiry.minLifetime,
+        creationFlags,
+        attributes,
+      },
+    ]),
+  }
+}
+
+/** Applies a set of mutations to an existing entity. Tombstones unset attributes. */
+export function patchOperation({
+  entityKey,
+  mutations,
+}: {
+  entityKey: Hex
+  mutations: AbiAttribute[]
+}): Operation {
+  return {
+    operation: OperationType.Patch,
+    operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.Patch], [
+      { entityKey, mutations },
+    ]),
+  }
+}
+
+/** Pushes an entity's expiry further out. Extending is allowed; shortening reverts. */
+export function extendExpiryOperation({
+  entityKey,
+  expiry,
+}: {
+  entityKey: Hex
+  expiry: EncodedExpiry
+}): Operation {
+  return {
+    operation: OperationType.ExtendExpiry,
+    operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.ExtendExpiry], [
+      { entityKey, expiresAt: expiry.expiresAt, minLifetime: expiry.minLifetime },
+    ]),
+  }
+}
+
+/** Hands an entity to a new owner. */
+export function transferOwnershipOperation({
+  entityKey,
+  newOwner,
+}: {
+  entityKey: Hex
+  newOwner: Address
+}): Operation {
+  return {
+    operation: OperationType.TransferOwnership,
+    operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.TransferOwnership], [
+      { entityKey, newOwner },
+    ]),
+  }
+}
+
+/** Deletes an entity before its expiry. */
+export function deleteOperation({ entityKey }: { entityKey: Hex }): Operation {
+  return {
+    operation: OperationType.Delete,
+    operationData: encodeAbiParameters(PAYLOAD_PARAMS[OperationType.Delete], [{ entityKey }]),
+  }
+}

package/src/entity/params.ts

@@ -0,0 +1,15 @@
+/**
+ * Max uint64 value
+ */
+export const MAX_EXPIRES_AT = 2n ** 64n - 1n
+
+/** The operation tags of the `execute` ABI's tagged union. */
+export const OperationType = {
+  Create: 1,
+  Patch: 2,
+  ExtendExpiry: 3,
+  TransferOwnership: 4,
+  Delete: 5,
+} as const
+
+export type OperationType = (typeof OperationType)[keyof typeof OperationType]