@effect-blockchain/stellar 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 (48) hide show
  1. package/LICENSE +21 -0
  2. package/README.md +12 -2
  3. package/dist/StellarAddress.d.ts +48 -0
  4. package/dist/StellarAddress.d.ts.map +1 -0
  5. package/dist/StellarAddress.js +68 -0
  6. package/dist/StellarAddress.js.map +1 -0
  7. package/dist/StellarContractEvent.d.ts +41 -0
  8. package/dist/StellarContractEvent.d.ts.map +1 -0
  9. package/dist/StellarContractEvent.js +49 -0
  10. package/dist/StellarContractEvent.js.map +1 -0
  11. package/dist/StellarIndexer.d.ts +121 -0
  12. package/dist/StellarIndexer.d.ts.map +1 -0
  13. package/dist/StellarIndexer.js +186 -0
  14. package/dist/StellarIndexer.js.map +1 -0
  15. package/dist/StellarNetwork.d.ts +56 -0
  16. package/dist/StellarNetwork.d.ts.map +1 -0
  17. package/dist/StellarNetwork.js +67 -0
  18. package/dist/StellarNetwork.js.map +1 -0
  19. package/dist/StellarRpc.d.ts +198 -0
  20. package/dist/StellarRpc.d.ts.map +1 -0
  21. package/dist/StellarRpc.js +244 -0
  22. package/dist/StellarRpc.js.map +1 -0
  23. package/dist/StellarTransactionHash.d.ts +17 -0
  24. package/dist/StellarTransactionHash.d.ts.map +1 -0
  25. package/dist/StellarTransactionHash.js +29 -0
  26. package/dist/StellarTransactionHash.js.map +1 -0
  27. package/dist/index.d.ts +28 -0
  28. package/dist/index.d.ts.map +1 -0
  29. package/dist/index.js +29 -0
  30. package/dist/index.js.map +1 -0
  31. package/dist/internal/LedgerFromNumber.d.ts +2 -0
  32. package/dist/internal/LedgerFromNumber.d.ts.map +1 -0
  33. package/dist/internal/LedgerFromNumber.js +12 -0
  34. package/dist/internal/LedgerFromNumber.js.map +1 -0
  35. package/dist/internal/rpcMethods.d.ts +2 -0
  36. package/dist/internal/rpcMethods.d.ts.map +1 -0
  37. package/dist/internal/rpcMethods.js +64 -0
  38. package/dist/internal/rpcMethods.js.map +1 -0
  39. package/package.json +68 -3
  40. package/src/StellarAddress.ts +114 -0
  41. package/src/StellarContractEvent.ts +54 -0
  42. package/src/StellarIndexer.ts +260 -0
  43. package/src/StellarNetwork.ts +82 -0
  44. package/src/StellarRpc.ts +371 -0
  45. package/src/StellarTransactionHash.ts +41 -0
  46. package/src/index.ts +35 -0
  47. package/src/internal/LedgerFromNumber.ts +11 -0
  48. package/src/internal/rpcMethods.ts +54 -0
@@ -0,0 +1,12 @@
1
+ import * as Schema from "effect/Schema";
2
+ import * as SchemaTransformation from "effect/SchemaTransformation";
3
+ /**
4
+ * A ledger sequence, a JSON number on the wire, decoded to a `bigint` like EVM block numbers.
5
+ *
6
+ * @internal
7
+ */
8
+ export const LedgerFromNumber = /*#__PURE__*/Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)).pipe(/*#__PURE__*/Schema.decodeTo(Schema.BigInt, /*#__PURE__*/SchemaTransformation.transform({
9
+ decode: BigInt,
10
+ encode: Number
11
+ })));
12
+ //# sourceMappingURL=LedgerFromNumber.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"LedgerFromNumber.js","names":[],"sources":["../../src/internal/LedgerFromNumber.ts"],"sourcesContent":[null],"mappings":"AAAA,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,OAAO,KAAK,oBAAoB,MAAM,6BAA6B;AAEnE;;;;;AAKA,OAAO,MAAM,gBAAgB,gBAAG,MAAM,CAAC,GAAG,CAAC,KAAK,CAAC,MAAM,CAAC,sBAAsB,CAAC,CAAC,CAAC,CAAC,CAAC,IAAI,cACrF,MAAM,CAAC,QAAQ,CAAC,MAAM,CAAC,MAAM,eAAE,oBAAoB,CAAC,SAAS,CAAC;EAAE,MAAM,EAAE,MAAM;EAAE,MAAM,EAAE;AAAM,CAAE,CAAC,CAAC,CACnG","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,64 @@
1
+ import * as Schema from "effect/Schema";
2
+ import { StellarContractAddress } from "../StellarAddress.js";
3
+ import { StellarContractEvent } from "../StellarContractEvent.js";
4
+ import { LedgerFromNumber } from "./LedgerFromNumber.js";
5
+ const make = method => method;
6
+ const NoParams = Schema.Undefined;
7
+ /**
8
+ * An RPC paging cursor or event id: a 19-digit TOID and a 10-digit event index.
9
+ *
10
+ * @internal
11
+ */
12
+ export const Cursor = /*#__PURE__*/Schema.String.check(/*#__PURE__*/Schema.isPattern(/^\d{19}-\d{10}$/u));
13
+ /** @internal */
14
+ export const getNetwork = /*#__PURE__*/make({
15
+ name: "getNetwork",
16
+ params: NoParams,
17
+ result: /*#__PURE__*/Schema.Struct({
18
+ passphrase: Schema.String,
19
+ protocolVersion: Schema.Int
20
+ })
21
+ });
22
+ /** @internal */
23
+ export const getLatestLedger = /*#__PURE__*/make({
24
+ name: "getLatestLedger",
25
+ params: NoParams,
26
+ result: /*#__PURE__*/Schema.Struct({
27
+ id: Schema.String,
28
+ protocolVersion: Schema.Int,
29
+ sequence: LedgerFromNumber
30
+ })
31
+ });
32
+ /** @internal */
33
+ export const getHealth = /*#__PURE__*/make({
34
+ name: "getHealth",
35
+ params: NoParams,
36
+ result: /*#__PURE__*/Schema.Struct({
37
+ latestLedger: LedgerFromNumber,
38
+ oldestLedger: LedgerFromNumber
39
+ })
40
+ });
41
+ /** @internal */
42
+ export const getEvents = /*#__PURE__*/make({
43
+ name: "getEvents",
44
+ params: /*#__PURE__*/Schema.Struct({
45
+ // `endLedger` is exclusive, and both bounds must be left out when paging with a cursor
46
+ startLedger: /*#__PURE__*/Schema.optionalKey(LedgerFromNumber),
47
+ endLedger: /*#__PURE__*/Schema.optionalKey(LedgerFromNumber),
48
+ filters: /*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Struct({
49
+ type: /*#__PURE__*/Schema.Literal("contract"),
50
+ contractIds: /*#__PURE__*/Schema.Array(StellarContractAddress),
51
+ topics: /*#__PURE__*/Schema.optionalKey(/*#__PURE__*/Schema.Array(/*#__PURE__*/Schema.Array(Schema.String)))
52
+ })),
53
+ pagination: /*#__PURE__*/Schema.Struct({
54
+ cursor: /*#__PURE__*/Schema.optionalKey(Cursor),
55
+ limit: Schema.Int
56
+ })
57
+ }),
58
+ result: /*#__PURE__*/Schema.Struct({
59
+ events: /*#__PURE__*/Schema.Array(StellarContractEvent),
60
+ cursor: Cursor,
61
+ latestLedger: LedgerFromNumber
62
+ })
63
+ });
64
+ //# sourceMappingURL=rpcMethods.js.map
@@ -0,0 +1 @@
1
+ {"version":3,"file":"rpcMethods.js","names":[],"sources":["../../src/internal/rpcMethods.ts"],"sourcesContent":[null],"mappings":"AACA,OAAO,KAAK,MAAM,MAAM,eAAe;AACvC,SAAS,sBAAsB,QAAQ,sBAAsB;AAC7D,SAAS,oBAAoB,QAAQ,4BAA4B;AACjE,SAAS,gBAAgB,QAAQ,uBAAuB;AAExD,MAAM,IAAI,GAAe,MAAiC,IAAgC,MAAM;AAEhG,MAAM,QAAQ,GAAG,MAAM,CAAC,SAAS;AAEjC;;;;;AAKA,OAAO,MAAM,MAAM,gBAAG,MAAM,CAAC,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,SAAS,CAAC,kBAAkB,CAAC,CAAC;AAE/E;AACA,OAAO,MAAM,UAAU,gBAAG,IAAI,CAAC;EAC7B,IAAI,EAAE,YAAY;EAClB,MAAM,EAAE,QAAQ;EAChB,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC;IAAE,UAAU,EAAE,MAAM,CAAC,MAAM;IAAE,eAAe,EAAE,MAAM,CAAC;EAAG,CAAE;CACjF,CAAC;AAEF;AACA,OAAO,MAAM,eAAe,gBAAG,IAAI,CAAC;EAClC,IAAI,EAAE,iBAAiB;EACvB,MAAM,EAAE,QAAQ;EAChB,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC;IAAE,EAAE,EAAE,MAAM,CAAC,MAAM;IAAE,eAAe,EAAE,MAAM,CAAC,GAAG;IAAE,QAAQ,EAAE;EAAgB,CAAE;CACrG,CAAC;AAEF;AACA,OAAO,MAAM,SAAS,gBAAG,IAAI,CAAC;EAC5B,IAAI,EAAE,WAAW;EACjB,MAAM,EAAE,QAAQ;EAChB,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC;IAAE,YAAY,EAAE,gBAAgB;IAAE,YAAY,EAAE;EAAgB,CAAE;CACzF,CAAC;AAEF;AACA,OAAO,MAAM,SAAS,gBAAG,IAAI,CAAC;EAC5B,IAAI,EAAE,WAAW;EACjB,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC;IACpB;IACA,WAAW,eAAE,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC;IACjD,SAAS,eAAE,MAAM,CAAC,WAAW,CAAC,gBAAgB,CAAC;IAC/C,OAAO,eAAE,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,MAAM,CAAC;MAClC,IAAI,eAAE,MAAM,CAAC,OAAO,CAAC,UAAU,CAAC;MAChC,WAAW,eAAE,MAAM,CAAC,KAAK,CAAC,sBAAsB,CAAC;MACjD,MAAM,eAAE,MAAM,CAAC,WAAW,cAAC,MAAM,CAAC,KAAK,cAAC,MAAM,CAAC,KAAK,CAAC,MAAM,CAAC,MAAM,CAAC,CAAC;KACrE,CAAC,CAAC;IACH,UAAU,eAAE,MAAM,CAAC,MAAM,CAAC;MAAE,MAAM,eAAE,MAAM,CAAC,WAAW,CAAC,MAAM,CAAC;MAAE,KAAK,EAAE,MAAM,CAAC;IAAG,CAAE;GACpF,CAAC;EACF,MAAM,eAAE,MAAM,CAAC,MAAM,CAAC;IAAE,MAAM,eAAE,MAAM,CAAC,KAAK,CAAC,oBAAoB,CAAC;IAAE,MAAM,EAAE,MAAM;IAAE,YAAY,EAAE;EAAgB,CAAE;CACrH,CAAC","ignoreList":[]}
package/package.json CHANGED
@@ -1,6 +1,71 @@
1
1
  {
2
2
  "name": "@effect-blockchain/stellar",
3
- "version": "0.0.0-stage",
4
- "stub": true,
5
- "description": "Temporary package placeholder for staged publishing"
3
+ "version": "0.1.0",
4
+ "description": "Stellar blockchain toolkit for Effect",
5
+ "keywords": [
6
+ "typescript",
7
+ "effect",
8
+ "blockchain",
9
+ "stellar",
10
+ "soroban"
11
+ ],
12
+ "homepage": "https://github.com/spiko-tech/effect-blockchain",
13
+ "bugs": {
14
+ "url": "https://github.com/spiko-tech/effect-blockchain/issues"
15
+ },
16
+ "repository": {
17
+ "type": "git",
18
+ "url": "https://github.com/spiko-tech/effect-blockchain.git",
19
+ "directory": "packages/stellar"
20
+ },
21
+ "license": "MIT",
22
+ "sideEffects": [],
23
+ "type": "module",
24
+ "exports": {
25
+ "./package.json": "./package.json",
26
+ ".": "./dist/index.js",
27
+ "./*": "./dist/*.js",
28
+ "./internal/*": null,
29
+ "./index": null,
30
+ "./*/index": null
31
+ },
32
+ "files": [
33
+ "src/**/*.ts",
34
+ "dist/**/*.js",
35
+ "dist/**/*.js.map",
36
+ "dist/**/*.d.ts",
37
+ "dist/**/*.d.ts.map"
38
+ ],
39
+ "dependencies": {
40
+ "@effect-blockchain/core": "^0.1.0"
41
+ },
42
+ "devDependencies": {
43
+ "@effect/vitest": "4.1.0",
44
+ "@stellar/stellar-sdk": "16.4.1",
45
+ "effect": "4.1.0"
46
+ },
47
+ "peerDependencies": {
48
+ "@stellar/stellar-sdk": "^16.4.1",
49
+ "effect": "^4.0.0"
50
+ },
51
+ "publishConfig": {
52
+ "access": "public",
53
+ "provenance": true
54
+ },
55
+ "tags": [
56
+ "typescript",
57
+ "effect",
58
+ "blockchain",
59
+ "stellar",
60
+ "soroban"
61
+ ],
62
+ "scripts": {
63
+ "codegen": "node ../../scripts/codegen.mjs . 'src/**/index.ts'",
64
+ "build": "tsc -b tsconfig.json tsconfig.release.json && pnpm babel",
65
+ "babel": "babel dist --plugins annotate-pure-calls --out-dir dist --source-maps",
66
+ "check": "tsc -b tsconfig.json",
67
+ "test": "vitest",
68
+ "coverage": "vitest --coverage",
69
+ "record-fixtures": "node --env-file-if-exists=../../.env scripts/record-fixtures.ts"
70
+ }
6
71
  }
@@ -0,0 +1,114 @@
1
+ /**
2
+ * Stellar account (`G…`) and contract (`C…`) addresses, validated as strkeys.
3
+ *
4
+ * Muxed accounts (`M…`) are rejected: they are an off-chain multiplexing convenience on top of a `G…` account and
5
+ * cannot hold balances or be used as contract arguments.
6
+ *
7
+ * @since 0.1.0
8
+ */
9
+ import { StrKey } from "@stellar/stellar-sdk"
10
+ import { pipe } from "effect/Function"
11
+ import * as Predicate from "effect/Predicate"
12
+ import * as Schema from "effect/Schema"
13
+ import * as SchemaGetter from "effect/SchemaGetter"
14
+ import * as SchemaTransformation from "effect/SchemaTransformation"
15
+
16
+ // Declared so arbitraries encode random 32-byte payloads: random base32 strings almost never pass the CRC16 checksum.
17
+ const strKey = (expected: string, isValid: (s: string) => boolean, encode: (payload: Buffer) => string) =>
18
+ Schema.declare((u): u is string => Predicate.isString(u) && isValid(u), {
19
+ expected,
20
+ toCodecArbitrary: () =>
21
+ Schema.link<string>()(Schema.String.check(Schema.isPattern(/^[0-9a-f]{64}$/u)), {
22
+ decode: SchemaGetter.transform((hex: string) => encode(Buffer.from(hex, "hex"))),
23
+ encode: SchemaGetter.forbiddenEncoding
24
+ })
25
+ })
26
+
27
+ const stellarAccountAddressRegex = /^G[A-Z2-7]{55}$/u
28
+
29
+ /**
30
+ * A Stellar account address: a `G…` ed25519 public key strkey (56 base32 characters, checksum verified). Input is
31
+ * upper-cased before validation.
32
+ *
33
+ * @since 0.1.0
34
+ * @category schemas
35
+ */
36
+ export const StellarAccountAddress = pipe(
37
+ Schema.String,
38
+ Schema.decodeTo(Schema.String.check(Schema.isUppercased()), SchemaTransformation.toUpperCase()),
39
+ Schema.check(Schema.isPattern(stellarAccountAddressRegex, { expected: "a valid Stellar account address" })),
40
+ Schema.decodeTo(
41
+ strKey("a valid Stellar account checksum", StrKey.isValidEd25519PublicKey, StrKey.encodeEd25519PublicKey),
42
+ SchemaTransformation.passthrough()
43
+ ),
44
+ Schema.brand("StellarAccountAddress"),
45
+ Schema.annotate({
46
+ identifier: "StellarAccountAddress",
47
+ title: "Stellar account address",
48
+ description:
49
+ "a valid Stellar account address, starting with G and followed by 55 base32 characters e.g. \"GBYIQXBKEB655EB3WTRITS6RR5GXEP6SQRBLPREZHNFYKT7WBMTMPR3H\""
50
+ })
51
+ )
52
+
53
+ /**
54
+ * @since 0.1.0
55
+ * @category models
56
+ */
57
+ export type StellarAccountAddress = typeof StellarAccountAddress.Type
58
+
59
+ const stellarContractAddressRegex = /^C[A-Z2-7]{55}$/u
60
+
61
+ /**
62
+ * A Stellar (Soroban) contract address: a `C…` contract strkey (56 base32 characters, checksum verified). Input is
63
+ * upper-cased before validation.
64
+ *
65
+ * @since 0.1.0
66
+ * @category schemas
67
+ */
68
+ export const StellarContractAddress = pipe(
69
+ Schema.String,
70
+ Schema.decodeTo(Schema.String.check(Schema.isUppercased()), SchemaTransformation.toUpperCase()),
71
+ Schema.check(Schema.isPattern(stellarContractAddressRegex, { expected: "a valid Stellar contract address" })),
72
+ Schema.decodeTo(
73
+ strKey("a valid Stellar contract checksum", StrKey.isValidContract, StrKey.encodeContract),
74
+ SchemaTransformation.passthrough()
75
+ ),
76
+ Schema.brand("StellarContractAddress"),
77
+ Schema.annotate({
78
+ identifier: "StellarContractAddress",
79
+ title: "Stellar contract address",
80
+ description:
81
+ "a valid Stellar contract address, starting with C and followed by 55 base32 characters e.g. \"CCAANR7HZNOXYZD7SXS2WQLV5BAOXSRZ7V4O43IANSB355QN2RNG7WVC\""
82
+ })
83
+ )
84
+
85
+ /**
86
+ * @since 0.1.0
87
+ * @category models
88
+ */
89
+ export type StellarContractAddress = typeof StellarContractAddress.Type
90
+
91
+ /**
92
+ * Either a Stellar account address or a Stellar contract address.
93
+ *
94
+ * @since 0.1.0
95
+ * @category schemas
96
+ */
97
+ export const StellarAddress = Schema.Union([StellarAccountAddress, StellarContractAddress])
98
+
99
+ /**
100
+ * @since 0.1.0
101
+ * @category models
102
+ */
103
+ export type StellarAddress = typeof StellarAddress.Type
104
+
105
+ /**
106
+ * The all-zero ed25519 account, used by Soroban as a placeholder source account (`contract.NULL_ACCOUNT` in
107
+ * `@stellar/stellar-sdk`).
108
+ *
109
+ * @since 0.1.0
110
+ * @category constants
111
+ */
112
+ export const NULL_ADDRESS: StellarAccountAddress = StellarAccountAddress.make(
113
+ "GAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAAWHF"
114
+ )
@@ -0,0 +1,54 @@
1
+ /**
2
+ * Soroban contract events, as returned by Stellar RPC `getEvents`.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Effect from "effect/Effect"
7
+ import { identity } from "effect/Function"
8
+ import * as Schema from "effect/Schema"
9
+ import * as SchemaTransformation from "effect/SchemaTransformation"
10
+ import { LedgerFromNumber } from "./internal/LedgerFromNumber.ts"
11
+ import { StellarContractAddress } from "./StellarAddress.ts"
12
+ import { StellarTransactionHash } from "./StellarTransactionHash.ts"
13
+
14
+ // the RPC sends the hash without `0x`: encode back to that shape
15
+ const RpcTransactionHash = Schema.String.pipe(
16
+ Schema.decodeTo(
17
+ StellarTransactionHash,
18
+ SchemaTransformation.transform({ decode: identity, encode: (hash: string) => hash.replace(/^0x/u, "") })
19
+ )
20
+ )
21
+
22
+ /**
23
+ * A contract event, decoded from the raw `getEvents` event. The encoded side is the RPC shape (`ledger`, `txHash`,
24
+ * `topic`), the decoded side uses the names shared with the other chains (`blockNumber`, `transactionHash`, `topics`).
25
+ *
26
+ * - `id` is the RPC event id, a 19-digit TOID and a 10-digit event index: sorting ids as strings gives chain order.
27
+ * - `topics` and `value` are base64 XDR `ScVal`s, left undecoded. The RPC omits `topic` when empty.
28
+ * - `inSuccessfulContractCall` is kept raw: filtering out events of failed calls is the indexer's job. Stellar RPC
29
+ * stopped sending it once it was always `true` (protocol 23 no longer emits events of failed calls), so a missing
30
+ * field decodes to `true`.
31
+ *
32
+ * @since 0.1.0
33
+ * @category schemas
34
+ */
35
+ export const StellarContractEvent = Schema.Struct({
36
+ id: Schema.String.check(Schema.isPattern(/^\d{19}-\d{10}$/u)),
37
+ type: Schema.Literals(["contract", "system", "diagnostic"]),
38
+ contractId: StellarContractAddress,
39
+ topics: Schema.Array(Schema.String).pipe(Schema.withDecodingDefaultKey(Effect.succeed([]))),
40
+ value: Schema.String,
41
+ blockNumber: LedgerFromNumber,
42
+ ledgerClosedAt: Schema.String,
43
+ transactionHash: RpcTransactionHash,
44
+ inSuccessfulContractCall: Schema.Boolean.pipe(Schema.withDecodingDefaultKey(Effect.succeed(true)))
45
+ }).pipe(
46
+ Schema.encodeKeys({ topics: "topic", blockNumber: "ledger", transactionHash: "txHash" }),
47
+ Schema.annotate({ identifier: "StellarContractEvent", title: "Stellar contract event" })
48
+ )
49
+
50
+ /**
51
+ * @since 0.1.0
52
+ * @category models
53
+ */
54
+ export type StellarContractEvent = typeof StellarContractEvent.Type
@@ -0,0 +1,260 @@
1
+ /**
2
+ * Soroban contract event indexing on top of {@link StellarRpc}: the last confirmed ledger, the events of a set of
3
+ * contracts over a ledger range, and a stream of them following the confirmed head.
4
+ *
5
+ * A range is split into ranges of at most `maxBlockRange` ledgers, each paged with `getEvents` until its cursor is
6
+ * `undefined`. `contractIds` is split into groups of 5, the RPC limit per filter (`MaxContractIDsLimit` in
7
+ * https://github.com/stellar/go-stellar-sdk/blob/main/protocols/rpc/get_events.go), merged back in event id order. A
8
+ * cursor page is pinned to the endpoint that issued it, so when it fails the group restarts once from its first page.
9
+ * Any other failure fails the whole call and drops the events already read: the caller retries the same range.
10
+ *
11
+ * @example
12
+ * ```ts
13
+ * import type { StellarIndexerFilter } from "@effect-blockchain/stellar/StellarIndexer"
14
+ * import { StellarIndexer } from "@effect-blockchain/stellar/StellarIndexer"
15
+ * import * as Effect from "effect/Effect"
16
+ * import * as Schedule from "effect/Schedule"
17
+ * import * as Stream from "effect/Stream"
18
+ *
19
+ * declare const filter: Omit<StellarIndexerFilter, "fromBlock" | "toBlock">
20
+ * declare const cursor: bigint
21
+ * declare const save: (ledger: bigint) => Effect.Effect<void>
22
+ *
23
+ * const program = Effect.gen(function*() {
24
+ * const indexer = yield* StellarIndexer
25
+ * // once caught up, read the head after 1 s, 2 s, 4 s... at most every minute
26
+ * const poll = Schedule.min([Schedule.exponential("1 second"), Schedule.spaced("1 minute")])
27
+ * yield* indexer.streamEvents({ filter, fromBlock: cursor + BigInt(1), poll }).pipe(
28
+ * Stream.runForEach((batch) => save(batch.toBlock))
29
+ * )
30
+ * })
31
+ * ```
32
+ *
33
+ * @since 0.1.0
34
+ */
35
+ import * as JsonRpc from "@effect-blockchain/core/JsonRpc"
36
+ import * as Arr from "effect/Array"
37
+ import * as BigInt_ from "effect/BigInt"
38
+ import * as Config from "effect/Config"
39
+ import * as Context from "effect/Context"
40
+ import * as Duration from "effect/Duration"
41
+ import * as Effect from "effect/Effect"
42
+ import * as Layer from "effect/Layer"
43
+ import * as Option from "effect/Option"
44
+ import * as Order from "effect/Order"
45
+ import * as Schedule from "effect/Schedule"
46
+ import * as Stream from "effect/Stream"
47
+ import type { StellarContractEvent } from "./StellarContractEvent.ts"
48
+ import * as StellarNetwork from "./StellarNetwork.ts"
49
+ import type { StellarEventsCursor, StellarEventsFilter, StellarRpcError } from "./StellarRpc.ts"
50
+ import { StellarRpc } from "./StellarRpc.ts"
51
+
52
+ /**
53
+ * The default `maxBlockRange`: 10000 ledgers, the most a Stellar RPC scans per request (`LedgerScanLimit` in
54
+ * https://github.com/stellar/stellar-rpc/blob/main/cmd/stellar-rpc/internal/methods/get_events.go).
55
+ *
56
+ * @since 0.1.0
57
+ * @category constants
58
+ */
59
+ export const DEFAULT_MAX_BLOCK_RANGE = 10_000
60
+
61
+ /**
62
+ * A {@link StellarEventsFilter} without its paging fields (`limit`, `cursor`), over the inclusive ledger range
63
+ * `[fromBlock, toBlock]`. `contractIds` has no size limit here.
64
+ *
65
+ * @since 0.1.0
66
+ * @category models
67
+ */
68
+ export type StellarIndexerFilter = Omit<StellarEventsFilter, "limit" | "cursor">
69
+
70
+ /**
71
+ * The events of the ledgers `[fromBlock, toBlock]` (both inclusive), in chain order, emitted by
72
+ * {@link StellarIndexer.Service.streamEvents}.
73
+ *
74
+ * A batch is emitted for every range, even without events. Delivery is at-least-once: save `batch.toBlock` once the
75
+ * batch is handled and resume from `toBlock + 1`. RPC nodes keep about 7 days of ledgers: an older `fromBlock` fails
76
+ * the stream with `Pruned`.
77
+ *
78
+ * @since 0.1.0
79
+ * @category models
80
+ */
81
+ export interface StellarIndexerBatch {
82
+ readonly fromBlock: bigint
83
+ readonly toBlock: bigint
84
+ readonly events: ReadonlyArray<StellarContractEvent>
85
+ }
86
+
87
+ /**
88
+ * The {@link StellarIndexer.Service.streamEvents} options.
89
+ *
90
+ * @since 0.1.0
91
+ * @category models
92
+ */
93
+ export interface StellarIndexerStreamOptions {
94
+ readonly filter: Omit<StellarIndexerFilter, "fromBlock" | "toBlock">
95
+ readonly fromBlock: bigint
96
+ /** The stream ends after the batch reaching it, and is empty when `fromBlock > toBlock`. */
97
+ readonly toBlock?: bigint | undefined
98
+ /**
99
+ * When to read the head again once caught up, `Schedule.spaced(DEFAULT_POLL_INTERVAL)` by default. It restarts after
100
+ * each batch, and its end ends the stream: `Schedule.recurs(0)` drains to the head and stops.
101
+ */
102
+ readonly poll?: Schedule.Schedule<unknown> | undefined
103
+ /** Retries a step failing with a transient reason ({@link JsonRpc.isTransient}) at the same ledger. Off by default. */
104
+ readonly retry?: Schedule.Schedule<unknown, StellarRpcError> | undefined
105
+ }
106
+
107
+ /**
108
+ * @since 0.1.0
109
+ * @category services
110
+ */
111
+ export class StellarIndexer extends Context.Service<StellarIndexer, {
112
+ /** The latest ledger minus the configured confirmations, never below 0. */
113
+ readonly lastConfirmedBlock: Effect.Effect<bigint, StellarRpcError>
114
+ /**
115
+ * Every contract event matching `filter`, in chain order (event id order). Events of failed contract calls
116
+ * (`inSuccessfulContractCall: false`) are dropped. `fromBlock > toBlock` returns no events.
117
+ */
118
+ readonly fetchEvents: (
119
+ filter: StellarIndexerFilter
120
+ ) => Effect.Effect<ReadonlyArray<StellarContractEvent>, StellarRpcError>
121
+ /**
122
+ * The events matching `filter` from `fromBlock` on, in batches of at most `maxBlockRange` confirmed ledgers,
123
+ * following the confirmed head.
124
+ */
125
+ readonly streamEvents: (options: StellarIndexerStreamOptions) => Stream.Stream<StellarIndexerBatch, StellarRpcError>
126
+ }>()("@effect-blockchain/stellar/StellarIndexer") {}
127
+
128
+ /**
129
+ * The default `poll` spacing of {@link StellarIndexer.Service.streamEvents}: 10 seconds.
130
+ *
131
+ * @since 0.1.0
132
+ * @category constants
133
+ */
134
+ export const DEFAULT_POLL_INTERVAL: Duration.Duration = Duration.seconds(10)
135
+
136
+ const MAX_CONTRACT_IDS = 5
137
+
138
+ const byId = Order.mapInput(Order.String, (event: StellarContractEvent) => event.id)
139
+
140
+ // the confirmed ledgers [next, head] not indexed yet, empty once the stream reaches the head it last read
141
+ interface StreamPosition {
142
+ readonly next: bigint
143
+ readonly head: bigint
144
+ }
145
+
146
+ /**
147
+ * Builds a {@link StellarIndexer} over the provided {@link StellarRpc}.
148
+ *
149
+ * - `confirmations`: ledgers kept behind the latest one, default {@link StellarNetwork.defaultConfirmations} of the
150
+ * RPC's network.
151
+ * - `maxBlockRange`: ledgers per range, a positive integer, default {@link DEFAULT_MAX_BLOCK_RANGE}.
152
+ * - `limit`: `getEvents` page size, default 1000, at most 10000.
153
+ *
154
+ * @since 0.1.0
155
+ * @category layers
156
+ */
157
+ export const layer = (options: {
158
+ readonly confirmations?: number | undefined
159
+ readonly maxBlockRange?: number | undefined
160
+ readonly limit?: number | undefined
161
+ } = {}): Layer.Layer<StellarIndexer, never, StellarRpc> =>
162
+ Layer.effect(
163
+ StellarIndexer,
164
+ Effect.gen(function*() {
165
+ const rpc = yield* StellarRpc
166
+ const maxBlockRange = options.maxBlockRange ?? DEFAULT_MAX_BLOCK_RANGE
167
+ if (!Number.isSafeInteger(maxBlockRange) || maxBlockRange < 1) {
168
+ return yield* Effect.die(new RangeError(`maxBlockRange must be a positive integer, got ${maxBlockRange}`))
169
+ }
170
+ const confirmations = BigInt(options.confirmations ?? StellarNetwork.defaultConfirmations(rpc.network))
171
+ const range = BigInt(maxBlockRange)
172
+ const { limit } = options
173
+
174
+ const lastConfirmedBlock = rpc.getLatestLedger.pipe(
175
+ Effect.map((ledger) => BigInt_.max(ledger.sequence - confirmations, BigInt(0))),
176
+ Effect.withSpan("StellarIndexer.lastConfirmedBlock")
177
+ )
178
+ const fetchEvents = Effect.fn("StellarIndexer.fetchEvents")((filter: StellarIndexerFilter) => {
179
+ if (filter.fromBlock > filter.toBlock) return Effect.succeed([])
180
+ const groups = Arr.chunksOf(filter.contractIds, MAX_CONTRACT_IDS)
181
+ const starts = Arr.makeBy(
182
+ Number((filter.toBlock - filter.fromBlock) / range) + 1,
183
+ (i) => filter.fromBlock + BigInt(i) * range
184
+ )
185
+ return Effect.forEach(starts, (fromBlock) => {
186
+ const toBlock = BigInt_.min(fromBlock + range - BigInt(1), filter.toBlock)
187
+ return Effect.forEach(groups, (contractIds) => {
188
+ const group = { ...filter, contractIds, fromBlock, toBlock, limit }
189
+ // a cursor page has no fallback: when it fails, the group restarts once from its first page
190
+ return Stream.paginate(
191
+ Option.none<StellarEventsCursor>(),
192
+ (cursor) =>
193
+ rpc.getEvents({ ...group, cursor: Option.getOrUndefined(cursor) }).pipe(Effect.mapBoth({
194
+ onFailure: (error) => Option.isNone(cursor) ? error : { cursorPage: error },
195
+ onSuccess: (page) =>
196
+ [page.events, Option.map(Option.fromUndefinedOr(page.cursor), Option.some)] as const
197
+ }))
198
+ ).pipe(
199
+ Stream.runCollect,
200
+ Effect.retry({ times: 1, while: (error) => "cursorPage" in error }),
201
+ Effect.mapError((error) => "cursorPage" in error ? error.cursorPage : error)
202
+ )
203
+ }).pipe(Effect.map((found) => groups.length > 1 ? Arr.sort(Arr.flatten(found), byId) : Arr.flatten(found)))
204
+ }).pipe(Effect.map((ranges) => Arr.flatten(ranges).filter((event) => event.inSuccessfulContractCall)))
205
+ })
206
+ return StellarIndexer.of({
207
+ lastConfirmedBlock,
208
+ fetchEvents,
209
+ streamEvents: ({ filter, fromBlock, poll = Schedule.spaced(DEFAULT_POLL_INTERVAL), retry, toBlock }) => {
210
+ if (toBlock !== undefined && fromBlock > toBlock) return Stream.empty
211
+ // the head last read is reused while it covers `next` (the confirmed head only moves forward), else polled
212
+ const step = (
213
+ { head, next }: StreamPosition
214
+ ): Effect.Effect<
215
+ readonly [ReadonlyArray<StellarIndexerBatch>, Option.Option<StreamPosition>],
216
+ StellarRpcError
217
+ > =>
218
+ (next <= head
219
+ ? Effect.succeed(head)
220
+ : lastConfirmedBlock.pipe(Effect.repeat({ schedule: poll, until: (confirmed) => confirmed >= next })))
221
+ .pipe(Effect.flatMap((confirmed) => {
222
+ const cap = toBlock === undefined ? confirmed : BigInt_.min(confirmed, toBlock)
223
+ if (next > cap) return Effect.succeed([[], Option.none()])
224
+ const end = BigInt_.min(next + range - BigInt(1), cap)
225
+ return fetchEvents({ ...filter, fromBlock: next, toBlock: end }).pipe(Effect.map((events) => [
226
+ [{ fromBlock: next, toBlock: end, events }],
227
+ end === toBlock ? Option.none() : Option.some({ next: end + BigInt(1), head: confirmed })
228
+ ]))
229
+ }))
230
+ return Stream.paginate(
231
+ // a head below `fromBlock`: the first step reads it
232
+ { next: fromBlock, head: fromBlock - BigInt(1) },
233
+ retry === undefined
234
+ ? step
235
+ : (remaining) =>
236
+ Effect.retry(step(remaining), { schedule: retry, while: (error) => JsonRpc.isTransient(error.reason) })
237
+ )
238
+ }
239
+ })
240
+ })
241
+ )
242
+
243
+ /**
244
+ * Builds an {@link StellarIndexer} like {@link layer}, reading the options from `Config`.
245
+ *
246
+ * @example
247
+ * ```ts
248
+ * import * as StellarIndexer from "@effect-blockchain/stellar/StellarIndexer"
249
+ * import * as Config from "effect/Config"
250
+ *
251
+ * const IndexerLive = StellarIndexer.layerConfig({ confirmations: Config.Int("STELLAR_CONFIRMATIONS") })
252
+ * ```
253
+ *
254
+ * @since 0.1.0
255
+ * @category layers
256
+ */
257
+ export const layerConfig = (
258
+ options: Config.Wrap<NonNullable<Parameters<typeof layer>[0]>>
259
+ ): Layer.Layer<StellarIndexer, Config.ConfigError, StellarRpc> =>
260
+ Layer.unwrap(Effect.map(Config.unwrap(options), layer))
@@ -0,0 +1,82 @@
1
+ /**
2
+ * Named Stellar networks and their passphrases.
3
+ *
4
+ * @since 0.1.0
5
+ */
6
+ import * as Schema from "effect/Schema"
7
+
8
+ /**
9
+ * @since 0.1.0
10
+ * @category constants
11
+ */
12
+ export const mainnets = ["Stellar"] as const
13
+
14
+ /**
15
+ * @since 0.1.0
16
+ * @category constants
17
+ */
18
+ export const testnets = ["StellarTestnet"] as const
19
+
20
+ /**
21
+ * Every supported network, mainnets first.
22
+ *
23
+ * @since 0.1.0
24
+ * @category constants
25
+ */
26
+ export const networks = [...mainnets, ...testnets] as const
27
+
28
+ /**
29
+ * A named Stellar network: `Stellar` (public mainnet) or `StellarTestnet`.
30
+ *
31
+ * @since 0.1.0
32
+ * @category schemas
33
+ */
34
+ export const StellarNetwork = Schema.Literals(networks).annotate({
35
+ identifier: "StellarNetwork",
36
+ title: "Stellar network",
37
+ description: "a Stellar network name"
38
+ })
39
+
40
+ /**
41
+ * @since 0.1.0
42
+ * @category models
43
+ */
44
+ export type StellarNetwork = typeof StellarNetwork.Type
45
+
46
+ // same values as `Networks.PUBLIC` / `Networks.TESTNET` in `@stellar/stellar-sdk`
47
+ const passphrases: Record<StellarNetwork, string> = {
48
+ Stellar: "Public Global Stellar Network ; September 2015",
49
+ StellarTestnet: "Test SDF Network ; September 2015"
50
+ }
51
+
52
+ /**
53
+ * The network passphrase, used to sign transactions and reported by `getNetwork`.
54
+ *
55
+ * @since 0.1.0
56
+ * @category conversions
57
+ */
58
+ export const toPassphrase = (network: StellarNetwork): string => passphrases[network]
59
+
60
+ const confirmations: Record<StellarNetwork, number> = {
61
+ // SCP gives deterministic finality, a closed ledger is never reverted:
62
+ // https://developers.stellar.org/docs/learn/fundamentals/stellar-consensus-protocol
63
+ Stellar: 0,
64
+ // same consensus as mainnet (testnet resets wipe all history, they do not reorganise closed ledgers)
65
+ StellarTestnet: 0
66
+ }
67
+
68
+ /**
69
+ * Ledgers to wait behind the latest closed ledger before treating it as confirmed: `0`, Stellar has no forks and a
70
+ * ledger is final once closed.
71
+ *
72
+ * @since 0.1.0
73
+ * @category getters
74
+ */
75
+ export const defaultConfirmations = (network: StellarNetwork): number => confirmations[network]
76
+
77
+ /**
78
+ * @since 0.1.0
79
+ * @category predicates
80
+ */
81
+ export const isTestnet = (network: StellarNetwork): boolean =>
82
+ (testnets as ReadonlyArray<StellarNetwork>).includes(network)