@arkiv-network/sdk 0.8.1-dev.1 → 0.9.0-next.2

package/src/actions/public/query.ts

@@ -1,47 +1,75 @@
 import type { ArkivClient } from "../../clients/baseClient"
 import { runQuery } from "../../query/engine"
 import type { Expression } from "../../query/expression"
-import { type SelectArg, toRpcSelect } from "../../query/selection"
-import type { Entity } from "../../types/entity"
+import {
+  type FullEntity,
+  projectSelection,
+  type ResultOf,
+  type SelectArg,
+  type SelectionOf,
+  toRow,
+} from "../../query/selection"
 
-export type QueryOptions = {
-  /** What to return. Defaults to everything. */
-  select?: SelectArg | undefined
+export type QueryOptions<TSelection extends SelectArg = SelectArg> = {
+  /** What to return — the same selection `select()` takes. Defaults to everything. */
+  select?: TSelection | undefined
   /** Block height to read at. Defaults to the head. */
   atBlock?: bigint | undefined
-  /** Page size, up to the node maximum of 200. */
+  /** Page size, up to the node maximum of 100. */
   limit?: number | undefined
   /** Cursor from a previous page. */
   cursor?: string | undefined
+  /** Whether to also count every entity the query matches, returned as `count`. */
+  count?: boolean | undefined
 }
 
-export type QueryReturnType = {
-  entities: Entity[]
+/**
+ * What one result of a `query()` reads as for selection `S`: the same row `select(S)` returns
+ * without a schema — every field when everything is selected, and every field optional when the
+ * selection is only known at runtime.
+ */
+export type QueryRow<S> = ResultOf<SelectionOf<S>, undefined>
+
+export type QueryReturnType<TResult = FullEntity> = {
+  entities: TResult[]
   /** The cursor for the next page, or `undefined` when no pages remain. */
   cursor: string | undefined
   /** The block the page was read at. */
   blockNumber: bigint
+  /** How many entities the query matches, if `count` was set. */
+  count: bigint | undefined
 }
 
 /**
  * Runs a single query and returns one page, with no builder in between.
  *
+ * The selection means what it does in `select()`, and each result is the same flat row a query
+ * without a schema returns — typed from the selection, with every attribute an `ArkivValue` or
+ * `undefined`.
+ *
  * Takes either an {@link Expression} or a raw query string. The string form is an escape hatch for
  * a query built elsewhere — it goes to the node exactly as written, with none of the name, type or
  * operator checks the expression combinators apply.
  *
+ * @throws If the selection asks for nothing, or names an attribute outside the name grammar.
  * @throws {QueryError} If the node rejects the query.
  */
-export function query(
+export async function query<const S extends SelectArg = "*">(
   client: ArkivClient,
   query: Expression | string,
-  options: QueryOptions = {},
-): Promise<QueryReturnType> {
-  return runQuery(client, {
+  options: QueryOptions<S> = {},
+): Promise<QueryReturnType<QueryRow<S>>> {
+  const projection = projectSelection(options.select)
+  const page = await runQuery(client, {
     query: query.toString(),
-    select: toRpcSelect(options.select),
+    select: projection.select,
     limit: options.limit,
     cursor: options.cursor,
     atBlock: options.atBlock,
+    count: options.count,
   })
+  return {
+    ...page,
+    entities: page.entities.map((entity) => toRow(entity, projection) as QueryRow<S>),
+  }
 }

package/src/actions/wallet/createEntity.ts

@@ -1,9 +1,9 @@
 import type { Hash, Hex } from "viem"
-import type { AttributeInputs } from "../../attr"
 import type { ArkivClient } from "../../clients/baseClient"
 import type { CreationFlags, Expiry, NO_SALT, SaltInput } from "../../entity"
 import { EntityMutationError } from "../../errors"
-import type { MimeType, TxParams } from "../../types"
+import type { CreateEntityValues, Schema } from "../../schema"
+import type { TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import type { ExpirationTime } from "../../utils/expirationTime"
 import { getLogger } from "../../utils/logger"
@@ -11,69 +11,27 @@ import { getLogger } from "../../utils/logger"
 const logger = getLogger("actions:wallet:create-entity")
 
 /**
- * Parameters for creating an entity.
- *
- * An entity always carries contents and a type for them, plus a lifetime. Attributes, flags and a
- * salt are optional on top of that.
+ * How an created entity lives: its lifetime, plus the flags and salt it is created with.
  *
  * @example
- * const { entityKey } = await client.createEntity({
- *   attributes: {
- *     level:   i32(10),
- *     balance: u256(1_000_000n),
- *     score:   dec("3.5"),
- *     name:    "Bob",   // bare string -> str
- *     flagged: true,    // bare boolean -> bool
- *   },
- *   payload: jsonToPayload({ hello: "world" }),
- *   contentType: "application/json",
- *   expires: ExpirationTime.fromDays(30),
- *   flags: { readonly: true },
- * })
+ * { expiration: ExpirationTime.fromDays(30) }
  *
- * @example Pin an absolute deadline, but refuse to create something nearly dead:
- * await client.createEntity({
- *   payload, contentType: "application/json",
- *   expires: ExpirationTime.atDate(someDeadline, {
+ * @example Pin an absolute deadline, but never let it leave the entity with less than a day:
+ * {
+ *   expiration: ExpirationTime.atDate(someDeadline, {
  *     atLeast: ExpirationTime.fromDays(1),    // ...but live at least a day regardless
  *   }),
- * })
- *
- * @example An entity that is nothing but queryable attributes still declares its (empty) contents:
- * await client.createEntity({
- *   attributes: { parent: key(parentKey), rank: i32(3) },
- *   payload: new Uint8Array(),
- *   contentType: "application/octet-stream",
- *   expires: ExpirationTime.fromDays(30),
- * })
+ *   flags: { readonly: true },
+ * }
  */
-export type CreateEntityParameters = {
+export type CreateEntityOptions = {
   /**
    * How long the entity should live, built with {@link ExpirationTime}.
    *
    * `ExpirationTime.fromDays(30)` is the everyday form. `atBlock` / `atDate` pin an absolute
    * deadline instead, and either can carry `{ atLeast }` to guarantee a minimum life on top of it.
    */
-  expires: Expiry
-  /**
-   * The entity's opaque payload. Travels to the engine as the `$payload` system attribute; on this
-   * surface it is just the entity's contents.
-   *
-   * Pass an empty `Uint8Array` for an entity that is nothing but queryable attributes — it is
-   * written as an empty payload rather than left unset, so what you pass is what is stored.
-   */
-  payload: Uint8Array
-  /** The payload's MIME type, e.g. `"application/json"`. Sent as the `$contentType` cell. */
-  contentType: MimeType | (string & {})
-  /**
-   * The entity's queryable attributes, keyed by name. Values are the tagged constructors from
-   * `@arkiv-network/sdk/attr` — `i32`, `u64`, `u256`, `dec`, `str`, `addr`, `key`, `bytes32`,
-   * `bool` — or a bare `boolean`, `number`, `bigint` or `string` where the type is unambiguous.
-   *
-   * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
-   * @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
-   */
-  attributes?: AttributeInputs | undefined
+  expiration: Expiry
   /**
    * Properties fixed at creation: `readonly` and `permissionlessExtension`. No operation changes
    * them afterwards, so an entity is whatever it was created as for life. Both default to `false`.
@@ -89,6 +47,21 @@ export type CreateEntityParameters = {
   salt?: SaltInput | undefined
 }
 
+/**
+ * One entity to create, as a batch carries it: the schema, the values, and the {@link CreateEntityOptions}.
+ *
+ * @typeParam S - The schema the values are typed by.
+ */
+export type CreateEntityParameters<S extends Schema = Schema> = CreateEntityOptions & {
+  /** The schema the entity is written through. */
+  schema: S
+  /**
+   * The entity's values, keyed by column. Every required column must be given; an optional one may
+   * be left out, and a defaulted one left out is written with its default.
+   */
+  values: CreateEntityValues<S>
+}
+
 /**
  * The result of creating an entity.
  */
@@ -97,25 +70,23 @@ export type CreateEntityReturnType = {
   entityKey: Hex
   txHash: Hash
   /**
-   * The block the entity is expected to expire at, resolved against the block the transaction was
-   * built on.
-   *
-   * The engine resolves a duration against the block the transaction actually lands in, so for
-   * `ExpirationTime.fromDays(30)` and friends this is a lower bound: the real expiry is later by
-   * however many blocks passed between building and inclusion. An `atBlock` deadline is exact.
+   * The block the entity expires at, as the engine recorded it — read from the `EntityCreated`
+   * event, so a duration is already resolved against the block the transaction landed in.
    */
   expiresAt: bigint
 }
 
-export async function createEntity(
+export async function createEntity<S extends Schema>(
   client: ArkivClient,
-  data: CreateEntityParameters,
+  schema: S,
+  values: CreateEntityValues<S>,
+  options: CreateEntityOptions,
   txParams?: TxParams,
 ): Promise<CreateEntityReturnType> {
-  logger("createEntity %o", data)
+  logger("createEntity %o", values)
   const { receipt, createdEntityKeys, createdExpiries } = await sendArkivTransaction(
     client,
-    { creates: [data] },
+    { creates: [{ ...options, schema, values }] },
     txParams,
   )
 

package/src/actions/wallet/executeBatch.test.ts

@@ -1,10 +1,18 @@
 import { describe, expect, it, vi } from "bun:test"
+import { decodeAbiParameters, parseAbiParameters, toHex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
+import { OperationType } from "../../entity/params"
+import { bytes, defineSchema, i32, str } from "../../schema"
 import { executeBatch } from "./executeBatch"
 
 const ENTITY_KEY = `0x${"ab".repeat(32)}` as const
+const OTHER_KEY = `0x${"cd".repeat(32)}` as const
 const NEW_OWNER = "0x2222222222222222222222222222222222222222"
 
+const PATCH_PARAMS = parseAbiParameters(
+  "(bytes32 entityKey, (bytes32 name, uint8 typeId, bytes value)[] mutations)",
+)
+
 function makeClient() {
   const writeContract = vi.fn().mockResolvedValue("0xdeadbeef")
   return {
@@ -74,3 +82,33 @@ describe("the empty-batch guard", () => {
     expect(writeContract.mock.calls[0][0].args[0]).toHaveLength(1)
   })
 })
+
+describe("schemas in a batch", () => {
+  it("types each patch by its own schema", async () => {
+    const Posts = defineSchema({ title: str(), score: i32().indexed() })
+    const Files = defineSchema({ path: str().indexed(), body: bytes().optional() })
+    const { client, writeContract } = makeClient()
+
+    const result = await executeBatch(client, {
+      patches: [
+        { schema: Posts, entityKey: ENTITY_KEY, set: { score: 5 } },
+        { schema: Files, entityKey: OTHER_KEY, set: { path: "/a" }, unset: ["body"] },
+      ],
+    })
+
+    expect(result.patchedEntities).toEqual([ENTITY_KEY, OTHER_KEY])
+    const ops = writeContract.mock.calls[0][0].args[0] as {
+      operation: number
+      operationData: `0x${string}`
+    }[]
+    expect(ops.map((op) => op.operation)).toEqual([OperationType.Patch, OperationType.Patch])
+    const [posts, files] = ops.map((op) => decodeAbiParameters(PATCH_PARAMS, op.operationData)[0])
+    expect(posts.mutations.map((m) => [m.name, m.typeId])).toEqual([
+      [toHex("score", { size: 32 }), 0x80 | 2],
+    ])
+    expect(files.mutations.map((m) => [m.name, m.typeId])).toEqual([
+      [toHex("body", { size: 32 }), 0],
+      [toHex("path", { size: 32 }), 0x80 | 8],
+    ])
+  })
+})

package/src/actions/wallet/executeBatch.ts

@@ -1,5 +1,6 @@
 import type { Hash, Hex } from "viem"
 import type { ArkivClient } from "../../clients/baseClient"
+import type { Schema } from "../../schema"
 import type { TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
@@ -16,18 +17,27 @@ const logger = getLogger("actions:wallet:execute-batch")
  *
  * At least one operation is required; a batch with nothing in it throws rather than spending gas on
  * an empty transaction.
+ *
+ * Each create and patch names its own schema, and is typed by it — a batch can write entities of
+ * several schemas at once.
+ *
+ * @typeParam TCreates - The schema of each create, in order. Inferred.
+ * @typeParam TPatches - The schema of each patch, in order. Inferred.
  */
-export type ExecuteBatchParameters = {
+export type ExecuteBatchParameters<
+  TCreates extends readonly Schema[] = readonly Schema[],
+  TPatches extends readonly Schema[] = readonly Schema[],
+> = {
   /** The entities to create. */
-  creates?: CreateEntityParameters[]
+  creates?: { readonly [I in keyof TCreates]: CreateEntityParameters<TCreates[I]> } | undefined
   /** The patches to apply. */
-  patches?: PatchEntityParameters[]
+  patches?: { readonly [I in keyof TPatches]: PatchEntityParameters<TPatches[I]> } | undefined
   /** The entities to delete. */
-  deletes?: DeleteEntityParameters[]
+  deletes?: readonly DeleteEntityParameters[] | undefined
   /** The expiries to set. */
-  extensions?: ExtendEntityParameters[]
+  extensions?: readonly ExtendEntityParameters[] | undefined
   /** The ownership transfers to perform. */
-  ownershipChanges?: ChangeOwnershipParameters[]
+  ownershipChanges?: readonly ChangeOwnershipParameters[] | undefined
 }
 
 /** Return type for the executeBatch function. */
@@ -46,12 +56,19 @@ export type ExecuteBatchReturnType = {
   ownershipChanges: Hex[]
 }
 
-export async function executeBatch(
+export async function executeBatch<
+  const TCreates extends readonly Schema[] = [],
+  const TPatches extends readonly Schema[] = [],
+>(
   client: ArkivClient,
-  data: ExecuteBatchParameters,
+  data: ExecuteBatchParameters<TCreates, TPatches>,
   txParams?: TxParams,
 ): Promise<ExecuteBatchReturnType> {
-  const { receipt, createdEntityKeys } = await sendArkivTransaction(client, data, txParams)
+  const { receipt, createdEntityKeys } = await sendArkivTransaction(
+    client,
+    data as ExecuteBatchParameters,
+    txParams,
+  )
 
   logger("Receipt from executeBatch %o", receipt)
 

package/src/actions/wallet/extendEntity.ts

@@ -17,17 +17,18 @@ const logger = getLogger("actions:wallet:extend-entity")
  * `ExpirationTime.fromDays(30)` means "alive for thirty more days from now" whatever the entity's
  * remaining life happened to be.
  *
- * The engine rejects an extension that would not move the expiry later, so extending an entity by
- * less than it already has left is an error rather than a silent shortening.
+ * The engine rejects an extension that would move the expiry earlier, so extending an entity by
+ * less than it already has left is an error rather than a silent shortening. One that resolves to
+ * the current expiry changes nothing.
  *
  * @example
- * await client.extendEntity({ entityKey, expires: ExpirationTime.fromDays(30) })
- * await client.extendEntity({ entityKey, expires: ExpirationTime.atBlock(1_200_000n) })
+ * await client.extendEntity({ entityKey, expiration: ExpirationTime.fromDays(30) })
+ * await client.extendEntity({ entityKey, expiration: ExpirationTime.atBlock(1_200_000n) })
  */
 export type ExtendEntityParameters = {
   entityKey: Hex
   /** The entity's new lifetime, built with {@link ExpirationTime}. */
-  expires: Expiry
+  expiration: Expiry
 }
 
 /**
@@ -37,9 +38,9 @@ export type ExtendEntityReturnType = {
   entityKey: Hex
   txHash: Hash
   /**
-   * The block the entity is now expected to expire at, resolved against the block the transaction
-   * was built on. Durations are approximate, so treat this as the estimate the operation was built
-   * from rather than the block the engine settled on.
+   * The block the entity now expires at, as the engine recorded it — read from the
+   * `ExpiryExtended` event, so a duration is already resolved against the block the transaction
+   * landed in.
    */
   expiresAt: bigint
 }

package/src/actions/wallet/patchEntity.ts

@@ -1,90 +1,81 @@
 import type { Hash, Hex } from "viem"
-import type { AttributeInputs } from "../../attr"
 import type { ArkivClient } from "../../clients/baseClient"
-import type { MimeType, TxParams } from "../../types"
+import type { OptionalColumnName, PatchEntityValues, Schema } from "../../schema"
+import type { TxParams } from "../../types"
 import { sendArkivTransaction } from "../../utils/arkivTransactions"
 import { getLogger } from "../../utils/logger"
 
 const logger = getLogger("actions:wallet:patch-entity")
 
 /**
- * Parameters for patching an entity.
+ * What a patch changes.
  *
- * A patch names only what changes. Attributes it does not mention keep whatever value they have, and
- * the payload and content type stay as they are unless given — so a caller can change one field
- * without first reading the entity to learn what the others are, and without racing anyone else who
- * is changing a different field.
+ * A patch names only what changes. Columns it does not mention keep whatever value they have — so
+ * a caller can change one column without first reading the entity to learn what the others are,
+ * and without racing anyone else who is changing a different one.
  *
- * The entity's identity is fixed: a patch never moves the key, the owner, the creation flags or the
- * expiry. Use `extendEntity` for the expiry and `changeOwnership` for the owner.
- *
- * @example Change one attribute and remove another, leaving the payload alone:
- * await client.patchEntity({
- *   entityKey,
- *   set: { status: "published", level: i32(11) },
- *   unset: ["draft"],
- * })
+ * @typeParam S - The schema the changes are typed by.
  *
- * @example Replace the contents without touching a single attribute:
- * await client.patchEntity({
- *   entityKey,
- *   payload: jsonToPayload({ hello: "again" }),
- * })
+ * @example
+ * { set: { title: "Cells, not entities", score: dec("4.2") }, unset: ["thumbnail"] }
  */
-export type PatchEntityParameters = {
-  /** The entity to patch. */
-  entityKey: Hex
+export type PatchEntityChanges<S extends Schema = Schema> = {
   /**
-   * Attributes to write, keyed by name. An existing attribute is overwritten — including with a
-   * different type — and a name the entity does not carry yet is added.
+   * Columns to write, keyed by name. Each is written with the indexed flag its column declares,
+   * so writing a column whose indexing the schema has since changed changes it on the entity too.
+   * Defaults do not apply: a patch writes only what it names.
    *
-   * Values are the tagged constructors from `@arkiv-network/sdk/attr` — `i32`, `u64`, `u256`,
-   * `dec`, `str`, `addr`, `key`, `bytes32`, `bool` — or a bare `boolean`, `number`, `bigint` or
-   * `string` where the type is unambiguous.
-   *
-   * @throws {InvalidAttributeNameError} If a name violates the attribute-name grammar.
-   * @throws {InvalidValueError} If a value does not fit the type it names or defaults to.
+   * @throws {SchemaMismatchError} If a name is not a column, or a value is not of its column's type.
    */
-  set?: AttributeInputs | undefined
+  set?: PatchEntityValues<S> | undefined
   /**
-   * Attribute names to remove. Naming one the entity does not carry is not an error — the outcome
-   * is the same either way, and a caller clearing a field should not have to know whether it was
+   * Optional columns to remove. Naming one the entity does not carry is not an error — the outcome
+   * is the same either way, and a caller clearing a column should not have to know whether it was
    * ever set.
    *
    * @throws {ConflictingMutationError} If a name also appears in `set`.
    */
-  unset?: readonly string[] | undefined
-  /**
-   * The entity's new payload. Omit it to leave the current contents untouched; pass an empty
-   * `Uint8Array` to replace them with nothing.
-   */
-  payload?: Uint8Array | undefined
-  /**
-   * The payload's new MIME type. Omit it to keep the current one — which is what you want when the
-   * new payload is the same kind of thing as the old.
-   */
-  contentType?: MimeType | (string & {}) | undefined
+  unset?: readonly OptionalColumnName<S>[] | undefined
+}
+
+/**
+ * One patch, as a batch carries it: the schema, the entity, and the {@link PatchEntityChanges}.
+ *
+ * The entity's identity is fixed: a patch never moves the key, the owner, the creation flags or the
+ * expiry. Use `extendEntity` for the expiry and `changeOwnership` for the owner.
+ */
+export type PatchEntityParameters<S extends Schema = Schema> = PatchEntityChanges<S> & {
+  /** The schema the changes are typed by. */
+  schema: S
+  /** The entity to patch. */
+  entityKey: Hex
 }
 
-/** The result of patching an entity. */
+/** The result of a patch. */
 export type PatchEntityReturnType = {
   /** The patched entity's key — unchanged, since a patch never moves it. */
   entityKey: Hex
   txHash: Hash
 }
 
-export async function patchEntity(
+export async function patchEntity<S extends Schema>(
   client: ArkivClient,
-  data: PatchEntityParameters,
+  schema: S,
+  entityKey: Hex,
+  changes: PatchEntityChanges<S>,
   txParams?: TxParams,
 ): Promise<PatchEntityReturnType> {
-  logger("patchEntity %o", data)
-  const { receipt } = await sendArkivTransaction(client, { patches: [data] }, txParams)
+  logger("patchEntity %s %o", entityKey, changes)
+  const { receipt } = await sendArkivTransaction(
+    client,
+    { patches: [{ ...changes, schema, entityKey }] },
+    txParams,
+  )
 
   logger("Receipt from patchEntity %o", receipt)
 
   return {
     txHash: receipt.transactionHash as Hash,
-    entityKey: data.entityKey,
+    entityKey,
   }
 }

package/src/clients/createPublicClient.test.ts

@@ -22,8 +22,6 @@ test("creates", () => {
   expect(typeof client.select).toBe("function")
   expect(client.query).toBeDefined()
   expect(typeof client.query).toBe("function")
-  expect(client.getEntityCount).toBeDefined()
-  expect(typeof client.getEntityCount).toBe("function")
   expect(client.getBlockTiming).toBeDefined()
   expect(typeof client.getBlockTiming).toBe("function")
   expect(client.watchEntityEvents).toBeDefined()
@@ -37,3 +35,13 @@ test("creates", () => {
   expect(client.changeOwnership).not.toBeDefined()
   expect(client.executeBatch).not.toBeDefined()
 })
+
+test("select() rejects a $ name that is not an entity field, at compile time and at runtime", () => {
+  const client = createPublicClient({ transport: mockTransport })
+  // @ts-expect-error - $title is not an entity field; an attribute name cannot start with $
+  expect(() => client.select({ $title: true })).toThrow(/not an entity field/)
+  // @ts-expect-error - $attributes reads every attribute; select the ones you want by name
+  expect(() => client.select({ $attributes: { title: true } })).toThrow(/select each by name/)
+  // Without the $, `owner` is an attribute like any other, read alongside the entity field.
+  expect(() => client.select({ $owner: true, owner: true })).not.toThrow()
+})

package/src/clients/createWalletClient.ts

@@ -28,7 +28,10 @@ export type WalletArkivClient<
  *
  * A Wallet Client signs and sends transactions, so it carries an `account` and exposes everything
  * that mutates state — `createEntity`, `patchEntity`, `deleteEntity`, `extendEntity`,
- * `changeOwnership` and `executeBatch` — on top of the read actions a Public Client has.
+ * `changeOwnership` and `executeBatch` — alongside the viem actions those need, such as
+ * `getBlockNumber`, `readContract` and `waitForTransactionReceipt`. It does not have the Arkiv
+ * read actions (`getEntity`, `query`, `select`, `watchEntityEvents`, `predictEntityKeys`); read
+ * through a Public Client from `createPublicClient` for those.
  *
  * @param parameters - Configuration object for the wallet client (chain, transport, account, etc.)
  * @returns An Arkiv Wallet Client. {@link WalletArkivClient}