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

``TypeScript
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
);
`

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.