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

package/dist/index-EeUO0nnJ.d.cts

@@ -0,0 +1,184 @@
+import { j as ArkivClient } from "./selection-DPg0uyJf.cjs";
+import { f as Operation } from "./index-CA4V7Pdh.cjs";
+import { c as TxParams, t as EntityMutationOps } from "./arkivTransactions-D74gERHG.cjs";
+import { Address, Hash, Hex, TransactionReceipt } from "viem";
+
+//#region src/actions/advanced/buildMutation.d.ts
+/** Options for the advanced-path builders ({@link buildMutation}, {@link sendMutation}). */
+type BuildMutationOptions = {
+  /**
+   * The chain head to resolve relative expiries against.
+   *
+   * Pass a block number you already hold — from a previous call, `getBlockTiming()`, or your own
+   * tracking — and the build spends no RPC call at all. Without it, one `eth_blockNumber` is made,
+   * and only when the batch actually needs the head (a relative lifetime or a `Date` deadline);
+   * purely absolute `atBlock(n)` expiries never trigger it.
+   *
+   * Supplying it also buys back a check: absolute expiries are validated against it, so an
+   * `atBlock(n)` already in the past throws {@link InvalidExpiryError} locally instead of
+   * reverting on-chain. When the head is neither supplied nor fetched, that dead-on-arrival
+   * check is skipped — the one local validation of the everyday path this path trades away.
+   */
+  currentBlock?: bigint;
+};
+/** What {@link buildMutation} hands back: the batch in every form a sender might want. */
+type BuildMutationReturnType = {
+  /** The encoded batch, in engine order, for `writeContract`-style sends. */
+  operations: Operation[];
+  /** The Arkiv engine address the transaction must be sent to. */
+  to: Address;
+  /**
+   * The full `execute(operations)` calldata. Sign a transaction carrying it offline (with your own
+   * nonce, gas and fees) and the whole mutation costs exactly one `eth_sendRawTransaction`.
+   */
+  data: Hex;
+  /**
+   * How many operations of each kind went into the batch — which is how many events of each kind a
+   * successful transaction emits, in batch order, for cross-checking a decoded result.
+   */
+  expected: {
+    creates: number;
+    patches: number;
+    deletes: number;
+    extensions: number;
+    ownershipChanges: number;
+  };
+};
+/**
+ * Encodes a mutation batch without sending anything.
+ *
+ * This is the first step of the advanced path: it performs only local validation and encoding, so
+ * it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
+ * and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
+ * to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
+ *
+ * One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
+ * locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
+ * expiry encodes cleanly and the engine reverts it on-chain — see
+ * {@link BuildMutationOptions.currentBlock}.
+ *
+ * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
+ * @throws {InvalidValueError} If an attribute value does not fit the type it names.
+ * @throws {EmptyPatchError} If a patch has nothing to apply.
+ */
+declare function buildMutation(client: ArkivClient, data: EntityMutationOps, options?: BuildMutationOptions): Promise<BuildMutationReturnType>;
+//#endregion
+//#region src/actions/advanced/getMutationResult.d.ts
+/**
+ * A mined mutation, decoded from its receipt alone.
+ *
+ * Everything here comes out of the events the batch emitted, so no request context is needed to
+ * read it — a process that holds nothing but the transaction hash gets the full picture. Arrays
+ * are in batch order, which is the order the operations were applied in.
+ */
+type MutationResult = {
+  /** `success` means the whole batch applied; `reverted` means none of it did (arrays are empty). */
+  status: "success" | "reverted";
+  /** The transaction hash. */
+  txHash: Hash;
+  /** The block the transaction landed in. */
+  blockNumber: bigint;
+  /** The keys the engine minted for the created entities, in batch order. */
+  createdEntities: Hex[];
+  /** The block each created entity expires at, as the engine recorded it, in the same order. */
+  createdExpiries: bigint[];
+  /** The keys of the patched entities. */
+  patchedEntities: Hex[];
+  /** The keys of the deleted entities. */
+  deletedEntities: Hex[];
+  /** The keys of the extended entities. */
+  extendedEntities: Hex[];
+  /** The block each extended entity now expires at, in the same order. */
+  extendedExpiries: bigint[];
+  /** The keys of the entities handed to a new owner. */
+  ownershipChanges: Hex[];
+  /** The raw receipt, so nothing the chain said is lost. */
+  receipt: TransactionReceipt;
+};
+/** Return type for {@link getMutationResult}: the decoded result, or still pending. */
+type GetMutationResultReturnType = MutationResult | {
+  status: "pending";
+};
+/**
+ * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
+ *
+ * The pure tail of the advanced path: if a receipt reached you some other way — your own
+ * `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
+ * expiries without touching the network. Lenient by design: it reports what the events say,
+ * without counting them against a request it never saw.
+ */
+declare function decodeMutationResult(receipt: TransactionReceipt): MutationResult;
+/**
+ * Fetches a transaction's receipt — once — and decodes what the mutation did.
+ *
+ * Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
+ * decoded entity events as well: created keys, recorded expiries, and the keys of everything
+ * patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
+ * `{ status: "pending" }` — check `status` before reading the rest.
+ *
+ * No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
+ * spending a `simulateContract` on the why is your call, not the SDK's.
+ */
+declare function getMutationResult(client: ArkivClient, txHash: Hash): Promise<GetMutationResultReturnType>;
+//#endregion
+//#region src/actions/advanced/pingTransaction.d.ts
+/** Return type for {@link pingTransaction}. */
+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`.
+ */
+declare function pingTransaction(client: ArkivClient, txHash: Hash): Promise<PingTransactionReturnType>;
+//#endregion
+//#region src/actions/advanced/sendMutation.d.ts
+/** Options for {@link sendMutation}. */
+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}. */
+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.
+ */
+declare function sendMutation(client: ArkivClient, data: EntityMutationOps, options?: SendMutationOptions): Promise<SendMutationReturnType>;
+//#endregion
+export { pingTransaction as a, decodeMutationResult as c, BuildMutationReturnType as d, buildMutation as f, PingTransactionReturnType as i, getMutationResult as l, SendMutationReturnType as n, GetMutationResultReturnType as o, sendMutation as r, MutationResult as s, SendMutationOptions as t, BuildMutationOptions as u };
+//# sourceMappingURL=index-EeUO0nnJ.d.cts.map

package/dist/index-EeUO0nnJ.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-EeUO0nnJ.d.cts","names":[],"sources":["../src/actions/advanced/buildMutation.ts","../src/actions/advanced/getMutationResult.ts","../src/actions/advanced/pingTransaction.ts","../src/actions/advanced/sendMutation.ts"],"sourcesContent":[],"mappings":";;;;;;;KAeY,oBAAA;EAAA;AAkBZ;;;;;AAwCA;;;;;;;;;;AC1DY,KDkBA,uBAAA,GClBc;EAIhB;EAIS,UAAA,EDYL,SCZK,EAAA;EAIA;EAEA,EAAA,EDQb,OCRa;EAEC;;;;EAUR,IAAA,EDCJ,GCDI;EAUI;AA4BhB;;;EAGW,QAAA,EAAA;IAAR,OAAA,EAAA,MAAA;IAAO,OAAA,EAAA,MAAA;;;;EC1EE,CAAA;AAwBZ,CAAA;;;;;;;;;AClBA;AASA;AAuBA;;;;;;;iBH2BsB,aAAA,SACZ,mBACF,6BACG,uBACR,QAAQ;;;;;;;AA9DX;AAkBA;;AAIM,KCtBM,cAAA,GDsBN;EAKE;EAAG,MAAA,EAAA,SAAA,GAAA,UAAA;EA+BW;EACZ,MAAA,ECvDA,IDuDA;EACF;EACG,WAAA,EAAA,MAAA;EACA;EAAR,eAAA,ECtDgB,GDsDhB,EAAA;EAAO;;;mBClDS;EAZP;EAIF,eAAA,EAUS,GAVT,EAAA;EAIS;EAIA,gBAAA,EAIC,GAJD,EAAA;EAEA;EAEC,gBAAA,EAAA,MAAA,EAAA;EAIA;EAET,gBAAA,EAFS,GAET,EAAA;EAAkB;EAIjB,OAAA,EAJD,kBAIC;AAUZ,CAAA;AA4BA;AACU,KAvCE,2BAAA,GAA8B,cAuChC,GAAA;EACA,MAAA,EAAA,SAAA;CACC;;;;;;AC1EX;AAwBA;;AAEU,iBDiBM,oBAAA,CCjBN,OAAA,EDiBoC,kBCjBpC,CAAA,EDiByD,cCjBzD;;;;;;;ACpBV;AASA;AAuBA;;;AAGW,iBF8BW,iBAAA,CE9BX,MAAA,EF+BD,WE/BC,EAAA,MAAA,EFgCD,IEhCC,CAAA,EFiCR,OEjCQ,CFiCA,2BEjCA,CAAA;;;;KDzCC,yBAAA;;;EFOA,WAAA,CAAA,EAAA,SAAoB;AAkBhC,CAAA,GAAY;EAEE;EAER,MAAA,EAAA,SAAA,GAAA,UAAA;EAKE;EAAG,WAAA,EAAA,MAAA;AA+BX,CAAA;;;;;;;;;;AC1DA;;AAQmB,iBCSG,eAAA,CDTH,MAAA,ECUT,WDVS,EAAA,MAAA,ECWT,IDXS,CAAA,ECYhB,ODZgB,CCYR,yBDZQ,CAAA;;;;ADRP,KGDA,mBAAA,GAAsB,oBHCF,GAAA;EAkBpB;;;;EASD,QAAA,CAAA,EGvBE,QHuBF;AA+BX,CAAA;;AAEQ,KGpDI,sBAAA,GHoDJ;EACG;EACA,MAAA,EGpDD,IHoDC;EAAR;EAAO,QAAA,EGlDE,uBHkDF,CAAA,UAAA,CAAA;;;;AC9DV;;;;;;;;;AA0BA;AAUA;AA4BA;;;AAGW,iBEpCW,YAAA,CFoCX,MAAA,EEnCD,WFmCC,EAAA,IAAA,EElCH,iBFkCG,EAAA,OAAA,CAAA,EEjCA,mBFiCA,CAAA,EEhCR,OFgCQ,CEhCA,sBFgCA,CAAA"}

package/dist/index-fX_XyqLp.d.ts

@@ -0,0 +1,167 @@
+import { Address, Hex } from "viem";
+
+//#region src/entity/operations.d.ts
+
+/** One entry of the `execute` batch: the operation tag and its ABI-encoded payload. */
+type Operation = {
+  operation: number;
+  operationData: Hex;
+};
+//#endregion
+//#region src/entity/errors.d.ts
+/** An expiry could not be expressed, or would be rejected by the engine. */
+declare class InvalidExpiryError extends Error {
+  constructor(reason: string);
+}
+/** A `creationFlags` byte could not be built or read. */
+declare class InvalidCreationFlagsError extends Error {
+  constructor(reason: string);
+}
+/** A key salt was outside the `uint128` the wire carries. */
+declare class InvalidSaltError extends Error {
+  constructor(salt: bigint);
+}
+/** No cryptographic randomness was available to generate a salt. */
+declare class NoRandomSourceError extends Error {
+  constructor();
+}
+//#endregion
+//#region src/entity/events.d.ts
+/**
+ * The events the engine emits: one per applied operation, in application order, so an off-chain
+ * replica can replay a transaction operation by operation.
+ */
+declare const ENTITY_EVENTS_ABI: readonly [{
+  readonly name: "EntityCreated";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "entityKey";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "owner";
+    readonly indexed: true;
+  }, {
+    readonly type: "uint64";
+    readonly name: "expiresAt";
+  }, {
+    readonly type: "uint8";
+    readonly name: "creationFlags";
+  }];
+}, {
+  readonly name: "EntityPatched";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "entityKey";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "owner";
+    readonly indexed: true;
+  }];
+}, {
+  readonly name: "ExpiryExtended";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "entityKey";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "owner";
+    readonly indexed: true;
+  }, {
+    readonly type: "uint64";
+    readonly name: "expiresAt";
+  }];
+}, {
+  readonly name: "OwnershipTransferred";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "entityKey";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "previousOwner";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "newOwner";
+    readonly indexed: true;
+  }];
+}, {
+  readonly name: "EntityDeleted";
+  readonly type: "event";
+  readonly inputs: readonly [{
+    readonly type: "bytes32";
+    readonly name: "entityKey";
+    readonly indexed: true;
+  }, {
+    readonly type: "address";
+    readonly name: "owner";
+    readonly indexed: true;
+  }];
+}];
+/** The name of each event in {@link ENTITY_EVENTS_ABI}. */
+type EntityEventName = (typeof ENTITY_EVENTS_ABI)[number]["name"];
+//#endregion
+//#region src/entity/key.d.ts
+/** The widest salt the `uint128` wire field carries. */
+declare const MAX_SALT: bigint;
+/**
+ * A cryptographically random 128-bit salt — what {@link CreateEntityParameters.salt} defaults to.
+ *
+ * The salt exists for unpredictability, not uniqueness: the per-owner nonce already guarantees
+ * distinct keys. Random bits mean only the creator can predict the key of an entity they are about
+ * to create, so nobody else can reference or squat it in advance.
+ *
+ * @throws {NoRandomSourceError} If the runtime has no `crypto.getRandomValues`.
+ */
+declare function randomSalt(): bigint;
+/**
+ * The key an entity will be created with, derived exactly as the engine derives it:
+ * `keccak256(domain ++ owner ++ nonce ++ salt)`.
+ *
+ * Deriving it client-side is what lets a batch compose: predict the key of a create, then have a
+ * later operation in the same transaction reference it, or store it as a `key` attribute on a
+ * sibling entity.
+ */
+declare function predictEntityKey({
+  owner,
+  nonce,
+  salt,
+  chainId
+}: {
+  /** The account creating the entity. */
+  owner: Address;
+  /**
+   * The owner's entity-nonce at creation time. Each create in a batch consumes one, so the *n*th
+   * create in a batch uses `nonce + n`.
+   */
+  nonce: bigint;
+  /** The salt the create will carry. */
+  salt: bigint;
+  /** The chain the entity is being created on — half of the derivation domain. */
+  chainId: number;
+}): Hex;
+//#endregion
+//#region src/entity/params.d.ts
+/**
+ * Max uint64 value
+ */
+declare const MAX_EXPIRES_AT: bigint;
+/** The operation tags of the `execute` ABI's tagged union. */
+declare const OperationType: {
+  readonly Create: 1;
+  readonly Patch: 2;
+  readonly ExtendExpiry: 3;
+  readonly TransferOwnership: 4;
+  readonly Delete: 5;
+};
+type OperationType = (typeof OperationType)[keyof typeof OperationType];
+//#endregion
+export { randomSalt as a, InvalidCreationFlagsError as c, NoRandomSourceError as d, Operation as f, predictEntityKey as i, InvalidExpiryError as l, OperationType as n, ENTITY_EVENTS_ABI as o, MAX_SALT as r, EntityEventName as s, MAX_EXPIRES_AT as t, InvalidSaltError as u };
+//# sourceMappingURL=index-fX_XyqLp.d.ts.map

package/dist/index-fX_XyqLp.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index-fX_XyqLp.d.ts","names":[],"sources":["../src/entity/operations.ts","../src/entity/errors.ts","../src/entity/events.ts","../src/entity/key.ts","../src/entity/params.ts"],"sourcesContent":[],"mappings":";;;;;KAgDY,SAAA;;iBAEK;;;;;cCjDJ,kBAAA,SAA2B,KAAA;;AD+CxC;;cCvCa,yBAAA,SAAkC,KAAA;;AAR/C;AAQA;AAQa,cAAA,gBAAA,SAAyB,KAAA,CAAK;EAW9B,WAAA,CAAA,IAAA,EAAA,MAAoB;;;cAApB,mBAAA,SAA4B,KAAA;ECtB5B,WAAA,CAAA;AASb;;;;;;AFiCA;cE1Ca;;;EDLA,SAAA,MAAA,EAAA,SAAmB,CAAA;IAQnB,SAAA,IAAA,EAAA,SAA0B;IAQ1B,SAAA,IAAA,EAAiB,WAAA;IAWjB,SAAA,OAAA,EAAoB,IAAA;;;;ICtBpB,SAAA,OAMX,EAAA,IAAA;EAGU,CAAA,EAAA;;;;ICVC,SAA0B,IAAA,EAAA,OAAA;IAWvB,SAAU,IAAA,EAAA,eAAA;EA2BV,CAAA,CAAA;CACd,EAAA;EACA,SAAA,IAAA,EAAA,eAAA;EACA,SAAA,IAAA,EAAA,OAAA;EACA,SAAA,MAAA,EAAA,SAAA,CAAA;IAGO,SAAA,IAAA,EAAA,SAAA;IAUL,SAAA,IAAA,EAAA,WAAA;IAAG,SAAA,OAAA,EAAA,IAAA;;;;ICzDM,SAAA,OAA+B,EAAA,IAAA;EAG/B,CAAA,CAAA;AAQb,CAAA,EAAA;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;KFCY,eAAA,WAA0B;;;;cCVzB;AH2Cb;;;;AC/CA;AAQA;AAQA;AAWA;;iBEZgB,UAAA,CAAA;ADDhB;;;;ACVA;AAWA;AA2BA;;AAEE,iBAFc,gBAAA,CAEd;EAAA,KAAA;EAAA,KAAA;EAAA,IAAA;EAAA;CAAA,EAAA;EACA;EACA,KAAA,EAGO,OAHP;EAGO;;;;;;EC/CI,IAAA,EAAA,MAAA;EAGA;EAQD,OAAA,EAAA,MAAA;ID8CR;;;;;;AHZQ,cI7CC,cJ+CO,EAAA,MAAA;;cI5CP;;EHLA,SAAA,KAAA,EAAA,CAAA;EAQA,SAAA,YAAA,EAAA,CAAA;EAQA,SAAA,iBAAiB,EAAA,CAAA;EAWjB,SAAA,MAAA,EAAA,CAAA;;KGdD,aAAA,WAAwB,4BAA4B"}