Use PDP

This guide walks you through using the PDP client tool (pdptool) to interact with a Filecoin Storage Provider running the Proof of Data Possession (PDP) service.

DEPRECATED DEVELOPER TOOL

This documentation refers to the legacy pdptool, which is intended only for low-level developer testing.

It is not the recommended method for onboarding or interacting with PDP Storage Providers.

For current usage, including working with live PDP SPs and submitting real deals, please use the Synapse SDK and Synapse dApp Tutorial.

PDP ensures that your data is verifiably stored by a Filecoin Storage Provider using cryptographic proofs without needing to retrieve the file itself.

Prerequisites

Before beginning, ensure:

You have access to a terminal with internet connectivity
Your system has pdptool installed (bundled with Curio)

If pdptool is not installed:

Option 1: Clone Curio and build pdptool:

git clone 
https://github.com/filecoin-project/curio.git

cd curio
cd cmd/pdptool
go build .

Option 2: Install the Docker version of pdptool - Provided by our friends at ChainSafe

Authenticate Your Client (JWT Token)

You first need to authenticate your pdptool with a PDP-enabled Storage Provider

Generate a service secret:

./pdptool create-service-secret

# Example output:

-----BEGIN PUBLIC KEY-----
LxP9MzVmHdC7KwYBvNAo1jXuIRfGXqQyo2JzE4Uctn0a5eFZbs6Wlvq3dKYgphTD
XAqRsm38LPt2iVcGb9MruZJxEkBhO71wDdNyaFMoXpCJnUqRAezvKlfbIg==
-----END PUBLIC KEY-----

Reach out in the #fil-pdp channel in Filecoin Slack to register your public key with a PDP-enabled Storage Provider

Connect to a PDP Service

Start by pinging the PDP service to confirm availability:

./pdptool ping --service-url https://yablu.net --service-name pdp-service

You should see something like:

Ping successful: Service is reachable and JWT token is valid.

Create a Proof Set

Start by creating an empty proof set. This step must happen before uploading files:

./pdptool create-proof-set \
  --service-url https://yablu.net \
  --service-name pdp-service \
  --recordkeeper 0x6170dE2b09b404776197485F3dc6c968Ef948505

# Example output:

Proof set creation initiated successfully.
Location: /pdp/proof-sets/created/0xf91617ef532748efb5a51e64391112e5328fbd9a5b9ac20e5127981cea0012a5
Response:

Use the 0x transaction hash from the previous output to monitor proof set creation status:

./pdptool get-proof-set-create-status \
  --service-url https://yablu.net \
  --service-name pdp-service \
  --tx-hash 0xf91617ef532748efb5a51e64391112e5328fbd9a5b9ac20e5127981cea0012a5

You should see something like:

Proof Set Creation Status:
Transaction Hash: 0xf91617ef532748efb5a51e64391112e5328fbd9a5b9ac20e5127981cea0012a5
Transaction Status: confirmed
Transaction Successful: true
Proofset Created: true
ProofSet ID: 43

The proof set creation process can take a few seconds to complete

Upload Files to the Storage Provider

Once your proof set is ready, you can begin uploading files:

./pdptool upload-file --service-url https://yablu.net --service-name pdp-service /path/to/file.ext

Example output:

0: pieceSize: 65536
baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli:baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli

🌳 Add File Roots to Proof Set

After uploading each file, extract its CID and add it to your proof set:

./pdptool add-roots \
  --service-url https://yablu.net \
  --service-name pdp-service \
  --proof-set-id <PROOF-SET-ID> \
  --root <CID1>+<CID2>+<CID3>...

Example using the information returned in the previous steps:

./pdptool add-roots \
  --service-url https://yablu.net \
  --service-name pdp-service \
  --proof-set-id 43 \
  --root baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli:baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli

In the above example, --proof-set-id came from the Create Proof Set step, and --root from the Upload Files to the Storage Provider step.

Example output:

Roots added to proof set ID 43 successfully.
Response:

View a Piece or Proof Set

You can retrieve a proof set or inspect a file root directly:

./pdptool get-proof-set \
  --service-url https://yablu.net \
  --service-name pdp-service 43

Example output:

Proof Set ID: 43
Next Challenge Epoch: 2577608
Roots:
  - Root ID: 0
    Root CID: baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli
    Subroot CID: baga6ea4seaqhsevhssmv3j7jjavm4gzdckpjrvbwhhvn73sgibob5bdvtzoqkli
    Subroot Offset: 0

Retrieve From a Proof Set

Download a file using an ordered chunks list:

./pdptool download-file \
  --service-url https://yablu.net \
  --chunk-file chunks.list \
  --output-file file.ext

💡In the above example, –chunk-file and –output-file flags were defined in the Upload Files to the Storage Provider step

You’re Done!

You’ve now:

✅ Connected to a PDP-enabled storage provider ✅ Created a proof set ✅ Uploaded files and added file roots ✅ Verified availability and proof status

🧭 Next: Track your proof sets in the PDP Explorer

💬 Questions? Join the conversation on Filecoin Slack: #fil-pdp

PreviousEnable PDP NextImplementations

Last updated 1 month ago

Was this helpful?