@haneullabs/haneul 0.1.0

package/src/jsonRpc/rpc-websocket-client.ts

@@ -0,0 +1,241 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import { JsonRpcError } from './errors.js';
+
+function getWebsocketUrl(httpUrl: string): string {
+	const url = new URL(httpUrl);
+	url.protocol = url.protocol.replace('http', 'ws');
+	return url.toString();
+}
+
+type JsonRpcMessage =
+	| {
+			id: number;
+			result: never;
+			error: {
+				code: number;
+				message: string;
+			};
+	  }
+	| {
+			id: number;
+			result: unknown;
+			error: never;
+	  }
+	| {
+			method: string;
+			params: NotificationMessageParams;
+	  };
+
+type NotificationMessageParams = {
+	subscription?: number;
+	result: object;
+};
+
+type SubscriptionRequest<T = any> = {
+	method: string;
+	unsubscribe: string;
+	params: any[];
+	onMessage: (event: T) => void;
+	signal?: AbortSignal;
+};
+
+/**
+ * Configuration options for the websocket connection
+ */
+export type WebsocketClientOptions = {
+	/**
+	 * Custom WebSocket class to use. Defaults to the global WebSocket class, if available.
+	 */
+	WebSocketConstructor?: typeof WebSocket;
+	/**
+	 * Milliseconds before timing out while calling an RPC method
+	 */
+	callTimeout?: number;
+	/**
+	 * Milliseconds between attempts to connect
+	 */
+	reconnectTimeout?: number;
+	/**
+	 * Maximum number of times to try connecting before giving up
+	 */
+	maxReconnects?: number;
+};
+
+export const DEFAULT_CLIENT_OPTIONS = {
+	// We fudge the typing because we also check for undefined in the constructor:
+	WebSocketConstructor: (typeof WebSocket !== 'undefined'
+		? WebSocket
+		: undefined) as typeof WebSocket,
+	callTimeout: 30000,
+	reconnectTimeout: 3000,
+	maxReconnects: 5,
+} satisfies WebsocketClientOptions;
+
+export class WebsocketClient {
+	endpoint: string;
+	options: Required<WebsocketClientOptions>;
+	#requestId = 0;
+	#disconnects = 0;
+	#webSocket: WebSocket | null = null;
+	#connectionPromise: Promise<WebSocket> | null = null;
+	#subscriptions = new Set<RpcSubscription>();
+	#pendingRequests = new Map<
+		number,
+		{
+			resolve: (result: Extract<JsonRpcMessage, { id: number }>) => void;
+			reject: (reason: unknown) => void;
+			timeout: ReturnType<typeof setTimeout>;
+		}
+	>();
+
+	constructor(endpoint: string, options: WebsocketClientOptions = {}) {
+		this.endpoint = endpoint;
+		this.options = { ...DEFAULT_CLIENT_OPTIONS, ...options };
+
+		if (!this.options.WebSocketConstructor) {
+			throw new Error('Missing WebSocket constructor');
+		}
+
+		if (this.endpoint.startsWith('http')) {
+			this.endpoint = getWebsocketUrl(this.endpoint);
+		}
+	}
+
+	async makeRequest<T>(method: string, params: any[], signal?: AbortSignal): Promise<T> {
+		const webSocket = await this.#setupWebSocket();
+
+		return new Promise<Extract<JsonRpcMessage, { id: number }>>((resolve, reject) => {
+			this.#requestId += 1;
+			this.#pendingRequests.set(this.#requestId, {
+				resolve: resolve,
+				reject,
+				timeout: setTimeout(() => {
+					this.#pendingRequests.delete(this.#requestId);
+					reject(new Error(`Request timeout: ${method}`));
+				}, this.options.callTimeout),
+			});
+
+			signal?.addEventListener('abort', () => {
+				this.#pendingRequests.delete(this.#requestId);
+				reject(signal.reason);
+			});
+
+			webSocket.send(JSON.stringify({ jsonrpc: '2.0', id: this.#requestId, method, params }));
+		}).then(({ error, result }) => {
+			if (error) {
+				throw new JsonRpcError(error.message, error.code);
+			}
+
+			return result as T;
+		});
+	}
+
+	#setupWebSocket() {
+		if (this.#connectionPromise) {
+			return this.#connectionPromise;
+		}
+
+		this.#connectionPromise = new Promise<WebSocket>((resolve) => {
+			this.#webSocket?.close();
+			this.#webSocket = new this.options.WebSocketConstructor(this.endpoint);
+
+			this.#webSocket.addEventListener('open', () => {
+				this.#disconnects = 0;
+				resolve(this.#webSocket!);
+			});
+
+			this.#webSocket.addEventListener('close', () => {
+				this.#disconnects++;
+				if (this.#disconnects <= this.options.maxReconnects) {
+					setTimeout(() => {
+						this.#reconnect();
+					}, this.options.reconnectTimeout);
+				}
+			});
+
+			this.#webSocket.addEventListener('message', ({ data }: { data: string }) => {
+				let json: JsonRpcMessage;
+				try {
+					json = JSON.parse(data) as JsonRpcMessage;
+				} catch (error) {
+					console.error(new Error(`Failed to parse RPC message: ${data}`, { cause: error }));
+					return;
+				}
+
+				if ('id' in json && json.id != null && this.#pendingRequests.has(json.id)) {
+					const { resolve, timeout } = this.#pendingRequests.get(json.id)!;
+
+					clearTimeout(timeout);
+					resolve(json);
+				} else if ('params' in json) {
+					const { params } = json;
+					this.#subscriptions.forEach((subscription) => {
+						if (subscription.subscriptionId === params.subscription)
+							if (params.subscription === subscription.subscriptionId) {
+								subscription.onMessage(params.result);
+							}
+					});
+				}
+			});
+		});
+
+		return this.#connectionPromise;
+	}
+
+	async #reconnect() {
+		this.#webSocket?.close();
+		this.#connectionPromise = null;
+
+		return Promise.allSettled(
+			[...this.#subscriptions].map((subscription) => subscription.subscribe(this)),
+		);
+	}
+
+	async subscribe<T>(input: SubscriptionRequest<T>) {
+		const subscription = new RpcSubscription(input);
+		this.#subscriptions.add(subscription);
+		await subscription.subscribe(this);
+		return () => subscription.unsubscribe(this);
+	}
+}
+
+class RpcSubscription {
+	subscriptionId: number | null = null;
+	input: SubscriptionRequest<any>;
+	subscribed = false;
+
+	constructor(input: SubscriptionRequest) {
+		this.input = input;
+	}
+
+	onMessage(message: unknown) {
+		if (this.subscribed) {
+			this.input.onMessage(message);
+		}
+	}
+
+	async unsubscribe(client: WebsocketClient) {
+		const { subscriptionId } = this;
+		this.subscribed = false;
+		if (subscriptionId == null) return false;
+		this.subscriptionId = null;
+
+		return client.makeRequest(this.input.unsubscribe, [subscriptionId]);
+	}
+
+	async subscribe(client: WebsocketClient) {
+		this.subscriptionId = null;
+		this.subscribed = true;
+		const newSubscriptionId = await client.makeRequest<number>(
+			this.input.method,
+			this.input.params,
+			this.input.signal,
+		);
+
+		if (this.subscribed) {
+			this.subscriptionId = newSubscriptionId;
+		}
+	}
+}

package/src/jsonRpc/types/chain.ts

@@ -0,0 +1,122 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type {
+	Checkpoint,
+	DynamicFieldInfo,
+	SuiCallArg,
+	SuiMoveNormalizedModule,
+	HaneulParsedData,
+	HaneulTransaction,
+	SuiValidatorSummary,
+} from './generated.js';
+
+export type ResolvedNameServiceNames = {
+	data: string[];
+	hasNextPage: boolean;
+	nextCursor: string | null;
+};
+
+export type EpochInfo = {
+	epoch: string;
+	validators: SuiValidatorSummary[];
+	epochTotalTransactions: string;
+	firstCheckpointId: string;
+	epochStartTimestamp: string;
+	endOfEpochInfo: EndOfEpochInfo | null;
+	referenceGasPrice: number | null;
+};
+
+export type EpochMetrics = {
+	epoch: string;
+	epochTotalTransactions: string;
+	firstCheckpointId: string;
+	epochStartTimestamp: string;
+	endOfEpochInfo: EndOfEpochInfo | null;
+};
+
+export type EpochPage = {
+	data: EpochInfo[];
+	nextCursor: string | null;
+	hasNextPage: boolean;
+};
+
+export type EpochMetricsPage = {
+	data: EpochMetrics[];
+	nextCursor: string | null;
+	hasNextPage: boolean;
+};
+
+export type EndOfEpochInfo = {
+	lastCheckpointId: string;
+	epochEndTimestamp: string;
+	protocolVersion: string;
+	referenceGasPrice: string;
+	totalStake: string;
+	storageFundReinvestment: string;
+	storageCharge: string;
+	storageRebate: string;
+	storageFundBalance: string;
+	stakeSubsidyAmount: string;
+	totalGasFees: string;
+	totalStakeRewardsDistributed: string;
+	leftoverStorageFundInflow: string;
+};
+
+export type CheckpointPage = {
+	data: Checkpoint[];
+	nextCursor: string | null;
+	hasNextPage: boolean;
+};
+
+export type NetworkMetrics = {
+	currentTps: number;
+	tps30Days: number;
+	currentCheckpoint: string;
+	currentEpoch: string;
+	totalAddresses: string;
+	totalObjects: string;
+	totalPackages: string;
+};
+
+export type AddressMetrics = {
+	checkpoint: number;
+	epoch: number;
+	timestampMs: number;
+	cumulativeAddresses: number;
+	cumulativeActiveAddresses: number;
+	dailyActiveAddresses: number;
+};
+
+export type AllEpochsAddressMetrics = AddressMetrics[];
+
+export type MoveCallMetrics = {
+	rank3Days: MoveCallMetric[];
+	rank7Days: MoveCallMetric[];
+	rank30Days: MoveCallMetric[];
+};
+
+export type MoveCallMetric = [
+	{
+		module: string;
+		package: string;
+		function: string;
+	},
+	string,
+];
+
+export type DynamicFieldPage = {
+	data: DynamicFieldInfo[];
+	nextCursor: string | null;
+	hasNextPage: boolean;
+};
+
+export type SuiMoveNormalizedModules = Record<string, SuiMoveNormalizedModule>;
+
+export type HaneulMoveObject = Extract<HaneulParsedData, { dataType: 'moveObject' }>;
+export type SuiMovePackage = Extract<HaneulParsedData, { dataType: 'package' }>;
+
+export type ProgrammableTransaction = {
+	transactions: HaneulTransaction[];
+	inputs: SuiCallArg[];
+};

package/src/jsonRpc/types/changes.ts

@@ -0,0 +1,11 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+import type { HaneulObjectChange } from './generated.js';
+
+export type HaneulObjectChangePublished = Extract<HaneulObjectChange, { type: 'published' }>;
+export type HaneulObjectChangeTransferred = Extract<HaneulObjectChange, { type: 'transferred' }>;
+export type HaneulObjectChangeMutated = Extract<HaneulObjectChange, { type: 'mutated' }>;
+export type HaneulObjectChangeDeleted = Extract<HaneulObjectChange, { type: 'deleted' }>;
+export type HaneulObjectChangeWrapped = Extract<HaneulObjectChange, { type: 'wrapped' }>;
+export type HaneulObjectChangeCreated = Extract<HaneulObjectChange, { type: 'created' }>;

package/src/jsonRpc/types/coins.ts

@@ -0,0 +1,9 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export type CoinBalance = {
+	coinType: string;
+	coinObjectCount: number;
+	totalBalance: string;
+	lockedBalance: Record<string, string>;
+};

package/src/jsonRpc/types/common.ts

@@ -0,0 +1,5 @@
+// Copyright (c) Mysten Labs, Inc.
+// SPDX-License-Identifier: Apache-2.0
+
+export type Order = 'ascending' | 'descending';
+export type Unsubscribe = () => Promise<boolean>;