@effect-blockchain/solana 0.0.0-stage → 0.1.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 (43) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/dist/SolanaAddress.d.ts +21 -0
  4. package/dist/SolanaAddress.d.ts.map +1 -0
  5. package/dist/SolanaAddress.js +33 -0
  6. package/dist/SolanaAddress.js.map +1 -0
  7. package/dist/SolanaIndexer.d.ts +156 -0
  8. package/dist/SolanaIndexer.d.ts.map +1 -0
  9. package/dist/SolanaIndexer.js +227 -0
  10. package/dist/SolanaIndexer.js.map +1 -0
  11. package/dist/SolanaNetwork.d.ts +64 -0
  12. package/dist/SolanaNetwork.d.ts.map +1 -0
  13. package/dist/SolanaNetwork.js +84 -0
  14. package/dist/SolanaNetwork.js.map +1 -0
  15. package/dist/SolanaRpc.d.ts +258 -0
  16. package/dist/SolanaRpc.d.ts.map +1 -0
  17. package/dist/SolanaRpc.js +154 -0
  18. package/dist/SolanaRpc.js.map +1 -0
  19. package/dist/SolanaTransactionHash.d.ts +14 -0
  20. package/dist/SolanaTransactionHash.d.ts.map +1 -0
  21. package/dist/SolanaTransactionHash.js +34 -0
  22. package/dist/SolanaTransactionHash.js.map +1 -0
  23. package/dist/index.d.ts +24 -0
  24. package/dist/index.d.ts.map +1 -0
  25. package/dist/index.js +25 -0
  26. package/dist/index.js.map +1 -0
  27. package/dist/internal/bigIntJson.d.ts +2 -0
  28. package/dist/internal/bigIntJson.d.ts.map +1 -0
  29. package/dist/internal/bigIntJson.js +9 -0
  30. package/dist/internal/bigIntJson.js.map +1 -0
  31. package/dist/internal/rpcMethods.d.ts +2 -0
  32. package/dist/internal/rpcMethods.d.ts.map +1 -0
  33. package/dist/internal/rpcMethods.js +105 -0
  34. package/dist/internal/rpcMethods.js.map +1 -0
  35. package/package.json +66 -3
  36. package/src/SolanaAddress.ts +40 -0
  37. package/src/SolanaIndexer.ts +376 -0
  38. package/src/SolanaNetwork.ts +105 -0
  39. package/src/SolanaRpc.ts +387 -0
  40. package/src/SolanaTransactionHash.ts +41 -0
  41. package/src/index.ts +30 -0
  42. package/src/internal/bigIntJson.ts +18 -0
  43. package/src/internal/rpcMethods.ts +143 -0
@@ -0,0 +1,105 @@
1
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc";
2
+ import * as Schema from "effect/Schema";
3
+ import * as SchemaTransformation from "effect/SchemaTransformation";
4
+ import { SolanaAddress } from "../SolanaAddress.js";
5
+ import { SolanaTransactionHash } from "../SolanaTransactionHash.js";
6
+ const make = method => method;
7
+ const RpcJson = /*#__PURE__*/Schema.Union([Schema.Null, Schema.Boolean, Schema.String, Schema.Number, Schema.BigInt, /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.suspend(() => RpcJson)), /*#__PURE__*/Schema.Record(Schema.String, /*#__PURE__*/Schema.suspend(() => RpcJson))]);
8
+ const toJson = value => {
9
+ if (typeof value === "bigint") return value.toString();
10
+ if (value === null || typeof value !== "object") return value;
11
+ if (Array.isArray(value)) return value.map(toJson);
12
+ return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, toJson(item)]));
13
+ };
14
+ // raw RPC data kept as JSON, every integer as a decimal string: exact, and storable as is
15
+ const JsonFromRpc = /*#__PURE__*/RpcJson.pipe(/*#__PURE__*/Schema.decodeTo(Schema.Json, /*#__PURE__*/SchemaTransformation.transform({
16
+ decode: toJson,
17
+ encode: json => json
18
+ })));
19
+ // a small JSON integer read as a `number`, e.g. an account index
20
+ const NumberFromBigInt = /*#__PURE__*/Schema.BigInt.pipe(/*#__PURE__*/Schema.decodeTo(Schema.Int, /*#__PURE__*/SchemaTransformation.transform({
21
+ decode: Number,
22
+ encode: BigInt
23
+ })));
24
+ const Indexes = /*#__PURE__*/Schema.Array(NumberFromBigInt);
25
+ // the `transaction` codec by encoding, checked against `SolanaEncodedTransaction` where `SolanaRpc.ts` uses it
26
+ const transactions = {
27
+ base64: /*#__PURE__*/Schema.Tuple([Schema.String, Schema.Literal("base64")]).pipe(/*#__PURE__*/Schema.decodeTo(Schema.String, /*#__PURE__*/SchemaTransformation.transform({
28
+ decode: ([data]) => data,
29
+ encode: data => [data, "base64"]
30
+ }))),
31
+ json: /*#__PURE__*/Schema.Struct({
32
+ signatures: /*#__PURE__*/Schema.Array(SolanaTransactionHash),
33
+ message: /*#__PURE__*/Schema.Struct({
34
+ accountKeys: /*#__PURE__*/Schema.Array(SolanaAddress),
35
+ header: /*#__PURE__*/Schema.Struct({
36
+ numRequiredSignatures: NumberFromBigInt,
37
+ numReadonlySignedAccounts: NumberFromBigInt,
38
+ numReadonlyUnsignedAccounts: NumberFromBigInt
39
+ }),
40
+ recentBlockhash: Schema.String,
41
+ instructions: /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Struct({
42
+ programIdIndex: NumberFromBigInt,
43
+ accounts: Indexes,
44
+ data: Schema.String
45
+ })),
46
+ // absent from legacy transactions
47
+ addressTableLookups: /*#__PURE__*/Schema.optionalKey(/*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Struct({
48
+ accountKey: SolanaAddress,
49
+ writableIndexes: Indexes,
50
+ readonlyIndexes: Indexes
51
+ })))
52
+ })
53
+ })
54
+ };
55
+ const NoParams = /*#__PURE__*/Schema.Tuple([]);
56
+ const Commitment = /*#__PURE__*/Schema.Literals(["confirmed", "finalized"]);
57
+ /** @internal */
58
+ export const getGenesisHash = /*#__PURE__*/make({
59
+ name: "getGenesisHash",
60
+ params: NoParams,
61
+ result: Schema.String
62
+ });
63
+ /** @internal */
64
+ export const getSlot = /*#__PURE__*/make({
65
+ name: "getSlot",
66
+ params: /*#__PURE__*/Schema.Tuple([/*#__PURE__*/Schema.Struct({
67
+ commitment: Commitment
68
+ })]),
69
+ result: Schema.BigInt
70
+ });
71
+ /** @internal */
72
+ export const getSignaturesForAddress = /*#__PURE__*/make({
73
+ name: "getSignaturesForAddress",
74
+ params: /*#__PURE__*/Schema.Tuple([SolanaAddress, /*#__PURE__*/Schema.Struct({
75
+ before: /*#__PURE__*/JsonRpc.optionalOmitted(SolanaTransactionHash),
76
+ until: /*#__PURE__*/JsonRpc.optionalOmitted(SolanaTransactionHash),
77
+ limit: /*#__PURE__*/JsonRpc.optionalOmitted(Schema.Int),
78
+ commitment: Commitment,
79
+ minContextSlot: /*#__PURE__*/JsonRpc.optionalOmitted(JsonRpc.BigIntFromInt)
80
+ })]),
81
+ result: /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Struct({
82
+ signature: SolanaTransactionHash,
83
+ slot: Schema.BigInt,
84
+ blockTime: /*#__PURE__*/Schema.NullOr(Schema.BigInt),
85
+ err: JsonFromRpc,
86
+ memo: /*#__PURE__*/Schema.NullOr(Schema.String)
87
+ }))
88
+ });
89
+ /** @internal */
90
+ export const getTransaction = encoding => make({
91
+ name: "getTransaction",
92
+ params: Schema.Tuple([SolanaTransactionHash, Schema.Struct({
93
+ commitment: Commitment,
94
+ encoding: Schema.Literal(encoding),
95
+ maxSupportedTransactionVersion: Schema.Literal(0)
96
+ })]),
97
+ // `null` when the endpoint does not have the transaction
98
+ result: Schema.NullOr(Schema.Struct({
99
+ slot: Schema.BigInt,
100
+ blockTime: Schema.NullOr(Schema.BigInt),
101
+ transaction: transactions[encoding],
102
+ meta: JsonFromRpc
103
+ }))
104
+ });
105
+ //# sourceMappingURL=rpcMethods.js.map
@@ -0,0 +1 @@
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,69 @@
1
1
  {
2
2
  "name": "@effect-blockchain/solana",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Solana blockchain toolkit for Effect",
5
+ "keywords": [
6
+ "typescript",
7
+ "effect",
8
+ "blockchain",
9
+ "solana"
10
+ ],
11
+ "homepage": "https://github.com/spiko-tech/effect-blockchain",
12
+ "bugs": {
13
+ "url": "https://github.com/spiko-tech/effect-blockchain/issues"
14
+ },
15
+ "repository": {
16
+ "type": "git",
17
+ "url": "https://github.com/spiko-tech/effect-blockchain.git",
18
+ "directory": "packages/solana"
19
+ },
20
+ "license": "MIT",
21
+ "sideEffects": [],
22
+ "type": "module",
23
+ "exports": {
24
+ "./package.json": "./package.json",
25
+ ".": "./dist/index.js",
26
+ "./*": "./dist/*.js",
27
+ "./internal/*": null,
28
+ "./index": null,
29
+ "./*/index": null
30
+ },
31
+ "files": [
32
+ "src/**/*.ts",
33
+ "dist/**/*.js",
34
+ "dist/**/*.js.map",
35
+ "dist/**/*.d.ts",
36
+ "dist/**/*.d.ts.map"
37
+ ],
38
+ "dependencies": {
39
+ "@effect-blockchain/core": "^0.1.0"
40
+ },
41
+ "devDependencies": {
42
+ "@effect/vitest": "4.1.0",
43
+ "@solana/kit": "^8.5.0",
44
+ "effect": "4.1.0"
45
+ },
46
+ "peerDependencies": {
47
+ "@solana/kit": "^8.5.0",
48
+ "effect": "^4.0.0"
49
+ },
50
+ "publishConfig": {
51
+ "access": "public",
52
+ "provenance": true
53
+ },
54
+ "tags": [
55
+ "typescript",
56
+ "effect",
57
+ "blockchain",
58
+ "solana"
59
+ ],
60
+ "scripts": {
61
+ "codegen": "node ../../scripts/codegen.mjs . 'src/**/index.ts'",
62
+ "build": "tsc -b tsconfig.json tsconfig.release.json && pnpm babel",
63
+ "babel": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",
64
+ "check": "tsc -b tsconfig.json",
65
+ "test": "vitest",
66
+ "coverage": "vitest --coverage",
67
+ "record-fixtures": "node --env-file-if-exists=../../.env scripts/record-fixtures.ts"
68
+ }
6
69
  }
@@ -0,0 +1,40 @@
1
+ /**
2
+ * @since 0.1.0
3
+ */
4
+ import { isAddress } from "@solana/kit"
5
+ import * as Schema from "effect/Schema"
6
+
7
+ const solanaAddressOf32BytesPattern = "^[2-9A-H][1-9A-HJ-NP-Za-km-z]{43}$"
8
+
9
+ /**
10
+ * A base58-encoded Solana address (32 bytes), validated with `@solana/kit`.
11
+ *
12
+ * @since 0.1.0
13
+ * @category schemas
14
+ */
15
+ export const SolanaAddress = Schema.String.annotate({
16
+ title: "Solana address",
17
+ description: "a valid Solana address, consisting of 32 to 44 base58 characters"
18
+ }).pipe(
19
+ Schema.check(
20
+ Schema.makeFilter((a: string) => isAddress(a) || `${a} is not a valid Solana address`, {
21
+ arbitraryConstraint: { patterns: [{ source: solanaAddressOf32BytesPattern, flags: "" }] }
22
+ })
23
+ ),
24
+ Schema.brand("SolanaAddress"),
25
+ Schema.annotate({ identifier: "SolanaAddress" })
26
+ )
27
+
28
+ /**
29
+ * @since 0.1.0
30
+ * @category models
31
+ */
32
+ export type SolanaAddress = typeof SolanaAddress.Type
33
+
34
+ /**
35
+ * The Solana System Program address.
36
+ *
37
+ * @since 0.1.0
38
+ * @category constants
39
+ */
40
+ export const SYSTEM_PROGRAM_ADDRESS: SolanaAddress = SolanaAddress.make("11111111111111111111111111111111")
@@ -0,0 +1,376 @@
1
+ /**
2
+ * Solana transaction indexing on top of {@link SolanaRpc}: the last confirmed slot, the transactions touching an
3
+ * address over a slot range, and a stream of them following the confirmed head. Blocks are slots.
4
+ *
5
+ * Everything is read at `finalized` commitment. `getSignaturesForAddress` has no slot range, so a range is paged from
6
+ * the head backwards until it passes `fromBlock`: the cost grows with the address's history since `fromBlock`, then
7
+ * each transaction costs one `getTransaction`. Each page sends `minContextSlot: toBlock`, so a lagging endpoint that
8
+ * honours it falls back. Any failure fails the whole call and nothing is returned: the caller retries the same range.
9
+ *
10
+ * @example
11
+ * ```ts
12
+ * import type { SolanaIndexerFilter } from "@effect-blockchain/solana/SolanaIndexer"
13
+ * import { SolanaIndexer } from "@effect-blockchain/solana/SolanaIndexer"
14
+ * import * as Effect from "effect/Effect"
15
+ * import * as Schedule from "effect/Schedule"
16
+ * import * as Stream from "effect/Stream"
17
+ *
18
+ * declare const filter: Omit<SolanaIndexerFilter, "fromBlock" | "toBlock">
19
+ * declare const cursor: bigint
20
+ * declare const save: (slot: bigint) => Effect.Effect<void>
21
+ *
22
+ * const program = Effect.gen(function*() {
23
+ * const indexer = yield* SolanaIndexer
24
+ * // once caught up, read the head after 1 s, 2 s, 4 s... at most every minute
25
+ * const poll = Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("1 minute")])
26
+ * yield* indexer.streamTransactions({ filter, fromBlock: cursor + BigInt(1), poll }).pipe(
27
+ * Stream.runForEach((batch) => save(batch.toBlock))
28
+ * )
29
+ * })
30
+ * ```
31
+ *
32
+ * @since 0.1.0
33
+ */
34
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc"
35
+ import * as Arr from "effect/Array"
36
+ import * as BigInt_ from "effect/BigInt"
37
+ import * as Config from "effect/Config"
38
+ import * as Context from "effect/Context"
39
+ import * as Duration from "effect/Duration"
40
+ import * as Effect from "effect/Effect"
41
+ import * as Layer from "effect/Layer"
42
+ import * as Option from "effect/Option"
43
+ import * as Schedule from "effect/Schedule"
44
+ import type * as Schema from "effect/Schema"
45
+ import * as Stream from "effect/Stream"
46
+ import type { SolanaAddress } from "./SolanaAddress.ts"
47
+ import * as SolanaNetwork from "./SolanaNetwork.ts"
48
+ import type {
49
+ SolanaRpcError,
50
+ SolanaSignatureInfo,
51
+ SolanaTransactionEncoding,
52
+ SolanaTransactionInfo
53
+ } from "./SolanaRpc.ts"
54
+ import { SolanaRpc } from "./SolanaRpc.ts"
55
+ import type { SolanaTransactionHash } from "./SolanaTransactionHash.ts"
56
+
57
+ /**
58
+ * A transaction touching the indexed address, kept raw: the `getTransaction` result with its `signature` and the
59
+ * `err` listed by `getSignaturesForAddress` (raw JSON, `null` when it succeeded). Failed transactions are kept: they
60
+ * still paid their fee. `transaction` follows the requested encoding.
61
+ *
62
+ * @since 0.1.0
63
+ * @category models
64
+ */
65
+ export interface SolanaIndexedTransaction<Encoding extends SolanaTransactionEncoding = "base64">
66
+ extends SolanaTransactionInfo<Encoding>
67
+ {
68
+ readonly signature: SolanaTransactionHash
69
+ readonly err: Schema.Json
70
+ }
71
+
72
+ /**
73
+ * A {@link SolanaIndexer} `fetchTransactions` filter: the address whose transactions are read, over the inclusive slot
74
+ * range `[fromBlock, toBlock]`.
75
+ *
76
+ * @since 0.1.0
77
+ * @category models
78
+ */
79
+ export interface SolanaIndexerFilter {
80
+ readonly address: SolanaAddress
81
+ readonly fromBlock: bigint
82
+ readonly toBlock: bigint
83
+ }
84
+
85
+ /**
86
+ * The transactions of slots `[fromBlock, toBlock]` (both inclusive), in chain order, emitted by
87
+ * {@link SolanaIndexer.Service.streamTransactions}.
88
+ *
89
+ * A batch is emitted for every range, even without transactions. Delivery is at-least-once: save `batch.toBlock` once
90
+ * the batch is handled and resume from `toBlock + 1`. A batch holds at most `maxBatchSize` transactions, more when a
91
+ * single slot has more, as a slot is never split.
92
+ *
93
+ * @since 0.1.0
94
+ * @category models
95
+ */
96
+ export interface SolanaIndexerBatch<Encoding extends SolanaTransactionEncoding = "base64"> {
97
+ readonly fromBlock: bigint
98
+ readonly toBlock: bigint
99
+ readonly transactions: ReadonlyArray<SolanaIndexedTransaction<Encoding>>
100
+ }
101
+
102
+ /**
103
+ * The {@link SolanaIndexer.Service.streamTransactions} options, `encoding` aside.
104
+ *
105
+ * @since 0.1.0
106
+ * @category models
107
+ */
108
+ export interface SolanaIndexerStreamOptions {
109
+ readonly filter: Omit<SolanaIndexerFilter, "fromBlock" | "toBlock">
110
+ readonly fromBlock: bigint
111
+ /** The stream ends after the batch reaching it, and is empty when `fromBlock > toBlock`. */
112
+ readonly toBlock?: bigint | undefined
113
+ /**
114
+ * When to read the head again once caught up, `Schedule.spaced(DEFAULT_POLL_INTERVAL)` by default. It restarts after
115
+ * each batch, and its end ends the stream: `Schedule.recurs(0)` drains to the head and stops.
116
+ */
117
+ readonly poll?: Schedule.Schedule<unknown> | undefined
118
+ /**
119
+ * Retries a step (the signature paging or one batch's transactions) failing with a transient reason
120
+ * ({@link JsonRpc.isTransient}) at the same position. Off by default.
121
+ */
122
+ readonly retry?: Schedule.Schedule<unknown, SolanaRpcError> | undefined
123
+ }
124
+
125
+ /**
126
+ * @since 0.1.0
127
+ * @category services
128
+ */
129
+ export class SolanaIndexer extends Context.Service<SolanaIndexer, {
130
+ /** The `finalized` slot minus the confirmations, never below 0. */
131
+ readonly lastConfirmedBlock: Effect.Effect<bigint, SolanaRpcError>
132
+ /**
133
+ * The transactions touching `address` in slots `fromBlock..toBlock` (both inclusive), in chain order. Empty when
134
+ * `fromBlock > toBlock`. `encoding` defaults to `base64`.
135
+ */
136
+ readonly fetchTransactions: {
137
+ (
138
+ filter: SolanaIndexerFilter,
139
+ options?: { readonly encoding?: "base64" | undefined }
140
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction>, SolanaRpcError>
141
+ <Encoding extends SolanaTransactionEncoding>(
142
+ filter: SolanaIndexerFilter,
143
+ options: { readonly encoding: Encoding }
144
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<Encoding>>, SolanaRpcError>
145
+ }
146
+ /**
147
+ * The transactions touching `filter.address` from slot `fromBlock` on, in batches of at most `maxBatchSize`
148
+ * signatures, following the confirmed head. `encoding` defaults to `base64`.
149
+ */
150
+ readonly streamTransactions: {
151
+ (
152
+ options: SolanaIndexerStreamOptions & { readonly encoding?: "base64" | undefined }
153
+ ): Stream.Stream<SolanaIndexerBatch, SolanaRpcError>
154
+ <Encoding extends SolanaTransactionEncoding>(
155
+ options: SolanaIndexerStreamOptions & { readonly encoding: Encoding }
156
+ ): Stream.Stream<SolanaIndexerBatch<Encoding>, SolanaRpcError>
157
+ }
158
+ }>()("@effect-blockchain/solana/SolanaIndexer") {}
159
+
160
+ // the node's maximum `limit`
161
+ const PAGE_SIZE = 1000
162
+ const COMMITMENT = "finalized"
163
+
164
+ /**
165
+ * The default `maxBatchSize`: each signature costs one sequential `getTransaction`, so 100 keeps a batch to a few
166
+ * dozen seconds of calls and about 100 transactions in memory between two saved cursors.
167
+ *
168
+ * @since 0.1.0
169
+ * @category constants
170
+ */
171
+ export const DEFAULT_MAX_BATCH_SIZE = 100
172
+
173
+ /**
174
+ * The default `poll` spacing of {@link SolanaIndexer.Service.streamTransactions}: 10 seconds.
175
+ *
176
+ * @since 0.1.0
177
+ * @category constants
178
+ */
179
+ export const DEFAULT_POLL_INTERVAL: Duration.Duration = Duration.seconds(10)
180
+
181
+ // consecutive groups of at most `max` signatures, a slot never split: a full group still takes its last slot's others
182
+ const groupBySlot = (
183
+ signatures: ReadonlyArray<SolanaSignatureInfo>,
184
+ max: number
185
+ ): Array<Arr.NonEmptyArray<SolanaSignatureInfo>> => {
186
+ const groups: Array<Arr.NonEmptyArray<SolanaSignatureInfo>> = []
187
+ for (const info of signatures) {
188
+ const last = groups.at(-1)
189
+ if (last !== undefined && (last.length < max || Arr.lastNonEmpty(last).slot === info.slot)) last.push(info)
190
+ else groups.push([info])
191
+ }
192
+ return groups
193
+ }
194
+
195
+ // a stream position: the next slot to emit, then either nothing pending (read the head and page the signatures) or
196
+ // the groups of `[next, cap]` still to fetch, one per step
197
+ interface StreamPosition {
198
+ readonly next: bigint
199
+ readonly cap: bigint
200
+ readonly groups: ReadonlyArray<Arr.NonEmptyReadonlyArray<SolanaSignatureInfo>>
201
+ }
202
+ type Step = readonly [ReadonlyArray<SolanaIndexerBatch<SolanaTransactionEncoding>>, Option.Option<StreamPosition>]
203
+
204
+ /**
205
+ * Builds a {@link SolanaIndexer} on the provided {@link SolanaRpc}.
206
+ *
207
+ * - `confirmations` defaults to {@link SolanaNetwork.defaultConfirmations} for the RPC's network.
208
+ * - `maxBatchSize`, a positive integer, the signatures per `streamTransactions` batch, defaults to
209
+ * {@link DEFAULT_MAX_BATCH_SIZE}.
210
+ *
211
+ * There is no `maxBlockRange`: `getSignaturesForAddress` takes no slot range to split.
212
+ *
213
+ * @since 0.1.0
214
+ * @category layers
215
+ */
216
+ export const layer = (options: {
217
+ readonly confirmations?: number | undefined
218
+ readonly maxBatchSize?: number | undefined
219
+ } = {}): Layer.Layer<SolanaIndexer, never, SolanaRpc> =>
220
+ Layer.effect(
221
+ SolanaIndexer,
222
+ Effect.gen(function*() {
223
+ const rpc = yield* SolanaRpc
224
+ const maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE
225
+ if (!Number.isSafeInteger(maxBatchSize) || maxBatchSize < 1) {
226
+ return yield* Effect.die(new RangeError(`maxBatchSize must be a positive integer, got ${maxBatchSize}`))
227
+ }
228
+ const confirmations = BigInt(options.confirmations ?? SolanaNetwork.defaultConfirmations(rpc.network))
229
+ const lastConfirmedBlock = rpc.getSlot({ commitment: COMMITMENT }).pipe(
230
+ Effect.map((slot) => BigInt_.max(slot - confirmations, BigInt(0))),
231
+ Effect.withSpan("SolanaIndexer.lastConfirmedBlock")
232
+ )
233
+ // the signatures of `[fromBlock, toBlock]` in chain order, paged from the head back to the first short page or
234
+ // the first page reaching below `fromBlock`
235
+ const fetchSignatures = (filter: SolanaIndexerFilter) =>
236
+ Stream.paginate(
237
+ Option.none<SolanaTransactionHash>(),
238
+ (before) =>
239
+ rpc.getSignaturesForAddress({
240
+ address: filter.address,
241
+ before: Option.getOrUndefined(before),
242
+ limit: PAGE_SIZE,
243
+ commitment: COMMITMENT,
244
+ minContextSlot: filter.toBlock
245
+ }).pipe(Effect.map((page) => {
246
+ const last = page.at(-1)
247
+ return [
248
+ page,
249
+ last === undefined || page.length < PAGE_SIZE || last.slot < filter.fromBlock
250
+ ? Option.none()
251
+ : Option.some(Option.some(last.signature))
252
+ ] as const
253
+ }))
254
+ ).pipe(
255
+ Stream.runCollect,
256
+ // newest first, so reversed slots ascend. The order within a slot is undocumented: reversing it is a best
257
+ // guess at execution order (`transactionIndex`, which some providers add, is not in the RPC model)
258
+ Effect.map((signatures) =>
259
+ Arr.reverse(Arr.filter(signatures, ({ slot }) => slot >= filter.fromBlock && slot <= filter.toBlock))
260
+ )
261
+ )
262
+ const fetchEach = (signatures: ReadonlyArray<SolanaSignatureInfo>, encoding: SolanaTransactionEncoding) =>
263
+ Effect.forEach(signatures, ({ err, signature }) =>
264
+ rpc.getTransaction({ signature, commitment: COMMITMENT, encoding }).pipe(
265
+ Effect.map((tx) => ({ signature, err, ...tx }))
266
+ ))
267
+ const fetchRange = Effect.fn("SolanaIndexer.fetchTransactions")(
268
+ function*(filter: SolanaIndexerFilter, encoding: SolanaTransactionEncoding) {
269
+ if (filter.fromBlock > filter.toBlock) {
270
+ return []
271
+ }
272
+ return yield* fetchEach(yield* fetchSignatures(filter), encoding)
273
+ }
274
+ )
275
+
276
+ function fetchTransactions(
277
+ filter: SolanaIndexerFilter,
278
+ options?: { readonly encoding?: "base64" | undefined }
279
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction>, SolanaRpcError>
280
+ function fetchTransactions<Encoding extends SolanaTransactionEncoding>(
281
+ filter: SolanaIndexerFilter,
282
+ options: { readonly encoding: Encoding }
283
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<Encoding>>, SolanaRpcError>
284
+ function fetchTransactions(
285
+ filter: SolanaIndexerFilter,
286
+ { encoding = "base64" }: { readonly encoding?: SolanaTransactionEncoding | undefined } = {}
287
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<SolanaTransactionEncoding>>, SolanaRpcError> {
288
+ return fetchRange(filter, encoding)
289
+ }
290
+
291
+ function streamTransactions(
292
+ options: SolanaIndexerStreamOptions & { readonly encoding?: "base64" | undefined }
293
+ ): Stream.Stream<SolanaIndexerBatch, SolanaRpcError>
294
+ function streamTransactions<Encoding extends SolanaTransactionEncoding>(
295
+ options: SolanaIndexerStreamOptions & { readonly encoding: Encoding }
296
+ ): Stream.Stream<SolanaIndexerBatch<Encoding>, SolanaRpcError>
297
+ function streamTransactions(
298
+ options: SolanaIndexerStreamOptions & { readonly encoding?: SolanaTransactionEncoding | undefined }
299
+ ): Stream.Stream<SolanaIndexerBatch<SolanaTransactionEncoding>, SolanaRpcError> {
300
+ const { encoding = "base64", filter, fromBlock, retry, toBlock } = options
301
+ const poll = options.poll ?? Schedule.spaced(DEFAULT_POLL_INTERVAL)
302
+ if (toBlock !== undefined && fromBlock > toBlock) {
303
+ return Stream.empty
304
+ }
305
+ const after = (end: bigint, cap: bigint, groups: StreamPosition["groups"]): Option.Option<StreamPosition> =>
306
+ end === toBlock ? Option.none() : Option.some({ next: end + BigInt(1), cap, groups })
307
+ // one step: the transactions of the next pending group, else the signatures up to the polled confirmed head
308
+ const step = (position: StreamPosition): Effect.Effect<Step, SolanaRpcError> => {
309
+ const { cap, groups, next } = position
310
+ if (Arr.isReadonlyArrayNonEmpty(groups)) {
311
+ const [group, ...rest] = groups
312
+ const end = rest.length === 0 ? cap : Arr.lastNonEmpty(group).slot
313
+ return fetchEach(group, encoding).pipe(
314
+ Effect.map((transactions): Step => [
315
+ [{ fromBlock: next, toBlock: end, transactions }],
316
+ after(end, cap, rest)
317
+ ]),
318
+ Effect.withSpan("SolanaIndexer.streamTransactions.fetchGroup")
319
+ )
320
+ }
321
+ return lastConfirmedBlock.pipe(
322
+ Effect.repeat({
323
+ schedule: poll,
324
+ until: (confirmed) =>
325
+ confirmed >= next
326
+ }),
327
+ Effect.flatMap((confirmed) => {
328
+ const end = toBlock === undefined ? confirmed : BigInt_.min(confirmed, toBlock)
329
+ if (next > end) {
330
+ return Effect.succeed([[], Option.none()] as const)
331
+ }
332
+ return fetchSignatures({ address: filter.address, fromBlock: next, toBlock: end }).pipe(
333
+ Effect.map((signatures): Step =>
334
+ Arr.isReadonlyArrayNonEmpty(signatures)
335
+ ? [[], Option.some({ next, cap: end, groups: groupBySlot(signatures, maxBatchSize) })]
336
+ : [[{ fromBlock: next, toBlock: end, transactions: [] }], after(end, end, [])]
337
+ ),
338
+ Effect.withSpan("SolanaIndexer.streamTransactions.fetchSignatures")
339
+ )
340
+ })
341
+ )
342
+ }
343
+ return Stream.paginate(
344
+ { next: fromBlock, cap: fromBlock, groups: [] } satisfies StreamPosition,
345
+ retry === undefined
346
+ ? step
347
+ : (position) =>
348
+ Effect.retry(step(position), {
349
+ schedule: retry,
350
+ while: (error) =>
351
+ JsonRpc.isTransient(error.reason)
352
+ })
353
+ )
354
+ }
355
+
356
+ return SolanaIndexer.of({ lastConfirmedBlock, fetchTransactions, streamTransactions })
357
+ })
358
+ )
359
+
360
+ /**
361
+ * Builds an {@link SolanaIndexer} like {@link layer}, reading the options from `Config`.
362
+ *
363
+ * @example
364
+ * ```ts
365
+ * import * as SolanaIndexer from "@effect-blockchain/solana/SolanaIndexer"
366
+ * import * as Config from "effect/Config"
367
+ *
368
+ * const IndexerLive = SolanaIndexer.layerConfig({ confirmations: Config.Int("SOLANA_CONFIRMATIONS") })
369
+ * ```
370
+ *
371
+ * @since 0.1.0
372
+ * @category layers
373
+ */
374
+ export const layerConfig = (
375
+ options: Config.Wrap<NonNullable<Parameters<typeof layer>[0]>>
376
+ ): Layer.Layer<SolanaIndexer, Config.ConfigError, SolanaRpc> => Layer.unwrap(Effect.map(Config.unwrap(options), layer))