filecoin-pin
    Preparing search index...

    Interface UploadExecutionOptions

    interface UploadExecutionOptions {
        contextId?: string;
        contexts?: StorageContext[];
        copies?: number;
        dataSetIds?: bigint[];
        excludeProviderIds?: bigint[];
        ipniValidation?: { enabled?: boolean } & Omit<
            WaitForIpniProviderResultsOptions,
            "onProgress",
        >;
        logger: Logger;
        metadata?: Record<string, string>;
        onProgress?: ProgressEventHandler<
            | {
                data: {
                    attempt: number;
                    cid: CID;
                    cidAttempt: number;
                    cidCount: number;
                    cidIndex: number;
                    cidMaxAttempts: number;
                    retryCount: number;
                    totalAttempts: number;
                };
                type: "ipniProviderResults.retryUpdate";
            }
            | {
                data: { result: true; retryCount: number };
                type: "ipniProviderResults.complete";
            }
            | { data: { error: Error }; type: "ipniProviderResults.failed" }
            | { data: { pieceCid: PieceLink; providerId: bigint }; type: "onStored" }
            | {
                data: { providerId: bigint; txHash: `0x${string}` };
                type: "onPiecesAdded";
            }
            | {
                data: { dataSetId: bigint; pieceIds: bigint[]; providerId: bigint };
                type: "onPiecesConfirmed";
            }
            | {
                data: { pieceCid: PieceLink; providerId: bigint };
                type: "onCopyComplete";
            }
            | {
                data: { error: Error; pieceCid: PieceLink; providerId: bigint };
                type: "onCopyFailed";
            }
            | {
                data: { pieceCid: PieceLink; providerId: bigint; status: PullStatus };
                type: "onPullProgress";
            }
            | { data: { provider: PDPProvider }; type: "onProviderSelected" }
            | {
                data: { dataSetId: bigint; provider: PDPProvider };
                type: "onDataSetResolved";
            },
        >;
        pieceMetadata?: Record<string, string>;
        providerIds?: bigint[];
        signal?: AbortSignal;
    }
    Index

    Properties

    contextId? contexts? copies? dataSetIds? excludeProviderIds? ipniValidation? logger metadata? onProgress? pieceMetadata? providerIds? signal?

    Properties

    contextId?: string

    Optional identifier to help correlate logs.

    contexts?: StorageContext[]

    Pre-created storage contexts to use directly. When provided, the SDK skips provider selection and uses these contexts as-is. Each context carries its provider binding and (optional) data set ID.

    Mutually exclusive with providerIds, dataSetIds, and copies.

    const [ctx] = await synapse.storage.createContexts({ providerIds: [9n] })
    executeUpload(synapse, carData, rootCid, { contexts: [ctx], logger, ... })
    copies?: number

    Number of storage copies to create (default determined by SDK).

    dataSetIds?: bigint[]

    Specific existing data set IDs to target. Mutually exclusive with providerIds and contexts.

    Use only when resuming into a known data set from a prior operation. For first-time uploads to specific providers, use providerIds instead.

    excludeProviderIds?: bigint[]

    Provider IDs to exclude from selection.

    ipniValidation?: { enabled?: boolean } & Omit<
        WaitForIpniProviderResultsOptions,
        "onProgress",
    >

    Optional IPNI validation behaviour. When enabled (default), the upload flow will wait for the IPFS Root CID to be announced to IPNI.

    Type Declaration

    • Optionalenabled?: boolean

      Enable the IPNI validation wait.

      @default: true

    logger: Logger

    Logger used for structured upload events.

    metadata?: Record<string, string>

    Data set metadata applied when creating or matching contexts.

    onProgress?: ProgressEventHandler<
        | {
            data: {
                attempt: number;
                cid: CID;
                cidAttempt: number;
                cidCount: number;
                cidIndex: number;
                cidMaxAttempts: number;
                retryCount: number;
                totalAttempts: number;
            };
            type: "ipniProviderResults.retryUpdate";
        }
        | {
            data: { result: true; retryCount: number };
            type: "ipniProviderResults.complete";
        }
        | { data: { error: Error }; type: "ipniProviderResults.failed" }
        | { data: { pieceCid: PieceLink; providerId: bigint }; type: "onStored" }
        | {
            data: { providerId: bigint; txHash: `0x${string}` };
            type: "onPiecesAdded";
        }
        | {
            data: { dataSetId: bigint; pieceIds: bigint[]; providerId: bigint };
            type: "onPiecesConfirmed";
        }
        | {
            data: { pieceCid: PieceLink; providerId: bigint };
            type: "onCopyComplete";
        }
        | {
            data: { error: Error; pieceCid: PieceLink; providerId: bigint };
            type: "onCopyFailed";
        }
        | {
            data: { pieceCid: PieceLink; providerId: bigint; status: PullStatus };
            type: "onPullProgress";
        }
        | { data: { provider: PDPProvider }; type: "onProviderSelected" }
        | {
            data: { dataSetId: bigint; provider: PDPProvider };
            type: "onDataSetResolved";
        },
    >

    Optional umbrella onProgress receiving child progress events.

    pieceMetadata?: Record<string, string>

    Optional metadata to associate with the upload (per-piece).

    providerIds?: bigint[]

    Specific provider IDs to upload to. The SDK resolves or creates data sets on each provider automatically. Mutually exclusive with dataSetIds and contexts.

    This is the recommended way to target specific providers. Do not call createContext() to resolve data sets first. Pass provider IDs here and the SDK handles the rest.

    executeUpload(synapse, carData, rootCid, { providerIds: [4n, 9n], ... })
    signal?: AbortSignal

    Optional AbortSignal to cancel the upload operation.

    Settings

    Member Visibility

    On This Page

    Properties