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

package/README.md

@@ -97,12 +97,12 @@ You can now use Arkiv's public client to query data. Paste the following in `rea
 
 ```typescript
 import { createPublicClient } from "@arkiv-network/sdk"
-import { braga } from "@arkiv-network/sdk/chains"
+import { cheesecake } from "@arkiv-network/sdk/chains"
 import { eq } from "@arkiv-network/sdk/query"
 import { http } from "viem"
 
 const publicClient = createPublicClient({
-  chain: braga, // "braga" is Arkiv's testnet
+  chain: cheesecake, // "cheesecake" is Arkiv's testnet
   transport: http(),
 });
 
@@ -124,10 +124,17 @@ const result = await publicClient
 
 console.log('Found entities:', result.entities);
 
-// Pagination - fetch next page
+// Pagination
 if (result.hasNextPage()) {
-  await result.next();
-  console.log('Next page:', result.entities);
+  const nextPage = await result.next();
+  console.log('Next page:', nextPage.entities);
+}
+
+// Or walk every page at once
+for await (const entity of publicClient
+  .select({ key: true })
+  .where(eq('category', 'documentation'))) {
+  console.log(entity.key);
 }
 ```
 
@@ -150,7 +157,9 @@ The result type is inferred from your selection: reading a field you didn't sele
 helpers are available only when you select `payload`.
 
 ```typescript
-const [entity] = (await publicClient.select({ owner: true, payload: true }).fetch()).entities;
+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
@@ -206,19 +215,20 @@ Create a file named `write_example.ts` with the following content:
 
 ```typescript
 import { createPublicClient, createWalletClient } from "@arkiv-network/sdk"
-import { braga } from "@arkiv-network/sdk/chains"
+import { dec, i32 } from "@arkiv-network/sdk/attr"
+import { cheesecake } from "@arkiv-network/sdk/chains"
 import { ExpirationTime, jsonToPayload } from "@arkiv-network/sdk/utils"
 import { http } from "viem"
 import { privateKeyToAccount } from "viem/accounts"
 
 // Create a public client
 const publicClient = createPublicClient({
-  chain: braga, // braga is the Arkiv testnet
+  chain: cheesecake, // cheesecake is the Arkiv testnet
   transport: http(),
 })
 // Create a wallet client with an account
 const client = createWalletClient({
-  chain: braga,
+  chain: cheesecake,
   transport: http(),
   account: privateKeyToAccount('0x...'), // Replace with your private key
 });
@@ -233,11 +243,15 @@ const { entityKey, txHash } = await client.createEntity({
     },
   }),
   contentType: 'application/json',
-  attributes: [
-    { key: 'category', value: 'documentation' },
-    { key: 'version', value: '1.0' },
-  ],
-  expiresIn: ExpirationTime.fromDays(30), // Entity expires in 30 days
+  // 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),
+    score: dec('4.5'),
+  },
+  expires: ExpirationTime.fromDays(30), // Entity expires in 30 days
 });
 
 console.log('Created entity:', entityKey);
@@ -267,8 +281,7 @@ Now you can run it in the same way as in the previous example:
 **Note:**  
 You must provide your own private key with a minimum balance on the Arkiv L3 network.  
 You can generate a private key using any tool, for example: https://vanity-eth.tk/  
-Once you have a key, you can paste it into the example above and fund its address using the Arkiv Braga testnet faucet at:  
-https://braga.hoodi.arkiv.network/faucet/
+Once you have a key, you can paste it into the example above and fund its address on the Arkiv Cheesecake testnet.
 
 For quick testing, you may use this example key:
 ```
@@ -278,6 +291,48 @@ However, funds may not always be available for this key.
 
 Sample code can also be found in the [`sample`](./sample) directory of this repository.
 
+### Advanced Path (Minimal RPC Calls)
+
+The everyday actions (`createEntity`, `mutateEntities`, ...) bundle send + wait + decode into one
+call, which is convenient but spends several RPC requests per mutation. The `client.advanced`
+namespace unbundles them so you control every call yourself:
+
+```typescript
+// 1. Send — submits the transaction and returns the hash immediately. No waiting, no polling,
+//    no revert diagnosis. Supply `currentBlock` and full `txParams` (nonce, gas, fees) and this
+//    is exactly one RPC call: eth_sendRawTransaction.
+const { txHash } = await client.advanced.sendMutation(
+  { creates: [{ payload, contentType: "application/json", expires: ExpirationTime.fromDays(30) }] },
+  {
+    currentBlock,                                              // skip eth_blockNumber
+    txParams: { nonce, gas, maxFeePerGas, maxPriorityFeePerGas }, // skip fee/nonce/gas lookups
+  },
+)
+
+// 2. Ping — one eth_getTransactionReceipt, on your own schedule. Never polls.
+const ping = await client.advanced.pingTransaction(txHash)
+// { status: "pending" } | { status: "success" | "reverted", blockNumber }
+
+// 3. Result — the same single call, decoded into entity keys and expiries.
+const result = await client.advanced.getMutationResult(txHash)
+if (result.status === "success") console.log(result.createdEntities, result.createdExpiries)
+
+// Or, with a receipt you already hold (your own watcher, webhook...): zero RPC calls.
+const decoded = client.advanced.decodeMutationResult(receipt)
+```
+
+For full offline control, `client.advanced.buildMutation(data, { currentBlock })` encodes the
+batch with **zero** RPC calls and returns the `execute` calldata (`{ to, data }`) — sign it
+yourself and the whole mutation costs a single `eth_sendRawTransaction`. Pair it with
+`predictEntityKeys` to know the created keys before the transaction is even mined.
+
+The checking half (`pingTransaction`, `getMutationResult`, `decodeMutationResult`) is also
+available on the public client, so a keyless process can follow a transaction by hash alone.
+
+A complete runnable walkthrough — manual nonce, gas and fee setup, the single-call send, and the
+hand-rolled receipt check — is in
+[`sample/write_example_advanced.ts`](./sample/write_example_advanced.ts).
+
 ## Package Distribution
 
 This package supports multiple module formats for maximum compatibility:

package/dist/actions/advanced/index.cjs

@@ -0,0 +1,13 @@
+require('../../expiry-BELY2Kpw.cjs');
+const require_advanced = require('../../advanced-fPImL6lW.cjs');
+require('../../attributes-Df9IsCVs.cjs');
+require('../../key-WKhXnXuU.cjs');
+require('../../errors-BVbjKVMN.cjs');
+require('../../flags-kr276q6i.cjs');
+require('../../logger-Cr15lPAQ.cjs');
+
+exports.buildMutation = require_advanced.buildMutation;
+exports.decodeMutationResult = require_advanced.decodeMutationResult;
+exports.getMutationResult = require_advanced.getMutationResult;
+exports.pingTransaction = require_advanced.pingTransaction;
+exports.sendMutation = require_advanced.sendMutation;

package/dist/actions/advanced/index.d.cts

@@ -0,0 +1,8 @@
+import "../../selection-DPg0uyJf.cjs";
+import "../../index-CV5zCdpa.cjs";
+import "../../expiry-DRV29F1r.cjs";
+import "../../index-CA4V7Pdh.cjs";
+import "../../arkivTransactions-D74gERHG.cjs";
+import "../../flags-CRjPpoh3.cjs";
+import { a as pingTransaction, c as decodeMutationResult, d as BuildMutationReturnType, f as buildMutation, i as PingTransactionReturnType, l as getMutationResult, n as SendMutationReturnType, o as GetMutationResultReturnType, r as sendMutation, s as MutationResult, t as SendMutationOptions, u as BuildMutationOptions } from "../../index-EeUO0nnJ.cjs";
+export { BuildMutationOptions, BuildMutationReturnType, GetMutationResultReturnType, MutationResult, PingTransactionReturnType, SendMutationOptions, SendMutationReturnType, buildMutation, decodeMutationResult, getMutationResult, pingTransaction, sendMutation };

package/dist/actions/advanced/index.d.ts

@@ -0,0 +1,9 @@
+import "../../selection-C4UhsMOO.js";
+import "../../codec-Car3KkFF.js";
+import "../../expiry-nDbCgZX4.js";
+import "../../index-fX_XyqLp.js";
+import "../../arkivTransactions-NtGD6uk5.js";
+import "../../index-DvYvrkdk.js";
+import "../../flags-5dTNRnow.js";
+import { a as pingTransaction, c as decodeMutationResult, d as BuildMutationReturnType, f as buildMutation, i as PingTransactionReturnType, l as getMutationResult, n as SendMutationReturnType, o as GetMutationResultReturnType, r as sendMutation, s as MutationResult, t as SendMutationOptions, u as BuildMutationOptions } from "../../index-B5j76711.js";
+export { BuildMutationOptions, BuildMutationReturnType, GetMutationResultReturnType, MutationResult, PingTransactionReturnType, SendMutationOptions, SendMutationReturnType, buildMutation, decodeMutationResult, getMutationResult, pingTransaction, sendMutation };

package/dist/actions/advanced/index.js

@@ -0,0 +1,9 @@
+import "../../expiry-BjpxZZQU.js";
+import { a as buildMutation, i as getMutationResult, n as pingTransaction, r as decodeMutationResult, t as sendMutation } from "../../advanced-8ZPTmmaN.js";
+import "../../attributes-BhY5DwJp.js";
+import "../../key-D1Bh7MF0.js";
+import "../../errors-LTe7bOYS.js";
+import "../../flags-DFBs2J94.js";
+import "../../logger-CVpvU8ik.js";
+
+export { buildMutation, decodeMutationResult, getMutationResult, pingTransaction, sendMutation };