@fleet-sdk/blockchain-providers 0.3.0

package/src/ergo-graphql/ergoGraphQLProvider.ts

@@ -0,0 +1,280 @@
+import {
+  Box,
+  QueryBoxesArgs as BoxesArgs,
+  Header,
+  QueryBlockHeadersArgs as HeadersArgs
+} from "@ergo-graphql/types";
+import {
+  Base58String,
+  BlockHeader,
+  ensureDefaults,
+  HexString,
+  isEmpty,
+  isUndefined,
+  NotSupportedError,
+  orderBy,
+  SignedTransaction,
+  some,
+  uniq,
+  uniqBy
+} from "@fleet-sdk/common";
+import { ErgoAddress } from "@fleet-sdk/core";
+import {
+  BoxQuery,
+  BoxWhere,
+  ChainProviderBox,
+  HeaderQuery,
+  IBlockchainProvider,
+  TransactionEvaluationResult,
+  TransactionReductionResult
+} from "../types";
+import {
+  createGqlOperation,
+  GraphQLOperation,
+  GraphQLRequestOptions,
+  GraphQLSuccessResponse,
+  GraphQLThrowableOptions,
+  GraphQLVariables,
+  isRequestParam
+} from "../utils";
+import {
+  ALL_BOXES_QUERY,
+  CHECK_TX_MUTATION,
+  CONF_BOXES_QUERY,
+  HEADERS_QUERY,
+  SEND_TX_MUTATION,
+  UNCONF_BOXES_QUERY
+} from "./queries";
+
+export type GraphQLBoxWhere = BoxWhere & {
+  /** Base16-encoded BoxIds */
+  boxIds?: HexString[];
+
+  /** Base16-encoded ErgoTrees */
+  ergoTrees?: HexString[];
+
+  /** Base58-encoded addresses or `ErgoAddress` objects */
+  addresses?: (Base58String | ErgoAddress)[];
+};
+
+export type GraphQLBoxQuery = BoxQuery<GraphQLBoxWhere>;
+export type ErgoGraphQLRequestOptions = Omit<GraphQLRequestOptions, "throwOnNonNetworkError">;
+
+type ConfBoxesResp = { boxes: Box[] };
+type UnconfBoxesResp = { mempool: { boxes: Box[] } };
+type AllBoxesResp = ConfBoxesResp & UnconfBoxesResp;
+type HeadersResp = { blockHeaders: Header[] };
+type CheckTxResp = { checkTransaction: string };
+type SendTxResp = { submitTransaction: string };
+type SignedTxArgsResp = { signedTransaction: SignedTransaction };
+
+const PAGE_SIZE = 50;
+
+export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
+  #options: GraphQLThrowableOptions;
+
+  #getConfBoxes;
+  #getUnconfBoxes;
+  #getAllBoxes;
+  #getHeaders;
+  #checkTx;
+  #sendTx;
+
+  constructor(url: string | URL);
+  constructor(url: ErgoGraphQLRequestOptions);
+  constructor(optOrUrl: ErgoGraphQLRequestOptions | string | URL) {
+    this.#options = {
+      ...(isRequestParam(optOrUrl) ? optOrUrl : { url: optOrUrl }),
+      throwOnNonNetworkErrors: true
+    };
+
+    this.#getConfBoxes = this.createOperation<ConfBoxesResp, BoxesArgs>(CONF_BOXES_QUERY);
+    this.#getUnconfBoxes = this.createOperation<UnconfBoxesResp, BoxesArgs>(UNCONF_BOXES_QUERY);
+    this.#getAllBoxes = this.createOperation<AllBoxesResp, BoxesArgs>(ALL_BOXES_QUERY);
+    this.#getHeaders = this.createOperation<HeadersResp, HeadersArgs>(HEADERS_QUERY);
+    this.#checkTx = this.createOperation<CheckTxResp, SignedTxArgsResp>(CHECK_TX_MUTATION);
+    this.#sendTx = this.createOperation<SendTxResp, SignedTxArgsResp>(SEND_TX_MUTATION);
+  }
+
+  #fetchBoxes(args: BoxesArgs, inclConf: boolean, inclUnconf: boolean) {
+    if (inclConf && inclUnconf) {
+      return this.#getAllBoxes(args);
+    } else if (inclUnconf) {
+      return this.#getUnconfBoxes(args);
+    } else {
+      return this.#getConfBoxes(args);
+    }
+  }
+
+  async *streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox[]> {
+    if (isEmpty(query.where)) {
+      throw new Error("Cannot fetch unspent boxes without a where clause.");
+    }
+
+    const notBeingSpent = (box: Box) => !box.beingSpent;
+    const returnedBoxIds = new Set<string>();
+    const { where, from } = query;
+    const args = buildGqlBoxQueryArgs(where);
+
+    let fetchFromChain = from !== "mempool";
+    let fetchFromMempool = from !== "blockchain";
+    const isMempoolAware = fetchFromMempool;
+
+    do {
+      const response = await this.#fetchBoxes(args, fetchFromChain, fetchFromMempool);
+
+      const { data } = response;
+      let boxes: ChainProviderBox[] = [];
+
+      if (fetchFromChain && hasConfirmed(data)) {
+        if (some(data.boxes)) {
+          const confirmedBoxes = (
+            isMempoolAware ? data.boxes.filter(notBeingSpent) : data.boxes
+          ).map(asConfirmed(true));
+
+          boxes = boxes.concat(confirmedBoxes);
+        }
+
+        fetchFromChain = data.boxes.length === PAGE_SIZE;
+      }
+
+      if (isMempoolAware && hasMempool(data)) {
+        if (some(data.mempool.boxes)) {
+          const mempoolBoxes = data.mempool.boxes.filter(notBeingSpent).map(asConfirmed(false));
+          boxes = boxes.concat(mempoolBoxes);
+        }
+
+        fetchFromMempool = data.mempool.boxes.length === PAGE_SIZE;
+      }
+
+      if (some(boxes)) {
+        // boxes can be moved from the mempool to the blockchain while streaming,
+        // so we need to filter out boxes that have already been returned.
+        if (boxes.some((box) => returnedBoxIds.has(box.boxId))) {
+          boxes = boxes.filter((b) => !returnedBoxIds.has(b.boxId));
+        }
+
+        if (some(boxes)) {
+          boxes = uniqBy(boxes, (box) => box.boxId);
+          boxes.forEach((box) => returnedBoxIds.add(box.boxId));
+
+          yield boxes;
+        }
+      }
+
+      if (fetchFromChain || fetchFromMempool) args.skip += PAGE_SIZE;
+    } while (fetchFromChain || fetchFromMempool);
+  }
+
+  async getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox[]> {
+    let boxes: ChainProviderBox[] = [];
+    for await (const chunk of this.streamBoxes(query)) {
+      boxes = boxes.concat(chunk);
+    }
+
+    return orderBy(boxes, (box) => box.creationHeight);
+  }
+
+  async getHeaders(query: HeaderQuery): Promise<BlockHeader[]> {
+    const response = await this.#getHeaders(query);
+
+    return (
+      response.data?.blockHeaders.map((header) => ({
+        ...header,
+        id: header.headerId,
+        timestamp: Number(header.timestamp),
+        nBits: Number(header.nBits),
+        votes: header.votes.join("")
+      })) ?? []
+    );
+  }
+
+  createOperation<R, V extends GraphQLVariables = GraphQLVariables>(
+    query: string,
+    options?: Partial<ErgoGraphQLRequestOptions>
+  ): GraphQLOperation<GraphQLSuccessResponse<R>, V> {
+    const opt = ensureDefaults(options, this.#options);
+    opt.throwOnNonNetworkErrors = true;
+
+    return createGqlOperation(query, opt);
+  }
+
+  async checkTransaction(
+    signedTransaction: SignedTransaction
+  ): Promise<TransactionEvaluationResult> {
+    try {
+      const response = await this.#checkTx({ signedTransaction });
+
+      return { success: true, transactionId: response.data.checkTransaction };
+    } catch (e) {
+      return { success: false, message: (e as Error).message };
+    }
+  }
+
+  async submitTransaction(
+    signedTransaction: SignedTransaction
+  ): Promise<TransactionEvaluationResult> {
+    try {
+      const response = await this.#sendTx({ signedTransaction });
+
+      return { success: true, transactionId: response.data.submitTransaction };
+    } catch (e) {
+      return { success: false, message: (e as Error).message };
+    }
+  }
+
+  reduceTransaction(): Promise<TransactionReductionResult> {
+    throw new NotSupportedError("Transaction reducing is not supported by ergo-graphql.");
+  }
+}
+
+function buildGqlBoxQueryArgs(where: GraphQLBoxWhere) {
+  const args = {
+    spent: false,
+    boxIds: merge(where.boxIds, where.boxId),
+    ergoTrees: merge(where.ergoTrees, where.ergoTree),
+    ergoTreeTemplateHash: where.templateHash,
+    tokenId: where.tokenId,
+    skip: 0,
+    take: PAGE_SIZE
+  } satisfies BoxesArgs;
+
+  const addresses = merge(where.addresses, where.address);
+  if (some(addresses)) {
+    const trees = addresses.map((address) =>
+      typeof address === "string" ? ErgoAddress.fromBase58(address).ergoTree : address.ergoTree
+    );
+
+    args.ergoTrees = uniq(some(args.ergoTrees) ? args.ergoTrees.concat(trees) : trees);
+  }
+
+  return args;
+}
+
+function merge<T>(array?: T[], el?: T) {
+  if (isEmpty(array) && isUndefined(el)) return;
+
+  const set = new Set<T>(array ?? []);
+  if (!isUndefined(el)) set.add(el);
+  return Array.from(set.values());
+}
+
+function hasMempool(data: AllBoxesResp | ConfBoxesResp | UnconfBoxesResp): data is UnconfBoxesResp {
+  return !!(data as UnconfBoxesResp)?.mempool?.boxes;
+}
+
+function hasConfirmed(data: AllBoxesResp | ConfBoxesResp | UnconfBoxesResp): data is ConfBoxesResp {
+  return !!(data as ConfBoxesResp)?.boxes;
+}
+
+function asConfirmed(confirmed: boolean) {
+  return (box: Box): ChainProviderBox => ({
+    ...box,
+    value: BigInt(box.value),
+    assets: box.assets.map((asset) => ({
+      tokenId: asset.tokenId,
+      amount: BigInt(asset.amount)
+    })),
+    confirmed
+  });
+}

package/src/ergo-graphql/index.ts

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

package/src/ergo-graphql/queries.ts

@@ -0,0 +1,12 @@
+const B = [
+  `query boxes($spent: Boolean! $boxIds: [String!] $ergoTrees: [String!] $ergoTreeTemplateHash: String $tokenId: String $skip: Int $take: Int)`,
+  `boxIds: $boxIds ergoTrees: $ergoTrees ergoTreeTemplateHash: $ergoTreeTemplateHash tokenId: $tokenId skip: $skip take: $take`,
+  `boxId transactionId index value creationHeight ergoTree assets { tokenId amount } additionalRegisters beingSpent`
+];
+
+export const CONF_BOXES_QUERY = `${B[0]} { boxes(spent: $spent ${B[1]}) { ${B[2]} } }`;
+export const UNCONF_BOXES_QUERY = `${B[0]} { mempool { boxes(${B[1]}) { ${B[2]} } } }`;
+export const ALL_BOXES_QUERY = `${B[0]} { boxes(spent: $spent ${B[1]}) { ${B[2]} } mempool { boxes(${B[1]}) { ${B[2]} } } }`;
+export const HEADERS_QUERY = `query blockHeaders($take: Int) { blockHeaders(take: $take) {headerId timestamp version adProofsRoot stateRoot transactionsRoot nBits extensionHash powSolutions height difficulty parentId votes } }`;
+export const CHECK_TX_MUTATION = `mutation checkTransaction($signedTransaction: SignedTransaction!) { checkTransaction(signedTransaction: $signedTransaction) }`;
+export const SEND_TX_MUTATION = `mutation submitTransaction($signedTransaction: SignedTransaction!) { submitTransaction(signedTransaction: $signedTransaction) }`;

package/src/index.ts

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

package/src/types/blockchainProvider.ts

@@ -0,0 +1,103 @@
+import {
+  Base58String,
+  BlockHeader,
+  Box,
+  BoxId,
+  HexString,
+  SignedTransaction,
+  TokenId,
+  TransactionId,
+  UnsignedTransaction
+} from "@fleet-sdk/common";
+import { ErgoAddress } from "@fleet-sdk/core";
+import { RequireAtLeastOne } from "type-fest";
+
+export type BoxSource = "blockchain" | "mempool" | "blockchain+mempool";
+
+export type BoxQuery<W extends BoxWhere> = {
+  /** The query to filter boxes. */
+  where: RequireAtLeastOne<W>;
+
+  /**
+   * The source of boxes to query.
+   * @default "blockchain+mempool"
+   */
+  from?: BoxSource;
+};
+
+export type HeaderQuery = { take: number };
+
+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 ChainProviderBox = Box<bigint> & {
+  confirmed: boolean;
+};
+
+export type TransactionEvaluationError = {
+  success: false;
+  message: string;
+};
+
+export type TransactionEvaluationSuccess = {
+  success: true;
+  transactionId: TransactionId;
+};
+
+export type TransactionReductionSuccess = {
+  success: true;
+  reducedTransaction: HexString;
+};
+
+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> {
+  /**
+   * Get boxes.
+   */
+  getBoxes(query: BoxQuery<B>): Promise<ChainProviderBox[]>;
+
+  /**
+   * Stream boxes.
+   */
+  streamBoxes(query: BoxQuery<B>): AsyncIterable<ChainProviderBox[]>;
+
+  /**
+   * Get headers.
+   */
+  getHeaders(query: HeaderQuery): Promise<BlockHeader[]>;
+
+  /**
+   * Check for transaction validity without broadcasting it to the network.
+   */
+  checkTransaction(transaction: SignedTransaction): Promise<TransactionEvaluationResult>;
+
+  /**
+   * Broadcast a transaction to the network.
+   */
+  submitTransaction(transaction: SignedTransaction): Promise<TransactionEvaluationResult>;
+
+  /**
+   * Evaluate a transaction and return Base16-encoded evaluation result.
+   */
+  reduceTransaction(transaction: UnsignedTransaction): Promise<TransactionReductionResult>;
+}

package/src/types/index.ts

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

package/src/utils/_tests.ts

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

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

@@ -0,0 +1,23 @@
+import { describe, expectTypeOf, it } from "vitest";
+import {
+  createGqlOperation,
+  GraphQLOperation,
+  GraphQLResponse,
+  GraphQLSuccessResponse,
+  GraphQLVariables
+} from "./graphql";
+
+describe("createGqlOperation() types", () => {
+  const query = "query test { state { height } }";
+  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 });
+    expectTypeOf(throwable).toMatchTypeOf<
+      GraphQLOperation<GraphQLSuccessResponse, GraphQLVariables>
+    >();
+
+    const notThrowable = createGqlOperation(query, { throwOnNonNetworkErrors: false, url });
+    expectTypeOf(notThrowable).toMatchTypeOf<GraphQLOperation<GraphQLResponse, GraphQLVariables>>();
+  });
+});

package/src/utils/graphql.ts

@@ -0,0 +1,110 @@
+import {
+  BlockchainProviderError,
+  clearUndefined,
+  ensureDefaults,
+  isEmpty,
+  some
+} from "@fleet-sdk/common";
+
+const OP_NAME_REGEX = /(query|mutation)\s?([\w\-_]+)?/;
+export const DEFAULT_HEADERS: 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 {
+  message: string;
+}
+
+export interface GraphQLSuccessResponse<T = unknown> {
+  data: T;
+  errors: null;
+}
+
+export interface GraphQLErrorResponse {
+  data: null;
+  errors: GraphQLError[];
+}
+
+export type GraphQLResponse<T = unknown> = GraphQLSuccessResponse<T> | GraphQLErrorResponse;
+
+export type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (
+  variables?: V
+) => Promise<R>;
+
+export interface ResponseParser {
+  parse<T>(text: string): T;
+  stringify<T>(value: T): string;
+}
+
+export 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;
+  throwOnNonNetworkErrors?: boolean;
+}
+
+export interface GraphQLThrowableOptions extends GraphQLRequestOptions {
+  throwOnNonNetworkErrors: true;
+}
+
+export function createGqlOperation<R, V extends GraphQLVariables = GraphQLVariables>(
+  query: string,
+  options: GraphQLThrowableOptions
+): GraphQLOperation<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)
+    });
+
+    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 });
+    }
+
+    return parsedData;
+  };
+}
+
+export function gql(query: TemplateStringsArray): string {
+  return query[0];
+}
+
+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/index.ts

@@ -0,0 +1,2 @@
+export * from "./graphql";
+export * from "./_tests";