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

package/src/actions/advanced/index.ts

@@ -1,21 +0,0 @@
-/**
- * The advanced path: send, ping and read results as separate, single-RPC-call steps.
- *
- * The everyday actions (`createEntity`, `mutateEntities`, …) bundle send + wait + decode into one
- * call, which is convenient and spends several RPC requests. These actions unbundle that so a
- * caller can hit the theoretical minimum:
- *
- * 1. {@link buildMutation} — encode locally (0 RPC calls with `currentBlock` supplied)
- * 2. {@link sendMutation} — submit and return the hash (1 call with full `txParams`)
- * 3. {@link pingTransaction} — one `eth_getTransactionReceipt`, on your schedule
- * 4. {@link getMutationResult} / {@link decodeMutationResult} — the same single call (or none)
- *    turned into entity keys and expiries
- */
-export type { BuildMutationOptions, BuildMutationReturnType } from "./buildMutation"
-export { buildMutation } from "./buildMutation"
-export type { GetMutationResultReturnType, MutationResult } from "./getMutationResult"
-export { decodeMutationResult, getMutationResult } from "./getMutationResult"
-export type { PingTransactionReturnType } from "./pingTransaction"
-export { pingTransaction } from "./pingTransaction"
-export type { SendMutationOptions, SendMutationReturnType } from "./sendMutation"
-export { sendMutation } from "./sendMutation"

package/src/actions/advanced/pingTransaction.ts

@@ -1,43 +0,0 @@
-import type { Hash } from "viem"
-import type { ArkivClient } from "../../clients/baseClient"
-import { getLogger } from "../../utils/logger"
-import { fetchReceipt } from "./getMutationResult"
-
-const logger = getLogger("actions:advanced:ping-transaction")
-
-/** Return type for {@link pingTransaction}. */
-export type PingTransactionReturnType =
-  | {
-      /** Not mined yet (or unknown to this node). Ping again later. */
-      status: "pending"
-      blockNumber?: undefined
-    }
-  | {
-      /** Mined. `success` means the whole batch applied; `reverted` means none of it did. */
-      status: "success" | "reverted"
-      /** The block the transaction landed in. */
-      blockNumber: bigint
-    }
-
-/**
- * Asks the chain — once — whether a transaction has landed.
- *
- * Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
- * back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
- * path — you own the schedule, the SDK owns nothing.
- *
- * When it reports `success` and you need the created keys or recorded expiries, spend the next
- * call on `getMutationResult` — or none at all, if you predicted the keys up front with
- * `predictEntityKeys`.
- */
-export async function pingTransaction(
-  client: ArkivClient,
-  txHash: Hash,
-): Promise<PingTransactionReturnType> {
-  const receipt = await fetchReceipt(client, txHash)
-  if (receipt === undefined) {
-    logger("Tx %s still pending", txHash)
-    return { status: "pending" }
-  }
-  return { status: receipt.status, blockNumber: receipt.blockNumber }
-}

package/src/actions/advanced/sendMutation.ts

@@ -1,59 +0,0 @@
-import type { Hash } from "viem"
-import type { ArkivClient } from "../../clients/baseClient"
-import type { TxParams } from "../../types"
-import { type EntityMutationOps, submitMutation } from "../../utils/arkivTransactions"
-import { getLogger } from "../../utils/logger"
-import {
-  type BuildMutationOptions,
-  type BuildMutationReturnType,
-  buildMutation,
-} from "./buildMutation"
-
-const logger = getLogger("actions:advanced:send-mutation")
-
-/** Options for {@link sendMutation}. */
-export type SendMutationOptions = BuildMutationOptions & {
-  /**
-   * Transaction parameters. Supply `nonce`, `gas` and the fee fields and viem has nothing left to
-   * look up — the send collapses to a single `eth_sendRawTransaction`.
-   */
-  txParams?: TxParams
-}
-
-/** Return type for {@link sendMutation}. */
-export type SendMutationReturnType = {
-  /** The transaction hash. Poll it with `pingTransaction` / fetch it with `getMutationResult`. */
-  txHash: Hash
-  /** The per-kind operation counts of the batch that was sent, for cross-checking the result. */
-  expected: BuildMutationReturnType["expected"]
-}
-
-/**
- * Signs and sends a mutation batch, returning as soon as the transaction is submitted.
- *
- * The fire-and-forget half of the advanced path. Unlike `mutateEntities`, this does **not** wait
- * for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
- * costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
- * RPC call; each omitted piece adds only the lookup viem needs to fill it.
- *
- * Follow up separately, on your own schedule:
- * - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
- * - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
- *
- * @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
- * the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
- * Anything after that — inclusion, success — is yours to check.
- */
-export async function sendMutation(
-  client: ArkivClient,
-  data: EntityMutationOps,
-  options: SendMutationOptions = {},
-): Promise<SendMutationReturnType> {
-  const { operations, expected } = await buildMutation(client, data, options)
-
-  logger("Sending execute with %d operations (no wait)", operations.length)
-
-  const txHash = await submitMutation(client, operations, options.txParams)
-
-  return { txHash, expected }
-}

package/src/clients/decorators/arkivAdvanced.ts

@@ -1,144 +0,0 @@
-import type { Account, Chain, Client, Hash, TransactionReceipt, Transport } from "viem"
-import type {
-  BuildMutationOptions,
-  BuildMutationReturnType,
-} from "../../actions/advanced/buildMutation"
-import { buildMutation } from "../../actions/advanced/buildMutation"
-import type {
-  GetMutationResultReturnType,
-  MutationResult,
-} from "../../actions/advanced/getMutationResult"
-import { decodeMutationResult, getMutationResult } from "../../actions/advanced/getMutationResult"
-import type { PingTransactionReturnType } from "../../actions/advanced/pingTransaction"
-import { pingTransaction } from "../../actions/advanced/pingTransaction"
-import type {
-  SendMutationOptions,
-  SendMutationReturnType,
-} from "../../actions/advanced/sendMutation"
-import { sendMutation } from "../../actions/advanced/sendMutation"
-import type { EntityMutationOps } from "../../utils/arkivTransactions"
-
-/**
- * The read-only half of the advanced path — checking on a transaction and decoding its result —
- * which needs no account, so a Public Client carries it too.
- *
- * Every action here costs at most one RPC call, and says exactly which.
- */
-export type PublicAdvancedActions = {
-  /**
-   * Asks the chain — once — whether a transaction has landed. Exactly one
-   * `eth_getTransactionReceipt`, never a poll: an unmined transaction comes back as
-   * `{ status: "pending" }` and the schedule stays yours.
-   *
-   * @param txHash - The transaction hash returned by `sendMutation` (or any other send)
-   * @returns `{ status: "pending" }`, or `{ status: "success" | "reverted", blockNumber }`
-   *
-   * @example
-   * const { status } = await client.advanced.pingTransaction(txHash)
-   * if (status === "pending") scheduleAnotherPing()
-   */
-  pingTransaction: (txHash: Hash) => Promise<PingTransactionReturnType>
-
-  /**
-   * Fetches a transaction's receipt — once — and decodes what the mutation did: created keys and
-   * expiries, plus the keys of everything patched, deleted, extended or handed over. One
-   * `eth_getTransactionReceipt`; `{ status: "pending" }` if not mined yet. No revert diagnosis is
-   * run on a `reverted` result — that extra call is yours to spend or skip.
-   *
-   * @param txHash - The transaction hash
-   * @returns The decoded {@link MutationResult}, or `{ status: "pending" }`
-   *
-   * @example
-   * const result = await client.advanced.getMutationResult(txHash)
-   * if (result.status === "success") console.log(result.createdEntities)
-   */
-  getMutationResult: (txHash: Hash) => Promise<GetMutationResultReturnType>
-
-  /**
-   * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls** — for
-   * receipts that reached you through your own `waitForTransactionReceipt`, a block watcher, or a
-   * webhook.
-   *
-   * @param receipt - The transaction receipt
-   * @returns The decoded {@link MutationResult}
-   */
-  decodeMutationResult: (receipt: TransactionReceipt) => MutationResult
-}
-
-/**
- * The advanced path on a Wallet Client: build, send, ping and read results as separate steps, each
- * costing the minimum number of RPC calls — down to one per transaction when you supply what the
- * SDK would otherwise look up.
- *
- * The everyday actions (`createEntity`, `mutateEntities`, …) bundle send + wait + decode and are
- * the right default. This namespace unbundles them for callers optimising their RPC budget.
- *
- * @example Minimal-call flow: one send, one ping, done.
- * const { txHash } = await client.advanced.sendMutation(
- *   { creates: [{ payload, contentType: "application/json", expires }] },
- *   { currentBlock, txParams: { nonce, gas: 1_000_000n, maxFeePerGas, maxPriorityFeePerGas } },
- * ) // exactly 1 RPC call: eth_sendRawTransaction
- * // ... later, on your own schedule:
- * const result = await client.advanced.getMutationResult(txHash) // 1 RPC call
- * if (result.status === "success") console.log(result.createdEntities)
- */
-export type WalletAdvancedActions = PublicAdvancedActions & {
-  /**
-   * Encodes a mutation batch without sending anything: zero RPC calls with `currentBlock` supplied
-   * (or when no expiry is relative), at most one `eth_blockNumber` otherwise. Returns the
-   * operations for `writeContract`, and the `{ to, data }` calldata for offline signing.
-   *
-   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
-   * @param options - Optional `currentBlock` to avoid the `eth_blockNumber` lookup
-   */
-  buildMutation: (
-    data: EntityMutationOps,
-    options?: BuildMutationOptions,
-  ) => Promise<BuildMutationReturnType>
-
-  /**
-   * Signs and sends a mutation batch, returning the hash as soon as the transaction is submitted —
-   * no waiting, no polling, no revert diagnosis. With `currentBlock` and full `txParams` (nonce,
-   * gas, fees) supplied this is exactly one `eth_sendRawTransaction`; each omitted piece adds only
-   * the lookup viem needs to fill it.
-   *
-   * @param data - The batch (creates, patches, deletes, extensions, ownershipChanges)
-   * @param options - Optional `currentBlock` and `txParams`
-   * @returns The transaction hash and the batch's per-kind operation counts
-   *
-   * @example
-   * const { txHash } = await client.advanced.sendMutation({
-   *   creates: [{ payload, contentType: "application/json", expires: ExpirationTime.atBlock(1_200_000n) }],
-   * })
-   */
-  sendMutation: (
-    data: EntityMutationOps,
-    options?: SendMutationOptions,
-  ) => Promise<SendMutationReturnType>
-}
-
-export function publicAdvancedActions<
-  transport extends Transport = Transport,
-  chain extends Chain | undefined = Chain | undefined,
-  account extends Account | undefined = Account | undefined,
->(client: Client<transport, chain, account>): PublicAdvancedActions {
-  return {
-    pingTransaction: (txHash: Hash) => pingTransaction(client, txHash),
-    getMutationResult: (txHash: Hash) => getMutationResult(client, txHash),
-    decodeMutationResult: (receipt: TransactionReceipt) => decodeMutationResult(receipt),
-  }
-}
-
-export function walletAdvancedActions<
-  transport extends Transport = Transport,
-  chain extends Chain | undefined = Chain | undefined,
-  account extends Account | undefined = Account | undefined,
->(client: Client<transport, chain, account>): WalletAdvancedActions {
-  return {
-    ...publicAdvancedActions(client),
-    buildMutation: (data: EntityMutationOps, options?: BuildMutationOptions) =>
-      buildMutation(client, data, options),
-    sendMutation: (data: EntityMutationOps, options?: SendMutationOptions) =>
-      sendMutation(client, data, options),
-  }
-}