@fleet-sdk/blockchain-providers 0.5.0 → 0.6.1

package/src/types/blockchainProvider.ts

@@ -3,7 +3,9 @@ import type {
   BlockHeader,
   Box,
   BoxId,
+  DataInput,
   HexString,
+  ProverResult,
   SignedTransaction,
   TokenId,
   TransactionId,
@@ -14,6 +16,23 @@ import type { RequireAtLeastOne } from "type-fest";
 
 export type BoxSource = "blockchain" | "mempool" | "blockchain+mempool";
 
+export type BoxWhere = {
+  /** Base16-encoded BoxId */
+  boxId?: BoxId;
+
+  /** Base16-encoded ErgoTree */
+  ergoTree?: HexString;
+
+  /** Base58-encoded address */
+  address?: ErgoAddress | Base58String;
+
+  /** Base16-encoded contract template hash */
+  templateHash?: HexString;
+
+  /**  Base16-encoded TokenId */
+  tokenId?: TokenId;
+};
+
 export type BoxQuery<W extends BoxWhere> = {
   /** The query to filter boxes. */
   where: RequireAtLeastOne<W>;
@@ -25,29 +44,69 @@ export type BoxQuery<W extends BoxWhere> = {
   from?: BoxSource;
 };
 
-export type HeaderQuery = { take: number };
+export type UnconfirmedTransactionWhere = {
+  /** Base16-encoded TransactionId */
+  transactionId?: TransactionId;
 
-export type BoxWhere = {
-  /** Base16-encoded BoxId */
-  boxId?: BoxId;
+  /** Base58-encoded address */
+  address?: ErgoAddress | Base58String;
 
   /** Base16-encoded ErgoTree */
   ergoTree?: HexString;
+};
+
+export type ConfirmedTransactionWhere = {
+  /** Base16-encoded TransactionId */
+  transactionId?: TransactionId;
+
+  /** Base16-encoded HeaderID */
+  headerId?: HexString;
 
   /** Base58-encoded address */
   address?: ErgoAddress | Base58String;
 
-  /** Base16-encoded contract template hash */
-  templateHash?: HexString;
+  /** Base16-encoded ErgoTree */
+  ergoTree?: HexString;
 
-  /**  Base16-encoded TokenId */
-  tokenId?: TokenId;
+  /** Min blockchain height */
+  minHeight?: number;
+
+  /** Only returns relevant outputs for the selected filter params */
+  onlyRelevantOutputs?: boolean;
+};
+
+export type TransactionQuery<W extends ConfirmedTransactionWhere> = {
+  /** The query to filter boxes. */
+  where: RequireAtLeastOne<W, keyof Omit<W, "minHeight" | "onlyRelevantOutputs">>;
 };
 
-export type ChainProviderBox = Box<bigint> & {
+export type HeaderQuery = { take: number };
+
+export type ChainProviderBox<T> = Omit<Box, "value" | "assets"> & {
+  value: T;
+  assets: { tokenId: TokenId; amount: T }[];
+  confirmed: boolean;
+};
+
+type TransactionOutput<T> = Omit<ChainProviderBox<T>, "confirmed">;
+type TransactionInput<T> = TransactionOutput<T> & { spendingProof: ProverResult };
+
+export type ChainProviderUnconfirmedTransaction<T> = {
+  transactionId: TransactionId;
+  inputs: TransactionInput<T>[];
+  dataInputs: DataInput[];
+  outputs: TransactionOutput<T>[];
   confirmed: boolean;
+  timestamp: number;
 };
 
+export type ChainProviderConfirmedTransaction<T> =
+  ChainProviderUnconfirmedTransaction<T> & {
+    height: number;
+    index: number;
+    headerId: HexString;
+  };
+
 export type TransactionEvaluationError = {
   success: false;
   message: string;
@@ -74,16 +133,44 @@ export type TransactionReductionResult =
  * Represents a blockchain provider that can interact with the blockchain.
  * @template B The type of the box query used by the provider.
  */
-export interface IBlockchainProvider<B extends BoxWhere> {
+export interface IBlockchainProvider<I> {
   /**
    * Get boxes.
    */
-  getBoxes(query: BoxQuery<B>): Promise<ChainProviderBox[]>;
+  getBoxes(query: BoxQuery<BoxWhere>): Promise<ChainProviderBox<I>[]>;
 
   /**
    * Stream boxes.
    */
-  streamBoxes(query: BoxQuery<B>): AsyncIterable<ChainProviderBox[]>;
+  streamBoxes(query: BoxQuery<BoxWhere>): AsyncIterable<ChainProviderBox<I>[]>;
+
+  /**
+   * Stream unconfirmed transactions
+   */
+  streamUnconfirmedTransactions(
+    query: TransactionQuery<UnconfirmedTransactionWhere>
+  ): AsyncIterable<ChainProviderUnconfirmedTransaction<I>[]>;
+
+  /**
+   * Get unconfirmed transactions
+   */
+  getUnconfirmedTransactions(
+    query: TransactionQuery<UnconfirmedTransactionWhere>
+  ): Promise<ChainProviderUnconfirmedTransaction<I>[]>;
+
+  /**
+   * Stream confirmed transactions
+   */
+  streamConfirmedTransactions(
+    query: TransactionQuery<ConfirmedTransactionWhere>
+  ): AsyncIterable<ChainProviderConfirmedTransaction<I>[]>;
+
+  /**
+   * Get confirmed transactions
+   */
+  getConfirmedTransactions(
+    query: TransactionQuery<ConfirmedTransactionWhere>
+  ): Promise<ChainProviderConfirmedTransaction<I>[]>;
 
   /**
    * Get headers.
@@ -93,16 +180,12 @@ export interface IBlockchainProvider<B extends BoxWhere> {
   /**
    * Check for transaction validity without broadcasting it to the network.
    */
-  checkTransaction(
-    transaction: SignedTransaction
-  ): Promise<TransactionEvaluationResult>;
+  checkTransaction(transaction: SignedTransaction): Promise<TransactionEvaluationResult>;
 
   /**
    * Broadcast a transaction to the network.
    */
-  submitTransaction(
-    transaction: SignedTransaction
-  ): Promise<TransactionEvaluationResult>;
+  submitTransaction(transaction: SignedTransaction): Promise<TransactionEvaluationResult>;
 
   /**
    * Evaluate a transaction and return Base16-encoded evaluation result.

package/src/utils/_tests.ts

@@ -1,12 +1,8 @@
-export const mockResponse = (data: string) => {
-  return {
+// export const mockSuccessResponse = (data: unknown) => resolveString(JSON.stringify(data));
+
+export const resolveString = (data: string) =>
+  ({
     text: () => new Promise((resolve) => resolve(data))
-  } as unknown as Response;
-};
+  }) as unknown as Response;
 
-export const mockChunkedResponse = (chunks: string[]) => {
-  let i = 0;
-  return {
-    text: () => new Promise((resolve) => resolve(chunks[i++]))
-  } as unknown as Response;
-};
+export const resolveData = (data: unknown) => resolveString(JSON.stringify(data));

package/src/utils/graphql.ts

@@ -5,17 +5,15 @@ import {
   isEmpty,
   some
 } from "@fleet-sdk/common";
+import type { FallbackRetryOptions, ParserLike } from "./networking";
+import { request } from "./networking";
 
 const OP_NAME_REGEX = /(query|mutation)\s?([\w\-_]+)?/;
-export const DEFAULT_HEADERS: Headers = {
+const DEFAULT_HEADERS = {
   "content-type": "application/json; charset=utf-8",
   accept: "application/graphql-response+json, application/json"
 };
 
-type Credentials = RequestCredentials;
-type Headers = HeadersInit;
-type Fetcher = typeof fetch;
-
 export type GraphQLVariables = Record<string, unknown> | null;
 
 export interface GraphQLError {
@@ -36,84 +34,80 @@ export type GraphQLResponse<T = unknown> =
   | GraphQLSuccessResponse<T>
   | GraphQLErrorResponse;
 
-export type GraphQLOperation<
+export type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (
+  variables?: V,
+  url?: string
+) => Promise<R>;
+
+export type GraphQLRequiredUrlOperation<
   R extends GraphQLResponse,
   V extends GraphQLVariables
-> = (variables?: V) => Promise<R>;
-
-export interface ResponseParser {
-  parse<T>(text: string): T;
-  stringify<T>(value: T): string;
-}
+> = (variables: V | undefined, url: string) => Promise<R>;
 
-export interface RequestParams {
+interface RequestParams {
   operationName?: string | null;
   query: string;
   variables?: Record<string, unknown> | null;
 }
 
 export interface GraphQLRequestOptions {
-  url: URL | string;
-  headers?: Headers;
-  parser?: ResponseParser;
-  fetcher?: Fetcher;
-  credentials?: Credentials;
+  url?: string;
+  parser?: ParserLike;
+  retry?: FallbackRetryOptions;
   throwOnNonNetworkErrors?: boolean;
+  httpOptions?: Omit<RequestInit, "body" | "method">;
 }
 
-export interface GraphQLThrowableOptions extends GraphQLRequestOptions {
-  throwOnNonNetworkErrors: true;
-}
-
-export function createGqlOperation<
-  R,
-  V extends GraphQLVariables = GraphQLVariables
->(
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
   query: string,
-  options: GraphQLThrowableOptions
+  options: GraphQLRequestOptions & { throwOnNonNetworkErrors: true }
 ): GraphQLOperation<GraphQLSuccessResponse<R>, V>;
-export function createGqlOperation<
-  R,
-  V extends GraphQLVariables = GraphQLVariables
->(
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
+  query: string,
+  options?: GraphQLRequestOptions & { url: undefined }
+): GraphQLRequiredUrlOperation<GraphQLResponse<R>, V>;
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
+  query: string,
+  options: GraphQLRequestOptions & { url: undefined; throwOnNonNetworkErrors: true }
+): GraphQLRequiredUrlOperation<GraphQLSuccessResponse<R>, V>;
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
   query: string,
   options: GraphQLRequestOptions
 ): GraphQLOperation<GraphQLResponse<R>, V>;
-export function createGqlOperation<
-  R,
-  V extends GraphQLVariables = GraphQLVariables
->(
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
   query: string,
-  options: GraphQLRequestOptions
-): GraphQLOperation<GraphQLResponse<R>, V> {
-  return async (variables?: V): Promise<GraphQLResponse<R>> => {
-    const response = await (options.fetcher ?? fetch)(options.url, {
-      method: "POST",
-      headers: ensureDefaults(options.headers, DEFAULT_HEADERS),
-      credentials: options.credentials,
-      body: (options.parser ?? JSON).stringify({
-        operationName: getOpName(query),
-        query,
-        variables: variables ? clearUndefined(variables) : undefined
-      } as RequestParams)
+  options?: GraphQLRequestOptions
+):
+  | GraphQLOperation<GraphQLResponse<R>, V>
+  | GraphQLRequiredUrlOperation<GraphQLResponse<R>, V> {
+  return async (variables?: V, url?: string): Promise<GraphQLResponse<R>> => {
+    url = url ?? options?.url;
+    if (!url) throw new Error("URL is required");
+
+    const response = await request<GraphQLResponse<R>>(url, {
+      ...options,
+      httpOptions: {
+        ...options?.httpOptions,
+        method: "POST",
+        headers: ensureDefaults(options?.httpOptions?.headers, DEFAULT_HEADERS),
+        body: (options?.parser ?? JSON).stringify({
+          operationName: getOpName(query),
+          query,
+          variables: variables ? clearUndefined(variables) : undefined
+        } as RequestParams)
+      }
     });
 
-    const rawData = await response.text();
-    const parsedData = (options.parser ?? JSON).parse(
-      rawData
-    ) as GraphQLResponse<R>;
-
     if (
-      options.throwOnNonNetworkErrors &&
-      some(parsedData.errors) &&
-      isEmpty(parsedData.data)
+      options?.throwOnNonNetworkErrors &&
+      some(response.errors) &&
+      isEmpty(response.data)
     ) {
-      throw new BlockchainProviderError(parsedData.errors[0].message, {
-        cause: parsedData.errors
-      });
+      const msg = response.errors[0].message;
+      throw new BlockchainProviderError(msg, { cause: response.errors });
     }
 
-    return parsedData;
+    return response;
   };
 }
 
@@ -124,9 +118,3 @@ export function gql(query: TemplateStringsArray): string {
 export function getOpName(query: string): string | undefined {
   return OP_NAME_REGEX.exec(query)?.at(2);
 }
-
-export function isRequestParam(obj: unknown): obj is GraphQLRequestOptions {
-  return (
-    typeof obj === "object" && (obj as GraphQLRequestOptions).url !== undefined
-  );
-}

package/src/utils/networking.ts

@@ -0,0 +1,83 @@
+import { some } from "@fleet-sdk/common";
+
+export interface ParserLike {
+  parse<T>(text: string): T;
+  stringify<T>(value: T): string;
+}
+
+export type Route = { base: string; path: string; query?: Record<string, unknown> };
+export type URLLike = string | Route;
+export type FallbackRetryOptions = { fallbacks?: URLLike[] } & RetryOptions;
+
+export type FetchOptions = {
+  parser?: ParserLike;
+  base?: string;
+  query?: Record<string, unknown>;
+  retry?: FallbackRetryOptions;
+  httpOptions?: RequestInit;
+};
+
+export async function request<T>(path: string, opt?: Partial<FetchOptions>): Promise<T> {
+  const url = buildURL(path, opt?.query, opt?.base);
+
+  let response: Response;
+  if (opt?.retry) {
+    const routes = some(opt.retry.fallbacks) ? [url, ...opt.retry.fallbacks] : [url];
+    const attempts = opt.retry.attempts;
+    response = await exponentialRetry(
+      (r) => fetch(resolveUrl(routes, attempts - r), opt.httpOptions),
+      opt.retry
+    );
+  } else {
+    response = await fetch(url, opt?.httpOptions);
+  }
+
+  return (opt?.parser || JSON).parse(await response.text());
+}
+
+function resolveUrl(routes: URLLike[], attempt: number) {
+  const route = routes[attempt % routes.length];
+  return typeof route === "string"
+    ? route
+    : buildURL(route.path, route.query, route.base).toString();
+}
+
+function buildURL(path: string, query?: Record<string, unknown>, base?: string) {
+  if (!base && !query) return path;
+
+  const url = new URL(path, base);
+  if (some(query)) {
+    for (const key in query) url.searchParams.append(key, String(query[key]));
+  }
+
+  return url.toString();
+}
+
+export type RetryOptions = {
+  attempts: number;
+  delay: number;
+};
+
+/**
+ * Retries an asynchronous operation a specified number of times with a delay
+ * growing exponentially between each attempt.
+ * @param operation - The asynchronous operation to retry.
+ * @param options - The retry options.
+ * @returns A promise that resolves to the result of the operation, or undefined
+ * if all attempts fail.
+ */
+export async function exponentialRetry<T>(
+  operation: (remainingAttempts: number) => Promise<T>,
+  { attempts, delay }: RetryOptions
+): Promise<T> {
+  try {
+    return await operation(attempts);
+  } catch (e) {
+    if (attempts > 0) {
+      await new Promise((resolve) => setTimeout(resolve, delay));
+      return exponentialRetry(operation, { attempts: attempts - 1, delay: delay * 2 });
+    }
+
+    throw e;
+  }
+}