PDPServer

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

Constructors

Constructor

new PDPServer(authHelper, serviceURL): PDPServer;

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

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

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

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

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

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

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

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

Returns

PDPAuthHelper

---

getDataSet()

getDataSet(dataSetId): Promise<DataSetData>;

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

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

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

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

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

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

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

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