import { GraphQLFormattedError } from 'graphql'; import { ContractAddress } from '@midnight-ntwrk/midnight-js-protocol/ledger'; import { PublicDataProvider, SegmentStatus, TxStatus, UnshieldedBalances, UnshieldedUtxos } from '@midnight-ntwrk/midnight-js-types'; import * as ws from 'isomorphic-ws'; /** * Base class for all errors raised by the indexer public data provider. * Consumers can catch any indexer error with a single `instanceof IndexerError` check. */ declare abstract class IndexerError extends Error { } /** * Raised when a GraphQL response includes one or more `GraphQLFormattedError` * entries. Aggregates all server-side errors into a single numbered message * and exposes the original array via {@link errors}. * * The field is named `errors` (not `cause`) because the standard ES2022 * `Error.cause` slot is contractually a single underlying error, not a * peer collection. Reusing `cause` would confuse Node's `util.inspect` * causal chain, Sentry, and other structured loggers. * * Transport-level and other Apollo failures are reported via {@link IndexerQueryError}. */ declare class IndexerFormattedError extends IndexerError { readonly errors: readonly GraphQLFormattedError[]; /** * @param errors The GraphQL errors reported by the server. */ constructor(errors: readonly GraphQLFormattedError[]); } /** * An error raised when an Apollo query or fetch fails at the transport layer * (network failure, malformed response, Apollo client error) — distinct from * the case where the server returns a well-formed response containing * `GraphQLFormattedError` entries, which is reported via * {@link IndexerFormattedError}. * * Preserves the original Apollo error via `Error.cause` so consumers can * inspect network details and the original stack. */ declare class IndexerQueryError extends IndexerError { constructor(message: string, options?: ErrorOptions); } /** * Discriminated context describing the specific way indexer-returned data * failed to satisfy the provider's expectations. The `kind` tag lets * consumers branch on the failure mode without parsing the error message. */ type IndexerDataErrorContext = { kind: 'unknown-status'; value: string; } | { kind: 'missing-contract-action'; contractAddress: string; } | { kind: 'missing-identifier'; contractAddress: string; actionIndex: number; identifiersLength: number; }; /** * An error raised when indexer-returned data is structurally inconsistent * with the provider's expectations: unknown enum values, broken referential * integrity between related rows, or missing relations the schema implies * should be present. * * Distinct from: * - {@link IndexerSubscriptionDataError} — missing top-level field on a * subscription payload (server returned `null`/`undefined` for a field). * - {@link IndexerFormattedError} — errors the server explicitly returned * as `GraphQLFormattedError` entries. * - {@link IndexerQueryError} — transport / Apollo failure before data is * parsed. * * Construct via the static factory methods to ensure the message and * {@link context} stay in sync. */ declare class IndexerDataError extends IndexerError { readonly context: IndexerDataErrorContext; constructor(context: IndexerDataErrorContext); static unknownStatus(value: string): IndexerDataError; static missingContractAction(contractAddress: string): IndexerDataError; static missingIdentifier(contractAddress: string, actionIndex: number, identifiersLength: number): IndexerDataError; private static formatMessage; } /** * Subscription payload fields the indexer provider depends on. * Narrowing this to a literal union prevents typos at throw sites and * documents the exhaustive set of fields the provider currently reads. */ type IndexerSubscriptionField = 'blocks' | 'contractActions'; /** * An error raised when an indexer subscription payload is missing a field * the provider relies on. Carries the missing field name for diagnostics. */ declare class IndexerSubscriptionDataError extends IndexerError { readonly missingField: IndexerSubscriptionField; constructor(missingField: IndexerSubscriptionField); } /** * An error raised when the consumer passes a configuration that the indexer * provider does not support (e.g. an observable mode that cannot be served * by the indexer's query surface). Signals API misuse, not server-side * issues — separate semantic category from {@link IndexerDataError}. */ declare class IndexerProviderConfigError extends IndexerError { constructor(message: string); } type Maybe = T | null; /** All built-in and custom scalars, mapped to their actual values */ type Scalars = { ID: { input: string; output: string; }; String: { input: string; output: string; }; Boolean: { input: boolean; output: boolean; }; Int: { input: number; output: number; }; Float: { input: number; output: number; }; CardanoRewardAddress: { input: string; output: string; }; DustAddress: { input: string; output: string; }; HexEncoded: { input: string; output: string; }; Unit: { input: null; output: null; }; UnshieldedAddress: { input: string; output: string; }; ViewingKey: { input: string; output: string; }; }; /** A block with its relevant data. */ type Block = { /** The hex-encoded block author. */ readonly author: Maybe; /** The block hash. */ readonly hash: Scalars['HexEncoded']['output']; /** The block height. */ readonly height: Scalars['Int']['output']; /** The hex-encoded ledger parameters for this block. */ readonly ledgerParameters: Scalars['HexEncoded']['output']; /** The parent of this block. */ readonly parent: Maybe; /** The protocol version. */ readonly protocolVersion: Scalars['Int']['output']; /** The system parameters (governance) at this block height. */ readonly systemParameters: SystemParameters; /** The UNIX timestamp. */ readonly timestamp: Scalars['Int']['output']; /** The transactions within this block. */ readonly transactions: ReadonlyArray; }; /** A contract action. */ type ContractAction = { readonly address: Scalars['HexEncoded']['output']; readonly state: Scalars['HexEncoded']['output']; readonly transaction: Transaction; readonly unshieldedBalances: ReadonlyArray; readonly zswapState: Scalars['HexEncoded']['output']; }; /** * Represents a token balance held by a contract. * This type is exposed through the GraphQL API to allow clients to query * unshielded token balances for any contract action (Deploy, Call, Update). */ type ContractBalance = { /** Balance amount as string to support larger integer values (up to 16 bytes). */ readonly amount: Scalars['String']['output']; /** Hex-encoded token type identifier. */ readonly tokenType: Scalars['HexEncoded']['output']; }; /** The D-parameter controlling validator committee composition. */ type DParameter = { /** Number of permissioned candidates. */ readonly numPermissionedCandidates: Scalars['Int']['output']; /** Number of registered candidates. */ readonly numRegisteredCandidates: Scalars['Int']['output']; }; /** A dust related ledger event. */ type DustLedgerEvent = { readonly id: Scalars['Int']['output']; readonly maxId: Scalars['Int']['output']; readonly protocolVersion: Scalars['Int']['output']; readonly raw: Scalars['HexEncoded']['output']; }; /** A regular Midnight transaction. */ type RegularTransaction = Transaction & { /** The block for this transaction. */ readonly block: Block; /** The contract actions for this transaction. */ readonly contractActions: ReadonlyArray; /** Dust ledger events of this transaction. */ readonly dustLedgerEvents: ReadonlyArray; /** The zswap state end index. */ readonly endIndex: Scalars['Int']['output']; /** Fee information for this transaction. */ readonly fees: TransactionFees; /** The hex-encoded transaction hash. */ readonly hash: Scalars['HexEncoded']['output']; /** The transaction ID. */ readonly id: Scalars['Int']['output']; /** The hex-encoded serialized transaction identifiers. */ readonly identifiers: ReadonlyArray; /** The hex-encoded serialized merkle-tree root. */ readonly merkleTreeRoot: Scalars['HexEncoded']['output']; /** The protocol version. */ readonly protocolVersion: Scalars['Int']['output']; /** The hex-encoded serialized transaction content. */ readonly raw: Scalars['HexEncoded']['output']; /** The zswap state start index. */ readonly startIndex: Scalars['Int']['output']; /** The result of applying this transaction to the ledger state. */ readonly transactionResult: TransactionResult; /** Unshielded UTXOs created by this transaction. */ readonly unshieldedCreatedOutputs: ReadonlyArray; /** Unshielded UTXOs spent (consumed) by this transaction. */ readonly unshieldedSpentOutputs: ReadonlyArray; /** Zswap ledger events of this transaction. */ readonly zswapLedgerEvents: ReadonlyArray; }; /** * One of many segments for a partially successful transaction result showing success for some * segment. */ type Segment = { /** Segment ID. */ readonly id: Scalars['Int']['output']; /** Successful or not. */ readonly success: Scalars['Boolean']['output']; }; /** System parameters at a specific block height. */ type SystemParameters = { /** The D-parameter controlling validator committee composition. */ readonly dParameter: DParameter; /** The current Terms and Conditions, if any have been set. */ readonly termsAndConditions: Maybe; }; /** Terms and Conditions agreement. */ type TermsAndConditions = { /** The hex-encoded hash of the Terms and Conditions document. */ readonly hash: Scalars['HexEncoded']['output']; /** The URL where the Terms and Conditions can be found. */ readonly url: Scalars['String']['output']; }; /** A Midnight transaction. */ type Transaction = { readonly block: Block; readonly contractActions: ReadonlyArray; readonly dustLedgerEvents: ReadonlyArray; readonly hash: Scalars['HexEncoded']['output']; readonly id: Scalars['Int']['output']; readonly protocolVersion: Scalars['Int']['output']; readonly raw: Scalars['HexEncoded']['output']; readonly unshieldedCreatedOutputs: ReadonlyArray; readonly unshieldedSpentOutputs: ReadonlyArray; readonly zswapLedgerEvents: ReadonlyArray; }; /** Fees information for a transaction, including both paid and estimated fees. */ type TransactionFees = { /** The estimated fees that was calculated for this transaction in DUST. */ readonly estimatedFees: Scalars['String']['output']; /** The actual fees paid for this transaction in DUST. */ readonly paidFees: Scalars['String']['output']; }; /** * The result of applying a transaction to the ledger state. In case of a partial success (status), * there will be segments. */ type TransactionResult = { readonly segments: Maybe>; readonly status: TransactionResultStatus; }; /** The status of the transaction result: success, partial success or failure. */ type TransactionResultStatus = 'FAILURE' | 'PARTIAL_SUCCESS' | 'SUCCESS' | '%future added value'; /** Represents an unshielded UTXO. */ type UnshieldedUtxo = { /** Transaction that created this UTXO. */ readonly createdAtTransaction: Transaction; /** The creation time in seconds. */ readonly ctime: Maybe; /** The hex-encoded initial nonce for DUST generation tracking. */ readonly initialNonce: Scalars['HexEncoded']['output']; /** The hex-encoded serialized intent hash. */ readonly intentHash: Scalars['HexEncoded']['output']; /** Index of this output within its creating transaction. */ readonly outputIndex: Scalars['Int']['output']; /** Owner Bech32m-encoded address. */ readonly owner: Scalars['UnshieldedAddress']['output']; /** Whether this UTXO is registered for DUST generation. */ readonly registeredForDustGeneration: Scalars['Boolean']['output']; /** Transaction that spent this UTXO. */ readonly spentAtTransaction: Maybe; /** Token hex-encoded serialized token type. */ readonly tokenType: Scalars['HexEncoded']['output']; /** UTXO value (quantity) as a string to support u128. */ readonly value: Scalars['String']['output']; }; /** A zswap related ledger event. */ type ZswapLedgerEvent = { /** The ID of this zswap ledger event. */ readonly id: Scalars['Int']['output']; /** The maximum ID of all zswap ledger events. */ readonly maxId: Scalars['Int']['output']; /** The protocol version. */ readonly protocolVersion: Scalars['Int']['output']; /** The hex-encoded serialized event. */ readonly raw: Scalars['HexEncoded']['output']; }; declare const isRegularTransaction: (tx: any) => tx is RegularTransaction & { hash: string; identifiers: string[]; }; declare const toTxStatus: (transactionResult: TransactionResult) => TxStatus; declare const toSegmentStatus: (success: boolean) => SegmentStatus; declare const toSegmentStatusMap: (transactionResult: TransactionResult) => Map | undefined; type IndexerUtxo = { owner: string; intentHash: string; tokenType: string; value: string; }; declare const toUnshieldedUtxos: (createdUtxo: readonly IndexerUtxo[], spentUtxo: readonly IndexerUtxo[]) => UnshieldedUtxos; declare const toUnshieldedBalances: (contractBalances: readonly ContractBalance[]) => UnshieldedBalances; /** * Correlates a contract action at `contractAddress` with the transaction's * identifier at the same positional index. Throws {@link IndexerDataError} * when the deploy lacks an action for the address, when the corresponding * identifier slot is missing, or when the identifier is not a non-empty * string — all indicate that the indexer's contract-action / identifier * rows are out of sync. * * @internal Exported for unit testing the correlation in isolation. * Production callers should go through `PublicDataProvider.watchForDeployTxData`. */ declare const correlateDeployTxId: (contractAddress: ContractAddress, contractActions: readonly { readonly address: string; }[], identifiers: readonly string[]) => string; /** * Constructs a {@link PublicDataProvider} based on an {@link ApolloClient}. * * @param queryURL The URL of a GraphQL server query endpoint. * @param subscriptionURL The URL of a GraphQL server subscription (websocket) endpoint. * @param webSocketImpl An optional websocket implementation for the Apollo client to use. * * TODO: Re-examine caching when 'ContractCall' and 'ContractDeploy' have transaction identifiers included. */ declare const indexerPublicDataProvider: (queryURL: string, subscriptionURL: string, webSocketImpl?: typeof ws.WebSocket) => PublicDataProvider; export { IndexerDataError, IndexerError, IndexerFormattedError, IndexerProviderConfigError, IndexerQueryError, IndexerSubscriptionDataError, correlateDeployTxId, indexerPublicDataProvider, isRegularTransaction, toSegmentStatus, toSegmentStatusMap, toTxStatus, toUnshieldedBalances, toUnshieldedUtxos }; export type { IndexerDataErrorContext, IndexerSubscriptionField, IndexerUtxo };