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

package/README.md

@@ -85,12 +85,52 @@ npm install @arkiv-network/sdk viem
 This command will update your `package.json` with a section like:
 ```json
 "dependencies": {
-  "@arkiv-network/sdk": "^0.6.0",
+  "@arkiv-network/sdk": "^0.9.0",
   "viem": "^2.38.2"
 }
 ```
 It will also create a `node_modules` directory with all dependencies installed.
 
+### Define a Schema
+
+Arkiv stores entities, and an entity is a set of named, typed attributes. You describe them once in a
+schema, much as you would describe a table's columns in SQL, and choose per column whether the node
+indexes it. Only indexed columns can be filtered on; the rest are stored and selectable, and do not
+pay for an index.
+
+The examples below use this schema for blog posts. Each example declares it at the top of its own
+file, so that it runs as a single file under Node.js, Bun or `tsc` alike:
+
+```typescript
+import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
+
+// Called with no arguments, a type constructor describes a column.
+const Posts = defineSchema("posts", {
+  author:    addr().indexed(),
+  category:  str().indexed(),
+  score:     dec().indexed(),
+  title:     str(),                          // stored, not indexed
+  body:      bytes(),                        // a blob; bytes can never be indexed
+  thumbnail: bytes().optional(),             // any number of bytes columns; this one may be absent
+  mimeType:  str().default("text/markdown"), // written on create when left out
+})
+```
+
+The type constructors are `bool`, `i32`, `u64`, `u256`, `dec`, `str`, `addr`, `key`, `bytes32` and
+`bytes`. Each column may be refined with `.indexed()` (every type but `bytes`), `.optional()` and
+`.default(...)`.
+
+The same constructors, called with a value, make a typed value: `dec("4.1")` is a decimal, the way SQL
+has `DECIMAL` as a type and `DECIMAL '4.1'` as a literal.
+
+A schema is an SDK-side convention: the node sees only attributes, each with a type and an indexed
+flag. The schema is what types your writes and reads, and checks them at runtime.
+
+The name, `"posts"`, is optional but recommended. A named schema tags every entity it creates with
+an indexed `arkiv.schema` attribute holding its name, and a query through it only matches entities
+with that tag — the way a collection keeps one model's documents apart from another's. For that
+reason `arkiv.schema` cannot be used as a column name.
+
 ### Public Client Example (Query Data)
 
 You can now use Arkiv's public client to query data. Paste the following in `read_example.ts`:
@@ -98,31 +138,41 @@ You can now use Arkiv's public client to query data. Paste the following in `rea
 ```typescript
 import { createPublicClient } from "@arkiv-network/sdk"
 import { tiramisu } from "@arkiv-network/sdk/chains"
-import { eq } from "@arkiv-network/sdk/query"
+import { and, eq, gt } from "@arkiv-network/sdk/query"
+import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
 import { http } from "viem"
 
+// The schema from "Define a Schema" above
+const Posts = defineSchema("posts", {
+  author:    addr().indexed(),
+  category:  str().indexed(),
+  score:     dec().indexed(),
+  title:     str(),
+  body:      bytes(),
+  thumbnail: bytes().optional(),
+  mimeType:  str().default("text/markdown"),
+})
+
 const publicClient = createPublicClient({
   chain: tiramisu, // "tiramisu" is Arkiv's testnet
   transport: http(),
 });
 
-// Get chain ID
-const chainId = await publicClient.getChainId();
-console.log('Chain ID:', chainId);
+// Get an entity by key, read through the schema
+const post = await publicClient.getEntity('0xcadb830a3414251d65e5c92cd28ecb648d9e73d85f2203eff631839d5421f9d7', Posts);
+console.log('Title:', post.title.value);
 
-// Get entity by key
-const entity = await publicClient.getEntity('0xcadb830a3414251d65e5c92cd28ecb648d9e73d85f2203eff631839d5421f9d7');
-console.log('Entity:', entity);
-
-// Build and execute a query using select()
+// Build and execute a query: select what to return, name the schema, then filter
 const result = await publicClient
-  .select({ owner: true, attributes: true, payload: true })
-  .where(eq('category', 'documentation'))
-  .ownedBy('0x6186B0DbA9652262942d5A465d49686eb560834C')
+  .select({ $key: true, author: true, title: true, body: true })
+  .from(Posts)
+  .where(and(eq('category', 'docs'), gt('score', dec('4.0'))))
   .limit(10)
   .fetch();
 
-console.log('Found entities:', result.entities);
+for (const row of result.entities) {
+  console.log(row.$key, row.author.value, row.title.value);
+}
 
 // Pagination
 if (result.hasNextPage()) {
@@ -131,46 +181,107 @@ if (result.hasNextPage()) {
 }
 
 // Or walk every page at once
-for await (const entity of publicClient
-  .select({ key: true })
-  .where(eq('category', 'documentation'))) {
-  console.log(entity.key);
+for await (const row of publicClient
+  .select({ $key: true, title: true })
+  .from(Posts)
+  .where(eq('category', 'docs'))) {
+  console.log(row.$key, row.title.value);
 }
 ```
 
 #### Selecting fields with `select()`
 
-Pass nothing (or `"*"`) to fetch everything, or pass an object to fetch only specific fields:
+Pass nothing (or `"*"`) to fetch everything — through a schema, every entity field and every
+column — or pass an object to fetch only specific fields. The selection names entity fields and
+attributes side by side, and each result is a flat row. Entity fields start with `$`, as they do in
+`where`: `$key`, `$owner`, `$creator`, `$createdAt`, `$updatedAt`, `$expiresAt` and
+`$creationFlags`. Any other name is an attribute. An attribute name cannot start with `$`, so the
+two never collide — an attribute called `owner` is just `owner`:
 
 ```typescript
-// All fields
-await publicClient.select().where(eq("category", "docs")).fetch();
+// Every entity field and every column
+await publicClient.select().from(Posts).where(eq("category", "docs")).fetch();
 
 // Only the fields you need
-await publicClient.select({ key: true, owner: true, payload: true }).where(eq("category", "docs")).fetch();
+await publicClient.select({ $key: true, title: true }).from(Posts).where(eq("category", "docs")).fetch();
 ```
 
 **Select only what you need.** Every selected field is fetched over the network, so requesting
 data you won't use makes queries slower. Narrowing the selection keeps responses small and fast.
 
-The result type is inferred from your selection: reading a field you didn't select is a compile error. The `toText()` / `toJson()` payload
-helpers are available only when you select `payload`.
+The result type is inferred from your selection and schema: each column is typed as the schema
+declares it, and reading a field you didn't select is a compile error.
 
 ```typescript
-const [entity] = (
-  await publicClient.select({ owner: true, payload: true }).where(eq("category", "docs")).fetch()
-).entities;
-entity.owner;     // ✅ Hex
-entity.toJson();  // ✅ payload was selected
-entity.creator;   // ❌ compile error — not selected
+const row = (
+  await publicClient.select({ $owner: true, score: true }).from(Posts).where(eq("category", "docs")).fetch()
+).entities[0]!;
+row.$owner;   // ✅ Hex
+row.score;    // ✅ DecValue — row.score.value is "4.1"
+row.title;    // ❌ compile error — not selected
 ```
 
+`where` is checked against the schema too. It takes the schema's indexed columns and the system
+attributes `$key`, `$owner`, `$creator` and `$expiresAt`. Filtering on a column the schema does not
+index, or comparing a column against a value of another type, is a compile error:
+
+```typescript
+.where(eq("title", "x"))   // ❌ title is not indexed
+.where(eq("score", 5))     // ❌ score is a dec, 5 is an i32 — write dec(5)
+.where(between("score", dec(1), 5))  // ❌ both bounds need one type
+```
+
+A named schema needs no `where` at all — `select().from(Posts)` matches every post: `fetch()`
+returns the first page, and `for await` walks them all. An unnamed schema types a query without
+filtering it, so `where` alone decides which entities match.
+
+Only what you select is checked. An entity that matches but does not fit the schema — a selected
+column that is required but missing or holds another type, or, for a named schema, another schema's
+tag — is left out of the page. Anyone can write an entity a query matches, so one that does not
+fit never fails the read of the others. A page can then hold fewer rows than its limit, and reports
+how many it left out as `skipped`. Pass `{ onMismatch: "throw" }` to fail the fetch with a
+`SchemaMismatchError` instead:
+
+```typescript
+const page = await publicClient.select().from(Posts).where(eq("category", "docs")).fetch();
+page.skipped; // matching entities on this page that did not fit Posts
+```
+
+A query reads the same without a schema — say, to explore what a node holds. Leave out
+`.from(...)` and the selection means what it did (save `"*"`, below), and the rows keep their
+shape. Only the checking is gone, along with a named schema's tag filter: each attribute comes back
+as whatever value the entity holds, or `undefined`, and `where` takes any attribute:
+
+```typescript
+const row = (
+  await publicClient.select({ $key: true, title: true }).where(eq("category", "docs")).fetch()
+).entities[0]!;
+row.title;    // ArkivValue | undefined — e.g. { type: "str", value: "Hello" }
+```
+
+To read every attribute without naming them, select `$attributes`, a map of all of them. `"*"` (or
+nothing) fetches it alongside the entity fields when there is no schema, since there are no columns
+to list.
+
+`$attributeSchema` is for finding out what entities hold without fetching their values: each
+attribute's name, its type, and whether it is indexed. Values can be large — a `bytes` attribute
+holds up to 128 KiB — and an RPC endpoint may cap how big a response it sends, so a page of 100
+entities with every attribute can be more than it will return. Fetch the schema first, then select
+the attributes you need by name. It is never part of `"*"`; select it by name:
+
+```typescript
+const page = await publicClient.select({ $key: true, $attributeSchema: true }).where(eq("category", "docs")).fetch();
+page.entities[0]?.$attributeSchema; // { title: { type: "str", indexed: false }, body: { type: "bytes", indexed: false } }
+```
+
+Both work through a schema too.
+
 > **Footgun:** pass the selection inline. A selection stored in a variable widens its `true` values
-> to `boolean`, so the result type can't be narrowed (you get `{}` and a compile error on every
-> field). If you need to reuse one, annotate it `as const`:
+> to `boolean`, so which fields come back is only known at runtime and every field of the result is
+> optional. If you need to reuse one, annotate it `as const`:
 > ```typescript
-> const fields = { owner: true, payload: true } as const;
-> await publicClient.select(fields).where(eq("category", "docs")).fetch();
+> const fields = { $owner: true, title: true } as const;
+> await publicClient.select(fields).from(Posts).where(eq("category", "docs")).fetch();
 > ```
 
 ### Running the Example
@@ -208,19 +319,29 @@ You have several options to run your TypeScript sample:
      node dist/read_example.js
      ```
 
-### Wallet Client Example (Create Entity)
+### Wallet Client Example (Create an Entity)
 
 Now let's add storage (write) functionality.  
 Create a file named `write_example.ts` with the following content:
 
 ```typescript
-import { createPublicClient, createWalletClient } from "@arkiv-network/sdk"
-import { dec, i32 } from "@arkiv-network/sdk/attr"
+import { createPublicClient, createWalletClient, ExpirationTime } from "@arkiv-network/sdk"
 import { tiramisu } from "@arkiv-network/sdk/chains"
-import { ExpirationTime, jsonToPayload } from "@arkiv-network/sdk/utils"
-import { http } from "viem"
+import { addr, bytes, dec, defineSchema, str } from "@arkiv-network/sdk/schema"
+import { http, stringToBytes } from "viem"
 import { privateKeyToAccount } from "viem/accounts"
 
+// The schema from "Define a Schema" above
+const Posts = defineSchema("posts", {
+  author:    addr().indexed(),
+  category:  str().indexed(),
+  score:     dec().indexed(),
+  title:     str(),
+  body:      bytes(),
+  thumbnail: bytes().optional(),
+  mimeType:  str().default("text/markdown"),
+})
+
 // Create a public client
 const publicClient = createPublicClient({
   chain: tiramisu, // tiramisu is the Arkiv testnet
@@ -233,32 +354,30 @@ const client = createWalletClient({
   account: privateKeyToAccount('0x...'), // Replace with your private key
 });
 
-// Create an entity
-const { entityKey, txHash } = await client.createEntity({
-  payload: jsonToPayload({
-    entity: {
-      entityType: 'document',
-      entityId: 'doc-123',
-      entityContent: "Hello from DevConnect Hackathon 2025! Arkiv chain wishes you all the best!"
-    },
-  }),
-  contentType: 'application/json',
-  // Attributes are keyed by name. Values carry their type: use the tagged constructors from
-  // "@arkiv-network/sdk/attr" (i32, u64, u256, dec, str, addr, key, bytes32, bool), or pass a bare
-  // boolean, number, bigint or string where the type is unambiguous.
-  attributes: {
-    category: 'documentation',   // bare string -> str
-    version: i32(1),
+// Create an entity. Every required column must be given; a defaulted one (mimeType) left out is
+// written with its default. Values carry their type: use the constructors from
+// "@arkiv-network/sdk/schema", or a bare string, boolean, number, bigint or Uint8Array where it is
+// unambiguous (string -> str, Uint8Array -> bytes, ...).
+const { entityKey, txHash } = await client.createEntity(
+  Posts,
+  {
+    author: addr(client.account.address),
+    category: 'docs',
     score: dec('4.5'),
+    title: 'Hello from Arkiv',
+    body: stringToBytes('# Hello\n\nArkiv wishes you all the best!'),
   },
-  expires: ExpirationTime.fromDays(30), // Entity expires in 30 days
-});
+  { expiration: ExpirationTime.fromDays(30) }, // Entity expires in 30 days
+);
 
 console.log('Created entity:', entityKey);
 console.log('Transaction hash:', txHash);
 
-const newEntity = await publicClient.getEntity(entityKey);
-console.log('Entity:', newEntity);
+// Change one column, leaving the rest alone
+await client.patchEntity(Posts, entityKey, { set: { score: dec('4.7') } });
+
+const post = await publicClient.getEntity(entityKey, Posts);
+console.log('Post:', post);
 ```
 
 Now you can run it in the same way as in the previous example:
@@ -356,12 +475,12 @@ For more information about refer to:
 
 ## Verbose Logging
 
-The SDK uses [debug](https://www.npmjs.com/package/debug) under the hood. Set the `DEBUG` environment variable to view verbose logs:
+Set the `DEBUG` environment variable (or, in a browser, the `DEBUG` key in `localStorage`) to view verbose logs:
 
 ```bash
 DEBUG=arkiv:* bun run your-script
 ```
 
-Adjust the namespace (for example, `arkiv:rpc` or `arkiv:query`) to target specific log sources. Unset `DEBUG` to silence debug output.
+Adjust the namespace (for example, `arkiv:query:*` or `arkiv:actions:wallet:*`) to target specific log sources, and prefix one with `-` to exclude it. Unset `DEBUG` to silence debug output.
 
 

package/dist/chains/index.d.ts

@@ -1,4 +1,4 @@
-import * as viem8 from "viem";
+import * as viem0 from "viem";
 
 //#region src/chains/localhost.d.ts
 /**
@@ -19,13 +19,13 @@ declare const localhost: {
   } | undefined | undefined;
   blockTime?: number | undefined | undefined;
   contracts?: {
-    [x: string]: viem8.ChainContract | {
-      [sourceId: number]: viem8.ChainContract | undefined;
+    [x: string]: viem0.ChainContract | {
+      [sourceId: number]: viem0.ChainContract | undefined;
     } | undefined;
-    ensRegistry?: viem8.ChainContract | undefined;
-    ensUniversalResolver?: viem8.ChainContract | undefined;
-    multicall3?: viem8.ChainContract | undefined;
-    erc6492Verifier?: viem8.ChainContract | undefined;
+    ensRegistry?: viem0.ChainContract | undefined;
+    ensUniversalResolver?: viem0.ChainContract | undefined;
+    multicall3?: viem0.ChainContract | undefined;
+    erc6492Verifier?: viem0.ChainContract | undefined;
   } | undefined;
   ensTlds?: readonly string[] | undefined;
   id: 1337;
@@ -44,9 +44,9 @@ declare const localhost: {
   sourceId?: number | undefined | undefined;
   testnet?: boolean | undefined | undefined;
   custom?: Record<string, unknown> | undefined;
-  fees?: viem8.ChainFees<undefined> | undefined;
+  fees?: viem0.ChainFees<undefined> | undefined;
   formatters?: undefined;
-  serializers?: viem8.ChainSerializers<undefined, viem8.TransactionSerializable> | undefined;
+  serializers?: viem0.ChainSerializers<undefined, viem0.TransactionSerializable> | undefined;
 };
 //#endregion
 //#region src/chains/tiramisu.d.ts
@@ -68,13 +68,13 @@ declare const tiramisu: {
   } | undefined | undefined;
   blockTime?: number | undefined | undefined;
   contracts?: {
-    [x: string]: viem8.ChainContract | {
-      [sourceId: number]: viem8.ChainContract | undefined;
+    [x: string]: viem0.ChainContract | {
+      [sourceId: number]: viem0.ChainContract | undefined;
     } | undefined;
-    ensRegistry?: viem8.ChainContract | undefined;
-    ensUniversalResolver?: viem8.ChainContract | undefined;
-    multicall3?: viem8.ChainContract | undefined;
-    erc6492Verifier?: viem8.ChainContract | undefined;
+    ensRegistry?: viem0.ChainContract | undefined;
+    ensUniversalResolver?: viem0.ChainContract | undefined;
+    multicall3?: viem0.ChainContract | undefined;
+    erc6492Verifier?: viem0.ChainContract | undefined;
   } | undefined;
   ensTlds?: readonly string[] | undefined;
   id: 7738577;
@@ -94,9 +94,9 @@ declare const tiramisu: {
   sourceId?: number | undefined | undefined;
   testnet: true;
   custom?: Record<string, unknown> | undefined;
-  fees?: viem8.ChainFees<undefined> | undefined;
+  fees?: viem0.ChainFees<undefined> | undefined;
   formatters?: undefined;
-  serializers?: viem8.ChainSerializers<undefined, viem8.TransactionSerializable> | undefined;
+  serializers?: viem0.ChainSerializers<undefined, viem0.TransactionSerializable> | undefined;
   readonly network: "tiramisu";
 };
 //#endregion