@fleet-sdk/blockchain-providers 0.4.1 → 0.6.0

package/src/types/blockchainProvider.ts

@@ -1,19 +1,38 @@
-import {
+import type {
   Base58String,
   BlockHeader,
   Box,
   BoxId,
+  DataInput,
   HexString,
+  ProverResult,
   SignedTransaction,
   TokenId,
   TransactionId,
   UnsignedTransaction
 } from "@fleet-sdk/common";
-import { ErgoAddress } from "@fleet-sdk/core";
-import { RequireAtLeastOne } from "type-fest";
+import type { ErgoAddress } from "@fleet-sdk/core";
+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;
@@ -63,23 +122,55 @@ export type TransactionReductionSuccess = {
   reducedTransaction: HexString;
 };
 
-export type TransactionEvaluationResult = TransactionEvaluationError | TransactionEvaluationSuccess;
-export type TransactionReductionResult = TransactionEvaluationError | TransactionReductionSuccess;
+export type TransactionEvaluationResult =
+  | TransactionEvaluationError
+  | TransactionEvaluationSuccess;
+export type TransactionReductionResult =
+  | TransactionEvaluationError
+  | TransactionReductionSuccess;
 
 /**
  * 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.
@@ -99,5 +190,7 @@ export interface IBlockchainProvider<B extends BoxWhere> {
   /**
    * Evaluate a transaction and return Base16-encoded evaluation result.
    */
-  reduceTransaction(transaction: UnsignedTransaction): Promise<TransactionReductionResult>;
+  reduceTransaction(
+    transaction: UnsignedTransaction
+  ): Promise<TransactionReductionResult>;
 }

package/src/utils/_tests.ts

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

package/src/utils/graphql.test-d.ts

@@ -1,10 +1,10 @@
 import { describe, expectTypeOf, it } from "vitest";
 import {
   createGqlOperation,
-  GraphQLOperation,
-  GraphQLResponse,
-  GraphQLSuccessResponse,
-  GraphQLVariables
+  type GraphQLOperation,
+  type GraphQLResponse,
+  type GraphQLSuccessResponse,
+  type GraphQLVariables
 } from "./graphql";
 
 describe("createGqlOperation() types", () => {
@@ -12,12 +12,20 @@ describe("createGqlOperation() types", () => {
   const url = "https://gql.example.com/";
 
   it("Should infer the correct type when throwOnNonNetworkErrors is set to true", () => {
-    const throwable = createGqlOperation(query, { throwOnNonNetworkErrors: true, url });
+    const throwable = createGqlOperation(query, {
+      throwOnNonNetworkErrors: true,
+      url
+    });
     expectTypeOf(throwable).toMatchTypeOf<
       GraphQLOperation<GraphQLSuccessResponse, GraphQLVariables>
     >();
 
-    const notThrowable = createGqlOperation(query, { throwOnNonNetworkErrors: false, url });
-    expectTypeOf(notThrowable).toMatchTypeOf<GraphQLOperation<GraphQLResponse, GraphQLVariables>>();
+    const notThrowable = createGqlOperation(query, {
+      throwOnNonNetworkErrors: false,
+      url
+    });
+    expectTypeOf(notThrowable).toMatchTypeOf<
+      GraphQLOperation<GraphQLResponse, GraphQLVariables>
+    >();
   });
 });

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 = {
+export 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 {
@@ -32,68 +30,84 @@ export interface GraphQLErrorResponse {
   errors: GraphQLError[];
 }
 
-export type GraphQLResponse<T = unknown> = GraphQLSuccessResponse<T> | GraphQLErrorResponse;
+export type GraphQLResponse<T = unknown> =
+  | GraphQLSuccessResponse<T>
+  | GraphQLErrorResponse;
 
 export type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (
-  variables?: V
+  variables?: V,
+  url?: string
 ) => Promise<R>;
 
-export interface ResponseParser {
-  parse<T>(text: string): T;
-  stringify<T>(value: T): string;
-}
+export type GraphQLRequiredUrlOperation<
+  R extends GraphQLResponse,
+  V extends GraphQLVariables
+> = (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;
-}
-
-export interface GraphQLThrowableOptions extends GraphQLRequestOptions {
-  throwOnNonNetworkErrors: true;
+  httpOptions?: Omit<RequestInit, "body" | "method">;
 }
 
 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>(
+  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>(
   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)) {
-      throw new BlockchainProviderError(parsedData.errors[0].message, { cause: parsedData.errors });
+    if (
+      options?.throwOnNonNetworkErrors &&
+      some(response.errors) &&
+      isEmpty(response.data)
+    ) {
+      const msg = response.errors[0].message;
+      throw new BlockchainProviderError(msg, { cause: response.errors });
     }
 
-    return parsedData;
+    return response;
   };
 }
 

package/src/utils/networking.ts

@@ -0,0 +1,84 @@
+import { some } from "@fleet-sdk/common";
+import { isEmpty } from "packages/common/src";
+
+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;
+  }
+}

package/src/ergo-graphql/index.ts

@@ -1 +0,0 @@
-export * from "./ergoGraphQLProvider";

package/src/types/index.ts

@@ -1 +0,0 @@
-export * from "./blockchainProvider";