filecoin-pin/dist/core/utils/validate-ipni-advertisement.d.ts

Bridge IPFS content to Filecoin Onchain Cloud using familiar tools

import type { ProviderInfo } from '@filoz/synapse-sdk';
import type { CID } from 'multiformats/cid';
import type { Logger } from 'pino';
import type { ProgressEvent, ProgressEventHandler } from './types.js';
export type ValidateIPNIProgressEvents = ProgressEvent<'ipniProviderResults.retryUpdate', {
    retryCount: number;
}> | ProgressEvent<'ipniProviderResults.complete', {
    result: true;
    retryCount: number;
}> | ProgressEvent<'ipniProviderResults.failed', {
    error: Error;
}>;
export interface WaitForIpniProviderResultsOptions {
    /**
     * maximum number of attempts
     *
     * @default: 20
     */
    maxAttempts?: number | undefined;
    /**
     * delay between attempts in milliseconds
     *
     * @default: 5000
     */
    delayMs?: number | undefined;
    /**
     * Abort signal
     *
     * @default: undefined
     */
    signal?: AbortSignal | undefined;
    /**
     * Logger instance
     *
     * @default: undefined
     */
    logger?: Logger | undefined;
    /**
     * Providers that are expected to appear in the IPNI provider results. All
     * providers supplied here must be present in the response for the validation
     * to succeed. When omitted or empty, the validation when the IPNI
     * response is non-empty.
     *
     * @default: []
     */
    expectedProviders?: ProviderInfo[] | undefined;
    /**
     * Callback for progress updates
     *
     * @default: undefined
     */
    onProgress?: ProgressEventHandler<ValidateIPNIProgressEvents>;
    /**
     * IPNI indexer URL to query for provider records to confirm that advertisements were processed.
     *
     * @default 'https://filecoinpin.contact'
     */
    ipniIndexerUrl?: string | undefined;
}
/**
 * Check if the IPNI Indexer has the provided ProviderResults for the provided ipfsRootCid.
 * This effectively verifies the entire SP<->IPNI flow, including:
 * - The SP announced the advertisement chain to the IPNI indexer(s)
 * - The IPNI indexer(s) pulled the advertisement chain from the SP
 * - The IPNI indexer(s) updated their index
 * This doesn't check individual steps, but rather the end ProviderResults reponse from the IPNI indexer.
 * If the IPNI indexer ProviderResults have the expected providers, then the steps abomove must have completed.
 * This doesn't actually do any IPFS Mainnet retrieval checks of the ipfsRootCid.
 *
 * This should not be called until you receive confirmation from the SP that the piece has been parked, i.e. `onPieceAdded` in the `synapse.storage.upload` callbacks.
 *
 * @param ipfsRootCid - The IPFS root CID to check
 * @param options - Options for the check
 * @returns True if the IPNI announce succeeded, false otherwise
 */
export declare function waitForIpniProviderResults(ipfsRootCid: CID, options?: WaitForIpniProviderResultsOptions): Promise<boolean>;
/**
 * Convert a PDP service URL to an IPNI multiaddr format.
 *
 * Storage providers expose their PDP (Proof of Data Possession) service via HTTP/HTTPS
 * endpoints (e.g., "https://provider.example.com:8443"). When they advertise content
 * to IPNI, they include multiaddrs in libp2p format (e.g., "/dns/provider.example.com/tcp/8443/https").
 *
 * This function converts between these representations to enable validation that a
 * provider's IPNI provider records matches their registered service endpoint.
 *
 * @param serviceURL - HTTP/HTTPS URL of the provider's PDP service
 * @param logger - Optional logger for warnings
 * @returns Multiaddr string in libp2p format, or undefined if conversion fails
 *
 * @example
 * serviceURLToMultiaddr('https://provider.example.com')
 * // Returns: '/dns/provider.example.com/tcp/443/https'
 *
 * @example
 * serviceURLToMultiaddr('http://provider.example.com:8080')
 * // Returns: '/dns/provider.example.com/tcp/8080/http'
 */
export declare function serviceURLToMultiaddr(serviceURL: string, logger?: Logger): string | undefined;
//# sourceMappingURL=validate-ipni-advertisement.d.ts.map