@arkiv-network/sdk 0.7.0 → 0.8.0-advanced.3

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (240) hide show
  1. package/README.md +71 -16
  2. package/dist/actions/advanced/index.cjs +13 -0
  3. package/dist/actions/advanced/index.d.cts +8 -0
  4. package/dist/actions/advanced/index.d.ts +9 -0
  5. package/dist/actions/advanced/index.js +9 -0
  6. package/dist/advanced-Ds2XRflQ.cjs +656 -0
  7. package/dist/advanced-FZy7WoYR.js +598 -0
  8. package/dist/advanced-FZy7WoYR.js.map +1 -0
  9. package/dist/arkivTransactions-BpARZOsH.d.cts +584 -0
  10. package/dist/arkivTransactions-BpARZOsH.d.cts.map +1 -0
  11. package/dist/arkivTransactions-DfZ_yVDD.d.ts +584 -0
  12. package/dist/arkivTransactions-DfZ_yVDD.d.ts.map +1 -0
  13. package/dist/attr/index.cjs +35 -0
  14. package/dist/attr/index.d.cts +2 -0
  15. package/dist/attr/index.d.ts +3 -0
  16. package/dist/attr/index.js +4 -0
  17. package/dist/attributes-BJGuhsqp.js +819 -0
  18. package/dist/attributes-BJGuhsqp.js.map +1 -0
  19. package/dist/attributes-CMJlp1wn.cjs +1039 -0
  20. package/dist/chains/index.cjs +2 -3
  21. package/dist/chains/index.d.cts +41 -76
  22. package/dist/chains/index.d.cts.map +1 -1
  23. package/dist/chains/index.d.ts +24 -59
  24. package/dist/chains/index.d.ts.map +1 -1
  25. package/dist/chains/index.js +2 -2
  26. package/dist/chains-BfNQliHU.cjs +76 -0
  27. package/dist/chains-Du8tql7I.js +60 -0
  28. package/dist/chains-Du8tql7I.js.map +1 -0
  29. package/dist/codec-M74UR1_0.d.ts +101 -0
  30. package/dist/codec-M74UR1_0.d.ts.map +1 -0
  31. package/dist/entity/index.cjs +21 -0
  32. package/dist/entity/index.d.cts +4 -0
  33. package/dist/entity/index.d.ts +5 -0
  34. package/dist/entity/index.js +7 -0
  35. package/dist/entity-B00Li04j.cjs +71 -0
  36. package/dist/entity-B7G8q_Eo.cjs +0 -0
  37. package/dist/entity-BYQR1uoe.js +67 -0
  38. package/dist/entity-BYQR1uoe.js.map +1 -0
  39. package/dist/entity-CD_qFF2M.js +0 -0
  40. package/dist/errors-51znTSB1.cjs +56 -0
  41. package/dist/errors-CwPJ16bn.js +33 -0
  42. package/dist/errors-CwPJ16bn.js.map +1 -0
  43. package/dist/expiry-CZErShX6.js +95 -0
  44. package/dist/expiry-CZErShX6.js.map +1 -0
  45. package/dist/expiry-DRV29F1r.d.cts +79 -0
  46. package/dist/expiry-DRV29F1r.d.cts.map +1 -0
  47. package/dist/expiry-nDbCgZX4.d.ts +79 -0
  48. package/dist/expiry-nDbCgZX4.d.ts.map +1 -0
  49. package/dist/expiry-xr6mx4f7.cjs +135 -0
  50. package/dist/flags-5dTNRnow.d.ts +41 -0
  51. package/dist/flags-5dTNRnow.d.ts.map +1 -0
  52. package/dist/flags-Bh0HJldY.cjs +43 -0
  53. package/dist/flags-CRjPpoh3.d.cts +41 -0
  54. package/dist/flags-CRjPpoh3.d.cts.map +1 -0
  55. package/dist/flags-Cr76ldwF.js +33 -0
  56. package/dist/flags-Cr76ldwF.js.map +1 -0
  57. package/dist/index-CMeD8uEq.d.cts +280 -0
  58. package/dist/index-CMeD8uEq.d.cts.map +1 -0
  59. package/dist/index-CTDI5pXZ.d.ts +184 -0
  60. package/dist/index-CTDI5pXZ.d.ts.map +1 -0
  61. package/dist/index-CekGjkRx.d.cts +184 -0
  62. package/dist/index-CekGjkRx.d.cts.map +1 -0
  63. package/dist/index-D0IzFwMX.d.ts +328 -0
  64. package/dist/index-D0IzFwMX.d.ts.map +1 -0
  65. package/dist/index-DZxwz2Ky.d.cts +177 -0
  66. package/dist/index-DZxwz2Ky.d.cts.map +1 -0
  67. package/dist/index-Dz4SkQWg.d.ts +280 -0
  68. package/dist/index-Dz4SkQWg.d.ts.map +1 -0
  69. package/dist/index-JP31fjyM.d.ts +177 -0
  70. package/dist/index-JP31fjyM.d.ts.map +1 -0
  71. package/dist/index-NbfnXxgr.d.cts +424 -0
  72. package/dist/index-NbfnXxgr.d.cts.map +1 -0
  73. package/dist/index.cjs +434 -412
  74. package/dist/index.d.cts +401 -235
  75. package/dist/index.d.cts.map +1 -1
  76. package/dist/index.d.ts +402 -235
  77. package/dist/index.d.ts.map +1 -1
  78. package/dist/index.js +370 -404
  79. package/dist/index.js.map +1 -1
  80. package/dist/key-E7mv0BYf.cjs +116 -0
  81. package/dist/key-XQkpw2xh.js +82 -0
  82. package/dist/key-XQkpw2xh.js.map +1 -0
  83. package/dist/logger-CVpvU8ik.js +153 -0
  84. package/dist/logger-CVpvU8ik.js.map +1 -0
  85. package/dist/logger-Cr15lPAQ.cjs +188 -0
  86. package/dist/payload-Cvrir3Q-.cjs +108 -0
  87. package/dist/payload-D53ms-Mg.d.ts +153 -0
  88. package/dist/payload-D53ms-Mg.d.ts.map +1 -0
  89. package/dist/payload-DaPzUvEh.js +92 -0
  90. package/dist/payload-DaPzUvEh.js.map +1 -0
  91. package/dist/payload-hluX1rc0.d.cts +153 -0
  92. package/dist/payload-hluX1rc0.d.cts.map +1 -0
  93. package/dist/query/index.cjs +26 -149
  94. package/dist/query/index.d.cts +5 -3
  95. package/dist/query/index.d.ts +6 -3
  96. package/dist/query/index.js +8 -137
  97. package/dist/queryBuilder-BXR-HxD9.cjs +947 -0
  98. package/dist/queryBuilder-BwauPaGO.js +823 -0
  99. package/dist/queryBuilder-BwauPaGO.js.map +1 -0
  100. package/dist/selection-C6KeWJ7g.d.cts +441 -0
  101. package/dist/selection-C6KeWJ7g.d.cts.map +1 -0
  102. package/dist/selection-mjiiAGDO.d.ts +442 -0
  103. package/dist/selection-mjiiAGDO.d.ts.map +1 -0
  104. package/dist/types/index.cjs +4 -1
  105. package/dist/types/index.d.cts +7 -2
  106. package/dist/types/index.d.ts +8 -2
  107. package/dist/types/index.js +4 -1
  108. package/dist/types-Bu_ZwMbZ.js +0 -0
  109. package/dist/types-NRqymi6S.cjs +0 -0
  110. package/dist/utils/index.cjs +4 -17
  111. package/dist/utils/index.d.cts +3 -17
  112. package/dist/utils/index.d.ts +3 -17
  113. package/dist/utils/index.js +4 -18
  114. package/package.json +26 -9
  115. package/src/actions/advanced/advanced.test.ts +258 -0
  116. package/src/actions/advanced/buildMutation.ts +104 -0
  117. package/src/actions/advanced/getMutationResult.ts +112 -0
  118. package/src/actions/advanced/index.ts +21 -0
  119. package/src/actions/advanced/pingTransaction.ts +43 -0
  120. package/src/actions/advanced/sendMutation.ts +59 -0
  121. package/src/actions/public/getEntity.ts +28 -43
  122. package/src/actions/public/getEntityNonce.ts +30 -0
  123. package/src/actions/public/predictEntityKeys.test.ts +159 -0
  124. package/src/actions/public/predictEntityKeys.ts +152 -0
  125. package/src/actions/public/query.ts +35 -67
  126. package/src/actions/public/watchEntityEvents.test.ts +414 -0
  127. package/src/actions/public/watchEntityEvents.ts +225 -0
  128. package/src/actions/wallet/changeOwnership.ts +8 -8
  129. package/src/actions/wallet/createEntity.ts +105 -26
  130. package/src/actions/wallet/deleteEntity.ts +2 -3
  131. package/src/actions/wallet/executeBatch.test.ts +76 -0
  132. package/src/actions/wallet/executeBatch.ts +51 -0
  133. package/src/actions/wallet/extendEntity.ts +40 -16
  134. package/src/actions/wallet/patchEntity.ts +90 -0
  135. package/src/attr/attributes.test.ts +120 -0
  136. package/src/attr/attributes.ts +196 -0
  137. package/src/attr/codec.test.ts +162 -0
  138. package/src/attr/codec.ts +220 -0
  139. package/src/attr/decimal.ts +86 -0
  140. package/src/attr/errors.ts +145 -0
  141. package/src/attr/index.ts +50 -0
  142. package/src/attr/names.ts +106 -0
  143. package/src/attr/types.ts +150 -0
  144. package/src/attr/values.test.ts +271 -0
  145. package/src/attr/values.ts +506 -0
  146. package/src/chains/cheesecake.ts +22 -0
  147. package/src/chains/index.ts +1 -2
  148. package/src/chains/localhost.ts +3 -0
  149. package/src/clients/createPublicClient.test.ts +4 -6
  150. package/src/clients/createPublicClient.ts +9 -8
  151. package/src/clients/createWalletClient.test.ts +4 -4
  152. package/src/clients/createWalletClient.ts +13 -9
  153. package/src/clients/decorators/arkivAdvanced.ts +144 -0
  154. package/src/clients/decorators/arkivPublic.ts +181 -147
  155. package/src/clients/decorators/arkivWallet.ts +141 -122
  156. package/src/consts.ts +2 -1
  157. package/src/entity/create.test.ts +203 -0
  158. package/src/entity/errors.ts +39 -0
  159. package/src/entity/events.ts +16 -0
  160. package/src/entity/expiry.test.ts +195 -0
  161. package/src/entity/expiry.ts +182 -0
  162. package/src/entity/flags.ts +65 -0
  163. package/src/entity/index.ts +16 -0
  164. package/src/entity/key.ts +88 -0
  165. package/src/entity/operations.ts +135 -0
  166. package/src/entity/params.ts +15 -0
  167. package/src/errors.ts +33 -28
  168. package/src/index.ts +19 -0
  169. package/src/query/engine.ts +68 -132
  170. package/src/query/errors.ts +151 -0
  171. package/src/query/expression.test.ts +286 -0
  172. package/src/query/expression.ts +500 -0
  173. package/src/query/index.ts +40 -4
  174. package/src/query/injection.test.ts +151 -0
  175. package/src/query/queryBuilder.test.ts +342 -637
  176. package/src/query/queryBuilder.ts +133 -359
  177. package/src/query/queryResult.ts +54 -51
  178. package/src/query/selection.test.ts +48 -98
  179. package/src/query/selection.ts +77 -65
  180. package/src/types/entity.test.ts +44 -155
  181. package/src/types/entity.ts +62 -44
  182. package/src/types/events.ts +64 -23
  183. package/src/types/index.ts +24 -20
  184. package/src/types/rpcSchema.ts +71 -33
  185. package/src/types/txParams.ts +8 -0
  186. package/src/utils/arkivTransactions.test.ts +687 -38
  187. package/src/utils/arkivTransactions.ts +400 -115
  188. package/src/utils/chains.test.ts +21 -24
  189. package/src/utils/compression.ts +1 -1
  190. package/src/utils/entities.test.ts +62 -0
  191. package/src/utils/entities.ts +111 -29
  192. package/src/utils/expirationTime.ts +153 -10
  193. package/src/utils/logger.ts +2 -2
  194. package/src/utils/payload.ts +29 -2
  195. package/src/utils/revert.test.ts +99 -0
  196. package/src/utils/revert.ts +145 -0
  197. package/dist/chains-BifaY04V.cjs +0 -108
  198. package/dist/chains-CrtkVbBh.js +0 -86
  199. package/dist/chains-CrtkVbBh.js.map +0 -1
  200. package/dist/consts-AUoL-v42.cjs +0 -18
  201. package/dist/consts-BV4PR-de.js +0 -7
  202. package/dist/consts-BV4PR-de.js.map +0 -1
  203. package/dist/entity-B6g_EPm1.d.cts +0 -382
  204. package/dist/entity-B6g_EPm1.d.cts.map +0 -1
  205. package/dist/entity-qoLMAuuk.d.ts +0 -382
  206. package/dist/entity-qoLMAuuk.d.ts.map +0 -1
  207. package/dist/index-DdspxNAA.d.ts +0 -481
  208. package/dist/index-DdspxNAA.d.ts.map +0 -1
  209. package/dist/index-Ds9dwqb5.d.cts +0 -481
  210. package/dist/index-Ds9dwqb5.d.cts.map +0 -1
  211. package/dist/payload-B2kFJyah.d.ts +0 -6
  212. package/dist/payload-B2kFJyah.d.ts.map +0 -1
  213. package/dist/payload-CJN8fTvX.d.cts +0 -6
  214. package/dist/payload-CJN8fTvX.d.cts.map +0 -1
  215. package/dist/payload-Claf2jUO.js +0 -13
  216. package/dist/payload-Claf2jUO.js.map +0 -1
  217. package/dist/payload-DpA5PA-w.cjs +0 -23
  218. package/dist/query/index.js.map +0 -1
  219. package/dist/queryBuilder-D2uwP9jI.js +0 -704
  220. package/dist/queryBuilder-D2uwP9jI.js.map +0 -1
  221. package/dist/queryBuilder-UW2MCaX4.cjs +0 -792
  222. package/dist/utils/index.d.cts.map +0 -1
  223. package/dist/utils/index.d.ts.map +0 -1
  224. package/dist/utils/index.js.map +0 -1
  225. package/src/actions/public/buildQuery.ts +0 -10
  226. package/src/actions/public/subscribeEntityEvents.ts +0 -119
  227. package/src/actions/wallet/mutateEntities.ts +0 -111
  228. package/src/actions/wallet/updateEntity.ts +0 -60
  229. package/src/chains/braga.ts +0 -26
  230. package/src/chains/kaolin.ts +0 -29
  231. package/src/query/engine.test.ts +0 -526
  232. package/src/query/predicate.test.ts +0 -461
  233. package/src/query/predicate.ts +0 -144
  234. package/src/query/queryResult.test.ts +0 -270
  235. package/src/query/selectQueryBuilder.test.ts +0 -210
  236. package/src/types/attributes.ts +0 -16
  237. package/src/utils/validation.test.ts +0 -60
  238. package/src/utils/validation.ts +0 -32
  239. /package/dist/{types-H-TSmRpm.js → attr-DlmErkvR.cjs} +0 -0
  240. /package/dist/{types-o3zWarRp.cjs → attr-GcQKatub.js} +0 -0
@@ -0,0 +1,184 @@
1
+ import { j as ArkivClient } from "./selection-mjiiAGDO.js";
2
+ import { m as Operation } from "./index-JP31fjyM.js";
3
+ import { c as TxParams, t as EntityMutationOps } from "./arkivTransactions-DfZ_yVDD.js";
4
+ import { Address, Hash, Hex, TransactionReceipt } from "viem";
5
+
6
+ //#region src/actions/advanced/buildMutation.d.ts
7
+ /** Options for the advanced-path builders ({@link buildMutation}, {@link sendMutation}). */
8
+ type BuildMutationOptions = {
9
+ /**
10
+ * The chain head to resolve relative expiries against.
11
+ *
12
+ * Pass a block number you already hold — from a previous call, `getBlockTiming()`, or your own
13
+ * tracking — and the build spends no RPC call at all. Without it, one `eth_blockNumber` is made,
14
+ * and only when the batch actually needs the head (a relative lifetime or a `Date` deadline);
15
+ * purely absolute `atBlock(n)` expiries never trigger it.
16
+ *
17
+ * Supplying it also buys back a check: absolute expiries are validated against it, so an
18
+ * `atBlock(n)` already in the past throws {@link InvalidExpiryError} locally instead of
19
+ * reverting on-chain. When the head is neither supplied nor fetched, that dead-on-arrival
20
+ * check is skipped — the one local validation of the everyday path this path trades away.
21
+ */
22
+ currentBlock?: bigint;
23
+ };
24
+ /** What {@link buildMutation} hands back: the batch in every form a sender might want. */
25
+ type BuildMutationReturnType = {
26
+ /** The encoded batch, in engine order, for `writeContract`-style sends. */
27
+ operations: Operation[];
28
+ /** The Arkiv engine address the transaction must be sent to. */
29
+ to: Address;
30
+ /**
31
+ * The full `execute(operations)` calldata. Sign a transaction carrying it offline (with your own
32
+ * nonce, gas and fees) and the whole mutation costs exactly one `eth_sendRawTransaction`.
33
+ */
34
+ data: Hex;
35
+ /**
36
+ * How many operations of each kind went into the batch — which is how many events of each kind a
37
+ * successful transaction emits, in batch order, for cross-checking a decoded result.
38
+ */
39
+ expected: {
40
+ creates: number;
41
+ patches: number;
42
+ deletes: number;
43
+ extensions: number;
44
+ ownershipChanges: number;
45
+ };
46
+ };
47
+ /**
48
+ * Encodes a mutation batch without sending anything.
49
+ *
50
+ * This is the first step of the advanced path: it performs only local validation and encoding, so
51
+ * it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
52
+ * and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
53
+ * to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
54
+ *
55
+ * One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
56
+ * locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
57
+ * expiry encodes cleanly and the engine reverts it on-chain — see
58
+ * {@link BuildMutationOptions.currentBlock}.
59
+ *
60
+ * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
61
+ * @throws {InvalidValueError} If an attribute value does not fit the type it names.
62
+ * @throws {EmptyPatchError} If a patch has nothing to apply.
63
+ */
64
+ declare function buildMutation(client: ArkivClient, data: EntityMutationOps, options?: BuildMutationOptions): Promise<BuildMutationReturnType>;
65
+ //#endregion
66
+ //#region src/actions/advanced/getMutationResult.d.ts
67
+ /**
68
+ * A mined mutation, decoded from its receipt alone.
69
+ *
70
+ * Everything here comes out of the events the batch emitted, so no request context is needed to
71
+ * read it — a process that holds nothing but the transaction hash gets the full picture. Arrays
72
+ * are in batch order, which is the order the operations were applied in.
73
+ */
74
+ type MutationResult = {
75
+ /** `success` means the whole batch applied; `reverted` means none of it did (arrays are empty). */
76
+ status: "success" | "reverted";
77
+ /** The transaction hash. */
78
+ txHash: Hash;
79
+ /** The block the transaction landed in. */
80
+ blockNumber: bigint;
81
+ /** The keys the engine minted for the created entities, in batch order. */
82
+ createdEntities: Hex[];
83
+ /** The block each created entity expires at, as the engine recorded it, in the same order. */
84
+ createdExpiries: bigint[];
85
+ /** The keys of the patched entities. */
86
+ patchedEntities: Hex[];
87
+ /** The keys of the deleted entities. */
88
+ deletedEntities: Hex[];
89
+ /** The keys of the extended entities. */
90
+ extendedEntities: Hex[];
91
+ /** The block each extended entity now expires at, in the same order. */
92
+ extendedExpiries: bigint[];
93
+ /** The keys of the entities handed to a new owner. */
94
+ ownershipChanges: Hex[];
95
+ /** The raw receipt, so nothing the chain said is lost. */
96
+ receipt: TransactionReceipt;
97
+ };
98
+ /** Return type for {@link getMutationResult}: the decoded result, or still pending. */
99
+ type GetMutationResultReturnType = MutationResult | {
100
+ status: "pending";
101
+ };
102
+ /**
103
+ * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
104
+ *
105
+ * The pure tail of the advanced path: if a receipt reached you some other way — your own
106
+ * `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
107
+ * expiries without touching the network. Lenient by design: it reports what the events say,
108
+ * without counting them against a request it never saw.
109
+ */
110
+ declare function decodeMutationResult(receipt: TransactionReceipt): MutationResult;
111
+ /**
112
+ * Fetches a transaction's receipt — once — and decodes what the mutation did.
113
+ *
114
+ * Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
115
+ * decoded entity events as well: created keys, recorded expiries, and the keys of everything
116
+ * patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
117
+ * `{ status: "pending" }` — check `status` before reading the rest.
118
+ *
119
+ * No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
120
+ * spending a `simulateContract` on the why is your call, not the SDK's.
121
+ */
122
+ declare function getMutationResult(client: ArkivClient, txHash: Hash): Promise<GetMutationResultReturnType>;
123
+ //#endregion
124
+ //#region src/actions/advanced/pingTransaction.d.ts
125
+ /** Return type for {@link pingTransaction}. */
126
+ type PingTransactionReturnType = {
127
+ /** Not mined yet (or unknown to this node). Ping again later. */
128
+ status: "pending";
129
+ blockNumber?: undefined;
130
+ } | {
131
+ /** Mined. `success` means the whole batch applied; `reverted` means none of it did. */
132
+ status: "success" | "reverted";
133
+ /** The block the transaction landed in. */
134
+ blockNumber: bigint;
135
+ };
136
+ /**
137
+ * Asks the chain — once — whether a transaction has landed.
138
+ *
139
+ * Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
140
+ * back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
141
+ * path — you own the schedule, the SDK owns nothing.
142
+ *
143
+ * When it reports `success` and you need the created keys or recorded expiries, spend the next
144
+ * call on `getMutationResult` — or none at all, if you predicted the keys up front with
145
+ * `predictEntityKeys`.
146
+ */
147
+ declare function pingTransaction(client: ArkivClient, txHash: Hash): Promise<PingTransactionReturnType>;
148
+ //#endregion
149
+ //#region src/actions/advanced/sendMutation.d.ts
150
+ /** Options for {@link sendMutation}. */
151
+ type SendMutationOptions = BuildMutationOptions & {
152
+ /**
153
+ * Transaction parameters. Supply `nonce`, `gas` and the fee fields and viem has nothing left to
154
+ * look up — the send collapses to a single `eth_sendRawTransaction`.
155
+ */
156
+ txParams?: TxParams;
157
+ };
158
+ /** Return type for {@link sendMutation}. */
159
+ type SendMutationReturnType = {
160
+ /** The transaction hash. Poll it with `pingTransaction` / fetch it with `getMutationResult`. */
161
+ txHash: Hash;
162
+ /** The per-kind operation counts of the batch that was sent, for cross-checking the result. */
163
+ expected: BuildMutationReturnType["expected"];
164
+ };
165
+ /**
166
+ * Signs and sends a mutation batch, returning as soon as the transaction is submitted.
167
+ *
168
+ * The fire-and-forget half of the advanced path. Unlike `executeBatch`, this does **not** wait
169
+ * for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
170
+ * costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
171
+ * RPC call; each omitted piece adds only the lookup viem needs to fill it.
172
+ *
173
+ * Follow up separately, on your own schedule:
174
+ * - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
175
+ * - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
176
+ *
177
+ * @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
178
+ * the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
179
+ * Anything after that — inclusion, success — is yours to check.
180
+ */
181
+ declare function sendMutation(client: ArkivClient, data: EntityMutationOps, options?: SendMutationOptions): Promise<SendMutationReturnType>;
182
+ //#endregion
183
+ 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 };
184
+ //# sourceMappingURL=index-CTDI5pXZ.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index-CTDI5pXZ.d.ts","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"}
@@ -0,0 +1,184 @@
1
+ import { j as ArkivClient } from "./selection-C6KeWJ7g.cjs";
2
+ import { m as Operation } from "./index-DZxwz2Ky.cjs";
3
+ import { c as TxParams, t as EntityMutationOps } from "./arkivTransactions-BpARZOsH.cjs";
4
+ import { Address, Hash, Hex, TransactionReceipt } from "viem";
5
+
6
+ //#region src/actions/advanced/buildMutation.d.ts
7
+ /** Options for the advanced-path builders ({@link buildMutation}, {@link sendMutation}). */
8
+ type BuildMutationOptions = {
9
+ /**
10
+ * The chain head to resolve relative expiries against.
11
+ *
12
+ * Pass a block number you already hold — from a previous call, `getBlockTiming()`, or your own
13
+ * tracking — and the build spends no RPC call at all. Without it, one `eth_blockNumber` is made,
14
+ * and only when the batch actually needs the head (a relative lifetime or a `Date` deadline);
15
+ * purely absolute `atBlock(n)` expiries never trigger it.
16
+ *
17
+ * Supplying it also buys back a check: absolute expiries are validated against it, so an
18
+ * `atBlock(n)` already in the past throws {@link InvalidExpiryError} locally instead of
19
+ * reverting on-chain. When the head is neither supplied nor fetched, that dead-on-arrival
20
+ * check is skipped — the one local validation of the everyday path this path trades away.
21
+ */
22
+ currentBlock?: bigint;
23
+ };
24
+ /** What {@link buildMutation} hands back: the batch in every form a sender might want. */
25
+ type BuildMutationReturnType = {
26
+ /** The encoded batch, in engine order, for `writeContract`-style sends. */
27
+ operations: Operation[];
28
+ /** The Arkiv engine address the transaction must be sent to. */
29
+ to: Address;
30
+ /**
31
+ * The full `execute(operations)` calldata. Sign a transaction carrying it offline (with your own
32
+ * nonce, gas and fees) and the whole mutation costs exactly one `eth_sendRawTransaction`.
33
+ */
34
+ data: Hex;
35
+ /**
36
+ * How many operations of each kind went into the batch — which is how many events of each kind a
37
+ * successful transaction emits, in batch order, for cross-checking a decoded result.
38
+ */
39
+ expected: {
40
+ creates: number;
41
+ patches: number;
42
+ deletes: number;
43
+ extensions: number;
44
+ ownershipChanges: number;
45
+ };
46
+ };
47
+ /**
48
+ * Encodes a mutation batch without sending anything.
49
+ *
50
+ * This is the first step of the advanced path: it performs only local validation and encoding, so
51
+ * it costs **zero RPC calls** when `options.currentBlock` is provided (or no expiry is relative),
52
+ * and at most one `eth_blockNumber` otherwise. Send the result however you like: pass `operations`
53
+ * to `writeContract`, or sign `{ to, data }` offline and push it with `eth_sendRawTransaction`.
54
+ *
55
+ * One check rides on knowing the head: an absolute `atBlock(n)` already in the past is rejected
56
+ * locally only when the head is supplied or was fetched anyway. With neither, a dead-on-arrival
57
+ * expiry encodes cleanly and the engine reverts it on-chain — see
58
+ * {@link BuildMutationOptions.currentBlock}.
59
+ *
60
+ * @throws {InvalidExpiryError} If an expiry exceeds a protocol bound.
61
+ * @throws {InvalidValueError} If an attribute value does not fit the type it names.
62
+ * @throws {EmptyPatchError} If a patch has nothing to apply.
63
+ */
64
+ declare function buildMutation(client: ArkivClient, data: EntityMutationOps, options?: BuildMutationOptions): Promise<BuildMutationReturnType>;
65
+ //#endregion
66
+ //#region src/actions/advanced/getMutationResult.d.ts
67
+ /**
68
+ * A mined mutation, decoded from its receipt alone.
69
+ *
70
+ * Everything here comes out of the events the batch emitted, so no request context is needed to
71
+ * read it — a process that holds nothing but the transaction hash gets the full picture. Arrays
72
+ * are in batch order, which is the order the operations were applied in.
73
+ */
74
+ type MutationResult = {
75
+ /** `success` means the whole batch applied; `reverted` means none of it did (arrays are empty). */
76
+ status: "success" | "reverted";
77
+ /** The transaction hash. */
78
+ txHash: Hash;
79
+ /** The block the transaction landed in. */
80
+ blockNumber: bigint;
81
+ /** The keys the engine minted for the created entities, in batch order. */
82
+ createdEntities: Hex[];
83
+ /** The block each created entity expires at, as the engine recorded it, in the same order. */
84
+ createdExpiries: bigint[];
85
+ /** The keys of the patched entities. */
86
+ patchedEntities: Hex[];
87
+ /** The keys of the deleted entities. */
88
+ deletedEntities: Hex[];
89
+ /** The keys of the extended entities. */
90
+ extendedEntities: Hex[];
91
+ /** The block each extended entity now expires at, in the same order. */
92
+ extendedExpiries: bigint[];
93
+ /** The keys of the entities handed to a new owner. */
94
+ ownershipChanges: Hex[];
95
+ /** The raw receipt, so nothing the chain said is lost. */
96
+ receipt: TransactionReceipt;
97
+ };
98
+ /** Return type for {@link getMutationResult}: the decoded result, or still pending. */
99
+ type GetMutationResultReturnType = MutationResult | {
100
+ status: "pending";
101
+ };
102
+ /**
103
+ * Decodes a receipt you already hold into a {@link MutationResult}. **Zero RPC calls.**
104
+ *
105
+ * The pure tail of the advanced path: if a receipt reached you some other way — your own
106
+ * `waitForTransactionReceipt`, a webhook, a block watcher — this turns it into entity keys and
107
+ * expiries without touching the network. Lenient by design: it reports what the events say,
108
+ * without counting them against a request it never saw.
109
+ */
110
+ declare function decodeMutationResult(receipt: TransactionReceipt): MutationResult;
111
+ /**
112
+ * Fetches a transaction's receipt — once — and decodes what the mutation did.
113
+ *
114
+ * Exactly one `eth_getTransactionReceipt`, like `pingTransaction`, but the answer carries the
115
+ * decoded entity events as well: created keys, recorded expiries, and the keys of everything
116
+ * patched, deleted, extended or handed over. A transaction that is not mined yet comes back as
117
+ * `{ status: "pending" }` — check `status` before reading the rest.
118
+ *
119
+ * No revert diagnosis is run: a `reverted` result reports the fact and the raw receipt, and
120
+ * spending a `simulateContract` on the why is your call, not the SDK's.
121
+ */
122
+ declare function getMutationResult(client: ArkivClient, txHash: Hash): Promise<GetMutationResultReturnType>;
123
+ //#endregion
124
+ //#region src/actions/advanced/pingTransaction.d.ts
125
+ /** Return type for {@link pingTransaction}. */
126
+ type PingTransactionReturnType = {
127
+ /** Not mined yet (or unknown to this node). Ping again later. */
128
+ status: "pending";
129
+ blockNumber?: undefined;
130
+ } | {
131
+ /** Mined. `success` means the whole batch applied; `reverted` means none of it did. */
132
+ status: "success" | "reverted";
133
+ /** The block the transaction landed in. */
134
+ blockNumber: bigint;
135
+ };
136
+ /**
137
+ * Asks the chain — once — whether a transaction has landed.
138
+ *
139
+ * Exactly one `eth_getTransactionReceipt`, never a poll: a transaction that is not mined yet comes
140
+ * back as `{ status: "pending" }` rather than being waited on. This is the "ping" of the advanced
141
+ * path — you own the schedule, the SDK owns nothing.
142
+ *
143
+ * When it reports `success` and you need the created keys or recorded expiries, spend the next
144
+ * call on `getMutationResult` — or none at all, if you predicted the keys up front with
145
+ * `predictEntityKeys`.
146
+ */
147
+ declare function pingTransaction(client: ArkivClient, txHash: Hash): Promise<PingTransactionReturnType>;
148
+ //#endregion
149
+ //#region src/actions/advanced/sendMutation.d.ts
150
+ /** Options for {@link sendMutation}. */
151
+ type SendMutationOptions = BuildMutationOptions & {
152
+ /**
153
+ * Transaction parameters. Supply `nonce`, `gas` and the fee fields and viem has nothing left to
154
+ * look up — the send collapses to a single `eth_sendRawTransaction`.
155
+ */
156
+ txParams?: TxParams;
157
+ };
158
+ /** Return type for {@link sendMutation}. */
159
+ type SendMutationReturnType = {
160
+ /** The transaction hash. Poll it with `pingTransaction` / fetch it with `getMutationResult`. */
161
+ txHash: Hash;
162
+ /** The per-kind operation counts of the batch that was sent, for cross-checking the result. */
163
+ expected: BuildMutationReturnType["expected"];
164
+ };
165
+ /**
166
+ * Signs and sends a mutation batch, returning as soon as the transaction is submitted.
167
+ *
168
+ * The fire-and-forget half of the advanced path. Unlike `executeBatch`, this does **not** wait
169
+ * for a receipt, does not poll, and runs no revert diagnosis — it spends only what submitting
170
+ * costs. With `options.currentBlock` and full `txParams` (nonce, gas, fees) that is exactly one
171
+ * RPC call; each omitted piece adds only the lookup viem needs to fill it.
172
+ *
173
+ * Follow up separately, on your own schedule:
174
+ * - `pingTransaction(txHash)` — one `eth_getTransactionReceipt`, tells you pending/success/reverted.
175
+ * - `getMutationResult(txHash)` — the same single call, plus the decoded entity keys and expiries.
176
+ *
177
+ * @throws {EntityMutationError} If the node rejects the submission (the batch never made it into
178
+ * the mempool) — in engine terms when the rejection decodes, with the node's message otherwise.
179
+ * Anything after that — inclusion, success — is yours to check.
180
+ */
181
+ declare function sendMutation(client: ArkivClient, data: EntityMutationOps, options?: SendMutationOptions): Promise<SendMutationReturnType>;
182
+ //#endregion
183
+ 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 };
184
+ //# sourceMappingURL=index-CekGjkRx.d.cts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index-CekGjkRx.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"}