@effect-blockchain/evm 0.2.0 → 0.4.0

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 (44) hide show
  1. package/README.md +79 -1
  2. package/dist/EvmFeeHistory.d.ts +26 -0
  3. package/dist/EvmFeeHistory.d.ts.map +1 -0
  4. package/dist/EvmFeeHistory.js +25 -0
  5. package/dist/EvmFeeHistory.js.map +1 -0
  6. package/dist/EvmIndexer.d.ts +47 -9
  7. package/dist/EvmIndexer.d.ts.map +1 -1
  8. package/dist/EvmIndexer.js +95 -36
  9. package/dist/EvmIndexer.js.map +1 -1
  10. package/dist/EvmNetwork.d.ts.map +1 -1
  11. package/dist/EvmNetwork.js +8 -6
  12. package/dist/EvmNetwork.js.map +1 -1
  13. package/dist/EvmRelayer.d.ts +256 -0
  14. package/dist/EvmRelayer.d.ts.map +1 -0
  15. package/dist/EvmRelayer.js +330 -0
  16. package/dist/EvmRelayer.js.map +1 -0
  17. package/dist/EvmRpc.d.ts +88 -8
  18. package/dist/EvmRpc.d.ts.map +1 -1
  19. package/dist/EvmRpc.js +30 -9
  20. package/dist/EvmRpc.js.map +1 -1
  21. package/dist/EvmSigner.d.ts +78 -0
  22. package/dist/EvmSigner.d.ts.map +1 -0
  23. package/dist/EvmSigner.js +96 -0
  24. package/dist/EvmSigner.js.map +1 -0
  25. package/dist/EvmTransaction.d.ts +65 -0
  26. package/dist/EvmTransaction.d.ts.map +1 -0
  27. package/dist/EvmTransaction.js +60 -0
  28. package/dist/EvmTransaction.js.map +1 -0
  29. package/dist/index.d.ts +16 -0
  30. package/dist/index.d.ts.map +1 -1
  31. package/dist/index.js +16 -0
  32. package/dist/index.js.map +1 -1
  33. package/dist/internal/rpcMethods.js +57 -5
  34. package/dist/internal/rpcMethods.js.map +1 -1
  35. package/package.json +2 -2
  36. package/src/EvmFeeHistory.ts +28 -0
  37. package/src/EvmIndexer.ts +142 -49
  38. package/src/EvmNetwork.ts +8 -6
  39. package/src/EvmRelayer.ts +425 -0
  40. package/src/EvmRpc.ts +106 -9
  41. package/src/EvmSigner.ts +128 -0
  42. package/src/EvmTransaction.ts +64 -0
  43. package/src/index.ts +20 -0
  44. package/src/internal/rpcMethods.ts +67 -6
@@ -2,26 +2,29 @@ import * as JsonRpc from "@effect-blockchain/core/JsonRpc";
2
2
  import * as Schema from "effect/Schema";
3
3
  import { EvmAddress } from "../EvmAddress.js";
4
4
  import { EvmBlock } from "../EvmBlock.js";
5
+ import { EvmFeeHistory } from "../EvmFeeHistory.js";
5
6
  import { EvmHexData } from "../EvmHexData.js";
6
7
  import { EvmLog } from "../EvmLog.js";
8
+ import { EvmTransaction, EvmTransactionReceipt } from "../EvmTransaction.js";
9
+ import { EvmTransactionHash } from "../EvmTransactionHash.js";
7
10
  import { IntFromHex, QuantityFromHex } from "./QuantityFromHex.js";
8
- const make = method => method;
9
11
  const NoParams = /*#__PURE__*/Schema.Tuple([]);
10
12
  const Topics = /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.NullOr(/*#__PURE__*/Schema.Union([EvmHexData, /*#__PURE__*/Schema.Array(EvmHexData)])));
13
+ const BlockTag = /*#__PURE__*/Schema.Literals(["latest", "pending"]);
11
14
  /** @internal */
12
- export const chainId = /*#__PURE__*/make({
15
+ export const chainId = /*#__PURE__*/JsonRpc.method({
13
16
  name: "eth_chainId",
14
17
  params: NoParams,
15
18
  result: IntFromHex
16
19
  });
17
20
  /** @internal */
18
- export const blockNumber = /*#__PURE__*/make({
21
+ export const blockNumber = /*#__PURE__*/JsonRpc.method({
19
22
  name: "eth_blockNumber",
20
23
  params: NoParams,
21
24
  result: QuantityFromHex
22
25
  });
23
26
  /** @internal */
24
- export const getBlockByNumber = /*#__PURE__*/make({
27
+ export const getBlockByNumber = /*#__PURE__*/JsonRpc.method({
25
28
  name: "eth_getBlockByNumber",
26
29
  // `false`: transaction hashes only, never the full transactions
27
30
  params: /*#__PURE__*/Schema.Tuple([QuantityFromHex, /*#__PURE__*/Schema.Literal(false)]),
@@ -29,7 +32,13 @@ export const getBlockByNumber = /*#__PURE__*/make({
29
32
  result: /*#__PURE__*/Schema.NullOr(EvmBlock)
30
33
  });
31
34
  /** @internal */
32
- export const getLogs = /*#__PURE__*/make({
35
+ export const getBalance = /*#__PURE__*/JsonRpc.method({
36
+ name: "eth_getBalance",
37
+ params: /*#__PURE__*/Schema.Tuple([EvmAddress, QuantityFromHex]),
38
+ result: QuantityFromHex
39
+ });
40
+ /** @internal */
41
+ export const getLogs = /*#__PURE__*/JsonRpc.method({
33
42
  name: "eth_getLogs",
34
43
  params: /*#__PURE__*/Schema.Tuple([/*#__PURE__*/Schema.Struct({
35
44
  address: /*#__PURE__*/Schema.Array(EvmAddress),
@@ -43,4 +52,47 @@ export const getLogs = /*#__PURE__*/make({
43
52
  removed: /*#__PURE__*/Schema.optionalKey(/*#__PURE__*/Schema.Literal(false))
44
53
  }))
45
54
  });
55
+ /** @internal */
56
+ export const getTransactionByHash = /*#__PURE__*/JsonRpc.method({
57
+ name: "eth_getTransactionByHash",
58
+ params: /*#__PURE__*/Schema.Tuple([EvmTransactionHash]),
59
+ // `null` when the node does not know the transaction
60
+ result: /*#__PURE__*/Schema.NullOr(EvmTransaction)
61
+ });
62
+ /** @internal */
63
+ export const getTransactionReceipt = /*#__PURE__*/JsonRpc.method({
64
+ name: "eth_getTransactionReceipt",
65
+ params: /*#__PURE__*/Schema.Tuple([EvmTransactionHash]),
66
+ // `null` until the transaction is in a block
67
+ result: /*#__PURE__*/Schema.NullOr(EvmTransactionReceipt)
68
+ });
69
+ /** @internal */
70
+ export const sendRawTransaction = /*#__PURE__*/JsonRpc.method({
71
+ name: "eth_sendRawTransaction",
72
+ params: /*#__PURE__*/Schema.Tuple([EvmHexData]),
73
+ result: EvmTransactionHash
74
+ });
75
+ /** @internal */
76
+ export const getTransactionCount = /*#__PURE__*/JsonRpc.method({
77
+ name: "eth_getTransactionCount",
78
+ params: /*#__PURE__*/Schema.Tuple([EvmAddress, BlockTag]),
79
+ result: QuantityFromHex
80
+ });
81
+ /** @internal */
82
+ export const estimateGas = /*#__PURE__*/JsonRpc.method({
83
+ name: "eth_estimateGas",
84
+ params: /*#__PURE__*/Schema.Tuple([/*#__PURE__*/Schema.Struct({
85
+ from: EvmAddress,
86
+ to: EvmAddress,
87
+ value: /*#__PURE__*/JsonRpc.optionalOmitted(QuantityFromHex),
88
+ data: /*#__PURE__*/JsonRpc.optionalOmitted(EvmHexData)
89
+ })]),
90
+ result: QuantityFromHex
91
+ });
92
+ /** @internal */
93
+ export const feeHistory = /*#__PURE__*/JsonRpc.method({
94
+ name: "eth_feeHistory",
95
+ params: /*#__PURE__*/Schema.Tuple([IntFromHex, BlockTag, /*#__PURE__*/Schema.Array(Schema.Number)]),
96
+ result: EvmFeeHistory
97
+ });
46
98
  //# sourceMappingURL=rpcMethods.js.map
@@ -1 +1 @@
1
- {"version":3,"file":"rpcMethods.js","names":[],"sources":["../../src/internal/rpcMethods.ts"],"sourcesContent":[null],"mappings":"AAAA,OAAO,KAAK,OAAO,MAAM,iCAAiC;AAC1D,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,SAAS,UAAU,QAAQ,kBAAkB;AAC7C,SAAS,QAAQ,QAAQ,gBAAgB;AACzC,SAAS,UAAU,QAAQ,kBAAkB;AAC7C,SAAS,MAAM,QAAQ,cAAc;AACrC,SAAS,UAAU,EAAE,eAAe,QAAQ,sBAAsB;AAElE,MAAM,IAAI,GAAoB,MAAsC,IAAqC,MAAM;AAE/G,MAAM,QAAQ,gBAAG,MAAM,CAAC,KAAK,CAAC,EAAE,CAAC;AAEjC,MAAM,MAAM,gBAAG,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,MAAM,cAAC,MAAM,CAAC,KAAK,CAAC,CAAC,UAAU,eAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC,CAAC,CAAC,CAAC,CAAC;AAEhG;AACA,OAAO,MAAM,OAAO,gBAAG,IAAI,CAAC;EAAE,IAAI,EAAE,aAAa;EAAE,MAAM,EAAE,QAAQ;EAAE,MAAM,EAAE;AAAU,CAAE,CAAC;AAE1F;AACA,OAAO,MAAM,WAAW,gBAAG,IAAI,CAAC;EAAE,IAAI,EAAE,iBAAiB;EAAE,MAAM,EAAE,QAAQ;EAAE,MAAM,EAAE;AAAe,CAAE,CAAC;AAEvG;AACA,OAAO,MAAM,gBAAgB,gBAAG,IAAI,CAAC;EACnC,IAAI,EAAE,sBAAsB;EAC5B;EACA,MAAM,eAAE,MAAM,CAAC,KAAK,CAAC,CAAC,eAAe,eAAE,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC,CAAC,CAAC;EAC9D;EACA,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC,QAAQ;CAC/B,CAAC;AAEF;AACA,OAAO,MAAM,OAAO,gBAAG,IAAI,CAAC;EAC1B,IAAI,EAAE,aAAa;EACnB,MAAM,eAAE,MAAM,CAAC,KAAK,CAAC,cACnB,MAAM,CAAC,MAAM,CAAC;IACZ,OAAO,eAAE,MAAM,CAAC,KAAK,CAAC,UAAU,CAAC;IACjC,SAAS,EAAE,eAAe;IAC1B,OAAO,EAAE,eAAe;IACxB,MAAM,eAAE,OAAO,CAAC,eAAe,CAAC,MAAM;GACvC,CAAC,CACH,CAAC;EACF;EACA,MAAM,eAAE,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,MAAM,CAAC;IAAE,GAAG,MAAM,CAAC,MAAM;IAAE,OAAO,eAAE,MAAM,CAAC,WAAW,cAAC,MAAM,CAAC,OAAO,CAAC,KAAK,CAAC;EAAC,CAAE,CAAC;CAC7G,CAAC","ignoreList":[]}
1
+ {"version":3,"file":"rpcMethods.js","names":[],"sources":["../../src/internal/rpcMethods.ts"],"sourcesContent":[null],"mappings":"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","ignoreList":[]}
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "@effect-blockchain/evm",
3
- "version": "0.2.0",
3
+ "version": "0.4.0",
4
4
  "description": "EVM blockchain toolkit for Effect",
5
5
  "keywords": [
6
6
  "typescript",
@@ -38,7 +38,7 @@
38
38
  "dist/**/*.d.ts.map"
39
39
  ],
40
40
  "dependencies": {
41
- "@effect-blockchain/core": "^0.1.0"
41
+ "@effect-blockchain/core": "0.2.0"
42
42
  },
43
43
  "devDependencies": {
44
44
  "@effect/vitest": "4.1.0",
@@ -0,0 +1,28 @@
1
+ /**
2
+ * EVM fee history, as returned by `eth_feeHistory`.
3
+ *
4
+ * @since 0.3.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+ import { QuantityFromHex } from "./internal/QuantityFromHex.ts"
8
+
9
+ /**
10
+ * The fees of a range of blocks starting at `oldestBlock`, in wei per gas. `baseFeePerGas` has one more entry than
11
+ * the range: the base fee of the block after it. `reward` holds, per block, the priority fee at each requested
12
+ * percentile, and is absent when none was requested.
13
+ *
14
+ * @since 0.3.0
15
+ * @category schemas
16
+ */
17
+ export const EvmFeeHistory = Schema.Struct({
18
+ oldestBlock: QuantityFromHex,
19
+ baseFeePerGas: Schema.NonEmptyArray(QuantityFromHex),
20
+ gasUsedRatio: Schema.Array(Schema.Number),
21
+ reward: Schema.optionalKey(Schema.Array(Schema.Array(QuantityFromHex)))
22
+ }).annotate({ identifier: "EvmFeeHistory", title: "EVM fee history" })
23
+
24
+ /**
25
+ * @since 0.3.0
26
+ * @category models
27
+ */
28
+ export type EvmFeeHistory = typeof EvmFeeHistory.Type
package/src/EvmIndexer.ts CHANGED
@@ -1,45 +1,59 @@
1
1
  /**
2
- * EVM log indexing on top of {@link EvmRpc.EvmRpc}: the last confirmed block, the logs of a set of contracts over a
3
- * block range, and a stream of them following the confirmed head.
2
+ * Reads the logs of a set of contracts and the native balance of an address over confirmed blocks, on top of
3
+ * {@link EvmRpc.EvmRpc}, once or as a stream following the confirmed head. The stream options are described in
4
+ * [Concepts](https://github.com/spiko-tech/effect-blockchain/blob/main/docs/concepts.md#indexer-streams).
4
5
  *
5
- * A range is split into ranges of at most `maxBlockRange` blocks, one `eth_getLogs` after another. A failing range
6
- * fails the whole call and drops the logs already read: the caller retries the same range.
6
+ * A log range is split into ranges of at most `maxBlockRange` blocks, with one `eth_getLogs` each. A failing range
7
+ * fails the whole call, and the caller retries the same range.
7
8
  *
8
9
  * @example
9
10
  * ```ts
10
- * import type { EvmIndexerFilter } from "@effect-blockchain/evm/EvmIndexer"
11
- * import { EvmIndexer } from "@effect-blockchain/evm/EvmIndexer"
11
+ * import * as EvmIndexer from "@effect-blockchain/evm/EvmIndexer"
12
+ * import * as EvmRpc from "@effect-blockchain/evm/EvmRpc"
13
+ * import * as Config from "effect/Config"
12
14
  * import * as Effect from "effect/Effect"
13
- * import * as Schedule from "effect/Schedule"
15
+ * import * as FetchHttpClient from "effect/http/FetchHttpClient"
16
+ * import * as Layer from "effect/Layer"
14
17
  * import * as Stream from "effect/Stream"
15
18
  *
16
- * declare const filter: Omit<EvmIndexerFilter, "fromBlock" | "toBlock">
19
+ * declare const filter: Omit<EvmIndexer.EvmIndexerFilter, "fromBlock" | "toBlock">
17
20
  * declare const cursor: bigint
18
21
  * declare const save: (block: bigint) => Effect.Effect<void>
19
22
  *
20
23
  * const program = Effect.gen(function*() {
21
- * const indexer = yield* EvmIndexer
22
- * // once caught up, read the head after 1 s, 2 s, 4 s... at most every minute
23
- * const poll = Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("1 minute")])
24
- * yield* indexer.streamLogs({ filter, fromBlock: cursor + BigInt(1), poll }).pipe(
24
+ * const rpc = yield* EvmRpc.EvmRpc
25
+ * const indexer = yield* EvmIndexer.EvmIndexer
26
+ * yield* Effect.log(`head: ${yield* rpc.blockNumber}`)
27
+ * yield* indexer.streamLogs({ filter, fromBlock: cursor + BigInt(1) }).pipe(
25
28
  * Stream.runForEach((batch) => save(batch.toBlock))
26
29
  * )
27
30
  * })
31
+ *
32
+ * const RpcLive = EvmRpc.layerConfig({
33
+ * network: Config.succeed("Ethereum"),
34
+ * endpoints: Config.all([Config.all({ name: Config.succeed("main"), url: Config.Redacted("ETHEREUM_RPC_URL") })])
35
+ * })
36
+ *
37
+ * const main = program.pipe(
38
+ * Effect.provide(EvmIndexer.layer().pipe(Layer.provideMerge(RpcLive), Layer.provide(FetchHttpClient.layer)))
39
+ * )
28
40
  * ```
29
41
  *
30
42
  * @since 0.1.0
31
43
  */
44
+ import * as Confirmations from "@effect-blockchain/core/Confirmations"
32
45
  import * as JsonRpc from "@effect-blockchain/core/JsonRpc"
33
46
  import * as Arr from "effect/Array"
34
47
  import * as BigInt_ from "effect/BigInt"
35
48
  import * as Config from "effect/Config"
36
49
  import * as Context from "effect/Context"
37
- import * as Duration from "effect/Duration"
50
+ import type * as Duration from "effect/Duration"
38
51
  import * as Effect from "effect/Effect"
39
52
  import * as Layer from "effect/Layer"
40
53
  import * as Option from "effect/Option"
41
54
  import * as Schedule from "effect/Schedule"
42
55
  import * as Stream from "effect/Stream"
56
+ import type { EvmAddress } from "./EvmAddress.ts"
43
57
  import type { EvmLog } from "./EvmLog.ts"
44
58
  import * as EvmNetwork from "./EvmNetwork.ts"
45
59
  import * as EvmRpc from "./EvmRpc.ts"
@@ -70,7 +84,8 @@ export interface EvmIndexerBatch {
70
84
  }
71
85
 
72
86
  /**
73
- * The {@link EvmIndexer.Service.streamLogs} options.
87
+ * The {@link EvmIndexer.Service.streamLogs} options. `toBlock`, `poll` and `retry` are described in
88
+ * [Concepts](https://github.com/spiko-tech/effect-blockchain/blob/main/docs/concepts.md#indexer-streams).
74
89
  *
75
90
  * @since 0.1.0
76
91
  * @category models
@@ -78,14 +93,36 @@ export interface EvmIndexerBatch {
78
93
  export interface EvmIndexerStreamOptions {
79
94
  readonly filter: Omit<EvmIndexerFilter, "fromBlock" | "toBlock">
80
95
  readonly fromBlock: bigint
81
- /** The stream ends after the batch reaching it, and is empty when `fromBlock > toBlock`. */
82
96
  readonly toBlock?: bigint | undefined
83
- /**
84
- * When to read the head again once caught up, `Schedule.spaced(DEFAULT_POLL_INTERVAL)` by default. It restarts after
85
- * each batch, and its end ends the stream: `Schedule.recurs(0)` drains to the head and stops.
86
- */
87
97
  readonly poll?: Schedule.Schedule<unknown> | undefined
88
- /** Retries a step failing with a transient reason ({@link JsonRpc.isTransient}) at the same block. Off by default. */
98
+ readonly retry?: Schedule.Schedule<unknown, EvmRpc.EvmRpcError> | undefined
99
+ }
100
+
101
+ /**
102
+ * The native balance of an address in wei at the end of `block`, emitted by
103
+ * {@link EvmIndexer.Service.streamNativeBalance}.
104
+ *
105
+ * @since 0.3.0
106
+ * @category models
107
+ */
108
+ export interface EvmNativeBalance {
109
+ readonly block: bigint
110
+ readonly balance: bigint
111
+ }
112
+
113
+ /**
114
+ * The {@link EvmIndexer.Service.streamNativeBalance} options: one sample at `fromBlock`, then every `step` blocks.
115
+ * `step` is a positive safe integer, `poll` and `retry` work as in {@link EvmIndexerStreamOptions}.
116
+ *
117
+ * @since 0.3.0
118
+ * @category models
119
+ */
120
+ export interface EvmIndexerNativeBalanceOptions {
121
+ readonly address: EvmAddress
122
+ readonly fromBlock: bigint
123
+ readonly toBlock?: bigint | undefined
124
+ readonly step: number
125
+ readonly poll?: Schedule.Schedule<unknown> | undefined
89
126
  readonly retry?: Schedule.Schedule<unknown, EvmRpc.EvmRpcError> | undefined
90
127
  }
91
128
 
@@ -106,6 +143,24 @@ export class EvmIndexer extends Context.Service<EvmIndexer, {
106
143
  * the confirmed head.
107
144
  */
108
145
  readonly streamLogs: (options: EvmIndexerStreamOptions) => Stream.Stream<EvmIndexerBatch, EvmRpc.EvmRpcError>
146
+ /**
147
+ * The native balance of `address` in wei at the end of `block`, which needs an archive endpoint for an old block.
148
+ *
149
+ * @since 0.3.0
150
+ */
151
+ readonly fetchNativeBalance: (options: {
152
+ readonly address: EvmAddress
153
+ readonly block: bigint
154
+ }) => Effect.Effect<bigint, EvmRpc.EvmRpcError>
155
+ /**
156
+ * The native balance of `address` at `fromBlock`, `fromBlock + step`, ... (a sample at every step, changed or not),
157
+ * each read once its block is confirmed, following the confirmed head.
158
+ *
159
+ * @since 0.3.0
160
+ */
161
+ readonly streamNativeBalance: (
162
+ options: EvmIndexerNativeBalanceOptions
163
+ ) => Stream.Stream<EvmNativeBalance, EvmRpc.EvmRpcError>
109
164
  }>()("@effect-blockchain/evm/EvmIndexer") {}
110
165
 
111
166
  /**
@@ -122,7 +177,7 @@ export const DEFAULT_MAX_BLOCK_RANGE = 1000
122
177
  * @since 0.1.0
123
178
  * @category constants
124
179
  */
125
- export const DEFAULT_POLL_INTERVAL: Duration.Duration = Duration.seconds(10)
180
+ export const DEFAULT_POLL_INTERVAL: Duration.Duration = Confirmations.DEFAULT_POLL_INTERVAL
126
181
 
127
182
  // the confirmed blocks [next, head] not indexed yet, empty once the stream reaches the head it last read
128
183
  interface StreamPosition {
@@ -130,10 +185,12 @@ interface StreamPosition {
130
185
  readonly head: bigint
131
186
  }
132
187
 
188
+ type Page<A> = readonly [ReadonlyArray<A>, Option.Option<StreamPosition>]
189
+
133
190
  /**
134
191
  * Builds an {@link EvmIndexer} reading through the provided {@link EvmRpc.EvmRpc}.
135
192
  *
136
- * - `confirmations` overrides {@link EvmNetwork.defaultConfirmations} for the RPC's network.
193
+ * - `confirmations` overrides `EvmNetwork.defaultConfirmations` for the RPC's network.
137
194
  * - `maxBlockRange`, a positive integer, defaults to {@link DEFAULT_MAX_BLOCK_RANGE}.
138
195
  *
139
196
  * @since 0.1.0
@@ -151,12 +208,30 @@ export const layer = (options: {
151
208
  if (!Number.isSafeInteger(maxBlockRange) || maxBlockRange < 1) {
152
209
  return yield* Effect.die(new RangeError(`maxBlockRange must be a positive integer, got ${maxBlockRange}`))
153
210
  }
154
- const confirmations = BigInt(options.confirmations ?? EvmNetwork.defaultConfirmations(rpc.network))
155
211
  const size = BigInt(maxBlockRange)
212
+ const confirmations = options.confirmations ?? EvmNetwork.defaultConfirmations(rpc.network)
156
213
  const lastConfirmedBlock = rpc.blockNumber.pipe(
157
- Effect.map((head) => BigInt_.max(head - confirmations, BigInt(0))),
214
+ Effect.map((head) => Confirmations.lastConfirmedBlock(head, confirmations)),
158
215
  Effect.withSpan("EvmIndexer.lastConfirmedBlock")
159
216
  )
217
+ // the head last read is reused while it covers `next` (the confirmed head only moves forward), else polled
218
+ const confirmedHead = (poll: Schedule.Schedule<unknown>, { head, next }: StreamPosition) =>
219
+ next <= head
220
+ ? Effect.succeed(head)
221
+ : lastConfirmedBlock.pipe(Effect.repeat({ schedule: poll, until: (confirmed) => confirmed >= next }))
222
+ const paginate = <A>(
223
+ start: bigint,
224
+ retry: Schedule.Schedule<unknown, EvmRpc.EvmRpcError> | undefined,
225
+ step: (position: StreamPosition) => Effect.Effect<Page<A>, EvmRpc.EvmRpcError>
226
+ ) =>
227
+ Stream.paginate(
228
+ // a head below `start`: the first step reads it
229
+ { next: start, head: start - BigInt(1) },
230
+ retry === undefined
231
+ ? step
232
+ : (position) =>
233
+ Effect.retry(step(position), { schedule: retry, while: (error) => JsonRpc.isTransient(error.reason) })
234
+ )
160
235
  const fetchLogs = Effect.fn("EvmIndexer.fetchLogs")((filter: EvmIndexerFilter) => {
161
236
  if (filter.fromBlock > filter.toBlock) return Effect.succeed([])
162
237
  const count = Number((filter.toBlock - filter.fromBlock) / size) + 1
@@ -166,38 +241,56 @@ export const layer = (options: {
166
241
  rpc.getLogs({ ...filter, fromBlock, toBlock: BigInt_.min(fromBlock + size - BigInt(1), filter.toBlock) })
167
242
  ).pipe(Effect.map(Arr.flatten))
168
243
  })
244
+ const fetchNativeBalance = Effect.fn("EvmIndexer.fetchNativeBalance")(
245
+ ({ address, block }: { readonly address: EvmAddress; readonly block: bigint }) =>
246
+ rpc.getBalance({ address, blockNumber: block })
247
+ )
169
248
  return EvmIndexer.of({
170
249
  lastConfirmedBlock,
171
250
  fetchLogs,
172
251
  streamLogs: ({ filter, fromBlock, poll = Schedule.spaced(DEFAULT_POLL_INTERVAL), retry, toBlock }) => {
173
252
  if (toBlock !== undefined && fromBlock > toBlock) return Stream.empty
174
- // the head last read is reused while it covers `next` (the confirmed head only moves forward), else polled
175
- const step = (
176
- { head, next }: StreamPosition
177
- ): Effect.Effect<
178
- readonly [ReadonlyArray<EvmIndexerBatch>, Option.Option<StreamPosition>],
179
- EvmRpc.EvmRpcError
180
- > =>
181
- (next <= head
182
- ? Effect.succeed(head)
183
- : lastConfirmedBlock.pipe(Effect.repeat({ schedule: poll, until: (confirmed) => confirmed >= next })))
184
- .pipe(Effect.flatMap((confirmed) => {
185
- const cap = toBlock === undefined ? confirmed : BigInt_.min(confirmed, toBlock)
186
- if (next > cap) return Effect.succeed([[], Option.none()])
187
- const end = BigInt_.min(next + size - BigInt(1), cap)
188
- return fetchLogs({ ...filter, fromBlock: next, toBlock: end }).pipe(Effect.map((logs) => [
253
+ return paginate(fromBlock, retry, (position) =>
254
+ confirmedHead(poll, position).pipe(Effect.flatMap((confirmed) => {
255
+ const { next } = position
256
+ const cap = toBlock === undefined ? confirmed : BigInt_.min(confirmed, toBlock)
257
+ if (next > cap) {
258
+ return Effect.succeed<Page<EvmIndexerBatch>>([[], Option.none()])
259
+ }
260
+ const end = BigInt_.min(next + size - BigInt(1), cap)
261
+ return fetchLogs({ ...filter, fromBlock: next, toBlock: end }).pipe(Effect.map((logs) =>
262
+ [
189
263
  [{ fromBlock: next, toBlock: end, logs }],
190
264
  end === toBlock ? Option.none() : Option.some({ next: end + BigInt(1), head: confirmed })
191
- ]))
192
- }))
193
- return Stream.paginate(
194
- // a head below `fromBlock`: the first step reads it
195
- { next: fromBlock, head: fromBlock - BigInt(1) },
196
- retry === undefined
197
- ? step
198
- : (remaining) =>
199
- Effect.retry(step(remaining), { schedule: retry, while: (error) => JsonRpc.isTransient(error.reason) })
200
- )
265
+ ] as const
266
+ ))
267
+ })))
268
+ },
269
+ fetchNativeBalance,
270
+ streamNativeBalance: (
271
+ { address, fromBlock, poll = Schedule.spaced(DEFAULT_POLL_INTERVAL), retry, step, toBlock }
272
+ ) => {
273
+ if (!Number.isSafeInteger(step) || step < 1) {
274
+ return Stream.die(new RangeError(`step must be a positive safe integer, got ${step}`))
275
+ }
276
+ if (toBlock !== undefined && fromBlock > toBlock) {
277
+ return Stream.empty
278
+ }
279
+ const stride = BigInt(step)
280
+ return paginate(fromBlock, retry, (position) =>
281
+ confirmedHead(poll, position).pipe(Effect.flatMap((confirmed) => {
282
+ const block = position.next
283
+ if (block > confirmed) {
284
+ return Effect.succeed<Page<EvmNativeBalance>>([[], Option.none()])
285
+ }
286
+ const next = block + stride
287
+ return fetchNativeBalance({ address, block }).pipe(Effect.map((balance) =>
288
+ [
289
+ [{ block, balance }],
290
+ toBlock !== undefined && next > toBlock ? Option.none() : Option.some({ next, head: confirmed })
291
+ ] as const
292
+ ))
293
+ })))
201
294
  }
202
295
  })
203
296
  })
package/src/EvmNetwork.ts CHANGED
@@ -134,10 +134,11 @@ export const isTestnet = (network: EvmNetwork): boolean => (testnets as Readonly
134
134
 
135
135
  // testnets reuse their mainnet value: same consensus and block time
136
136
  const confirmations: Record<EvmNetwork, number> = {
137
- // 2 epochs, Kraken credits at finalization "typically after 64-96": https://support.kraken.com/articles/203325283
137
+ // finalized after 2 epochs of 32 slots: https://ethereum.org/en/developers/docs/consensus-mechanisms/pos/#finality
138
138
  Ethereum: 64,
139
139
  Sepolia: 64,
140
- // milestones finalize in 2-5s since Heimdall v2: https://docs.polygon.technology/pos/concepts/finality/finality/
140
+ // milestones finalize a block within 2 to 5 s, 1 to 3 blocks of 2 s. 32 blocks keep a margin for a late milestone,
141
+ // when a block only has probabilistic finality: https://docs.polygon.technology/pos/concepts/finality/finality/
141
142
  Polygon: 32,
142
143
  PolygonAmoy: 32,
143
144
  // ~1 min of 2s blocks against sequencer reorgs: https://docs.optimism.io/stack/transactions/transaction-finality
@@ -149,18 +150,19 @@ const confirmations: Record<EvmNetwork, number> = {
149
150
  // confirmed on Tezos L1 in ~6s: https://docs.etherlink.com
150
151
  Etherlink: 20,
151
152
  EtherlinkTestnet: 20,
152
- // Pionex uses 27 for Optimism: https://intercom.help/pionex/en/articles/14700793-what-is-block-confirmation
153
+ // OP Stack, as Base: https://docs.optimism.io/stack/transactions/transaction-finality
153
154
  Optimism: 30,
154
155
  OptimismSepolia: 30,
155
- // Snowman finality is irreversible, Circle uses 1: https://developers.circle.com/circle-mint/blockchain-confirmations
156
+ // Snowman acceptance is final: https://build.avax.network/docs/primary-network/avalanche-consensus
156
157
  Avalanche: 1,
157
158
  AvalancheFuji: 1,
158
- // Kraken uses 50 (fast finality in 2 blocks): https://support.kraken.com/articles/203325283
159
+ // fast finality finalizes a block once its child is justified. 50 blocks keep a margin for when no block is
160
+ // justified and finality is probabilistic again: https://github.com/bnb-chain/BEPs/blob/master/BEPs/BEP126.md
159
161
  BnbSmartChain: 50,
160
162
  BnbSmartChainTestnet: 50,
161
163
  // 2 epochs of 16 slots: https://docs.gnosischain.com/about/specs/consensus/
162
164
  Gnosis: 32,
163
- // ~1 min of 2s blocks, Circle Fast Transfer uses 1: https://developers.circle.com/cctp/required-block-confirmations
165
+ // ~1 min of 2s blocks against sequencer reorgs: https://docs.linea.build/protocol/transaction-lifecycle
164
166
  Linea: 30,
165
167
  LineaSepolia: 30,
166
168
  // local node mines instantly and never reorgs: https://getfoundry.sh/anvil/overview