@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

package/src/clients/decorators/arkivWallet.ts

@@ -14,28 +14,29 @@ import type {
   DeleteEntityReturnType,
 } from "../../actions/wallet/deleteEntity"
 import { deleteEntity } from "../../actions/wallet/deleteEntity"
+import type {
+  ExecuteBatchParameters,
+  ExecuteBatchReturnType,
+} from "../../actions/wallet/executeBatch"
+import { executeBatch } from "../../actions/wallet/executeBatch"
 import type {
   ExtendEntityParameters,
   ExtendEntityReturnType,
 } from "../../actions/wallet/extendEntity"
 import { extendEntity } from "../../actions/wallet/extendEntity"
-import type {
-  MutateEntitiesParameters,
-  MutateEntitiesReturnType,
-} from "../../actions/wallet/mutateEntities"
-import { mutateEntities } from "../../actions/wallet/mutateEntities"
-import type {
-  UpdateEntityParameters,
-  UpdateEntityReturnType,
-} from "../../actions/wallet/updateEntity"
-import { updateEntity } from "../../actions/wallet/updateEntity"
+import type { PatchEntityParameters, PatchEntityReturnType } from "../../actions/wallet/patchEntity"
+import { patchEntity } from "../../actions/wallet/patchEntity"
 import type { TxParams } from "../../types"
+import { type WalletAdvancedActions, walletAdvancedActions } from "./arkivAdvanced"
 
 export type WalletArkivActions<
   transport extends Transport = Transport,
   chain extends Chain | undefined = Chain | undefined,
   account extends Account | undefined = Account | undefined,
-> = Pick<PublicActions<transport, chain, account>, "waitForTransactionReceipt" | "call"> &
+> = Pick<
+  PublicActions<transport, chain, account>,
+  "waitForTransactionReceipt" | "call" | "simulateContract" | "readContract" | "getBlockNumber"
+> &
   Pick<
     WalletActions<chain, account>,
     | "addChain"
@@ -45,41 +46,41 @@ export type WalletArkivActions<
     | "sendRawTransaction"
     | "signMessage"
     | "signTransaction"
+    | "writeContract"
   > & {
     /**
      * Creates a new entity.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/createEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity creation parameters
      * @param txParams - Optional transaction parameters
-     * @returns The created entity with transaction hash
+     * @returns The new entity's key, the transaction hash, and the block it is expected to
+     * expire at. {@link CreateEntityReturnType}
      *
-     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-     * that is a multiple of the block time (2 seconds).
-     * @throws {InvalidAttributeError} If a numeric attribute value is not an
-     * integer.
+     * @throws {InvalidExpiryError} If the expiry exceeds a protocol bound or would leave the
+     * entity dead on arrival.
+     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+     * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
      *
      * @example
-     * import { createPublicClient, http } from 'arkiv'
-     * import { braga } from 'arkiv/chains'
+     * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
+     * import { i32 } from "@arkiv-network/sdk/attr"
+     * import { cheesecake } from "@arkiv-network/sdk/chains"
+     * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
-     * const client = createPublicClient({
-     *   chain: braga,
+     * const client = createWalletClient({
+     *   account: privateKeyToAccount("0x..."),
+     *   chain: cheesecake,
      *   transport: http(),
      * })
-     * const { entityKey, txHash } = await client.createEntity({
-     *   payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-     *   attributes: [{ key: "testKey", value: "testValue" }],
-     *   expiresIn: 1000,
+     * const { entityKey, txHash, expiresAt } = await client.createEntity({
+     *   payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
+     *   contentType: "application/json",
+     *   attributes: { testKey: "testValue", level: i32(3) },
+     *   expires: ExpirationTime.fromDays(30),
      * })
-     * console.log("entityKey", entityKey)
-     * console.log("txHash", txHash)
-     * // {
-     * //   entityKey: "0x123",
-     * //   txHash: "0x123",
-     * // }
      */
     createEntity: (
       data: CreateEntityParameters,
@@ -87,59 +88,67 @@ export type WalletArkivActions<
     ) => Promise<CreateEntityReturnType>
 
     /**
-     * Updates the entity with the given key.
+     * Applies a patch to the entity with the given key: sets some fields, unsets others, and leaves
+     * everything it does not name alone.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/updateEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
-     * @param data - The entity update parameters
+     * @param data - The entity key and the mutations to apply
      * @param txParams - Optional transaction parameters
-     * @returns The updated entity with transaction hash
+     * @returns The patched entity's key and the transaction hash. {@link PatchEntityReturnType}
      *
-     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-     * that is a multiple of the block time (2 seconds).
-     * @throws {InvalidAttributeError} If a numeric attribute value is not an
-     * integer.
+     * @throws {EmptyPatchError} If the patch has nothing to apply.
+     * @throws {ConflictingMutationError} If a name appears in both `set` and `unset`.
+     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+     * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
      *
      * @example
-     * import { createWalletClient, http } from 'arkiv'
-     * import { braga } from 'arkiv/chains'
+     * import { createWalletClient, jsonToPayload } from "@arkiv-network/sdk"
+     * import { i32 } from "@arkiv-network/sdk/attr"
+     * import { cheesecake } from "@arkiv-network/sdk/chains"
+     * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
-     *   chain: braga,
+     *   account: privateKeyToAccount("0x..."),
+     *   chain: cheesecake,
      *   transport: http(),
      * })
+     * // Publish the entity: one attribute changes, one goes away, the payload is replaced.
+     * const { txHash } = await client.patchEntity({
+     *   entityKey,
+     *   set: { status: "published", revision: i32(2) },
+     *   unset: ["draft"],
+     *   payload: jsonToPayload({ title: "Hello" }),
+     * })
      */
-    updateEntity: (
-      data: UpdateEntityParameters,
+    patchEntity: (
+      data: PatchEntityParameters,
       txParams?: TxParams,
-    ) => Promise<UpdateEntityReturnType>
+    ) => Promise<PatchEntityReturnType>
 
     /**
      * Deletes the entity with the given key.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/deleteEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The entity deletion parameters
      * @param txParams - Optional transaction parameters
-     * @returns The deleted entity with transaction hash
+     * @returns The deleted entity's key and the transaction hash. {@link DeleteEntityReturnType}
      *
      * @example
-     * import { createWalletClient, http } from 'arkiv'
-     * import { braga } from 'arkiv/chains'
+     * import { createWalletClient } from "@arkiv-network/sdk"
+     * import { cheesecake } from "@arkiv-network/sdk/chains"
+     * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
-     *   chain: braga,
+     *   account: privateKeyToAccount("0x..."),
+     *   chain: cheesecake,
      *   transport: http(),
      * })
-     * const { entityKey, txHash } = await client.deleteEntity({ entityKey: "0x123" })
-     * console.log("entityKey", entityKey)
-     * console.log("txHash", txHash)
-     * // {
-     * //   entityKey: "0x123",
-     * //   txHash: "0x123",
-     * // }
+     * // entityKey is the bytes32 key returned by createEntity.
+     * const { txHash } = await client.deleteEntity({ entityKey })
      */
     deleteEntity: (
       data: DeleteEntityParameters,
@@ -147,35 +156,37 @@ export type WalletArkivActions<
     ) => Promise<DeleteEntityReturnType>
 
     /**
-     * Extends the entity with the given key.
+     * Sets a new expiry on the entity with the given key.
+     *
+     * The new lifetime is resolved the same way a create's is: a duration counts from now rather
+     * than adding to what the entity has left, and `atBlock` / `atDate` pin an absolute deadline.
+     * The engine rejects an extension that would not move the expiry later.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/extendEntity
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
-     * @param data - The entity update parameters
+     * @param data - The entity key and its new lifetime
      * @param txParams - Optional transaction parameters
-     * @returns The updated entity with transaction hash
+     * @returns The entity's key, the transaction hash, and the block it is now expected to expire
+     * at. {@link ExtendEntityReturnType}
      *
-     * @throws {InvalidExpirationError} If `expiresIn` is not a positive integer
-     * that is a multiple of the block time (2 seconds).
+     * @throws {InvalidExpiryError} If the expiry is malformed, exceeds a protocol bound, or would
+     * leave the entity dead on arrival.
      *
      * @example
-     * import { createWalletClient, http } from 'arkiv'
-     * import { braga } from 'arkiv/chains'
+     * import { createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
+     * import { cheesecake } from "@arkiv-network/sdk/chains"
+     * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
-     *   chain: braga,
+     *   account: privateKeyToAccount("0x..."),
+     *   chain: cheesecake,
      *   transport: http(),
      * })
-     * const { entityKey, txHash } = await client.extendEntity("0x123", {
-     *   expiresIn: 1000,
+     * const { txHash, expiresAt } = await client.extendEntity({
+     *   entityKey,
+     *   expires: ExpirationTime.fromDays(30),
      * })
-     * console.log("entityKey", entityKey)
-     * console.log("txHash", txHash)
-     * // {
-     * //   entityKey: "0x123",
-     * //   txHash: "0x123",
-     * // }
      */
     extendEntity: (
       data: ExtendEntityParameters,
@@ -183,14 +194,13 @@ export type WalletArkivActions<
     ) => Promise<ExtendEntityReturnType>
 
     /**
-     * Changes the ownership of the entity with the given address.
+     * Hands the entity with the given key to a new owner.
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/changeOwnership
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
      * @param data - The ownership change parameters
      * @param txParams - Optional transaction parameters
-     * @returns The entity with updated ownership and transaction hash
+     * @returns The entity's key and the transaction hash. {@link ChangeOwnershipReturnType}
      */
     changeOwnership: (
       data: ChangeOwnershipParameters,
@@ -198,59 +208,67 @@ export type WalletArkivActions<
     ) => Promise<ChangeOwnershipReturnType>
 
     /**
-     * Mutates the entities with the given keys.
+     * Applies a batch of entity operations — creates, patches, deletes, extensions and ownership
+     * transfers — in one transaction.
+     *
+     * - JSON-RPC Methods: `eth_sendRawTransaction`
      *
-     * - Docs: https://docs.arkiv.network/ts-sdk/actions/wallet/mutateEntities
-     * - JSON-RPC Methods: [`eth_sendRawTransaction`](https://docs.arkiv.network/dev/json-rpc-api/#mutateEntities)
+     * Every operation lands in one transaction, so the whole batch applies or none of it does.
+     * At least one operation is required.
      *
-     * @param data - The mutation parameters (creates, updates, deletes, extensions)
+     * @param data - The batch parameters (creates, patches, deletes, extensions, ownershipChanges)
      * @param txParams - Optional transaction parameters
-     * @returns The mutation result with transaction hash
+     * @returns The transaction hash, plus the keys touched by each kind of operation.
+     * {@link ExecuteBatchReturnType}
      *
-     * @throws {InvalidExpirationError} If any create/update/extension `expiresIn`
-     * is not a positive integer that is a multiple of the block time (2 seconds).
-     * @throws {InvalidAttributeError} If a numeric attribute value is not an
-     * integer.
+     * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound or would leave the entity
+     * dead on arrival.
+     * @throws {InvalidValueError} If an attribute value does not fit the type it names.
      *
      * @example
-     * import { createWalletClient, http } from 'arkiv'
-     * import { braga } from 'arkiv/chains'
+     * import { createWalletClient, ExpirationTime, jsonToPayload } from "@arkiv-network/sdk"
+     * import { cheesecake } from "@arkiv-network/sdk/chains"
+     * import { http } from "viem"
+     * import { privateKeyToAccount } from "viem/accounts"
      *
      * const client = createWalletClient({
-     *   chain: braga,
+     *   account: privateKeyToAccount("0x..."),
+     *   chain: cheesecake,
      *   transport: http(),
      * })
-     * const { entityKey, txHash } = await client.mutateEntities({
+     * const { txHash, createdEntities } = await client.executeBatch({
      *   creates: [{
-     *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-     *     attriubutes: [{ key: "testKey", value: "testValue" }],
-     *     expiresIn: 1000,
-     *   }],
-     *   updates: [{
-     *     entityKey: "0x123",
-     *     payload: toBytes(JSON.stringify({ entity: { entityType: "testType", entityId: "testId" } })),
-     *     attributes: [{ key: "testKey", value: "testValue" }],
-     *     expiresIn: 1000,
-     *   }],
-     *   deletes: [{
-     *     entityKey: "0x321",
+     *     payload: jsonToPayload({ entityType: "testType", entityId: "testId" }),
+     *     contentType: "application/json",
+     *     attributes: { testKey: "testValue" },
+     *     expires: ExpirationTime.fromDays(30),
      *   }],
+     *   patches: [{ entityKey: keyToRevise, set: { status: "archived" }, unset: ["draft"] }],
+     *   deletes: [{ entityKey: staleKey }],
      *   extensions: [{
-     *     entityKey: "0x1234",
-     *     expiresIn: 1000,
+     *     entityKey: keyToKeepAlive,
+     *     expires: ExpirationTime.atBlock(1_200_000n),
      *   }],
+     *   ownershipChanges: [{ entityKey: keyToHandOver, newOwner }],
      * })
-     * console.log("entityKey", entityKey)
-     * console.log("txHash", txHash)
-     * // {
-     * //   entityKey: "0x123",
-     * //   txHash: "0x123",
-     * // }
      */
-    mutateEntities: (
-      data: MutateEntitiesParameters,
+    executeBatch: (
+      data: ExecuteBatchParameters,
       txParams?: TxParams,
-    ) => Promise<MutateEntitiesReturnType>
+    ) => Promise<ExecuteBatchReturnType>
+
+    /**
+     * The advanced path: build, send, ping and read mutation results as separate steps, each
+     * costing the minimum number of RPC calls. Use it when you are optimising your RPC budget;
+     * the everyday actions above remain the right default. {@link WalletAdvancedActions}
+     *
+     * @example
+     * const { txHash } = await client.advanced.sendMutation({ creates: [entity] }) // no waiting
+     * // ... later, one eth_getTransactionReceipt on your own schedule:
+     * const result = await client.advanced.getMutationResult(txHash)
+     * if (result.status === "success") console.log(result.createdEntities)
+     */
+    advanced: WalletAdvancedActions
   }
 
 export function walletArkivActions<
@@ -261,15 +279,16 @@ export function walletArkivActions<
   return {
     createEntity: (data: CreateEntityParameters, txParams?: TxParams) =>
       createEntity(client, data, txParams),
-    updateEntity: (data: UpdateEntityParameters, txParams?: TxParams) =>
-      updateEntity(client, data, txParams),
+    patchEntity: (data: PatchEntityParameters, txParams?: TxParams) =>
+      patchEntity(client, data, txParams),
     deleteEntity: (data: DeleteEntityParameters, txParams?: TxParams) =>
       deleteEntity(client, data, txParams),
     extendEntity: (data: ExtendEntityParameters, txParams?: TxParams) =>
       extendEntity(client, data, txParams),
     changeOwnership: (data: ChangeOwnershipParameters, txParams?: TxParams) =>
       changeOwnership(client, data, txParams),
-    mutateEntities: (data: MutateEntitiesParameters, txParams?: TxParams) =>
-      mutateEntities(client, data, txParams),
+    executeBatch: (data: ExecuteBatchParameters, txParams?: TxParams) =>
+      executeBatch(client, data, txParams),
+    advanced: walletAdvancedActions(client),
   }
 }

package/src/consts.ts

@@ -1,2 +1,3 @@
-export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+//export const ARKIV_ADDRESS = "0x00000000000000000000000000000061726b6976" as `0x${string}`
+export const ARKIV_ADDRESS = "0x4400000000000000000000000000000000000044" as `0x${string}`
 export const BLOCK_TIME = 2 // 2 seconds

package/src/entity/create.test.ts

@@ -0,0 +1,203 @@
+import { describe, expect, it } from "bun:test"
+import { decodeAbiParameters, parseAbiParameters, toHex } from "viem"
+import { encodeAttributes } from "../attr/attributes"
+import { dec, i32, str, u256 } from "../attr/values"
+import { InvalidCreationFlagsError } from "./errors"
+import { decodeCreationFlags, encodeCreationFlags } from "./flags"
+import { MAX_SALT, NO_SALT, predictEntityKey, randomSalt, resolveSalt, validateSalt } from "./key"
+import { createOperation } from "./operations"
+import { OperationType } from "./params"
+
+const OWNER = "0xd8dA6BF26964aF9D7eEd9e03E53415D37aA96045"
+
+const CREATE_PARAMS = parseAbiParameters(
+  "(uint128 salt, uint64 expiresAt, uint64 minLifetime, uint8 creationFlags, (bytes32 name, uint8 typeId, bytes value)[] attributes)",
+)
+
+/** Decodes an operation's payload back into the Create struct it encodes. */
+function decodeCreate(operationData: `0x${string}`) {
+  const [create] = decodeAbiParameters(CREATE_PARAMS, operationData)
+  return create
+}
+
+describe("creation flags", () => {
+  it("packs each flag into its documented bit", () => {
+    expect(encodeCreationFlags({})).toBe(0b00)
+    expect(encodeCreationFlags({ readonly: true })).toBe(0b01)
+    expect(encodeCreationFlags({ permissionlessExtension: true })).toBe(0b10)
+    expect(encodeCreationFlags({ readonly: true, permissionlessExtension: true })).toBe(0b11)
+    expect(encodeCreationFlags()).toBe(0)
+  })
+
+  it("round-trips through the byte", () => {
+    for (const readonly of [true, false]) {
+      for (const permissionlessExtension of [true, false]) {
+        const decoded = decodeCreationFlags(
+          encodeCreationFlags({ readonly, permissionlessExtension }),
+        )
+        expect(decoded.readonly).toBe(readonly)
+        expect(decoded.permissionlessExtension).toBe(permissionlessExtension)
+      }
+    }
+  })
+
+  it("refuses a value that is not a byte at all", () => {
+    // Malformed input
+    expect(() => decodeCreationFlags(256)).toThrow(InvalidCreationFlagsError)
+    expect(() => decodeCreationFlags(256)).toThrow(/not a byte/)
+    expect(() => decodeCreationFlags(-1)).toThrow(/not a byte/)
+  })
+
+  it("keeps the raw byte, so unknown state stays visible", () => {
+    expect(decodeCreationFlags(0b11).raw).toBe(3)
+  })
+})
+
+describe("salt", () => {
+  it("generates 128 bits within the wire field", () => {
+    for (let i = 0; i < 32; i++) {
+      const salt = randomSalt()
+      expect(salt).toBeGreaterThanOrEqual(0n)
+      expect(salt).toBeLessThanOrEqual(MAX_SALT)
+    }
+  })
+
+  it("does not repeat", () => {
+    const seen = new Set(Array.from({ length: 64 }, () => randomSalt().toString()))
+    expect(seen.size).toBe(64)
+  })
+
+  it("bounds a caller-supplied salt to the uint128 field", () => {
+    expect(validateSalt(0n)).toBe(0n)
+    expect(validateSalt(MAX_SALT)).toBe(MAX_SALT)
+    expect(() => validateSalt(MAX_SALT + 1n)).toThrow(/uint128/)
+    expect(() => validateSalt(-1n)).toThrow(/uint128/)
+  })
+
+  it("resolves NO_SALT to the zero, and passes anything else through", () => {
+    expect(resolveSalt(NO_SALT)).toBe(0n)
+    expect(resolveSalt(0n)).toBe(0n)
+    expect(resolveSalt(42n)).toBe(42n)
+    expect(() => resolveSalt(MAX_SALT + 1n)).toThrow(/uint128/)
+  })
+
+  it("reports a salt it cannot use without choking on a symbol", () => {
+    // @ts-expect-error
+    expect(() => validateSalt(Symbol("nope"))).toThrow(/Invalid salt/)
+  })
+})
+
+describe("predictEntityKey", () => {
+  it("is deterministic in owner, nonce and salt", () => {
+    const base = { owner: OWNER, nonce: 0n, salt: 7n, chainId: 1 } as const
+    expect(predictEntityKey(base)).toBe(predictEntityKey(base))
+    expect(predictEntityKey({ ...base, nonce: 1n })).not.toBe(predictEntityKey(base))
+    expect(predictEntityKey({ ...base, salt: 8n })).not.toBe(predictEntityKey(base))
+    expect(
+      predictEntityKey({ ...base, owner: "0x1111111111111111111111111111111111111111" }),
+    ).not.toBe(predictEntityKey(base))
+  })
+
+  it("derives the same key from NO_SALT as from an explicit zero", () => {
+    const base = { owner: OWNER, nonce: 3n, chainId: 1 } as const
+    expect(predictEntityKey({ ...base, salt: NO_SALT })).toBe(
+      predictEntityKey({ ...base, salt: 0n }),
+    )
+  })
+
+  it("separates chains through the domain", () => {
+    const base = { owner: OWNER, nonce: 0n, salt: 0n } as const
+    expect(predictEntityKey({ ...base, chainId: 1 })).not.toBe(
+      predictEntityKey({ ...base, chainId: 2 }),
+    )
+  })
+
+  it("returns a 32-byte key", () => {
+    expect(predictEntityKey({ owner: OWNER, nonce: 0n, salt: 0n, chainId: 1 })).toMatch(
+      /^0x[0-9a-f]{64}$/,
+    )
+  })
+})
+
+describe("the Create operation", () => {
+  const build = (over: Partial<Parameters<typeof createOperation>[0]> = {}) =>
+    createOperation({
+      salt: 42n,
+      expiry: { expiresAt: 0n, minLifetime: 43_200n },
+      creationFlags: 0,
+      attributes: [],
+      ...over,
+    })
+
+  it("carries the CREATE tag", () => {
+    expect(build().operation).toBe(OperationType.Create)
+  })
+
+  it("round-trips its fields through the ABI", () => {
+    const create = decodeCreate(
+      build({
+        salt: 42n,
+        expiry: { expiresAt: 1_200_000n, minLifetime: 100n },
+        creationFlags: 0b11,
+      }).operationData,
+    )
+    expect(create.salt).toBe(42n)
+    expect(create.expiresAt).toBe(1_200_000n)
+    expect(create.minLifetime).toBe(100n)
+    expect(create.creationFlags).toBe(3)
+  })
+
+  it("carries attributes as (name, typeId, bytes), sorted ascending by name", () => {
+    const create = decodeCreate(
+      build({
+        attributes: encodeAttributes({ zebra: i32(1), apple: str("x"), mango: u256(2n) }),
+      }).operationData,
+    )
+    const names = create.attributes.map((a) => a.name)
+    expect(names).toEqual([...names].sort())
+    expect(create.attributes.map((a) => a.typeId)).toEqual([8, 4, 2]) // apple str, mango u256, zebra i32
+  })
+
+  it("sends the payload and content type as system cells, ahead of user attributes", () => {
+    const create = decodeCreate(
+      build({
+        attributes: encodeAttributes(
+          { level: i32(10) },
+          { payload: new Uint8Array([0xde, 0xad]), contentType: "application/json" },
+        ),
+      }).operationData,
+    )
+    const byName = Object.fromEntries(create.attributes.map((a) => [a.name, a]))
+
+    // "$" sorts below every letter, so the system cells lead.
+    expect(create.attributes[0].name).toBe(toHex("$contentType", { size: 32 }))
+    expect(create.attributes[1].name).toBe(toHex("$payload", { size: 32 }))
+
+    expect(byName[toHex("$payload", { size: 32 })]).toMatchObject({ typeId: 7, value: "0xdead" })
+    expect(byName[toHex("$contentType", { size: 32 })].typeId).toBe(8)
+    expect(byName[toHex("level", { size: 32 })].typeId).toBe(2)
+  })
+
+  it("omits the system cells entirely when there is no payload or content type", () => {
+    const create = decodeCreate(
+      build({ attributes: encodeAttributes({ level: i32(10) }) }).operationData,
+    )
+    expect(create.attributes).toHaveLength(1)
+    expect(create.attributes[0].name).toBe(toHex("level", { size: 32 }))
+  })
+
+  it("encodes each value type at its documented width", () => {
+    const create = decodeCreate(
+      build({
+        attributes: encodeAttributes({ n: i32(-42), big: u256(1n), d: dec("1.5"), s: str("hi") }),
+      }).operationData,
+    )
+    const byName = Object.fromEntries(create.attributes.map((a) => [a.name, a.value]))
+    // Word types are exactly 32 bytes; i32 is sign-extended.
+    expect(byName[toHex("n", { size: 32 })]).toBe(`0x${"ff".repeat(31)}d6`)
+    expect(byName[toHex("big", { size: 32 })]).toBe(`0x${"00".repeat(31)}01`)
+    expect(BigInt(byName[toHex("d", { size: 32 })])).toBe(1_500_000_000_000_000_000n)
+    // str is raw UTF-8, not padded.
+    expect(byName[toHex("s", { size: 32 })]).toBe("0x6869")
+  })
+})

package/src/entity/errors.ts

@@ -0,0 +1,39 @@
+/** An expiry could not be expressed, or would be rejected by the engine. */
+export class InvalidExpiryError extends Error {
+  constructor(reason: string) {
+    super(`Invalid expiry: ${reason}`)
+    this.name = "InvalidExpiryError"
+  }
+}
+
+/** A `creationFlags` byte could not be built or read. */
+export class InvalidCreationFlagsError extends Error {
+  constructor(reason: string) {
+    super(`Invalid creation flags: ${reason}`)
+    this.name = "InvalidCreationFlagsError"
+  }
+}
+
+/** A key salt was outside the `uint128` the wire carries. */
+export class InvalidSaltError extends Error {
+  constructor(salt: unknown) {
+    super(
+      `Invalid salt ${String(salt)}. A salt is a uint128, so it must be between 0 and ` +
+        `${2n ** 128n - 1n}. Omit it to get 128 random bits, or pass NO_SALT for a key derived ` +
+        `from the owner and nonce alone.`,
+    )
+    this.name = "InvalidSaltError"
+  }
+}
+
+/** No cryptographic randomness was available to generate a salt. */
+export class NoRandomSourceError extends Error {
+  constructor() {
+    super(
+      "No cryptographic random source is available (globalThis.crypto.getRandomValues is " +
+        "missing), so a key salt cannot be generated. Upgrade to Node 18+ or a modern browser, " +
+        "or pass an explicit salt.",
+    )
+    this.name = "NoRandomSourceError"
+  }
+}

package/src/entity/events.ts

@@ -0,0 +1,16 @@
+import { parseAbi } from "viem"
+
+/**
+ * The events the engine emits: one per applied operation, in application order, so an off-chain
+ * replica can replay a transaction operation by operation.
+ */
+export const ENTITY_EVENTS_ABI = parseAbi([
+  "event EntityCreated(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt, uint8 creationFlags)",
+  "event EntityPatched(bytes32 indexed entityKey, address indexed owner)",
+  "event ExpiryExtended(bytes32 indexed entityKey, address indexed owner, uint64 expiresAt)",
+  "event OwnershipTransferred(bytes32 indexed entityKey, address indexed previousOwner, address indexed newOwner)",
+  "event EntityDeleted(bytes32 indexed entityKey, address indexed owner)",
+])
+
+/** The name of each event in {@link ENTITY_EVENTS_ABI}. */
+export type EntityEventName = (typeof ENTITY_EVENTS_ABI)[number]["name"]