@radix-effects/transaction-stream 0.1.0

package/README.md

@@ -0,0 +1,127 @@
+# @radix-effects/transaction-stream
+
+Stream transactions from the Radix network using [Effect](https://effect.website/).
+
+## Installation
+
+```bash
+npm install @radix-effects/transaction-stream
+```
+
+## Usage
+
+```typescript
+import { Effect, Layer, Stream, Ref, Option, Duration } from 'effect';
+import {
+  TransactionStreamService,
+  ConfigService,
+  TransactionDetailsOptInsSchema,
+} from '@radix-effects/transaction-stream';
+
+const program = Effect.gen(function* () {
+  // Create the transaction stream
+  const stream = yield* TransactionStreamService.pipe(
+    Effect.provide(TransactionStreamService.Default),
+  );
+
+  // Configure the stream
+  const configRef = yield* ConfigService.make;
+  yield* Ref.update(configRef, (config) => ({
+    ...config,
+    stateVersion: Option.some(1), // Start from state version 1
+    limitPerPage: 100,
+    waitTime: Duration.seconds(60),
+    optIns: TransactionDetailsOptInsSchema.make({
+      detailed_events: true,
+      balance_changes: true,
+    }),
+  }));
+
+  // Process transactions
+  yield* Stream.runForEach(stream, (transactions) =>
+    Effect.gen(function* () {
+      for (const tx of transactions) {
+        yield* Effect.log(`Processing tx: ${tx.intent_hash}`);
+      }
+    }),
+  ).pipe(
+    Effect.provide(Layer.effect(ConfigService, Effect.succeed(configRef))),
+  );
+});
+```
+
+## Configuration
+
+The `ConfigService` allows you to configure the transaction stream:
+
+| Option         | Type                        | Default             | Description                                   |
+| -------------- | --------------------------- | ------------------- | --------------------------------------------- |
+| `stateVersion` | `Option<number>`            | `Option.none()`     | Starting state version (none = current)       |
+| `limitPerPage` | `number`                    | `100`               | Number of transactions per page               |
+| `waitTime`     | `Duration`                  | `Duration.seconds(60)` | Wait time when no new transactions available |
+| `optIns`       | `TransactionDetailsOptIns`  | See below           | Optional data to include in response          |
+
+### Opt-ins
+
+Control what data is included in the transaction response:
+
+```typescript
+TransactionDetailsOptInsSchema.make({
+  raw_hex: false,                  // Raw transaction hex
+  receipt_state_changes: false,    // State changes in receipt
+  receipt_fee_summary: false,      // Fee summary in receipt
+  receipt_fee_source: false,       // Fee source in receipt
+  receipt_fee_destination: false,  // Fee destination in receipt
+  receipt_costing_parameters: false, // Costing parameters in receipt
+  receipt_events: false,           // Events in receipt (deprecated)
+  detailed_events: false,          // Detailed events object
+  receipt_output: true,            // Transaction receipt output
+  affected_global_entities: false, // Affected global entities
+  manifest_instructions: false,    // Manifest instructions
+  balance_changes: false,          // Fungible/non-fungible balance changes
+});
+```
+
+## Multiple Networks
+
+You can run multiple streams for different networks simultaneously:
+
+```typescript
+import { ConfigProvider, Fiber } from 'effect';
+
+const program = Effect.gen(function* () {
+  // Configure for Stokenet (network ID 2)
+  const stokenetConfig = Layer.setConfigProvider(
+    ConfigProvider.fromJson({ NETWORK_ID: '2' }),
+  );
+
+  const stokenetStream = yield* TransactionStreamService.pipe(
+    Effect.provide(TransactionStreamService.Default),
+    Effect.provide(stokenetConfig),
+  );
+
+  // Mainnet uses default config (network ID 1)
+  const mainnetStream = yield* TransactionStreamService.pipe(
+    Effect.provide(TransactionStreamService.Default),
+  );
+
+  // Run both streams concurrently
+  const stokenetFiber = yield* Effect.fork(
+    Stream.runForEach(stokenetStream, processTransactions).pipe(
+      Effect.provide(Layer.effect(ConfigService, Effect.succeed(stokenetConfigRef))),
+    ),
+  );
+
+  const mainnetFiber = yield* Effect.fork(
+    Stream.runForEach(mainnetStream, processTransactions).pipe(
+      Effect.provide(Layer.effect(ConfigService, Effect.succeed(mainnetConfigRef))),
+    ),
+  );
+
+  yield* Fiber.joinAll([stokenetFiber, mainnetFiber]);
+});
+```
+
+## License
+
+MIT

package/dist/index.d.ts

@@ -0,0 +1,177 @@
+import * as _radix_effects_gateway0 from "@radix-effects/gateway";
+import { GatewayApiClient } from "@radix-effects/gateway";
+import { Context, Duration, Effect, Layer, Option, Ref, Schema, Stream } from "effect";
+import * as _radixdlt_babylon_gateway_api_sdk0 from "@radixdlt/babylon-gateway-api-sdk";
+import * as effect_Effect0 from "effect/Effect";
+
+//#region src/config.d.ts
+declare const ConfigService_base: Context.TagClass<ConfigService, "Config", Ref.Ref<{
+  readonly stateVersion: Option.Option<number>;
+  readonly limitPerPage: number;
+  readonly waitTime: Duration.Duration;
+  readonly optIns: {
+    readonly raw_hex: boolean;
+    readonly receipt_state_changes: boolean;
+    readonly receipt_fee_summary: boolean;
+    readonly receipt_fee_source: boolean;
+    readonly receipt_fee_destination: boolean;
+    readonly receipt_costing_parameters: boolean;
+    readonly receipt_events: boolean;
+    readonly detailed_events: boolean;
+    readonly receipt_output: boolean;
+    readonly affected_global_entities: boolean;
+    readonly manifest_instructions: boolean;
+    readonly balance_changes: boolean;
+  };
+}>>;
+declare class ConfigService extends ConfigService_base {
+  static make: effect_Effect0.Effect<Ref.Ref<{
+    readonly stateVersion: Option.Option<number>;
+    readonly limitPerPage: number;
+    readonly waitTime: Duration.Duration;
+    readonly optIns: {
+      readonly raw_hex: boolean;
+      readonly receipt_state_changes: boolean;
+      readonly receipt_fee_summary: boolean;
+      readonly receipt_fee_source: boolean;
+      readonly receipt_fee_destination: boolean;
+      readonly receipt_costing_parameters: boolean;
+      readonly receipt_events: boolean;
+      readonly detailed_events: boolean;
+      readonly receipt_output: boolean;
+      readonly affected_global_entities: boolean;
+      readonly manifest_instructions: boolean;
+      readonly balance_changes: boolean;
+    };
+  }>, never, never>;
+}
+//#endregion
+//#region src/streamer.d.ts
+declare const TransactionStreamService_base: Effect.Service.Class<TransactionStreamService, "TransactionStreamService", {
+  readonly dependencies: readonly [Layer.Layer<GatewayApiClient, never, never>];
+  readonly effect: Effect.Effect<Stream.Stream<_radixdlt_babylon_gateway_api_sdk0.CommittedTransactionInfo[], _radix_effects_gateway0.InvalidRequestError | _radix_effects_gateway0.InternalServerError | _radix_effects_gateway0.NotSyncedUpError | _radix_effects_gateway0.RateLimitExceededError | _radix_effects_gateway0.UnknownGatewayError, ConfigService>, never, GatewayApiClient>;
+}>;
+declare class TransactionStreamService extends TransactionStreamService_base {}
+//#endregion
+//#region src/schemas.d.ts
+declare const TransactionDetailsOptInsSchema: Schema.Struct<{
+  /** if set to `true`, raw transaction hex is returned. */
+  raw_hex: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, state changes inside receipt object are returned. */
+  receipt_state_changes: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, fee summary inside receipt object is returned. */
+  receipt_fee_summary: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, fee source inside receipt object is returned. */
+  receipt_fee_source: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, fee destination inside receipt object is returned. */
+  receipt_fee_destination: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, costing parameters inside receipt object is returned. */
+  receipt_costing_parameters: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /**
+   * if set to `true`, events inside receipt object is returned.
+   * @deprecated Please use `detailed_events` instead.
+   */
+  receipt_events: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, detailed events object is returned. */
+  detailed_events: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** (true by default) if set to `true`, transaction receipt output is returned. */
+  receipt_output: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => true;
+  }>;
+  /** if set to `true`, all affected global entities by given transaction are returned. */
+  affected_global_entities: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /** if set to `true`, manifest instructions for user transactions are returned. */
+  manifest_instructions: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+  /**
+   * if set to `true`, returns the fungible and non-fungible balance changes.
+   * Warning: This opt-in might be missing for recently committed transactions.
+   */
+  balance_changes: Schema.optionalWith<typeof Schema.Boolean, {
+    default: () => false;
+  }>;
+}>;
+type TransactionDetailsOptIns = typeof TransactionDetailsOptInsSchema.Type;
+declare const ConfigSchema: Schema.Struct<{
+  stateVersion: Schema.Option<typeof Schema.Number>;
+  limitPerPage: typeof Schema.Number;
+  waitTime: typeof Schema.Duration;
+  optIns: Schema.Struct<{
+    /** if set to `true`, raw transaction hex is returned. */
+    raw_hex: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, state changes inside receipt object are returned. */
+    receipt_state_changes: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, fee summary inside receipt object is returned. */
+    receipt_fee_summary: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, fee source inside receipt object is returned. */
+    receipt_fee_source: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, fee destination inside receipt object is returned. */
+    receipt_fee_destination: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, costing parameters inside receipt object is returned. */
+    receipt_costing_parameters: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /**
+     * if set to `true`, events inside receipt object is returned.
+     * @deprecated Please use `detailed_events` instead.
+     */
+    receipt_events: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, detailed events object is returned. */
+    detailed_events: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** (true by default) if set to `true`, transaction receipt output is returned. */
+    receipt_output: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => true;
+    }>;
+    /** if set to `true`, all affected global entities by given transaction are returned. */
+    affected_global_entities: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /** if set to `true`, manifest instructions for user transactions are returned. */
+    manifest_instructions: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+    /**
+     * if set to `true`, returns the fungible and non-fungible balance changes.
+     * Warning: This opt-in might be missing for recently committed transactions.
+     */
+    balance_changes: Schema.optionalWith<typeof Schema.Boolean, {
+      default: () => false;
+    }>;
+  }>;
+}>;
+type Config = typeof ConfigSchema.Type;
+//#endregion
+export { Config, ConfigSchema, ConfigService, TransactionDetailsOptIns, TransactionDetailsOptInsSchema, TransactionStreamService };

package/dist/index.js

@@ -0,0 +1,95 @@
+import { GatewayApiClient } from "@radix-effects/gateway";
+import { Array, Context, Duration, Effect, Option, Order, Ref, Schema, Stream, pipe } from "effect";
+
+//#region src/schemas.ts
+const TransactionDetailsOptInsSchema = Schema.Struct({
+	raw_hex: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_state_changes: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_fee_summary: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_fee_source: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_fee_destination: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_costing_parameters: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_events: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	detailed_events: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	receipt_output: Schema.optionalWith(Schema.Boolean, { default: () => true }),
+	affected_global_entities: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	manifest_instructions: Schema.optionalWith(Schema.Boolean, { default: () => false }),
+	balance_changes: Schema.optionalWith(Schema.Boolean, { default: () => false })
+});
+const ConfigSchema = Schema.Struct({
+	stateVersion: Schema.Option(Schema.Number),
+	limitPerPage: Schema.Number,
+	waitTime: Schema.Duration,
+	optIns: TransactionDetailsOptInsSchema
+});
+
+//#endregion
+//#region src/config.ts
+var ConfigService = class extends Context.Tag("Config")() {
+	static {
+		this.make = Ref.make({
+			stateVersion: Option.none(),
+			limitPerPage: 100,
+			waitTime: Duration.seconds(60),
+			optIns: TransactionDetailsOptInsSchema.make()
+		});
+	}
+};
+
+//#endregion
+//#region src/streamer.ts
+var TransactionStreamService = class extends Effect.Service()("TransactionStreamService", {
+	dependencies: [GatewayApiClient.Default],
+	effect: Effect.gen(function* () {
+		const gatewayApiClient = yield* GatewayApiClient;
+		const currentStateVersion = yield* gatewayApiClient.status.getCurrent().pipe(Effect.catchAll(Effect.die));
+		yield* Effect.logDebug(currentStateVersion.ledger_state);
+		return Stream.paginateEffect(1, () => Effect.gen(function* () {
+			const configRef = yield* ConfigService;
+			const config = yield* configRef.pipe(Ref.get);
+			const stateVersion = yield* config.stateVersion.pipe(Option.match({
+				onNone: () => gatewayApiClient.status.getCurrent().pipe(Effect.map((res) => res.ledger_state.state_version), Effect.catchAll(Effect.die)),
+				onSome: (version) => Effect.succeed(version)
+			}));
+			yield* Effect.logDebug(`fetching transactions from state version ${stateVersion}`);
+			const result = yield* gatewayApiClient.stream.innerClient.streamTransactions({ streamTransactionsRequest: {
+				limit_per_page: config.limitPerPage,
+				from_ledger_state: { state_version: stateVersion },
+				order: "Asc",
+				kind_filter: "User",
+				opt_ins: config.optIns
+			} }).pipe(Effect.catchTags({
+				AccountLockerNotFoundError: Effect.die,
+				EntityNotFoundError: Effect.die,
+				ErrorResponse: Effect.die,
+				InvalidEntityError: Effect.die,
+				InvalidTransactionError: Effect.die,
+				ResponseError: Effect.die,
+				TransactionNotFoundError: Effect.die
+			}));
+			yield* Effect.logDebug(`fetched ${result.items.length} transactions`);
+			const firstItem = pipe(result.items, Array.sortBy(Order.mapInput(Order.number, (tx) => tx.state_version)), Array.head);
+			const lastItem = pipe(result.items, Array.sortBy(Order.mapInput(Order.number, (tx) => tx.state_version)), Array.last);
+			yield* Option.all([firstItem, lastItem]).pipe(Option.match({
+				onNone: () => Effect.void,
+				onSome: ([first, last]) => Effect.log(`${first.round_timestamp} -> ${last.round_timestamp}`)
+			}));
+			const nextStateVersion = lastItem.pipe(Option.map((res) => res.state_version + 1), Option.getOrElse(() => stateVersion));
+			yield* Ref.update(configRef, (config$1) => {
+				return {
+					...config$1,
+					stateVersion: Option.some(nextStateVersion)
+				};
+			});
+			if (nextStateVersion === stateVersion) {
+				yield* Effect.logDebug("Waiting for new transactions...");
+				yield* Effect.sleep(config.waitTime);
+				return [[], Option.some(stateVersion)];
+			}
+			return [result.items, Option.some(nextStateVersion)];
+		})).pipe(Stream.filter((item) => item.length > 0));
+	})
+}) {};
+
+//#endregion
+export { ConfigSchema, ConfigService, TransactionDetailsOptInsSchema, TransactionStreamService };

package/package.json

@@ -0,0 +1,36 @@
+{
+  "name": "@radix-effects/transaction-stream",
+  "version": "0.1.0",
+  "type": "module",
+  "main": "./dist/index.js",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/xstelea/radix-web3.js.git"
+  },
+  "files": [
+    "dist"
+  ],
+  "devDependencies": {
+    "@types/node": "^22.13.10",
+    "tsdown": "^0.15.12",
+    "tsx": "^4.7.1",
+    "typescript": "^5.3.3",
+    "vitest": "^1.2.1"
+  },
+  "dependencies": {
+    "effect": "^3.14.1",
+    "@radix-effects/gateway": "0.3.0"
+  },
+  "license": "MIT",
+  "scripts": {
+    "dev": "tsx --watch src/index.ts",
+    "dev:debug": "tsx --inspect-brk --watch src/index.ts",
+    "build": "tsdown"
+  }
+}