@effect-blockchain/evm 0.0.0-stage → 0.2.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 (58) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/dist/EvmAddress.d.ts +33 -0
  4. package/dist/EvmAddress.d.ts.map +1 -0
  5. package/dist/EvmAddress.js +43 -0
  6. package/dist/EvmAddress.js.map +1 -0
  7. package/dist/EvmBlock.d.ts +25 -0
  8. package/dist/EvmBlock.d.ts.map +1 -0
  9. package/dist/EvmBlock.js +25 -0
  10. package/dist/EvmBlock.js.map +1 -0
  11. package/dist/EvmHexData.d.ts +19 -0
  12. package/dist/EvmHexData.d.ts.map +1 -0
  13. package/dist/EvmHexData.js +31 -0
  14. package/dist/EvmHexData.js.map +1 -0
  15. package/dist/EvmIndexer.d.ts +115 -0
  16. package/dist/EvmIndexer.d.ts.map +1 -0
  17. package/dist/EvmIndexer.js +153 -0
  18. package/dist/EvmIndexer.js.map +1 -0
  19. package/dist/EvmLog.d.ts +32 -0
  20. package/dist/EvmLog.d.ts.map +1 -0
  21. package/dist/EvmLog.js +34 -0
  22. package/dist/EvmLog.js.map +1 -0
  23. package/dist/EvmNetwork.d.ts +74 -0
  24. package/dist/EvmNetwork.d.ts.map +1 -0
  25. package/dist/EvmNetwork.js +128 -0
  26. package/dist/EvmNetwork.js.map +1 -0
  27. package/dist/EvmRpc.d.ts +154 -0
  28. package/dist/EvmRpc.d.ts.map +1 -0
  29. package/dist/EvmRpc.js +174 -0
  30. package/dist/EvmRpc.js.map +1 -0
  31. package/dist/EvmTransactionHash.d.ts +19 -0
  32. package/dist/EvmTransactionHash.d.ts.map +1 -0
  33. package/dist/EvmTransactionHash.js +29 -0
  34. package/dist/EvmTransactionHash.js.map +1 -0
  35. package/dist/index.d.ts +36 -0
  36. package/dist/index.d.ts.map +1 -0
  37. package/dist/index.js +37 -0
  38. package/dist/index.js.map +1 -0
  39. package/dist/internal/QuantityFromHex.d.ts +2 -0
  40. package/dist/internal/QuantityFromHex.d.ts.map +1 -0
  41. package/dist/internal/QuantityFromHex.js +23 -0
  42. package/dist/internal/QuantityFromHex.js.map +1 -0
  43. package/dist/internal/rpcMethods.d.ts +2 -0
  44. package/dist/internal/rpcMethods.d.ts.map +1 -0
  45. package/dist/internal/rpcMethods.js +46 -0
  46. package/dist/internal/rpcMethods.js.map +1 -0
  47. package/package.json +70 -3
  48. package/src/EvmAddress.ts +53 -0
  49. package/src/EvmBlock.ts +28 -0
  50. package/src/EvmHexData.ts +39 -0
  51. package/src/EvmIndexer.ts +222 -0
  52. package/src/EvmLog.ts +37 -0
  53. package/src/EvmNetwork.ts +176 -0
  54. package/src/EvmRpc.ts +272 -0
  55. package/src/EvmTransactionHash.ts +36 -0
  56. package/src/index.ts +45 -0
  57. package/src/internal/QuantityFromHex.ts +24 -0
  58. package/src/internal/rpcMethods.ts +43 -0
package/dist/index.js ADDED
@@ -0,0 +1,37 @@
1
+ /**
2
+ * @since 0.1.0
3
+ */
4
+ // @barrel: Auto-generated exports. Do not edit manually.
5
+ /**
6
+ * @since 0.1.0
7
+ */
8
+ export * as EvmAddress from "./EvmAddress.js";
9
+ /**
10
+ * @since 0.1.0
11
+ */
12
+ export * as EvmBlock from "./EvmBlock.js";
13
+ /**
14
+ * @since 0.1.0
15
+ */
16
+ export * as EvmHexData from "./EvmHexData.js";
17
+ /**
18
+ * @since 0.1.0
19
+ */
20
+ export * as EvmIndexer from "./EvmIndexer.js";
21
+ /**
22
+ * @since 0.1.0
23
+ */
24
+ export * as EvmLog from "./EvmLog.js";
25
+ /**
26
+ * @since 0.1.0
27
+ */
28
+ export * as EvmNetwork from "./EvmNetwork.js";
29
+ /**
30
+ * @since 0.1.0
31
+ */
32
+ export * as EvmRpc from "./EvmRpc.js";
33
+ /**
34
+ * @since 0.1.0
35
+ */
36
+ export * as EvmTransactionHash from "./EvmTransactionHash.js";
37
+ //# sourceMappingURL=index.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"index.js","names":[],"sources":["../src/index.ts"],"sourcesContent":[null],"mappings":"AAAA;;;AAIA;AAEA;;;AAGA,OAAO,KAAK,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAK,QAAQ,MAAM,eAAe;AAEzC;;;AAGA,OAAO,KAAK,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAK,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAK,MAAM,MAAM,aAAa;AAErC;;;AAGA,OAAO,KAAK,UAAU,MAAM,iBAAiB;AAE7C;;;AAGA,OAAO,KAAK,MAAM,MAAM,aAAa;AAErC;;;AAGA,OAAO,KAAK,kBAAkB,MAAM,yBAAyB","ignoreList":[]}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=QuantityFromHex.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"QuantityFromHex.d.ts","sourceRoot":"","sources":["../../src/internal/QuantityFromHex.ts"],"names":[],"mappings":""}
@@ -0,0 +1,23 @@
1
+ import * as Schema from "effect/Schema";
2
+ import * as SchemaTransformation from "effect/SchemaTransformation";
3
+ const HexQuantity = /*#__PURE__*/Schema.String.check(/*#__PURE__*/Schema.isPattern(/^0x[0-9a-fA-F]+$/));
4
+ const toHex = value => `0x${value.toString(16)}`;
5
+ /**
6
+ * A JSON-RPC hex quantity (`"0x10"`) decoded to a `bigint`, e.g. a block number.
7
+ *
8
+ * @internal
9
+ */
10
+ export const QuantityFromHex = /*#__PURE__*/HexQuantity.pipe(/*#__PURE__*/Schema.decodeTo(Schema.BigInt, /*#__PURE__*/SchemaTransformation.transform({
11
+ decode: BigInt,
12
+ encode: toHex
13
+ })));
14
+ /**
15
+ * A JSON-RPC hex quantity decoded to a safe integer `number`, e.g. a chain ID or a log index.
16
+ *
17
+ * @internal
18
+ */
19
+ export const IntFromHex = /*#__PURE__*/HexQuantity.pipe(/*#__PURE__*/Schema.decodeTo(Schema.Int, /*#__PURE__*/SchemaTransformation.transform({
20
+ decode: Number,
21
+ encode: toHex
22
+ })));
23
+ //# sourceMappingURL=QuantityFromHex.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"QuantityFromHex.js","names":[],"sources":["../../src/internal/QuantityFromHex.ts"],"sourcesContent":[null],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,OAAO,KAAK,oBAAoB,MAAM,6BAA6B;AAEnE,MAAM,WAAW,gBAAG,MAAM,CAAC,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAE7E,MAAM,KAAK,GAAI,KAAsB,IAAK,KAAK,KAAK,CAAC,QAAQ,CAAC,EAAE,CAAC,EAAE;AAEnE;;;;;AAKA,OAAO,MAAM,eAAe,gBAAG,WAAW,CAAC,IAAI,cAC7C,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,eAAE,oBAAoB,CAAC,SAAS,CAAC;EAAE,MAAM,EAAE,MAAM;EAAE,MAAM,EAAE;AAAK,CAAE,CAAC,CAAC,CAClG;AAED;;;;;AAKA,OAAO,MAAM,UAAU,gBAAG,WAAW,CAAC,IAAI,cACxC,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,GAAG,eAAE,oBAAoB,CAAC,SAAS,CAAC;EAAE,MAAM,EAAE,MAAM;EAAE,MAAM,EAAE;AAAK,CAAE,CAAC,CAAC,CAC/F","ignoreList":[]}
@@ -0,0 +1,2 @@
1
+ export {};
2
+ //# sourceMappingURL=rpcMethods.d.ts.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rpcMethods.d.ts","sourceRoot":"","sources":["../../src/internal/rpcMethods.ts"],"names":[],"mappings":""}
@@ -0,0 +1,46 @@
1
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc";
2
+ import * as Schema from "effect/Schema";
3
+ import { EvmAddress } from "../EvmAddress.js";
4
+ import { EvmBlock } from "../EvmBlock.js";
5
+ import { EvmHexData } from "../EvmHexData.js";
6
+ import { EvmLog } from "../EvmLog.js";
7
+ import { IntFromHex, QuantityFromHex } from "./QuantityFromHex.js";
8
+ const make = method => method;
9
+ const NoParams = /*#__PURE__*/Schema.Tuple([]);
10
+ const Topics = /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.NullOr(/*#__PURE__*/Schema.Union([EvmHexData, /*#__PURE__*/Schema.Array(EvmHexData)])));
11
+ /** @internal */
12
+ export const chainId = /*#__PURE__*/make({
13
+ name: "eth_chainId",
14
+ params: NoParams,
15
+ result: IntFromHex
16
+ });
17
+ /** @internal */
18
+ export const blockNumber = /*#__PURE__*/make({
19
+ name: "eth_blockNumber",
20
+ params: NoParams,
21
+ result: QuantityFromHex
22
+ });
23
+ /** @internal */
24
+ export const getBlockByNumber = /*#__PURE__*/make({
25
+ name: "eth_getBlockByNumber",
26
+ // `false`: transaction hashes only, never the full transactions
27
+ params: /*#__PURE__*/Schema.Tuple([QuantityFromHex, /*#__PURE__*/Schema.Literal(false)]),
28
+ // `null` when the node does not know the block
29
+ result: /*#__PURE__*/Schema.NullOr(EvmBlock)
30
+ });
31
+ /** @internal */
32
+ export const getLogs = /*#__PURE__*/make({
33
+ name: "eth_getLogs",
34
+ params: /*#__PURE__*/Schema.Tuple([/*#__PURE__*/Schema.Struct({
35
+ address: /*#__PURE__*/Schema.Array(EvmAddress),
36
+ fromBlock: QuantityFromHex,
37
+ toBlock: QuantityFromHex,
38
+ topics: /*#__PURE__*/JsonRpc.optionalOmitted(Topics)
39
+ })]),
40
+ // a log dropped by a reorg comes back with `removed: true` and must not be returned
41
+ result: /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Struct({
42
+ ...EvmLog.fields,
43
+ removed: /*#__PURE__*/Schema.optionalKey(/*#__PURE__*/Schema.Literal(false))
44
+ }))
45
+ });
46
+ //# sourceMappingURL=rpcMethods.js.map
@@ -0,0 +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":[]}
package/package.json CHANGED
@@ -1,6 +1,73 @@
1
1
  {
2
2
  "name": "@effect-blockchain/evm",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.2.0",
4
+ "description": "EVM blockchain toolkit for Effect",
5
+ "keywords": [
6
+ "typescript",
7
+ "effect",
8
+ "blockchain",
9
+ "evm",
10
+ "ethereum",
11
+ "viem"
12
+ ],
13
+ "homepage": "https://github.com/spiko-tech/effect-blockchain",
14
+ "bugs": {
15
+ "url": "https://github.com/spiko-tech/effect-blockchain/issues"
16
+ },
17
+ "repository": {
18
+ "type": "git",
19
+ "url": "https://github.com/spiko-tech/effect-blockchain.git",
20
+ "directory": "packages/evm"
21
+ },
22
+ "license": "MIT",
23
+ "sideEffects": [],
24
+ "type": "module",
25
+ "exports": {
26
+ "./package.json": "./package.json",
27
+ ".": "./dist/index.js",
28
+ "./*": "./dist/*.js",
29
+ "./internal/*": null,
30
+ "./index": null,
31
+ "./*/index": null
32
+ },
33
+ "files": [
34
+ "src/**/*.ts",
35
+ "dist/**/*.js",
36
+ "dist/**/*.js.map",
37
+ "dist/**/*.d.ts",
38
+ "dist/**/*.d.ts.map"
39
+ ],
40
+ "dependencies": {
41
+ "@effect-blockchain/core": "^0.1.0"
42
+ },
43
+ "devDependencies": {
44
+ "@effect/vitest": "4.1.0",
45
+ "effect": "4.1.0",
46
+ "viem": "2.57.11"
47
+ },
48
+ "peerDependencies": {
49
+ "effect": "^4.0.0",
50
+ "viem": "^2.57.0"
51
+ },
52
+ "publishConfig": {
53
+ "access": "public",
54
+ "provenance": true
55
+ },
56
+ "tags": [
57
+ "typescript",
58
+ "effect",
59
+ "blockchain",
60
+ "evm",
61
+ "ethereum",
62
+ "viem"
63
+ ],
64
+ "scripts": {
65
+ "codegen": "node ../../scripts/codegen.mjs . 'src/**/index.ts'",
66
+ "build": "tsc -b tsconfig.json tsconfig.release.json && pnpm babel",
67
+ "babel": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",
68
+ "check": "tsc -b tsconfig.json",
69
+ "test": "vitest",
70
+ "coverage": "vitest --coverage",
71
+ "record-fixtures": "node --env-file-if-exists=../../.env scripts/record-fixtures.ts"
72
+ }
6
73
  }
@@ -0,0 +1,53 @@
1
+ /**
2
+ * EVM account and contract addresses.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+ import * as SchemaTransformation from "effect/SchemaTransformation"
8
+ import { getAddress, isAddress } from "viem"
9
+
10
+ const evmAddressRegex = /^0x[a-f0-9]{40}$/
11
+
12
+ /**
13
+ * An EVM address, decoded from any casing (including EIP-55 checksummed) and stored lowercase.
14
+ *
15
+ * @since 0.1.0
16
+ * @category schemas
17
+ */
18
+ export const EvmAddress = Schema.String.pipe(
19
+ Schema.decodeTo(Schema.String.check(Schema.isLowercased()), SchemaTransformation.toLowerCase()),
20
+ Schema.refine((address: string): address is `0x${string}` => isAddress(address), {
21
+ expected: "a valid EVM address",
22
+ arbitraryConstraint: { patterns: [{ source: evmAddressRegex.source, flags: "" }] }
23
+ }),
24
+ Schema.brand("EvmAddress"),
25
+ Schema.annotate({
26
+ identifier: "EvmAddress",
27
+ title: "EVM address",
28
+ description:
29
+ "a valid EVM address, starting with 0x and followed by 40 hexadecimal characters e.g. \"0xb794f5ea0ba39494ce839613fffba74279579268\""
30
+ })
31
+ )
32
+
33
+ /**
34
+ * @since 0.1.0
35
+ * @category models
36
+ */
37
+ export type EvmAddress = typeof EvmAddress.Type
38
+
39
+ /**
40
+ * The zero address `0x0000000000000000000000000000000000000000`, used as the mint source and burn target of tokens.
41
+ *
42
+ * @since 0.1.0
43
+ * @category constants
44
+ */
45
+ export const NULL_ADDRESS: EvmAddress = EvmAddress.make("0x0000000000000000000000000000000000000000")
46
+
47
+ /**
48
+ * Returns the EIP-55 mixed-case checksum form of an address, e.g. for display.
49
+ *
50
+ * @since 0.1.0
51
+ * @category conversions
52
+ */
53
+ export const toEip55 = (address: EvmAddress): string => getAddress(address)
@@ -0,0 +1,28 @@
1
+ /**
2
+ * EVM block headers, as returned by `eth_getBlockByNumber`.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+ import { EvmHexData } from "./EvmHexData.ts"
8
+ import { QuantityFromHex } from "./internal/QuantityFromHex.ts"
9
+
10
+ /**
11
+ * The header fields of a mined block, decoded from the raw JSON-RPC block with hex quantities (`"0x10"`) as `bigint`.
12
+ * Every other field is ignored. `timestamp` is in Unix seconds.
13
+ *
14
+ * @since 0.1.0
15
+ * @category schemas
16
+ */
17
+ export const EvmBlock = Schema.Struct({
18
+ number: QuantityFromHex,
19
+ hash: EvmHexData,
20
+ parentHash: EvmHexData,
21
+ timestamp: QuantityFromHex
22
+ }).annotate({ identifier: "EvmBlock", title: "EVM block" })
23
+
24
+ /**
25
+ * @since 0.1.0
26
+ * @category models
27
+ */
28
+ export type EvmBlock = typeof EvmBlock.Type
@@ -0,0 +1,39 @@
1
+ /**
2
+ * Raw EVM hex data such as calldata, return data or event payloads.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+ import * as SchemaTransformation from "effect/SchemaTransformation"
8
+ import { isHex } from "viem"
9
+
10
+ const evmHexDataRegex = /^0x(?:[a-f0-9]{2})*$/
11
+
12
+ /**
13
+ * An even-length 0x-prefixed hex string (`0x` alone is the empty payload), stored lowercase.
14
+ *
15
+ * @since 0.1.0
16
+ * @category schemas
17
+ */
18
+ export const EvmHexData = Schema.String.pipe(
19
+ Schema.decodeTo(Schema.String.check(Schema.isLowercased()), SchemaTransformation.toLowerCase()),
20
+ Schema.refine(
21
+ (value: string): value is `0x${string}` => isHex(value, { strict: true }) && value.length % 2 === 0,
22
+ {
23
+ expected: "an even-length 0x-prefixed hex string",
24
+ arbitraryConstraint: { patterns: [{ source: evmHexDataRegex.source, flags: "" }] }
25
+ }
26
+ ),
27
+ Schema.brand("EvmHexData"),
28
+ Schema.annotate({
29
+ identifier: "EvmHexData",
30
+ title: "EVM hex data",
31
+ description: "an even-length 0x-prefixed hex string e.g. \"0xa9059cbb\""
32
+ })
33
+ )
34
+
35
+ /**
36
+ * @since 0.1.0
37
+ * @category models
38
+ */
39
+ export type EvmHexData = typeof EvmHexData.Type
@@ -0,0 +1,222 @@
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.
4
+ *
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.
7
+ *
8
+ * @example
9
+ * ```ts
10
+ * import type { EvmIndexerFilter } from "@effect-blockchain/evm/EvmIndexer"
11
+ * import { EvmIndexer } from "@effect-blockchain/evm/EvmIndexer"
12
+ * import * as Effect from "effect/Effect"
13
+ * import * as Schedule from "effect/Schedule"
14
+ * import * as Stream from "effect/Stream"
15
+ *
16
+ * declare const filter: Omit<EvmIndexerFilter, "fromBlock" | "toBlock">
17
+ * declare const cursor: bigint
18
+ * declare const save: (block: bigint) => Effect.Effect<void>
19
+ *
20
+ * 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(
25
+ * Stream.runForEach((batch) => save(batch.toBlock))
26
+ * )
27
+ * })
28
+ * ```
29
+ *
30
+ * @since 0.1.0
31
+ */
32
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc"
33
+ import * as Arr from "effect/Array"
34
+ import * as BigInt_ from "effect/BigInt"
35
+ import * as Config from "effect/Config"
36
+ import * as Context from "effect/Context"
37
+ import * as Duration from "effect/Duration"
38
+ import * as Effect from "effect/Effect"
39
+ import * as Layer from "effect/Layer"
40
+ import * as Option from "effect/Option"
41
+ import * as Schedule from "effect/Schedule"
42
+ import * as Stream from "effect/Stream"
43
+ import type { EvmLog } from "./EvmLog.ts"
44
+ import * as EvmNetwork from "./EvmNetwork.ts"
45
+ import * as EvmRpc from "./EvmRpc.ts"
46
+
47
+ /**
48
+ * A {@link EvmIndexer} `fetchLogs` filter: an `eth_getLogs` filter over the inclusive block range
49
+ * `[fromBlock, toBlock]`.
50
+ *
51
+ * @since 0.1.0
52
+ * @category models
53
+ */
54
+ export type EvmIndexerFilter = EvmRpc.EvmLogsFilter
55
+
56
+ /**
57
+ * The logs of `[fromBlock, toBlock]` (both inclusive), in chain order, emitted by
58
+ * {@link EvmIndexer.Service.streamLogs}.
59
+ *
60
+ * A batch is emitted for every range, even without logs. Delivery is at-least-once: save `batch.toBlock` once the
61
+ * batch is handled and resume from `toBlock + 1`.
62
+ *
63
+ * @since 0.1.0
64
+ * @category models
65
+ */
66
+ export interface EvmIndexerBatch {
67
+ readonly fromBlock: bigint
68
+ readonly toBlock: bigint
69
+ readonly logs: ReadonlyArray<EvmLog>
70
+ }
71
+
72
+ /**
73
+ * The {@link EvmIndexer.Service.streamLogs} options.
74
+ *
75
+ * @since 0.1.0
76
+ * @category models
77
+ */
78
+ export interface EvmIndexerStreamOptions {
79
+ readonly filter: Omit<EvmIndexerFilter, "fromBlock" | "toBlock">
80
+ readonly fromBlock: bigint
81
+ /** The stream ends after the batch reaching it, and is empty when `fromBlock > toBlock`. */
82
+ 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
+ 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. */
89
+ readonly retry?: Schedule.Schedule<unknown, EvmRpc.EvmRpcError> | undefined
90
+ }
91
+
92
+ /**
93
+ * @since 0.1.0
94
+ * @category services
95
+ */
96
+ export class EvmIndexer extends Context.Service<EvmIndexer, {
97
+ /** The head block number minus the confirmations, never below 0. */
98
+ readonly lastConfirmedBlock: Effect.Effect<bigint, EvmRpc.EvmRpcError>
99
+ /**
100
+ * The logs matching `filter` between `fromBlock` and `toBlock` (both inclusive), in chain order: sorted by block
101
+ * then log index. `fromBlock > toBlock` returns `[]`. A `toBlock` above {@link lastConfirmedBlock} is accepted.
102
+ */
103
+ readonly fetchLogs: (filter: EvmIndexerFilter) => Effect.Effect<ReadonlyArray<EvmLog>, EvmRpc.EvmRpcError>
104
+ /**
105
+ * The logs matching `filter` from `fromBlock` on, in batches of at most `maxBlockRange` confirmed blocks, following
106
+ * the confirmed head.
107
+ */
108
+ readonly streamLogs: (options: EvmIndexerStreamOptions) => Stream.Stream<EvmIndexerBatch, EvmRpc.EvmRpcError>
109
+ }>()("@effect-blockchain/evm/EvmIndexer") {}
110
+
111
+ /**
112
+ * The default `maxBlockRange`: most RPC providers accept `eth_getLogs` over 1000 blocks, lower it for stricter ones.
113
+ *
114
+ * @since 0.1.0
115
+ * @category constants
116
+ */
117
+ export const DEFAULT_MAX_BLOCK_RANGE = 1000
118
+
119
+ /**
120
+ * The default `poll` spacing of {@link EvmIndexer.Service.streamLogs}: 10 seconds.
121
+ *
122
+ * @since 0.1.0
123
+ * @category constants
124
+ */
125
+ export const DEFAULT_POLL_INTERVAL: Duration.Duration = Duration.seconds(10)
126
+
127
+ // the confirmed blocks [next, head] not indexed yet, empty once the stream reaches the head it last read
128
+ interface StreamPosition {
129
+ readonly next: bigint
130
+ readonly head: bigint
131
+ }
132
+
133
+ /**
134
+ * Builds an {@link EvmIndexer} reading through the provided {@link EvmRpc.EvmRpc}.
135
+ *
136
+ * - `confirmations` overrides {@link EvmNetwork.defaultConfirmations} for the RPC's network.
137
+ * - `maxBlockRange`, a positive integer, defaults to {@link DEFAULT_MAX_BLOCK_RANGE}.
138
+ *
139
+ * @since 0.1.0
140
+ * @category layers
141
+ */
142
+ export const layer = (options: {
143
+ readonly confirmations?: number | undefined
144
+ readonly maxBlockRange?: number | undefined
145
+ } = {}): Layer.Layer<EvmIndexer, never, EvmRpc.EvmRpc> =>
146
+ Layer.effect(
147
+ EvmIndexer,
148
+ Effect.gen(function*() {
149
+ const rpc = yield* EvmRpc.EvmRpc
150
+ const maxBlockRange = options.maxBlockRange ?? DEFAULT_MAX_BLOCK_RANGE
151
+ if (!Number.isSafeInteger(maxBlockRange) || maxBlockRange < 1) {
152
+ return yield* Effect.die(new RangeError(`maxBlockRange must be a positive integer, got ${maxBlockRange}`))
153
+ }
154
+ const confirmations = BigInt(options.confirmations ?? EvmNetwork.defaultConfirmations(rpc.network))
155
+ const size = BigInt(maxBlockRange)
156
+ const lastConfirmedBlock = rpc.blockNumber.pipe(
157
+ Effect.map((head) => BigInt_.max(head - confirmations, BigInt(0))),
158
+ Effect.withSpan("EvmIndexer.lastConfirmedBlock")
159
+ )
160
+ const fetchLogs = Effect.fn("EvmIndexer.fetchLogs")((filter: EvmIndexerFilter) => {
161
+ if (filter.fromBlock > filter.toBlock) return Effect.succeed([])
162
+ const count = Number((filter.toBlock - filter.fromBlock) / size) + 1
163
+ return Effect.forEach(
164
+ Arr.makeBy(count, (i) => filter.fromBlock + BigInt(i) * size),
165
+ (fromBlock) =>
166
+ rpc.getLogs({ ...filter, fromBlock, toBlock: BigInt_.min(fromBlock + size - BigInt(1), filter.toBlock) })
167
+ ).pipe(Effect.map(Arr.flatten))
168
+ })
169
+ return EvmIndexer.of({
170
+ lastConfirmedBlock,
171
+ fetchLogs,
172
+ streamLogs: ({ filter, fromBlock, poll = Schedule.spaced(DEFAULT_POLL_INTERVAL), retry, toBlock }) => {
173
+ 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) => [
189
+ [{ fromBlock: next, toBlock: end, logs }],
190
+ 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
+ )
201
+ }
202
+ })
203
+ })
204
+ )
205
+
206
+ /**
207
+ * Builds an {@link EvmIndexer} like {@link layer}, reading the options from `Config`.
208
+ *
209
+ * @example
210
+ * ```ts
211
+ * import * as EvmIndexer from "@effect-blockchain/evm/EvmIndexer"
212
+ * import * as Config from "effect/Config"
213
+ *
214
+ * const IndexerLive = EvmIndexer.layerConfig({ confirmations: Config.Int("ETHEREUM_CONFIRMATIONS") })
215
+ * ```
216
+ *
217
+ * @since 0.1.0
218
+ * @category layers
219
+ */
220
+ export const layerConfig = (
221
+ options: Config.Wrap<NonNullable<Parameters<typeof layer>[0]>>
222
+ ): Layer.Layer<EvmIndexer, Config.ConfigError, EvmRpc.EvmRpc> => Layer.unwrap(Effect.map(Config.unwrap(options), layer))
package/src/EvmLog.ts ADDED
@@ -0,0 +1,37 @@
1
+ /**
2
+ * EVM event logs, as returned by `eth_getLogs`.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+ import { EvmAddress } from "./EvmAddress.ts"
8
+ import { EvmHexData } from "./EvmHexData.ts"
9
+ import { EvmTransactionHash } from "./EvmTransactionHash.ts"
10
+ import { IntFromHex, QuantityFromHex } from "./internal/QuantityFromHex.ts"
11
+
12
+ /**
13
+ * A log emitted by a contract in a mined block, decoded from the raw JSON-RPC log: quantities are hex strings on the
14
+ * encoded side (`"0x10"`) and `bigint` / `number` on the decoded side.
15
+ *
16
+ * A pending log (null block or transaction fields) does not decode. `logIndex` is the position of the log in its
17
+ * block (EVM log indexes are per block, not per transaction).
18
+ *
19
+ * @since 0.1.0
20
+ * @category schemas
21
+ */
22
+ export const EvmLog = Schema.Struct({
23
+ address: EvmAddress,
24
+ topics: Schema.Array(EvmHexData),
25
+ data: EvmHexData,
26
+ blockNumber: QuantityFromHex,
27
+ blockHash: EvmHexData,
28
+ transactionHash: EvmTransactionHash,
29
+ transactionIndex: IntFromHex,
30
+ logIndex: IntFromHex
31
+ }).annotate({ identifier: "EvmLog", title: "EVM log" })
32
+
33
+ /**
34
+ * @since 0.1.0
35
+ * @category models
36
+ */
37
+ export type EvmLog = typeof EvmLog.Type