@effect-blockchain/solana 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/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 +198 -0
  8. package/dist/SolanaIndexer.d.ts.map +1 -0
  9. package/dist/SolanaIndexer.js +344 -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/SolanaRelayer.d.ts +207 -0
  16. package/dist/SolanaRelayer.d.ts.map +1 -0
  17. package/dist/SolanaRelayer.js +377 -0
  18. package/dist/SolanaRelayer.js.map +1 -0
  19. package/dist/SolanaRpc.d.ts +427 -0
  20. package/dist/SolanaRpc.d.ts.map +1 -0
  21. package/dist/SolanaRpc.js +216 -0
  22. package/dist/SolanaRpc.js.map +1 -0
  23. package/dist/SolanaSigner.d.ts +49 -0
  24. package/dist/SolanaSigner.d.ts.map +1 -0
  25. package/dist/SolanaSigner.js +82 -0
  26. package/dist/SolanaSigner.js.map +1 -0
  27. package/dist/SolanaTransactionHash.d.ts +14 -0
  28. package/dist/SolanaTransactionHash.d.ts.map +1 -0
  29. package/dist/SolanaTransactionHash.js +34 -0
  30. package/dist/SolanaTransactionHash.js.map +1 -0
  31. package/dist/index.d.ts +32 -0
  32. package/dist/index.d.ts.map +1 -0
  33. package/dist/index.js +33 -0
  34. package/dist/index.js.map +1 -0
  35. package/dist/internal/bigIntJson.d.ts +2 -0
  36. package/dist/internal/bigIntJson.d.ts.map +1 -0
  37. package/dist/internal/bigIntJson.js +9 -0
  38. package/dist/internal/bigIntJson.js.map +1 -0
  39. package/dist/internal/confirmations.d.ts +2 -0
  40. package/dist/internal/confirmations.d.ts.map +1 -0
  41. package/dist/internal/confirmations.js +15 -0
  42. package/dist/internal/confirmations.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 +223 -0
  46. package/dist/internal/rpcMethods.js.map +1 -0
  47. package/package.json +66 -3
  48. package/src/SolanaAddress.ts +40 -0
  49. package/src/SolanaIndexer.ts +552 -0
  50. package/src/SolanaNetwork.ts +105 -0
  51. package/src/SolanaRelayer.ts +493 -0
  52. package/src/SolanaRpc.ts +595 -0
  53. package/src/SolanaSigner.ts +98 -0
  54. package/src/SolanaTransactionHash.ts +41 -0
  55. package/src/index.ts +40 -0
  56. package/src/internal/bigIntJson.ts +18 -0
  57. package/src/internal/confirmations.ts +17 -0
  58. package/src/internal/rpcMethods.ts +260 -0
@@ -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,552 @@
1
+ /**
2
+ * Solana transaction indexing on top of {@link SolanaRpc}: the last confirmed slot, the transactions touching an
3
+ * address over a slot range, its lamport balance at a slot, and streams of both following the confirmed head. Blocks
4
+ * are slots.
5
+ *
6
+ * Everything is read at `finalized` commitment. `getSignaturesForAddress` has no slot range, so a range is paged from
7
+ * the head backwards until it passes `fromBlock`: the cost grows with the address's history since `fromBlock`, then
8
+ * each transaction costs one `getTransaction`. Each page sends `minContextSlot: toBlock`, so a lagging endpoint that
9
+ * honours it falls back. Any failure fails the whole call and nothing is returned: the caller retries the same range.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import type { SolanaAddress } from "@effect-blockchain/solana/SolanaAddress"
14
+ * import type { SolanaIndexerFilter } from "@effect-blockchain/solana/SolanaIndexer"
15
+ * import { SolanaIndexer } from "@effect-blockchain/solana/SolanaIndexer"
16
+ * import * as Effect from "effect/Effect"
17
+ * import * as Schedule from "effect/Schedule"
18
+ * import * as Stream from "effect/Stream"
19
+ *
20
+ * declare const filter: Omit<SolanaIndexerFilter, "fromBlock" | "toBlock">
21
+ * declare const cursor: bigint
22
+ * declare const save: (slot: bigint) => Effect.Effect<void>
23
+ *
24
+ * const program = Effect.gen(function*() {
25
+ * const indexer = yield* SolanaIndexer
26
+ * // once caught up, read the head after 1 s, 2 s, 4 s... at most every minute
27
+ * const poll = Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("1 minute")])
28
+ * yield* indexer.streamTransactions({ filter, fromBlock: cursor + BigInt(1), poll }).pipe(
29
+ * Stream.runForEach((batch) => save(batch.toBlock))
30
+ * )
31
+ * })
32
+ *
33
+ * declare const address: SolanaAddress
34
+ *
35
+ * // the lamports of `address` every 9000 slots (about an hour) from slot 400000000
36
+ * const balances = Effect.gen(function*() {
37
+ * const indexer = yield* SolanaIndexer
38
+ * yield* indexer.streamNativeBalance({ address, fromBlock: BigInt(400000000), step: 9000 }).pipe(
39
+ * Stream.runForEach(({ balance, block }) => Effect.log(`${block}: ${balance}`))
40
+ * )
41
+ * })
42
+ * ```
43
+ *
44
+ * @since 0.1.0
45
+ */
46
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc"
47
+ import * as Arr from "effect/Array"
48
+ import * as BigInt_ from "effect/BigInt"
49
+ import * as Config from "effect/Config"
50
+ import * as Context from "effect/Context"
51
+ import * as Duration from "effect/Duration"
52
+ import * as Effect from "effect/Effect"
53
+ import * as Layer from "effect/Layer"
54
+ import * as Option from "effect/Option"
55
+ import * as Schedule from "effect/Schedule"
56
+ import type * as Schema from "effect/Schema"
57
+ import * as Stream from "effect/Stream"
58
+ import * as Confirmations from "./internal/confirmations.ts"
59
+ import type { SolanaAddress } from "./SolanaAddress.ts"
60
+ import type { SolanaSignatureInfo, SolanaTransactionEncoding, SolanaTransactionInfo } from "./SolanaRpc.ts"
61
+ import { SolanaRpc, SolanaRpcError } from "./SolanaRpc.ts"
62
+ import type { SolanaTransactionHash } from "./SolanaTransactionHash.ts"
63
+
64
+ /**
65
+ * A transaction touching the indexed address, kept raw: the `getTransaction` result with its `signature` and the
66
+ * `err` listed by `getSignaturesForAddress` (raw JSON, `null` when it succeeded). Failed transactions are kept: they
67
+ * still paid their fee. `transaction` follows the requested encoding.
68
+ *
69
+ * @since 0.1.0
70
+ * @category models
71
+ */
72
+ export interface SolanaIndexedTransaction<Encoding extends SolanaTransactionEncoding = "base64">
73
+ extends SolanaTransactionInfo<Encoding>
74
+ {
75
+ readonly signature: SolanaTransactionHash
76
+ readonly err: Schema.Json
77
+ }
78
+
79
+ /**
80
+ * A {@link SolanaIndexer} `fetchTransactions` filter: the address whose transactions are read, over the inclusive slot
81
+ * range `[fromBlock, toBlock]`.
82
+ *
83
+ * @since 0.1.0
84
+ * @category models
85
+ */
86
+ export interface SolanaIndexerFilter {
87
+ readonly address: SolanaAddress
88
+ readonly fromBlock: bigint
89
+ readonly toBlock: bigint
90
+ }
91
+
92
+ /**
93
+ * The transactions of slots `[fromBlock, toBlock]` (both inclusive), in chain order, emitted by
94
+ * {@link SolanaIndexer.Service.streamTransactions}.
95
+ *
96
+ * A batch is emitted for every range, even without transactions. Delivery is at-least-once: save `batch.toBlock` once
97
+ * the batch is handled and resume from `toBlock + 1`. A batch holds at most `maxBatchSize` transactions, more when a
98
+ * single slot has more, as a slot is never split.
99
+ *
100
+ * @since 0.1.0
101
+ * @category models
102
+ */
103
+ export interface SolanaIndexerBatch<Encoding extends SolanaTransactionEncoding = "base64"> {
104
+ readonly fromBlock: bigint
105
+ readonly toBlock: bigint
106
+ readonly transactions: ReadonlyArray<SolanaIndexedTransaction<Encoding>>
107
+ }
108
+
109
+ /**
110
+ * The {@link SolanaIndexer.Service.streamTransactions} options, `encoding` aside.
111
+ *
112
+ * @since 0.1.0
113
+ * @category models
114
+ */
115
+ export interface SolanaIndexerStreamOptions {
116
+ readonly filter: Omit<SolanaIndexerFilter, "fromBlock" | "toBlock">
117
+ readonly fromBlock: bigint
118
+ /** The stream ends after the batch reaching it, and is empty when `fromBlock > toBlock`. */
119
+ readonly toBlock?: bigint | undefined
120
+ /**
121
+ * When to read the head again once caught up, `Schedule.spaced(DEFAULT_POLL_INTERVAL)` by default. It restarts after
122
+ * each batch, and its end ends the stream: `Schedule.recurs(0)` drains to the head and stops.
123
+ */
124
+ readonly poll?: Schedule.Schedule<unknown> | undefined
125
+ /**
126
+ * Retries a step (the signature paging or one batch's transactions) failing with a transient reason
127
+ * ({@link JsonRpc.isTransient}) at the same position. Off by default.
128
+ */
129
+ readonly retry?: Schedule.Schedule<unknown, SolanaRpcError> | undefined
130
+ }
131
+
132
+ /**
133
+ * The lamports of an address at the end of slot `block`, emitted by {@link SolanaIndexer.Service.streamNativeBalance}.
134
+ *
135
+ * @since 0.2.0
136
+ * @category models
137
+ */
138
+ export interface SolanaNativeBalance {
139
+ readonly block: bigint
140
+ readonly balance: bigint
141
+ }
142
+
143
+ /**
144
+ * The {@link SolanaIndexer.Service.streamNativeBalance} options: a sample of the balance of `address` at `fromBlock`,
145
+ * `fromBlock + step`, `fromBlock + 2 * step`... `poll` and `retry` behave as in {@link SolanaIndexerStreamOptions}.
146
+ *
147
+ * @since 0.2.0
148
+ * @category models
149
+ */
150
+ export interface SolanaIndexerNativeBalanceOptions {
151
+ readonly address: SolanaAddress
152
+ readonly fromBlock: bigint
153
+ /** The stream ends after the last sample not above it, and is empty when `fromBlock > toBlock`. */
154
+ readonly toBlock?: bigint | undefined
155
+ /** The slots between two samples, a positive safe integer. */
156
+ readonly step: number
157
+ readonly poll?: Schedule.Schedule<unknown> | undefined
158
+ readonly retry?: Schedule.Schedule<unknown, SolanaRpcError> | undefined
159
+ }
160
+
161
+ /**
162
+ * @since 0.1.0
163
+ * @category services
164
+ */
165
+ export class SolanaIndexer extends Context.Service<SolanaIndexer, {
166
+ /** The `finalized` slot minus the confirmations, never below 0. */
167
+ readonly lastConfirmedBlock: Effect.Effect<bigint, SolanaRpcError>
168
+ /**
169
+ * The transactions touching `address` in slots `fromBlock..toBlock` (both inclusive), in chain order. Empty when
170
+ * `fromBlock > toBlock`. `encoding` defaults to `base64`.
171
+ */
172
+ readonly fetchTransactions: {
173
+ (
174
+ filter: SolanaIndexerFilter,
175
+ options?: { readonly encoding?: "base64" | undefined }
176
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction>, SolanaRpcError>
177
+ <Encoding extends SolanaTransactionEncoding>(
178
+ filter: SolanaIndexerFilter,
179
+ options: { readonly encoding: Encoding }
180
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<Encoding>>, SolanaRpcError>
181
+ }
182
+ /**
183
+ * The transactions touching `filter.address` from slot `fromBlock` on, in batches of at most `maxBatchSize`
184
+ * signatures, following the confirmed head. `encoding` defaults to `base64`.
185
+ */
186
+ readonly streamTransactions: {
187
+ (
188
+ options: SolanaIndexerStreamOptions & { readonly encoding?: "base64" | undefined }
189
+ ): Stream.Stream<SolanaIndexerBatch, SolanaRpcError>
190
+ <Encoding extends SolanaTransactionEncoding>(
191
+ options: SolanaIndexerStreamOptions & { readonly encoding: Encoding }
192
+ ): Stream.Stream<SolanaIndexerBatch<Encoding>, SolanaRpcError>
193
+ }
194
+ /**
195
+ * The lamports of `address` at the end of slot `block`: the `postBalances` of its newest transaction at or before
196
+ * `block`, else the `preBalances` of its first one after. At or above the confirmed head with no newer transaction,
197
+ * its `getBalance`: an address without any transaction reads its current balance there and 0 below.
198
+ */
199
+ readonly fetchNativeBalance: (options: {
200
+ readonly address: SolanaAddress
201
+ readonly block: bigint
202
+ }) => Effect.Effect<bigint, SolanaRpcError>
203
+ /**
204
+ * The lamports of `address` at every `step` slots from `fromBlock`, following the confirmed head. A sample only
205
+ * reads the meta of the newest transaction since the previous one, so epoch rewards, which change a balance without
206
+ * a transaction, show from the next transaction on.
207
+ */
208
+ readonly streamNativeBalance: (
209
+ options: SolanaIndexerNativeBalanceOptions
210
+ ) => Stream.Stream<SolanaNativeBalance, SolanaRpcError>
211
+ }>()("@effect-blockchain/solana/SolanaIndexer") {}
212
+
213
+ // the node's maximum `limit`
214
+ const PAGE_SIZE = 1000
215
+ const COMMITMENT = "finalized"
216
+
217
+ /**
218
+ * The default `maxBatchSize`: each signature costs one sequential `getTransaction`, so 100 keeps a batch to a few
219
+ * dozen seconds of calls and about 100 transactions in memory between two saved cursors.
220
+ *
221
+ * @since 0.1.0
222
+ * @category constants
223
+ */
224
+ export const DEFAULT_MAX_BATCH_SIZE = 100
225
+
226
+ /**
227
+ * The default `poll` spacing of {@link SolanaIndexer.Service.streamTransactions}: 10 seconds.
228
+ *
229
+ * @since 0.1.0
230
+ * @category constants
231
+ */
232
+ export const DEFAULT_POLL_INTERVAL: Duration.Duration = Duration.seconds(10)
233
+
234
+ // consecutive groups of at most `max` signatures, a slot never split: a full group still takes its last slot's others
235
+ const groupBySlot = (
236
+ signatures: ReadonlyArray<SolanaSignatureInfo>,
237
+ max: number
238
+ ): Array<Arr.NonEmptyArray<SolanaSignatureInfo>> => {
239
+ const groups: Array<Arr.NonEmptyArray<SolanaSignatureInfo>> = []
240
+ for (const info of signatures) {
241
+ const last = groups.at(-1)
242
+ if (last !== undefined && (last.length < max || Arr.lastNonEmpty(last).slot === info.slot)) last.push(info)
243
+ else groups.push([info])
244
+ }
245
+ return groups
246
+ }
247
+
248
+ // a stream position: the next slot to emit, then either nothing pending (read the head and page the signatures) or
249
+ // the groups of `[next, cap]` still to fetch, one per step
250
+ interface StreamPosition {
251
+ readonly next: bigint
252
+ readonly cap: bigint
253
+ readonly groups: ReadonlyArray<Arr.NonEmptyReadonlyArray<SolanaSignatureInfo>>
254
+ }
255
+ // a sample, then the next stream position: the previous sample, none for the first
256
+ type Sample = readonly [ReadonlyArray<SolanaNativeBalance>, Option.Option<Option.Option<SolanaNativeBalance>>]
257
+ type Step = readonly [ReadonlyArray<SolanaIndexerBatch<SolanaTransactionEncoding>>, Option.Option<StreamPosition>]
258
+
259
+ // the lamports of `address` before and after `transaction`, none when it is not one of its accounts. An account's
260
+ // index runs over the static account keys, then the addresses loaded from lookup tables, writable then readonly
261
+ // (https://solana.com/docs/advanced/versions)
262
+ const balanceChange = (
263
+ { meta, transaction }: SolanaTransactionInfo<"json">,
264
+ address: SolanaAddress
265
+ ): Option.Option<{ readonly pre: bigint; readonly post: bigint }> => {
266
+ if (meta === null) return Option.none()
267
+ const index = [
268
+ ...transaction.message.accountKeys,
269
+ ...meta.loadedAddresses?.writable ?? [],
270
+ ...meta.loadedAddresses?.readonly ?? []
271
+ ].indexOf(address)
272
+ const pre = meta.preBalances[index]
273
+ const post = meta.postBalances[index]
274
+ return pre === undefined || post === undefined ? Option.none() : Option.some({ pre, post })
275
+ }
276
+
277
+ // retries a stream step failing with a transient reason at the same position
278
+ const withRetry = <S, A>(
279
+ retry: Schedule.Schedule<unknown, SolanaRpcError> | undefined,
280
+ step: (position: S) => Effect.Effect<A, SolanaRpcError>
281
+ ) =>
282
+ retry === undefined
283
+ ? step
284
+ : (position: S) =>
285
+ Effect.retry(step(position), { schedule: retry, while: (error) => JsonRpc.isTransient(error.reason) })
286
+
287
+ /**
288
+ * Builds a {@link SolanaIndexer} on the provided {@link SolanaRpc}.
289
+ *
290
+ * - `confirmations` defaults to `SolanaNetwork.defaultConfirmations` for the RPC's network.
291
+ * - `maxBatchSize`, a positive integer, the signatures per `streamTransactions` batch, defaults to
292
+ * {@link DEFAULT_MAX_BATCH_SIZE}.
293
+ *
294
+ * There is no `maxBlockRange`: `getSignaturesForAddress` takes no slot range to split.
295
+ *
296
+ * @since 0.1.0
297
+ * @category layers
298
+ */
299
+ export const layer = (options: {
300
+ readonly confirmations?: number | undefined
301
+ readonly maxBatchSize?: number | undefined
302
+ } = {}): Layer.Layer<SolanaIndexer, never, SolanaRpc> =>
303
+ Layer.effect(
304
+ SolanaIndexer,
305
+ Effect.gen(function*() {
306
+ const rpc = yield* SolanaRpc
307
+ const maxBatchSize = options.maxBatchSize ?? DEFAULT_MAX_BATCH_SIZE
308
+ if (!Number.isSafeInteger(maxBatchSize) || maxBatchSize < 1) {
309
+ return yield* Effect.die(new RangeError(`maxBatchSize must be a positive integer, got ${maxBatchSize}`))
310
+ }
311
+ const lastConfirmedBlock = Confirmations.lastConfirmedBlock(rpc, options.confirmations).pipe(
312
+ Effect.withSpan("SolanaIndexer.lastConfirmedBlock")
313
+ )
314
+ // the signatures of `address`, newest first, a page read only when the previous one is consumed
315
+ const signatures = (address: SolanaAddress, minContextSlot: bigint) =>
316
+ Stream.paginate(
317
+ Option.none<SolanaTransactionHash>(),
318
+ (before) =>
319
+ rpc.getSignaturesForAddress({
320
+ address,
321
+ before: Option.getOrUndefined(before),
322
+ limit: PAGE_SIZE,
323
+ commitment: COMMITMENT,
324
+ minContextSlot
325
+ }).pipe(Effect.map((page) => {
326
+ const last = page.at(-1)
327
+ return [
328
+ page,
329
+ last === undefined || page.length < PAGE_SIZE ? Option.none() : Option.some(Option.some(last.signature))
330
+ ] as const
331
+ }))
332
+ )
333
+ // the signatures of `[fromBlock, toBlock]` in chain order, paged from the head back to the first short page or
334
+ // the first page reaching below `fromBlock`
335
+ const fetchSignatures = (filter: SolanaIndexerFilter) =>
336
+ signatures(filter.address, filter.toBlock).pipe(
337
+ Stream.takeWhile(({ slot }) => slot >= filter.fromBlock),
338
+ Stream.runCollect,
339
+ // newest first, so reversed slots ascend. The order within a slot is undocumented: reversing it is a best
340
+ // guess at execution order (`transactionIndex`, which some providers add, is not in the RPC model)
341
+ Effect.map((signatures) => Arr.reverse(Arr.filter(signatures, ({ slot }) => slot <= filter.toBlock)))
342
+ )
343
+ const fetchEach = (signatures: ReadonlyArray<SolanaSignatureInfo>, encoding: SolanaTransactionEncoding) =>
344
+ Effect.forEach(signatures, ({ err, signature }) =>
345
+ rpc.getTransaction({ signature, commitment: COMMITMENT, encoding }).pipe(
346
+ Effect.map((tx) => ({ signature, err, ...tx }))
347
+ ))
348
+ const fetchRange = Effect.fn("SolanaIndexer.fetchTransactions")(
349
+ function*(filter: SolanaIndexerFilter, encoding: SolanaTransactionEncoding) {
350
+ if (filter.fromBlock > filter.toBlock) {
351
+ return []
352
+ }
353
+ return yield* fetchEach(yield* fetchSignatures(filter), encoding)
354
+ }
355
+ )
356
+
357
+ function fetchTransactions(
358
+ filter: SolanaIndexerFilter,
359
+ options?: { readonly encoding?: "base64" | undefined }
360
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction>, SolanaRpcError>
361
+ function fetchTransactions<Encoding extends SolanaTransactionEncoding>(
362
+ filter: SolanaIndexerFilter,
363
+ options: { readonly encoding: Encoding }
364
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<Encoding>>, SolanaRpcError>
365
+ function fetchTransactions(
366
+ filter: SolanaIndexerFilter,
367
+ { encoding = "base64" }: { readonly encoding?: SolanaTransactionEncoding | undefined } = {}
368
+ ): Effect.Effect<ReadonlyArray<SolanaIndexedTransaction<SolanaTransactionEncoding>>, SolanaRpcError> {
369
+ return fetchRange(filter, encoding)
370
+ }
371
+
372
+ function streamTransactions(
373
+ options: SolanaIndexerStreamOptions & { readonly encoding?: "base64" | undefined }
374
+ ): Stream.Stream<SolanaIndexerBatch, SolanaRpcError>
375
+ function streamTransactions<Encoding extends SolanaTransactionEncoding>(
376
+ options: SolanaIndexerStreamOptions & { readonly encoding: Encoding }
377
+ ): Stream.Stream<SolanaIndexerBatch<Encoding>, SolanaRpcError>
378
+ function streamTransactions(
379
+ options: SolanaIndexerStreamOptions & { readonly encoding?: SolanaTransactionEncoding | undefined }
380
+ ): Stream.Stream<SolanaIndexerBatch<SolanaTransactionEncoding>, SolanaRpcError> {
381
+ const { encoding = "base64", filter, fromBlock, retry, toBlock } = options
382
+ const poll = options.poll ?? Schedule.spaced(DEFAULT_POLL_INTERVAL)
383
+ if (toBlock !== undefined && fromBlock > toBlock) {
384
+ return Stream.empty
385
+ }
386
+ const after = (end: bigint, cap: bigint, groups: StreamPosition["groups"]): Option.Option<StreamPosition> =>
387
+ end === toBlock ? Option.none() : Option.some({ next: end + BigInt(1), cap, groups })
388
+ // one step: the transactions of the next pending group, else the signatures up to the polled confirmed head
389
+ const step = (position: StreamPosition): Effect.Effect<Step, SolanaRpcError> => {
390
+ const { cap, groups, next } = position
391
+ if (Arr.isReadonlyArrayNonEmpty(groups)) {
392
+ const [group, ...rest] = groups
393
+ const end = rest.length === 0 ? cap : Arr.lastNonEmpty(group).slot
394
+ return fetchEach(group, encoding).pipe(
395
+ Effect.map((transactions): Step => [
396
+ [{ fromBlock: next, toBlock: end, transactions }],
397
+ after(end, cap, rest)
398
+ ]),
399
+ Effect.withSpan("SolanaIndexer.streamTransactions.fetchGroup")
400
+ )
401
+ }
402
+ return lastConfirmedBlock.pipe(
403
+ Effect.repeat({
404
+ schedule: poll,
405
+ until: (confirmed) =>
406
+ confirmed >= next
407
+ }),
408
+ Effect.flatMap((confirmed) => {
409
+ const end = toBlock === undefined ? confirmed : BigInt_.min(confirmed, toBlock)
410
+ if (next > end) {
411
+ return Effect.succeed([[], Option.none()] as const)
412
+ }
413
+ return fetchSignatures({ address: filter.address, fromBlock: next, toBlock: end }).pipe(
414
+ Effect.map((signatures): Step =>
415
+ Arr.isReadonlyArrayNonEmpty(signatures)
416
+ ? [[], Option.some({ next, cap: end, groups: groupBySlot(signatures, maxBatchSize) })]
417
+ : [[{ fromBlock: next, toBlock: end, transactions: [] }], after(end, end, [])]
418
+ ),
419
+ Effect.withSpan("SolanaIndexer.streamTransactions.fetchSignatures")
420
+ )
421
+ })
422
+ )
423
+ }
424
+ return Stream.paginate(
425
+ { next: fromBlock, cap: fromBlock, groups: [] } satisfies StreamPosition,
426
+ withRetry(retry, step)
427
+ )
428
+ }
429
+
430
+ const balanceOf = (address: SolanaAddress, signature: SolanaTransactionHash, side: "pre" | "post") =>
431
+ rpc.getTransaction({ signature, commitment: COMMITMENT, encoding: "json" }).pipe(
432
+ Effect.flatMap((tx) =>
433
+ Option.match(balanceChange(tx, address), {
434
+ onSome: (change) =>
435
+ Effect.succeed(change[side]),
436
+ onNone: () =>
437
+ Effect.fail(
438
+ new SolanaRpcError({
439
+ reason: new JsonRpc.InvalidResponse(),
440
+ method: "getTransaction",
441
+ endpoint: "SolanaIndexer",
442
+ cause: new Error(`transaction ${signature} has no balance for ${address}`)
443
+ })
444
+ )
445
+ })
446
+ )
447
+ )
448
+ // the balance at the end of `block`, at or below `confirmed`, given the sample before it when there is one
449
+ const balanceAt = Effect.fnUntraced(function*(
450
+ address: SolanaAddress,
451
+ block: bigint,
452
+ confirmed: bigint,
453
+ previous: Option.Option<SolanaNativeBalance>
454
+ ): Effect.fn.Return<bigint, SolanaRpcError> {
455
+ // read before the signatures, so that a transaction landing in between is listed
456
+ const current = Option.isNone(previous) && block >= confirmed
457
+ ? Option.some(yield* rpc.getBalance({ address }))
458
+ : Option.none()
459
+ // the newest signature, and the newest at or before `block` or else the oldest
460
+ const { last, newest } = yield* signatures(address, BigInt_.min(block, confirmed)).pipe(
461
+ Stream.takeUntil(({ slot }) => slot <= block),
462
+ Stream.runFold(
463
+ () => ({ newest: Option.none<SolanaSignatureInfo>(), last: Option.none<SolanaSignatureInfo>() }),
464
+ (acc, info) => ({ newest: Option.orElseSome(acc.newest, () => info), last: Option.some(info) })
465
+ )
466
+ )
467
+ if (
468
+ Option.isSome(current) &&
469
+ Option.match(newest, {
470
+ onNone: () => true,
471
+ onSome: ({ slot }) => slot <= BigInt_.min(block, current.value.slot)
472
+ })
473
+ ) {
474
+ return current.value.value
475
+ }
476
+ if (Option.isSome(last) && last.value.slot <= block) {
477
+ return Option.isSome(previous) && last.value.slot <= previous.value.block
478
+ ? previous.value.balance
479
+ : yield* balanceOf(address, last.value.signature, "post")
480
+ }
481
+ if (Option.isSome(previous)) return previous.value.balance
482
+ return Option.isSome(last) ? yield* balanceOf(address, last.value.signature, "pre") : BigInt(0)
483
+ })
484
+
485
+ const fetchNativeBalance = Effect.fn("SolanaIndexer.fetchNativeBalance")(
486
+ function*({ address, block }: { readonly address: SolanaAddress; readonly block: bigint }) {
487
+ return yield* balanceAt(address, block, yield* lastConfirmedBlock, Option.none())
488
+ }
489
+ )
490
+
491
+ const streamNativeBalance = (
492
+ { address, fromBlock, poll = Schedule.spaced(DEFAULT_POLL_INTERVAL), retry, step, toBlock }:
493
+ SolanaIndexerNativeBalanceOptions
494
+ ): Stream.Stream<SolanaNativeBalance, SolanaRpcError> => {
495
+ if (!Number.isSafeInteger(step) || step < 1) {
496
+ return Stream.die(new RangeError(`step must be a positive safe integer, got ${step}`))
497
+ }
498
+ if (toBlock !== undefined && fromBlock > toBlock) {
499
+ return Stream.empty
500
+ }
501
+ const sample = (
502
+ previous: Option.Option<SolanaNativeBalance>
503
+ ): Effect.Effect<Sample, SolanaRpcError> => {
504
+ const block = Option.match(previous, { onNone: () => fromBlock, onSome: (p) => p.block + BigInt(step) })
505
+ return lastConfirmedBlock.pipe(
506
+ Effect.repeat({ schedule: poll, until: (confirmed) => confirmed >= block }),
507
+ Effect.flatMap((confirmed) =>
508
+ confirmed < block
509
+ ? Effect.succeed<Sample>([[], Option.none()])
510
+ : balanceAt(address, block, confirmed, previous).pipe(Effect.map((balance): Sample => {
511
+ const current = { block, balance }
512
+ return [
513
+ [current],
514
+ toBlock !== undefined && block + BigInt(step) > toBlock
515
+ ? Option.none()
516
+ : Option.some(Option.some(current))
517
+ ]
518
+ }))
519
+ ),
520
+ Effect.withSpan("SolanaIndexer.streamNativeBalance.sample")
521
+ )
522
+ }
523
+ return Stream.paginate(Option.none<SolanaNativeBalance>(), withRetry(retry, sample))
524
+ }
525
+
526
+ return SolanaIndexer.of({
527
+ lastConfirmedBlock,
528
+ fetchTransactions,
529
+ streamTransactions,
530
+ fetchNativeBalance,
531
+ streamNativeBalance
532
+ })
533
+ })
534
+ )
535
+
536
+ /**
537
+ * Builds an {@link SolanaIndexer} like {@link layer}, reading the options from `Config`.
538
+ *
539
+ * @example
540
+ * ```ts
541
+ * import * as SolanaIndexer from "@effect-blockchain/solana/SolanaIndexer"
542
+ * import * as Config from "effect/Config"
543
+ *
544
+ * const IndexerLive = SolanaIndexer.layerConfig({ confirmations: Config.Int("SOLANA_CONFIRMATIONS") })
545
+ * ```
546
+ *
547
+ * @since 0.1.0
548
+ * @category layers
549
+ */
550
+ export const layerConfig = (
551
+ options: Config.Wrap<NonNullable<Parameters<typeof layer>[0]>>
552
+ ): Layer.Layer<SolanaIndexer, Config.ConfigError, SolanaRpc> => Layer.unwrap(Effect.map(Config.unwrap(options), layer))