PDPServer

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

Constructors

Constructor

new PDPServer(authHelper, serviceURL): PDPServer;

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

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,
   nextPieceId,
   pieceDataArray,
metadata?): Promise<AddPiecesResponse>;

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

Add pieces to an existing data set

Parameters

Parameter	Type	Description
`dataSetId`	`number`	The ID of the data set to add pieces to
`clientDataSetId`	`number`	The client’s dataset ID used when creating the data set
`nextPieceId`	`number`	The ID to assign to the first piece being added, this should be the next available ID on chain or the signature will fail to be validated
`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, nextPieceId, pieceData, metadata)

createDataSet()

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

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

Create a new data set on the PDP server

Parameters

Parameter	Type	Description
`clientDataSetId`	`number` \| `bigint`	Unique ID for the client’s dataset
`payee`	`string`	Address that will receive payments (service provider)
`payer`	`string`	-
`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:647

Delete a piece from a data set

Parameters

Parameter	Type	Description
`dataSetId`	`number`	The ID of dataset to delete
`clientDataSetId`	`number`	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:594

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:439

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:744

Returns

PDPAuthHelper

getDataSet()

getDataSet(dataSetId): Promise<DataSetData>;

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

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:384

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:413

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:470

Get indexing and IPNI status for a piece

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:740

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:724

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): Promise<UploadResponse>;

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

Upload a piece to the PDP server

Parameters

Parameter	Type	Description
`data`	\| `ArrayBuffer` \| `Uint8Array`<`ArrayBufferLike`>	The data to upload

Returns

Promise<UploadResponse>

Upload response with PieceCID and size