@pcd/pod

A library for creating and manipulating objects in the Provable Object Data format. For a full introduction, see the Developer Site.

POD libraries enable any app to create zero-knowledge proofs of cryptographic data. A POD could represent your ticket to an event, a secure message, a collectible badge, or an item in a role-playing game. Using PODs, developers can create ZK-enabled apps without the effort and risk of developing custom cryptography.

ZK proofs about PODs use General Purpose Circuits (GPC) which can prove many different things about PODs without revealing all details. GPCs use human-readable configuration and pre-compiled circuits so no knowledge of circuit programming is required.

PODs and GPCs can be used in Zupass, or in your own apps without Zupass.

What is a POD?

To a user, a POD is a piece of cryptographic data attested by some issuing authority. For a developer, a POD object is a key-value store which can hold any data. The whole POD is signed by an issuer. Apps can verify the signature, to trust the authenticity of the values in the POD.

When a POD is issued, its entries (key-value pairs) are hashed as part of a Merkle tree. This allows GPCs to selectively prove about individual entries without revealing the whole POD.

const podSword = POD.sign(
  {
    pod_type: { type: "string", value: "myrpg.item.weapon" },
    attack: { type: "int", value: 7n },
    weaponType: { type: "string", value: "sword" },
    itemSet: { type: "string", value: "celestial" },
    isMagical: { type: "boolean", value: true },
    owner: { type: "eddsa_pubkey", value: purchaser.pubKey }
  } satisfies PODEntries,
  privateKey
);
Copy

Entry Points

• The PODEntries type represents names and values in a POD. Start there to learn what a POD can represent.
• The POD class represents a signed POD, which you can create by signing with your private key, or load with an existing signature.
• The PODContent class links POD entries together into a Merkle tree and provides Map-like accessors for named values.

For more details on usage, check out the tutorial code.

Related Packages

• For information about making proofs about PODs, see the @pcd/gpc package.

• To see how PODs are created and stored in the Zupass app, see the @pcd/pod-pcd package.

Package Installation

This package will work either in browser or in a Node.js server. Packaging for a browser requires polyfill for some Node modules, including buffer.

Stability and Security

POD and GPC libraries are in beta and subject to change. We encourage devs to try them out and use them for apps, but be aware that updates will come in future.

The PODs themselves are persistent data, and we expect to maintain backward-compatibility when we make changes to the format. Library interfaces may also change. Any breaking changes will be reflected in the NPM versions using standard semantic versioning.