PDPServer

Defined in: packages/synapse-sdk/src/pdp/server.ts:167

Constructors

Constructor

new PDPServer(authHelper, serviceURL): PDPServer;

Defined in: packages/synapse-sdk/src/pdp/server.ts:176

Create a new PDPServer instance

Parameters

Parameter	Type	Description
authHelper	| PDPAuthHelper | null	PDPAuthHelper instance for signing operations
serviceURL	string	The PDP service URL (e.g., https://pdp.provider.com)

Returns

PDPServer

Methods

addPieces()

addPieces(
   dataSetId,
   clientDataSetId,
   pieceDataArray,
metadata?): Promise<AddPiecesResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:343

Add pieces to an existing data set

Parameters

Parameter	Type	Description
dataSetId	number	The ID of the data set to add pieces to
clientDataSetId	bigint	The client’s dataset ID used when creating the data set
pieceDataArray	string[] | PieceLink[]	Array of piece data containing PieceCID CIDs and raw sizes
metadata?	MetadataEntry[][]	Optional metadata for each piece (array of arrays, one per piece)

Returns

Promise<AddPiecesResponse>

Promise that resolves when the pieces are added (201 Created)

Throws

Error if any CID is invalid

Example

const pieceData = ['bafkzcibcd...']
const metadata = [[{ key: 'snapshotDate', value: '20250711' }]]
await pdpTool.addPieces(dataSetId, clientDataSetId, pieceData, metadata)

---

createAndAddPieces()

createAndAddPieces(
   clientDataSetId,
   payee,
   payer,
   recordKeeper,
   pieceDataArray,
metadata): Promise<CreateDataSetResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:235

Creates a data set and adds pieces to it in a combined operation. Users can poll the status of the operation using the returned data set status URL. After which the user can use the returned transaction hash and data set ID to check the status of the piece addition.

Parameters

Parameter	Type	Description
clientDataSetId	bigint	Unique ID for the client’s dataset
payee	string	Address that will receive payments (service provider)
payer	string	Address that will pay for the storage (client)
recordKeeper	string	Address of the Warm Storage contract
pieceDataArray	string[] | PieceLink[]	Array of piece data containing PieceCID CIDs and raw sizes
metadata	{ dataset?: MetadataEntry[]; pieces?: MetadataEntry[][]; }	Optional metadata for dataset and each of the pieces.
metadata.dataset?	MetadataEntry[]	-
metadata.pieces?	MetadataEntry[][]	-

Returns

Promise<CreateDataSetResponse>

Promise that resolves with transaction hash and status URL

---

createDataSet()

createDataSet(
   clientDataSetId,
   payee,
   payer,
   metadata,
recordKeeper): Promise<CreateDataSetResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:194

Create a new data set on the PDP server

Parameters

Parameter	Type	Description
clientDataSetId	bigint	Unique ID for the client’s dataset
payee	string	Address that will receive payments (service provider)
payer	string	Address that will pay for the storage (client)
metadata	MetadataEntry[]	Metadata entries for the data set (key-value pairs)
recordKeeper	string	Address of the Warm Storage contract

Returns

Promise<CreateDataSetResponse>

Promise that resolves with transaction hash and status URL

---

deletePiece()

deletePiece(
   dataSetId,
   clientDataSetId,
pieceID): Promise<string>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:594

Delete a piece from a data set

Parameters

Parameter	Type	Description
dataSetId	number	The ID of dataset to delete
clientDataSetId	bigint	Client dataset ID of the dataset to delete
pieceID	number	The ID of the piece to delete

Returns

Promise<string>

Promise for transaction hash of the delete operation

---

downloadPiece()

downloadPiece(pieceCid): Promise<Uint8Array<ArrayBufferLike>>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:546

Download a piece from a service provider

Parameters

Parameter	Type	Description
pieceCid	string | PieceLink	The PieceCID CID of the piece

Returns

Promise<Uint8Array<ArrayBufferLike>>

The downloaded data

---

findPiece()

findPiece(pieceCid): Promise<FindPieceResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:443

Find a piece by PieceCID and size

Parameters

Parameter	Type	Description
pieceCid	string | PieceLink	The PieceCID CID (as string or PieceCID object)

Returns

Promise<FindPieceResponse>

Piece information if found

---

getAuthHelper()

getAuthHelper(): PDPAuthHelper;

Defined in: packages/synapse-sdk/src/pdp/server.ts:685

Returns

PDPAuthHelper

---

getDataSet()

getDataSet(dataSetId): Promise<DataSetData>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:566

Get data set details from the PDP server

Parameters

Parameter	Type	Description
dataSetId	number	The ID of the data set to fetch

Returns

Promise<DataSetData>

Promise that resolves with data set data

---

getDataSetCreationStatus()

getDataSetCreationStatus(txHash): Promise<DataSetCreationStatusResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:388

Check the status of a data set creation

Parameters

Parameter	Type	Description
txHash	string	Transaction hash from createDataSet

Returns

Promise<DataSetCreationStatusResponse>

Promise that resolves with the creation status

---

getPieceAdditionStatus()

getPieceAdditionStatus(dataSetId, txHash): Promise<PieceAdditionStatusResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:417

Check the status of a piece addition transaction

Parameters

Parameter	Type	Description
dataSetId	number	The data set ID
txHash	string	Transaction hash from addPieces

Returns

Promise<PieceAdditionStatusResponse>

Promise that resolves with the addition status

---

getPieceStatus()

getPieceStatus(pieceCid): Promise<PieceStatusResponse>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:467

Get indexing and IPNI status for a piece

TODO: not used anywhere, remove?

Parameters

Parameter	Type	Description
pieceCid	string | PieceLink	The PieceCID CID (as string or PieceCID object)

Returns

Promise<PieceStatusResponse>

Piece status information including indexing and IPNI advertisement status

Throws

Error if piece not found or doesn’t belong to service (404)

---

getServiceURL()

getServiceURL(): string;

Defined in: packages/synapse-sdk/src/pdp/server.ts:681

Get the service URL for this PDPServer instance

Returns

string

The service URL

---

ping()

ping(): Promise<void>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:664

Ping the service provider to check connectivity

Returns

Promise<void>

Promise that resolves if provider is reachable (200 response)

Throws

Error if provider is not reachable or returns non-200 status

---

uploadPiece()

uploadPiece(data, options?): Promise<void>;

Defined in: packages/synapse-sdk/src/pdp/server.ts:505

Upload a piece to the PDP server using the commp-last protocol.

Accepts data as Uint8Array, AsyncIterable, or ReadableStream. For optimal performance with non-trivial sizes, prefer streaming types (AsyncIterable or ReadableStream) to avoid memory pressure and blocking behavior. See SIZE_CONSTANTS.MAX_UPLOAD_SIZE documentation for detailed guidance.

Parameters

Parameter	Type	Description
data	| Uint8Array<ArrayBufferLike> | AsyncIterable<Uint8Array<ArrayBufferLike>, any, any> | ReadableStream<Uint8Array<ArrayBufferLike>>	The data to upload (Uint8Array, AsyncIterable, or ReadableStream)
options?	UploadPieceOptions	Optional upload options

Returns

Promise<void>