@effect-blockchain/solana 0.1.0 → 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.
@@ -1,6 +1,7 @@
1
1
  /**
2
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.
3
+ * address over a slot range, its lamport balance at a slot, and streams of both following the confirmed head. Blocks
4
+ * are slots.
4
5
  *
5
6
  * Everything is read at `finalized` commitment. `getSignaturesForAddress` has no slot range, so a range is paged from
6
7
  * the head backwards until it passes `fromBlock`: the cost grows with the address's history since `fromBlock`, then
@@ -9,6 +10,7 @@
9
10
  *
10
11
  * @example
11
12
  * ```ts
13
+ * import type { SolanaAddress } from "@effect-blockchain/solana/SolanaAddress"
12
14
  * import type { SolanaIndexerFilter } from "@effect-blockchain/solana/SolanaIndexer"
13
15
  * import { SolanaIndexer } from "@effect-blockchain/solana/SolanaIndexer"
14
16
  * import * as Effect from "effect/Effect"
@@ -27,6 +29,16 @@
27
29
  * Stream.runForEach((batch) => save(batch.toBlock))
28
30
  * )
29
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
+ * })
30
42
  * ```
31
43
  *
32
44
  * @since 0.1.0
@@ -43,15 +55,10 @@ import * as Option from "effect/Option"
43
55
  import * as Schedule from "effect/Schedule"
44
56
  import type * as Schema from "effect/Schema"
45
57
  import * as Stream from "effect/Stream"
58
+ import * as Confirmations from "./internal/confirmations.ts"
46
59
  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"
60
+ import type { SolanaSignatureInfo, SolanaTransactionEncoding, SolanaTransactionInfo } from "./SolanaRpc.ts"
61
+ import { SolanaRpc, SolanaRpcError } from "./SolanaRpc.ts"
55
62
  import type { SolanaTransactionHash } from "./SolanaTransactionHash.ts"
56
63
 
57
64
  /**
@@ -122,6 +129,35 @@ export interface SolanaIndexerStreamOptions {
122
129
  readonly retry?: Schedule.Schedule<unknown, SolanaRpcError> | undefined
123
130
  }
124
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
+
125
161
  /**
126
162
  * @since 0.1.0
127
163
  * @category services
@@ -155,6 +191,23 @@ export class SolanaIndexer extends Context.Service<SolanaIndexer, {
155
191
  options: SolanaIndexerStreamOptions & { readonly encoding: Encoding }
156
192
  ): Stream.Stream<SolanaIndexerBatch<Encoding>, SolanaRpcError>
157
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>
158
211
  }>()("@effect-blockchain/solana/SolanaIndexer") {}
159
212
 
160
213
  // the node's maximum `limit`
@@ -199,12 +252,42 @@ interface StreamPosition {
199
252
  readonly cap: bigint
200
253
  readonly groups: ReadonlyArray<Arr.NonEmptyReadonlyArray<SolanaSignatureInfo>>
201
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>>]
202
257
  type Step = readonly [ReadonlyArray<SolanaIndexerBatch<SolanaTransactionEncoding>>, Option.Option<StreamPosition>]
203
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
+
204
287
  /**
205
288
  * Builds a {@link SolanaIndexer} on the provided {@link SolanaRpc}.
206
289
  *
207
- * - `confirmations` defaults to {@link SolanaNetwork.defaultConfirmations} for the RPC's network.
290
+ * - `confirmations` defaults to `SolanaNetwork.defaultConfirmations` for the RPC's network.
208
291
  * - `maxBatchSize`, a positive integer, the signatures per `streamTransactions` batch, defaults to
209
292
  * {@link DEFAULT_MAX_BATCH_SIZE}.
210
293
  *
@@ -225,39 +308,37 @@ export const layer = (options: {
225
308
  if (!Number.isSafeInteger(maxBatchSize) || maxBatchSize < 1) {
226
309
  return yield* Effect.die(new RangeError(`maxBatchSize must be a positive integer, got ${maxBatchSize}`))
227
310
  }
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))),
311
+ const lastConfirmedBlock = Confirmations.lastConfirmedBlock(rpc, options.confirmations).pipe(
231
312
  Effect.withSpan("SolanaIndexer.lastConfirmedBlock")
232
313
  )
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) =>
314
+ // the signatures of `address`, newest first, a page read only when the previous one is consumed
315
+ const signatures = (address: SolanaAddress, minContextSlot: bigint) =>
236
316
  Stream.paginate(
237
317
  Option.none<SolanaTransactionHash>(),
238
318
  (before) =>
239
319
  rpc.getSignaturesForAddress({
240
- address: filter.address,
320
+ address,
241
321
  before: Option.getOrUndefined(before),
242
322
  limit: PAGE_SIZE,
243
323
  commitment: COMMITMENT,
244
- minContextSlot: filter.toBlock
324
+ minContextSlot
245
325
  }).pipe(Effect.map((page) => {
246
326
  const last = page.at(-1)
247
327
  return [
248
328
  page,
249
- last === undefined || page.length < PAGE_SIZE || last.slot < filter.fromBlock
250
- ? Option.none()
251
- : Option.some(Option.some(last.signature))
329
+ last === undefined || page.length < PAGE_SIZE ? Option.none() : Option.some(Option.some(last.signature))
252
330
  ] as const
253
331
  }))
254
- ).pipe(
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),
255
338
  Stream.runCollect,
256
339
  // newest first, so reversed slots ascend. The order within a slot is undocumented: reversing it is a best
257
340
  // 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
- )
341
+ Effect.map((signatures) => Arr.reverse(Arr.filter(signatures, ({ slot }) => slot <= filter.toBlock)))
261
342
  )
262
343
  const fetchEach = (signatures: ReadonlyArray<SolanaSignatureInfo>, encoding: SolanaTransactionEncoding) =>
263
344
  Effect.forEach(signatures, ({ err, signature }) =>
@@ -342,18 +423,113 @@ export const layer = (options: {
342
423
  }
343
424
  return Stream.paginate(
344
425
  { 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
- })
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
+ )
353
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))
354
524
  }
355
525
 
356
- return SolanaIndexer.of({ lastConfirmedBlock, fetchTransactions, streamTransactions })
526
+ return SolanaIndexer.of({
527
+ lastConfirmedBlock,
528
+ fetchTransactions,
529
+ streamTransactions,
530
+ fetchNativeBalance,
531
+ streamNativeBalance
532
+ })
357
533
  })
358
534
  )
359
535