@piplabs/cdr-sdk

TypeScript SDK for Confidential Data Rails (CDR) on Story L1. Encrypt data to a threshold DKG public key, store it in on-chain vaults, and recover it when a quorum of validators provide partial decryptions.

This is the main entry point. It re-exports everything you need from @piplabs/cdr-contracts (ABIs + addresses) and @piplabs/cdr-crypto (TDH2 / ECIES primitives).

Install

npm install @piplabs/cdr-sdk viem

Optional storage providers (peer dependencies, install only what you use):

npm install helia @helia/unixfs multiformats     # IPFS via Helia
npm install @storacha/client                     # Storacha
npm install @filoz/synapse-sdk                   # Filecoin via Synapse

Quick start

import { CDRClient, initWasm } from "@piplabs/cdr-sdk";
import { createPublicClient, createWalletClient, http } from "viem";
import { privateKeyToAccount } from "viem/accounts";

await initWasm(); // Required before any encryption

const account = privateKeyToAccount(process.env.PRIVATE_KEY as `0x${string}`);
const client = new CDRClient({
  network: "testnet",
  publicClient: createPublicClient({ transport: http("https://aeneid.storyrpc.io") }),
  walletClient: createWalletClient({ account, transport: http("https://aeneid.storyrpc.io") }),
  apiUrl: "http://172.192.41.96:1317", // Story-API REST endpoint — see Networks table in repo README
});

const globalPubKey = await client.observer.getGlobalPubKey();
const threshold = await client.observer.getThreshold();

See the full repository README for end-to-end upload + read flows, condition contracts, and architecture docs.

Public API

• CDRClient — top-level client with .observer, .uploader, .consumer
• Uploader — write encrypted data to a CDR vault
• Consumer — request a vault read and combine partial decryptions
• Observer — query CDR contract state and DKG round info
• conditions — helpers for write/read condition contracts (open, ownerOnly, tokenGate, merkle, custom)
• CDRPublicClient / CDRWalletClient — structural client interfaces accepted by CDRClient. Any viem version (or wagmi wrapper / custom client) that implements the subset works, so dual-viem monorepos don't need pnpm.overrides or as any casts
• CDRLogger, noopLogger — optional structured logger passed to new CDRClient({ logger }). SDK emits stable events such as registry.prefetch.ready, read.tx.sent, read.preflight.insufficient_balance, partial.accepted, and partial.dropped with non-sensitive contexts. Amounts are logged as decimal strings. Defaults to a no-op
• Consumer.registryStatus — synchronous getter ("unbuilt" | "building" | "ready" | "failed") reflecting the most recent prefetchRegistry() call, for UIs that want to show a "preparing verifier" chip
• Typed errors — CDRError is the common base, and SDK errors expose stable code fields. Branch on err.code rather than matching message text
• Consumer.read() runs a balance pre-flight before submitting the fee-bearing read tx (skipped when the client surface omits getBalance or the wallet has no resolvable address) and throws InsufficientBalanceError if the wallet is short on IP
• Re-exported from @piplabs/cdr-crypto: tdh2Encrypt, tdh2Combine, verifyPartialSignature, encryptFile, decryptFile, initWasm, ...
• Re-exported from @piplabs/cdr-contracts: cdrAbi, dkgAbi, contractAddresses, Network, ...

License

MIT — see LICENSE.