@fleet-sdk/blockchain-providers 0.5.0 → 0.6.0

package/CHANGELOG.md

@@ -1,5 +1,17 @@
 # @fleet-sdk/blockchain-providers
 
+## 0.6.0
+
+### Minor Changes
+
+- 6ef2c1b: Add custom `BigInt` mapping support
+- 9cdf4dd: Add transaction fetching
+
+### Patch Changes
+
+- 62b881b: Add exponential delay retrying strategy
+- 9ed3499: Add GraphQL operation URL override
+
 ## 0.5.0
 
 ### Patch Changes

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { BoxId, HexString, Base58String, TokenId, Box, BlockHeader, SignedTransaction, UnsignedTransaction, TransactionId } from '@fleet-sdk/common';
+import { BoxId, HexString, Base58String, TokenId, TransactionId, Box, DataInput, BlockHeader, SignedTransaction, UnsignedTransaction, ProverResult } from '@fleet-sdk/common';
 import { ErgoAddress } from '@fleet-sdk/core';
 
 declare global {
@@ -153,6 +153,18 @@ type RequireAtLeastOne<
 Except<ObjectType, KeysType>;
 
 type BoxSource = "blockchain" | "mempool" | "blockchain+mempool";
+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;
+};
 type BoxQuery<W extends BoxWhere> = {
     /** The query to filter boxes. */
     where: RequireAtLeastOne<W>;
@@ -162,23 +174,59 @@ type BoxQuery<W extends BoxWhere> = {
      */
     from?: BoxSource;
 };
-type HeaderQuery = {
-    take: number;
-};
-type BoxWhere = {
-    /** Base16-encoded BoxId */
-    boxId?: BoxId;
+type UnconfirmedTransactionWhere = {
+    /** Base16-encoded TransactionId */
+    transactionId?: TransactionId;
+    /** Base58-encoded address */
+    address?: ErgoAddress | Base58String;
     /** Base16-encoded ErgoTree */
     ergoTree?: HexString;
+};
+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 TokenId */
-    tokenId?: TokenId;
+    /** Base16-encoded ErgoTree */
+    ergoTree?: HexString;
+    /** Min blockchain height */
+    minHeight?: number;
+    /** Only returns relevant outputs for the selected filter params */
+    onlyRelevantOutputs?: boolean;
+};
+type TransactionQuery<W extends ConfirmedTransactionWhere> = {
+    /** The query to filter boxes. */
+    where: RequireAtLeastOne<W, keyof Omit<W, "minHeight" | "onlyRelevantOutputs">>;
+};
+type HeaderQuery = {
+    take: number;
+};
+type ChainProviderBox<T> = Omit<Box, "value" | "assets"> & {
+    value: T;
+    assets: {
+        tokenId: TokenId;
+        amount: T;
+    }[];
+    confirmed: boolean;
 };
-type ChainProviderBox = Box<bigint> & {
+type TransactionOutput<T> = Omit<ChainProviderBox<T>, "confirmed">;
+type TransactionInput<T> = TransactionOutput<T> & {
+    spendingProof: ProverResult;
+};
+type ChainProviderUnconfirmedTransaction<T> = {
+    transactionId: TransactionId;
+    inputs: TransactionInput<T>[];
+    dataInputs: DataInput[];
+    outputs: TransactionOutput<T>[];
     confirmed: boolean;
+    timestamp: number;
+};
+type ChainProviderConfirmedTransaction<T> = ChainProviderUnconfirmedTransaction<T> & {
+    height: number;
+    index: number;
+    headerId: HexString;
 };
 type TransactionEvaluationError = {
     success: false;
@@ -198,15 +246,31 @@ type TransactionReductionResult = TransactionEvaluationError | TransactionReduct
  * Represents a blockchain provider that can interact with the blockchain.
  * @template B The type of the box query used by the provider.
  */
-interface IBlockchainProvider<B extends BoxWhere> {
+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.
      */
@@ -225,9 +289,24 @@ interface IBlockchainProvider<B extends BoxWhere> {
     reduceTransaction(transaction: UnsignedTransaction): Promise<TransactionReductionResult>;
 }
 
-type Credentials = RequestCredentials;
-type Headers = HeadersInit;
-type Fetcher = typeof fetch;
+interface ParserLike {
+    parse<T>(text: string): T;
+    stringify<T>(value: T): string;
+}
+type Route = {
+    base: string;
+    path: string;
+    query?: Record<string, unknown>;
+};
+type URLLike = string | Route;
+type FallbackRetryOptions = {
+    fallbacks?: URLLike[];
+} & RetryOptions;
+type RetryOptions = {
+    attempts: number;
+    delay: number;
+};
+
 type GraphQLVariables = Record<string, unknown> | null;
 interface GraphQLError {
     message: string;
@@ -241,20 +320,16 @@ interface GraphQLErrorResponse {
     errors: GraphQLError[];
 }
 type GraphQLResponse<T = unknown> = GraphQLSuccessResponse<T> | GraphQLErrorResponse;
-type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (variables?: V) => Promise<R>;
-interface ResponseParser {
-    parse<T>(text: string): T;
-    stringify<T>(value: T): string;
-}
+type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (variables?: V, url?: string) => Promise<R>;
 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">;
 }
 
+type BiMapper<T> = (value: string) => T;
 type GraphQLBoxWhere = BoxWhere & {
     /** Base16-encoded BoxIds */
     boxIds?: HexString[];
@@ -263,14 +338,30 @@ type GraphQLBoxWhere = BoxWhere & {
     /** Base58-encoded addresses or `ErgoAddress` objects */
     addresses?: (Base58String | ErgoAddress)[];
 };
+type GraphQLConfirmedTransactionWhere = ConfirmedTransactionWhere & {
+    transactionIds?: HexString[];
+    addresses?: (Base58String | ErgoAddress)[];
+    ergoTrees?: HexString[];
+};
+type GraphQLUnconfirmedTransactionWhere = UnconfirmedTransactionWhere & {
+    transactionIds?: HexString[];
+    addresses?: (Base58String | ErgoAddress)[];
+    ergoTrees?: HexString[];
+};
 type GraphQLBoxQuery = BoxQuery<GraphQLBoxWhere>;
 type ErgoGraphQLRequestOptions = Omit<GraphQLRequestOptions, "throwOnNonNetworkError">;
-declare class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
+declare class ErgoGraphQLProvider<I = bigint> implements IBlockchainProvider<I> {
     #private;
-    constructor(url: string | URL);
+    constructor(url: string);
     constructor(url: ErgoGraphQLRequestOptions);
-    streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox[]>;
-    getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox[]>;
+    setUrl(url: string): ErgoGraphQLProvider<I>;
+    setBigIntMapper<M>(mapper: BiMapper<M>): ErgoGraphQLProvider<M>;
+    streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox<I>[]>;
+    getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox<I>[]>;
+    streamUnconfirmedTransactions(query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>): AsyncIterable<ChainProviderUnconfirmedTransaction<I>[]>;
+    getUnconfirmedTransactions(query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>): Promise<ChainProviderUnconfirmedTransaction<I>[]>;
+    streamConfirmedTransactions(query: TransactionQuery<GraphQLConfirmedTransactionWhere>): AsyncIterable<ChainProviderConfirmedTransaction<I>[]>;
+    getConfirmedTransactions(query: TransactionQuery<GraphQLConfirmedTransactionWhere>): Promise<ChainProviderConfirmedTransaction<I>[]>;
     getHeaders(query: HeaderQuery): Promise<BlockHeader[]>;
     createOperation<R, V extends GraphQLVariables = GraphQLVariables>(query: string, options?: Partial<ErgoGraphQLRequestOptions>): GraphQLOperation<GraphQLSuccessResponse<R>, V>;
     checkTransaction(signedTransaction: SignedTransaction): Promise<TransactionEvaluationResult>;
@@ -278,4 +369,4 @@ declare class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     reduceTransaction(): Promise<TransactionReductionResult>;
 }
 
-export { ErgoGraphQLProvider, type ErgoGraphQLRequestOptions, type GraphQLBoxQuery, type GraphQLBoxWhere };
+export { ErgoGraphQLProvider, type ErgoGraphQLRequestOptions, type GraphQLBoxQuery, type GraphQLBoxWhere, type GraphQLConfirmedTransactionWhere, type GraphQLUnconfirmedTransactionWhere };

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { BoxId, HexString, Base58String, TokenId, Box, BlockHeader, SignedTransaction, UnsignedTransaction, TransactionId } from '@fleet-sdk/common';
+import { BoxId, HexString, Base58String, TokenId, TransactionId, Box, DataInput, BlockHeader, SignedTransaction, UnsignedTransaction, ProverResult } from '@fleet-sdk/common';
 import { ErgoAddress } from '@fleet-sdk/core';
 
 declare global {
@@ -153,6 +153,18 @@ type RequireAtLeastOne<
 Except<ObjectType, KeysType>;
 
 type BoxSource = "blockchain" | "mempool" | "blockchain+mempool";
+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;
+};
 type BoxQuery<W extends BoxWhere> = {
     /** The query to filter boxes. */
     where: RequireAtLeastOne<W>;
@@ -162,23 +174,59 @@ type BoxQuery<W extends BoxWhere> = {
      */
     from?: BoxSource;
 };
-type HeaderQuery = {
-    take: number;
-};
-type BoxWhere = {
-    /** Base16-encoded BoxId */
-    boxId?: BoxId;
+type UnconfirmedTransactionWhere = {
+    /** Base16-encoded TransactionId */
+    transactionId?: TransactionId;
+    /** Base58-encoded address */
+    address?: ErgoAddress | Base58String;
     /** Base16-encoded ErgoTree */
     ergoTree?: HexString;
+};
+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 TokenId */
-    tokenId?: TokenId;
+    /** Base16-encoded ErgoTree */
+    ergoTree?: HexString;
+    /** Min blockchain height */
+    minHeight?: number;
+    /** Only returns relevant outputs for the selected filter params */
+    onlyRelevantOutputs?: boolean;
+};
+type TransactionQuery<W extends ConfirmedTransactionWhere> = {
+    /** The query to filter boxes. */
+    where: RequireAtLeastOne<W, keyof Omit<W, "minHeight" | "onlyRelevantOutputs">>;
+};
+type HeaderQuery = {
+    take: number;
+};
+type ChainProviderBox<T> = Omit<Box, "value" | "assets"> & {
+    value: T;
+    assets: {
+        tokenId: TokenId;
+        amount: T;
+    }[];
+    confirmed: boolean;
 };
-type ChainProviderBox = Box<bigint> & {
+type TransactionOutput<T> = Omit<ChainProviderBox<T>, "confirmed">;
+type TransactionInput<T> = TransactionOutput<T> & {
+    spendingProof: ProverResult;
+};
+type ChainProviderUnconfirmedTransaction<T> = {
+    transactionId: TransactionId;
+    inputs: TransactionInput<T>[];
+    dataInputs: DataInput[];
+    outputs: TransactionOutput<T>[];
     confirmed: boolean;
+    timestamp: number;
+};
+type ChainProviderConfirmedTransaction<T> = ChainProviderUnconfirmedTransaction<T> & {
+    height: number;
+    index: number;
+    headerId: HexString;
 };
 type TransactionEvaluationError = {
     success: false;
@@ -198,15 +246,31 @@ type TransactionReductionResult = TransactionEvaluationError | TransactionReduct
  * Represents a blockchain provider that can interact with the blockchain.
  * @template B The type of the box query used by the provider.
  */
-interface IBlockchainProvider<B extends BoxWhere> {
+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.
      */
@@ -225,9 +289,24 @@ interface IBlockchainProvider<B extends BoxWhere> {
     reduceTransaction(transaction: UnsignedTransaction): Promise<TransactionReductionResult>;
 }
 
-type Credentials = RequestCredentials;
-type Headers = HeadersInit;
-type Fetcher = typeof fetch;
+interface ParserLike {
+    parse<T>(text: string): T;
+    stringify<T>(value: T): string;
+}
+type Route = {
+    base: string;
+    path: string;
+    query?: Record<string, unknown>;
+};
+type URLLike = string | Route;
+type FallbackRetryOptions = {
+    fallbacks?: URLLike[];
+} & RetryOptions;
+type RetryOptions = {
+    attempts: number;
+    delay: number;
+};
+
 type GraphQLVariables = Record<string, unknown> | null;
 interface GraphQLError {
     message: string;
@@ -241,20 +320,16 @@ interface GraphQLErrorResponse {
     errors: GraphQLError[];
 }
 type GraphQLResponse<T = unknown> = GraphQLSuccessResponse<T> | GraphQLErrorResponse;
-type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (variables?: V) => Promise<R>;
-interface ResponseParser {
-    parse<T>(text: string): T;
-    stringify<T>(value: T): string;
-}
+type GraphQLOperation<R extends GraphQLResponse, V extends GraphQLVariables> = (variables?: V, url?: string) => Promise<R>;
 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">;
 }
 
+type BiMapper<T> = (value: string) => T;
 type GraphQLBoxWhere = BoxWhere & {
     /** Base16-encoded BoxIds */
     boxIds?: HexString[];
@@ -263,14 +338,30 @@ type GraphQLBoxWhere = BoxWhere & {
     /** Base58-encoded addresses or `ErgoAddress` objects */
     addresses?: (Base58String | ErgoAddress)[];
 };
+type GraphQLConfirmedTransactionWhere = ConfirmedTransactionWhere & {
+    transactionIds?: HexString[];
+    addresses?: (Base58String | ErgoAddress)[];
+    ergoTrees?: HexString[];
+};
+type GraphQLUnconfirmedTransactionWhere = UnconfirmedTransactionWhere & {
+    transactionIds?: HexString[];
+    addresses?: (Base58String | ErgoAddress)[];
+    ergoTrees?: HexString[];
+};
 type GraphQLBoxQuery = BoxQuery<GraphQLBoxWhere>;
 type ErgoGraphQLRequestOptions = Omit<GraphQLRequestOptions, "throwOnNonNetworkError">;
-declare class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
+declare class ErgoGraphQLProvider<I = bigint> implements IBlockchainProvider<I> {
     #private;
-    constructor(url: string | URL);
+    constructor(url: string);
     constructor(url: ErgoGraphQLRequestOptions);
-    streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox[]>;
-    getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox[]>;
+    setUrl(url: string): ErgoGraphQLProvider<I>;
+    setBigIntMapper<M>(mapper: BiMapper<M>): ErgoGraphQLProvider<M>;
+    streamBoxes(query: GraphQLBoxQuery): AsyncGenerator<ChainProviderBox<I>[]>;
+    getBoxes(query: GraphQLBoxQuery): Promise<ChainProviderBox<I>[]>;
+    streamUnconfirmedTransactions(query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>): AsyncIterable<ChainProviderUnconfirmedTransaction<I>[]>;
+    getUnconfirmedTransactions(query: TransactionQuery<GraphQLUnconfirmedTransactionWhere>): Promise<ChainProviderUnconfirmedTransaction<I>[]>;
+    streamConfirmedTransactions(query: TransactionQuery<GraphQLConfirmedTransactionWhere>): AsyncIterable<ChainProviderConfirmedTransaction<I>[]>;
+    getConfirmedTransactions(query: TransactionQuery<GraphQLConfirmedTransactionWhere>): Promise<ChainProviderConfirmedTransaction<I>[]>;
     getHeaders(query: HeaderQuery): Promise<BlockHeader[]>;
     createOperation<R, V extends GraphQLVariables = GraphQLVariables>(query: string, options?: Partial<ErgoGraphQLRequestOptions>): GraphQLOperation<GraphQLSuccessResponse<R>, V>;
     checkTransaction(signedTransaction: SignedTransaction): Promise<TransactionEvaluationResult>;
@@ -278,4 +369,4 @@ declare class ErgoGraphQLProvider implements IBlockchainProvider<BoxWhere> {
     reduceTransaction(): Promise<TransactionReductionResult>;
 }
 
-export { ErgoGraphQLProvider, type ErgoGraphQLRequestOptions, type GraphQLBoxQuery, type GraphQLBoxWhere };
+export { ErgoGraphQLProvider, type ErgoGraphQLRequestOptions, type GraphQLBoxQuery, type GraphQLBoxWhere, type GraphQLConfirmedTransactionWhere, type GraphQLUnconfirmedTransactionWhere };