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.

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 .

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

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
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
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
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.

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

Last updated

Was this helpful?