@fleet-sdk/blockchain-providers 0.5.0 → 0.6.0

package/src/ergo-graphql/ergoGraphQLProvider.ts

@@ -1,8 +1,13 @@
 import type {
-  Box,
+  Box as GQLBox,
   QueryBoxesArgs,
   Header,
-  QueryBlockHeadersArgs
+  QueryBlockHeadersArgs,
+  Transaction,
+  QueryTransactionsArgs,
+  MempoolTransactionsArgs,
+  UnconfirmedTransaction,
+  UnconfirmedBox as GQLUnconfirmedBox
 } from "@ergo-graphql/types";
 import {
   type Base58String,
@@ -23,17 +28,21 @@ import type {
   BoxQuery,
   BoxWhere,
   ChainProviderBox,
+  ChainProviderConfirmedTransaction,
+  ChainProviderUnconfirmedTransaction,
   HeaderQuery,
   IBlockchainProvider,
   TransactionEvaluationResult,
-  TransactionReductionResult
+  TransactionQuery,
+  TransactionReductionResult,
+  ConfirmedTransactionWhere,
+  UnconfirmedTransactionWhere
 } from "../types/blockchainProvider";
 import {
   createGqlOperation,
   type GraphQLOperation,
   type GraphQLRequestOptions,
   type GraphQLSuccessResponse,
-  type GraphQLThrowableOptions,
   type GraphQLVariables,
   isRequestParam
 } from "../utils";
@@ -41,11 +50,17 @@ import {
   ALL_BOXES_QUERY,
   CHECK_TX_MUTATION,
   CONF_BOXES_QUERY,
+  CONF_TX_QUERY,
   HEADERS_QUERY,
   SEND_TX_MUTATION,
-  UNCONF_BOXES_QUERY
+  UNCONF_BOXES_QUERY,
+  UNCONF_TX_QUERY
 } from "./queries";
 
+type GraphQLThrowableOptions = GraphQLRequestOptions & { throwOnNonNetworkErrors: true };
+type OP<R, V extends GraphQLVariables> = GraphQLOperation<GraphQLSuccessResponse<R>, V>;
+type BiMapper<T> = (value: string) => T;
+
 export type GraphQLBoxWhere = BoxWhere & {
   /** Base16-encoded BoxIds */
   boxIds?: HexString[];
@@ -57,15 +72,29 @@ export type GraphQLBoxWhere = BoxWhere & {
   addresses?: (Base58String | ErgoAddress)[];
 };
 
+export type GraphQLConfirmedTransactionWhere = ConfirmedTransactionWhere & {
+  transactionIds?: HexString[];
+  addresses?: (Base58String | ErgoAddress)[];
+  ergoTrees?: HexString[];
+};
+
+export type GraphQLUnconfirmedTransactionWhere = UnconfirmedTransactionWhere & {
+  transactionIds?: HexString[];
+  addresses?: (Base58String | ErgoAddress)[];
+  ergoTrees?: HexString[];
+};
+
 export type GraphQLBoxQuery = BoxQuery<GraphQLBoxWhere>;
 export type ErgoGraphQLRequestOptions = Omit<
   GraphQLRequestOptions,
   "throwOnNonNetworkError"
 >;
 
-type ConfirmedBoxesResponse = { boxes: Box[] };
-type UnconfirmedBoxesResponse = { mempool: { boxes: Box[] } };
+type ConfirmedBoxesResponse = { boxes: GQLBox[] };
+type UnconfirmedBoxesResponse = { mempool: { boxes: GQLBox[] } };
 type CombinedBoxesResponse = ConfirmedBoxesResponse & UnconfirmedBoxesResponse;
+type UnconfirmedTxResponse = { mempool: { transactions: UnconfirmedTransaction[] } };
+type ConfirmedTxResponse = { transactions: Transaction[] };
 type BlockHeadersResponse = { blockHeaders: Header[] };
 type CheckTransactionResponse = { checkTransaction: string };
 type TransactionSubmissionResponse = { submitTransaction: string };
@@ -73,71 +102,63 @@ type SignedTxArgsResp = { signedTransaction: SignedTransaction };
 
 const PAGE_SIZE = 50;
 
-export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
+export class ErgoGraphQLProvider<I = bigint> implements IBlockchainProvider<I> {
   #options: GraphQLThrowableOptions;
-
-  #getConfBoxes;
-  #getUnconfBoxes;
-  #getAllBoxes;
-  #getHeaders;
-  #checkTx;
-  #sendTx;
-
-  constructor(url: string | URL);
+  #biMapper: BiMapper<I>;
+
+  #getConfirmedBoxes: OP<ConfirmedBoxesResponse, QueryBoxesArgs>;
+  #getUnconfirmedBoxes: OP<UnconfirmedBoxesResponse, QueryBoxesArgs>;
+  #getAllBoxes: OP<CombinedBoxesResponse, QueryBoxesArgs>;
+  #getConfirmedTransactions: OP<ConfirmedTxResponse, QueryTransactionsArgs>;
+  #getUnconfirmedTransactions: OP<UnconfirmedTxResponse, MempoolTransactionsArgs>;
+  #checkTransaction: OP<CheckTransactionResponse, SignedTxArgsResp>;
+  #sendTransaction: OP<TransactionSubmissionResponse, SignedTxArgsResp>;
+  #getHeaders!: OP<BlockHeadersResponse, QueryBlockHeadersArgs>;
+
+  constructor(url: string);
   constructor(url: ErgoGraphQLRequestOptions);
-  constructor(optOrUrl: ErgoGraphQLRequestOptions | string | URL) {
+  constructor(optOrUrl: ErgoGraphQLRequestOptions | string) {
     this.#options = {
       ...(isRequestParam(optOrUrl) ? optOrUrl : { url: optOrUrl }),
       throwOnNonNetworkErrors: true
     };
 
-    this.#getConfBoxes = this.createOperation<
-      ConfirmedBoxesResponse,
-      QueryBoxesArgs
-    >(CONF_BOXES_QUERY);
-
-    this.#getUnconfBoxes = this.createOperation<
-      UnconfirmedBoxesResponse,
-      QueryBoxesArgs
-    >(UNCONF_BOXES_QUERY);
-
-    this.#getAllBoxes = this.createOperation<
-      CombinedBoxesResponse,
-      QueryBoxesArgs
-    >(ALL_BOXES_QUERY);
-
-    this.#getHeaders = this.createOperation<
-      BlockHeadersResponse,
-      QueryBlockHeadersArgs
-    >(HEADERS_QUERY);
-
-    this.#checkTx = this.createOperation<
-      CheckTransactionResponse,
-      SignedTxArgsResp
-    >(CHECK_TX_MUTATION);
-
-    this.#sendTx = this.createOperation<
-      TransactionSubmissionResponse,
-      SignedTxArgsResp
-    >(SEND_TX_MUTATION);
+    this.#biMapper = (value) => BigInt(value) as I;
+
+    this.#getConfirmedBoxes = this.createOperation(CONF_BOXES_QUERY);
+    this.#getUnconfirmedBoxes = this.createOperation(UNCONF_BOXES_QUERY);
+    this.#getAllBoxes = this.createOperation(ALL_BOXES_QUERY);
+    this.#getConfirmedTransactions = this.createOperation(CONF_TX_QUERY);
+    this.#getUnconfirmedTransactions = this.createOperation(UNCONF_TX_QUERY);
+    this.#checkTransaction = this.createOperation(CHECK_TX_MUTATION);
+    this.#sendTransaction = this.createOperation(SEND_TX_MUTATION);
+    this.#getHeaders = this.createOperation(HEADERS_QUERY);
   }
 
   #fetchBoxes(args: QueryBoxesArgs, inclConf: boolean, inclUnconf: boolean) {
     return inclConf && inclUnconf
-      ? this.#getAllBoxes(args)
+      ? this.#getAllBoxes(args, this.#options.url)
       : inclUnconf
-        ? this.#getUnconfBoxes(args)
-        : this.#getConfBoxes(args);
+        ? this.#getUnconfirmedBoxes(args, this.#options.url)
+        : this.#getConfirmedBoxes(args, this.#options.url);
+  }
+
+  setUrl(url: string): ErgoGraphQLProvider<I> {
+    this.#options.url = url;
+    return this;
+  }
+
+  setBigIntMapper<M>(mapper: BiMapper<M>): ErgoGraphQLProvider<M> {
+    this.#biMapper = mapper as unknown as BiMapper<I>;
+    return this as unknown as ErgoGraphQLProvider<M>;
   }
 
-  async *streamBoxes(
-    query: GraphQLBoxQuery
-  ): AsyncGenerator<ChainProviderBox[]> {
+  async *streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox<I>[]> {
     if (isEmpty(query.where)) {
       throw new Error("Cannot fetch unspent boxes without a where clause.");
     }
 
-    const notBeingSpent = (box: Box) => !box.beingSpent;
+    const notBeingSpent = (box: GQLBox) => !box.beingSpent;
     const returnedBoxIds = new Set<string>();
     const { where, from } = query;
     const args = buildGqlBoxQueryArgs(where);
@@ -147,16 +168,14 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     const isMempoolAware = inclPool;
 
     do {
-      const response = await this.#fetchBoxes(args, inclChain, inclPool);
-
-      const { data } = response;
-      let boxes: ChainProviderBox[] = [];
+      const { data } = await this.#fetchBoxes(args, inclChain, inclPool);
+      let boxes: ChainProviderBox<I>[] = [];
 
       if (inclChain && hasConfirmed(data)) {
         if (some(data.boxes)) {
           const confirmedBoxes = (
             isMempoolAware ? data.boxes.filter(notBeingSpent) : data.boxes
-          ).map(asConfirmed(true));
+          ).map((b) => mapConfirmedBox(b, this.#biMapper));
 
           boxes = boxes.concat(confirmedBoxes);
         }
@@ -168,7 +187,7 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
         if (some(data.mempool.boxes)) {
           const mempoolBoxes = data.mempool.boxes
             .filter(notBeingSpent)
-            .map(asConfirmed(false));
+            .map((b) => mapUnconfirmedBox(b, this.#biMapper));
           boxes = boxes.concat(mempoolBoxes);
         }
 
@@ -193,17 +212,74 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     } while (inclChain || inclPool);
   }
 
-  async getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox[]> {
-    let boxes: ChainProviderBox[] = [];
-    for await (const chunk of this.streamBoxes(query)) {
-      boxes = boxes.concat(chunk);
+  async getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox<I>[]> {
+    const boxes: ChainProviderBox<I>[][] = [];
+    for await (const chunk of this.streamBoxes(query)) boxes.push(chunk);
+    return orderBy(boxes.flat(), (box) => box.creationHeight);
+  }
+
+  async *streamUnconfirmedTransactions(
+    query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>
+  ): AsyncIterable<ChainProviderUnconfirmedTransaction<I>[]> {
+    const args = buildGqlUnconfirmedTxQueryArgs(query.where);
+
+    let keepFetching = true;
+    while (keepFetching) {
+      const response = await this.#getUnconfirmedTransactions(args);
+      if (some(response.data?.mempool?.transactions)) {
+        yield response.data.mempool.transactions.map((t) =>
+          mapUnconfirmedTransaction(t, this.#biMapper)
+        );
+      }
+
+      keepFetching = response.data?.mempool?.transactions?.length === PAGE_SIZE;
+      if (keepFetching) args.skip += PAGE_SIZE;
+    }
+  }
+
+  async getUnconfirmedTransactions(
+    query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>
+  ): Promise<ChainProviderUnconfirmedTransaction<I>[]> {
+    const transactions: ChainProviderUnconfirmedTransaction<I>[][] = [];
+    for await (const chunk of this.streamUnconfirmedTransactions(query)) {
+      transactions.push(chunk);
+    }
+
+    return transactions.flat();
+  }
+
+  async *streamConfirmedTransactions(
+    query: TransactionQuery<GraphQLConfirmedTransactionWhere>
+  ): AsyncIterable<ChainProviderConfirmedTransaction<I>[]> {
+    const args = buildGqlConfirmedTxQueryArgs(query.where);
+
+    let keepFetching = true;
+    while (keepFetching) {
+      const response = await this.#getConfirmedTransactions(args);
+      if (some(response.data?.transactions)) {
+        yield response.data.transactions.map((t) =>
+          mapConfirmedTransaction(t, this.#biMapper)
+        );
+      }
+
+      keepFetching = response.data?.transactions?.length === PAGE_SIZE;
+      if (keepFetching) args.skip += PAGE_SIZE;
+    }
+  }
+
+  async getConfirmedTransactions(
+    query: TransactionQuery<GraphQLConfirmedTransactionWhere>
+  ): Promise<ChainProviderConfirmedTransaction<I>[]> {
+    const transactions: ChainProviderConfirmedTransaction<I>[][] = [];
+    for await (const chunk of this.streamConfirmedTransactions(query)) {
+      transactions.push(chunk);
     }
 
-    return orderBy(boxes, (box) => box.creationHeight);
+    return transactions.flat();
   }
 
   async getHeaders(query: HeaderQuery): Promise<BlockHeader[]> {
-    const response = await this.#getHeaders(query);
+    const response = await this.#getHeaders(query, this.#options.url);
 
     return (
       response.data?.blockHeaders.map((header) => ({
@@ -230,8 +306,10 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     signedTransaction: SignedTransaction
   ): Promise<TransactionEvaluationResult> {
     try {
-      const response = await this.#checkTx({ signedTransaction });
-
+      const response = await this.#checkTransaction(
+        { signedTransaction },
+        this.#options.url
+      );
       return { success: true, transactionId: response.data.checkTransaction };
     } catch (e) {
       return { success: false, message: (e as Error).message };
@@ -242,8 +320,10 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     signedTransaction: SignedTransaction
   ): Promise<TransactionEvaluationResult> {
     try {
-      const response = await this.#sendTx({ signedTransaction });
-
+      const response = await this.#sendTransaction(
+        { signedTransaction },
+        this.#options.url
+      );
       return { success: true, transactionId: response.data.submitTransaction };
     } catch (e) {
       return { success: false, message: (e as Error).message };
@@ -251,9 +331,7 @@ export class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
   }
 
   reduceTransaction(): Promise<TransactionReductionResult> {
-    throw new NotSupportedError(
-      "Transaction reducing is not supported by ergo-graphql."
-    );
+    throw new NotSupportedError("Transaction reducing is not supported by ergo-graphql.");
   }
 }
 
@@ -272,18 +350,45 @@ function buildGqlBoxQueryArgs(where: GraphQLBoxWhere) {
   if (some(addresses)) {
     const trees = addresses.map((address) =>
       typeof address === "string"
-        ? ErgoAddress.fromBase58(address).ergoTree
+        ? ErgoAddress.decode(address).ergoTree
         : address.ergoTree
     );
 
-    args.ergoTrees = uniq(
-      some(args.ergoTrees) ? args.ergoTrees.concat(trees) : trees
-    );
+    args.ergoTrees = uniq(some(args.ergoTrees) ? args.ergoTrees.concat(trees) : trees);
   }
 
   return args;
 }
 
+function buildGqlUnconfirmedTxQueryArgs(where: GraphQLConfirmedTransactionWhere) {
+  const addresses = uniq(
+    [
+      merge(where.addresses, where.address)?.map((address): string =>
+        typeof address === "string" ? address : address.encode()
+      ) ?? [],
+      merge(where.ergoTrees, where.ergoTree)?.map((tree) =>
+        ErgoAddress.fromErgoTree(tree).encode()
+      ) ?? []
+    ].flat()
+  );
+
+  return {
+    addresses: addresses.length ? addresses : undefined,
+    transactionIds: merge(where.transactionIds, where.transactionId),
+    skip: 0,
+    take: PAGE_SIZE
+  };
+}
+
+function buildGqlConfirmedTxQueryArgs(where: GraphQLConfirmedTransactionWhere) {
+  return {
+    ...buildGqlUnconfirmedTxQueryArgs(where),
+    headerId: where.headerId,
+    minHeight: where.minHeight,
+    onlyRelevantOutputs: where.onlyRelevantOutputs
+  };
+}
+
 function merge<T>(array?: T[], el?: T) {
   if (isEmpty(array) && isUndefined(el)) return;
 
@@ -300,14 +405,79 @@ function hasConfirmed(data: unknown): data is ConfirmedBoxesResponse {
   return !!(data as ConfirmedBoxesResponse)?.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)
+function mapConfirmedBox<T>(box: GQLBox, mapper: BiMapper<T>): ChainProviderBox<T> {
+  const mapped = mapBox(box, mapper) as ChainProviderBox<T>;
+  mapped.confirmed = true;
+  return mapped;
+}
+
+function mapUnconfirmedBox<T>(box: GQLBox, mapper: BiMapper<T>): ChainProviderBox<T> {
+  const mapped = mapBox(box, mapper) as ChainProviderBox<T>;
+  mapped.confirmed = false;
+  return mapped;
+}
+
+function mapBox<T>(
+  box: GQLBox | GQLUnconfirmedBox,
+  mapper: BiMapper<T>
+): Omit<ChainProviderBox<T>, "confirmed"> {
+  return {
+    boxId: box.boxId,
+    transactionId: box.transactionId,
+    value: mapper(box.value),
+    ergoTree: box.ergoTree,
+    assets: box.assets.map((t) => ({ tokenId: t.tokenId, amount: mapper(t.amount) })),
+    creationHeight: box.creationHeight,
+    additionalRegisters: box.additionalRegisters,
+    index: box.index
+  };
+}
+
+function mapUnconfirmedTransaction<T>(
+  tx: UnconfirmedTransaction,
+  mapper: BiMapper<T>
+): ChainProviderUnconfirmedTransaction<T> {
+  return {
+    transactionId: tx.transactionId,
+    timestamp: Number(tx.timestamp),
+    inputs: tx.inputs.map((i) => ({
+      spendingProof: {
+        // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+        extension: i.extension!,
+        // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+        proofBytes: i.proofBytes!
+      },
+      // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+      ...mapBox(i.box!, mapper)
+    })),
+    dataInputs: tx.dataInputs.map((di) => ({ boxId: di.boxId })),
+    outputs: tx.outputs.map((b) => mapBox(b, mapper)),
+    confirmed: false
+  };
+}
+
+function mapConfirmedTransaction<T>(
+  tx: Transaction,
+  mapper: BiMapper<T>
+): ChainProviderConfirmedTransaction<T> {
+  return {
+    transactionId: tx.transactionId,
+    timestamp: Number(tx.timestamp),
+    inputs: tx.inputs.map((i) => ({
+      spendingProof: {
+        // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+        extension: i.extension!,
+        // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+        proofBytes: i.proofBytes!
+      },
+      // biome-ignore lint/style/noNonNullAssertion: bad type declarations at '@ergo-graphql/type'
+      ...mapBox(i.box!, mapper)
     })),
-    confirmed
-  });
+    dataInputs: tx.dataInputs.map((di) => ({ boxId: di.boxId })),
+    outputs: tx.outputs.map((b) => mapBox(b, mapper)),
+    height: tx.inclusionHeight,
+    headerId: tx.headerId,
+    index: tx.index,
+    confirmed: true
+  };
 }

package/src/ergo-graphql/queries.ts

@@ -1,15 +1,24 @@
 const B = [
-  "query boxes($spent: Boolean! $boxIds: [String!] $ergoTrees: [String!] $ergoTreeTemplateHash: String $tokenId: String $skip: Int $take: Int)",
+  "$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"
+  "boxId transactionId index value creationHeight ergoTree assets { tokenId amount } additionalRegisters"
 ];
 
-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 CONF_BOXES_QUERY = `query boxes($spent: Boolean! ${B[0]}) { boxes(spent: $spent ${B[1]}) { ${B[2]} beingSpent } }`;
+export const UNCONF_BOXES_QUERY = `query boxes(${B[0]}) { mempool { boxes(${B[1]}) { ${B[2]} beingSpent } } }`;
+export const ALL_BOXES_QUERY = `query boxes($spent: Boolean! ${B[0]}) { boxes(spent: $spent ${B[1]}) { ${B[2]} beingSpent } mempool { boxes(${B[1]}) { ${B[2]} beingSpent } } }`;
+
 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) }";
+
+const T = [
+  "$addresses: [String!], $transactionIds: [String!], $skip: Int, $take: Int",
+  "addresses: $addresses, transactionIds: $transactionIds, skip: $skip, take: $take",
+  `transactionId timestamp inputs { proofBytes extension index box { ${B[2]} } } dataInputs { boxId }`
+];
+export const CONF_TX_QUERY = `query confirmedTransactions(${T[0]}  $relevantOnly: Boolean) { transactions(${T[1]}) { ${T[2]} outputs(relevantOnly: $relevantOnly) { ${B[2]} } inclusionHeight headerId index } }`;
+export const UNCONF_TX_QUERY = `query unconfirmedTransactions(${T[0]}) { mempool { transactions(${T[1]}) { ${T[2]} outputs { ${B[2]} } } } }`;

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.