Skip to main content

Documentation Index

Fetch the complete documentation index at: https://docs.story.foundation/llms.txt

Use this file to discover all available pages before exploring further.

This guide walks through the two main CDR flows:
  • uploadCDR / accessCDR for small secrets stored directly on-chain
  • uploadFile / downloadFile for larger encrypted files stored off-chain

​
Prerequisites

  • CDR SDK setup complete with WASM initialized and client created

​
What Runs On-Chain vs Off-Chain

OperationSends transaction?What happens
observer.getGlobalPubKey()NoPure read of DKG state over the Story-API REST endpoint
uploadCDR()Yes, 2 txsLocal TDH2 encryption plus allocate() and write()
uploadFile()Yes, 2 txs + storage uploadLocal AES encryption, storage upload, then allocate() and write()
accessCDR()Yes, 1 txread() on-chain, then off-chain partial collection and local combination
downloadFile()Yes, 1 tx + storage downloadaccessCDR() plus encrypted file download and local AES decryption

​
Encrypt a Secret

The diagram below shows the on-chain secret flow: allocate a vault, encrypt the secret locally with TDH2, and write the ciphertext to the vault.
CDR encryption flow showing vault allocation, local encryption, and writing the ciphertext to the vault
The simplest “owner-only” pattern uses your wallet (EOA) address as both the write and read condition. The CDR contract bypasses the condition check when msg.sender equals the configured condition address, so only that wallet can write or read the vault. Because the high-level uploadCDR() helper validates that condition addresses point at deployed condition contracts, EOA conditions are configured through the low-level allocate() call with skipConditionValidation: true. 
import { initWasm, uuidToLabel } from "@piplabs/cdr-sdk";
import { toHex } from "viem";

await initWasm();

// Assumes `client` and `walletClient` are already created (see Setup)
const { uploader, observer } = client;
const walletAddress = walletClient.account!.address;

// Pure read: fetch the DKG global public key
const globalPubKey = await observer.getGlobalPubKey();

// Encode your secret as bytes
const secret = "my confidential data";
const dataKey = new TextEncoder().encode(secret);

// On-chain transaction: allocate a vault using the wallet address as the
// write AND read condition. Only this EOA can write or read.
const { uuid, txHash: allocateTx } = await uploader.allocate({
  updatable: false,
  writeConditionAddr: walletAddress,
  readConditionAddr: walletAddress,
  writeConditionData: "0x",
  readConditionData: "0x",
  skipConditionValidation: true,
});

// Local: TDH2-encrypt the secret, bound to this vault's UUID
const label = uuidToLabel(uuid);
const ciphertext = await uploader.encryptDataKey({
  dataKey,
  globalPubKey,
  label,
});

// On-chain transaction: write encrypted data to the vault
const { txHash: writeTx } = await uploader.write({
  uuid,
  accessAuxData: "0x",
  encryptedData: toHex(ciphertext.raw),
});

console.log(`Vault created with UUID: ${uuid}`);
console.log(`Allocate tx: ${allocateTx}`);
console.log(`Write tx: ${writeTx}`);
Any EOA address works as a write or read condition — only that EOA can perform the matching action. To gate just one side, set your wallet address on that side and a condition contract (such as LicenseReadCondition) on the other. The high-level uploadCDR() helper expects deployed condition contracts on both sides and does not support EOA conditions, so use it for patterns like Story license-gated reads (see IP Asset Vaults) and use the low-level allocate() + write() flow above for owner-only EOA conditions.
The value of the transaction must be exactly the same as the fee.
dataKey is the historical parameter name. In encryptDataKey() it can be any secret bytes, not just a cryptographic key.
Vault encrypted data is limited to 1024 bytes on Aeneid (maxEncryptedDataSize). TDH2 adds overhead, so the maximum plaintext is smaller. For larger content, use uploadFile() so only a small {cid, key} payload is written to the vault.

​
Decrypt a Secret

Decryption requires submitting a read request on-chain, collecting partial decryptions from validators, and combining them client-side.
CDR decryption flow showing ephemeral key generation, access control check, partial decryptions from validators, and client-side combination
const { consumer } = client;

// Sends 1 transaction, then collects partials and combines them locally
const { dataKey, txHash } = await consumer.accessCDR({
  uuid,
  accessAuxData: "0x",
  timeoutMs: 120_000, // wait up to 2 minutes for validators
});

const secret = new TextDecoder().decode(dataKey);
console.log(`Read tx: ${txHash}`);
console.log(`Decrypted secret: ${secret}`);
accessCDR() auto-generates the ephemeral keypair and auto-queries globalPubKey when you omit them. The threshold is derived automatically from the partial-decryption bucket’s DKG round.
The timeout of the request on the server side is 200 blocks, which is approximately 7 minutes. If you’re not able to collect enough partials within this timeout, try another read request.
import { secp256k1 } from "@noble/curves/secp256k1";
import { toHex } from "viem";

const { consumer, observer } = client;

const globalPubKey = await observer.getGlobalPubKey();

const recipientPrivKey = secp256k1.utils.randomPrivateKey();
const requesterPubKey = toHex(
secp256k1.getPublicKey(recipientPrivKey, false),
);

const { dataKey, txHash } = await consumer.accessCDR({
uuid,
accessAuxData: "0x",
requesterPubKey,
recipientPrivKey,
globalPubKey,
timeoutMs: 120_000,
});

console.log(`Read tx: ${txHash}`);
console.log(new TextDecoder().decode(dataKey));

​
Encrypt and Download a File

CDR encryption flow showing vault allocation, local encryption, and writing the encrypted key plus data URL to the vault
CDR decryption flow showing ephemeral key generation, access control check, partial decryptions from validators, and client-side combination
Use the file workflow when the encrypted payload should live off-chain and only the encrypted file key plus pointer should be stored in the vault. Upload happens once by the data owner. Download happens later by an authorized reader who recovers the vault payload and then decrypts the stored file. The uploadFile() helper requires deployed condition contracts on both sides, so the example below uses Story’s OwnerWriteCondition for the write side and LicenseReadCondition for the read side. License token holders can decrypt the file (see IP Asset Vaults for the end-to-end license setup). For an owner-only file flow, replicate the low-level steps shown earlier with your wallet (EOA) address as both conditions. 
import { HeliaProvider } from "@piplabs/cdr-sdk";
import { readFile, writeFile } from "node:fs/promises";
import { createHelia } from "helia";
import { unixfs } from "@helia/unixfs";
import { CID } from "multiformats/cid";
import { encodeAbiParameters } from "viem";

const uploaderAddress = walletClient.account!.address;
const OWNER_WRITE_CONDITION = "0x4C9bFC96d7092b590D497A191826C3dA2277c34B";
const LICENSE_READ_CONDITION = "0xC0640AD4CF2CaA9914C8e5C44234359a9102f7a3";
const LICENSE_TOKEN = "0xFe3838BFb30B34170F00030B52eA4893d8aAC6bC";

const writeConditionData = encodeAbiParameters(
  [{ type: "address" }],
  [uploaderAddress],
);

const readConditionData = encodeAbiParameters(
  [{ type: "address" }, { type: "address" }],
  [LICENSE_TOKEN, ipId],
);

// Pure read
const globalPubKey = await client.observer.getGlobalPubKey();

const helia = await createHelia();
const storage = new HeliaProvider({
  helia,
  unixfs: unixfs(helia),
  CID: (s) => CID.parse(s),
});

const sourceFile = await readFile("./example.pdf");

// Off-chain upload + 2 on-chain transactions
const { uuid, cid } = await client.uploader.uploadFile({
  content: new Uint8Array(sourceFile),
  storageProvider: storage,
  globalPubKey,
  updatable: false,
  writeConditionAddr: OWNER_WRITE_CONDITION,
  readConditionAddr: LICENSE_READ_CONDITION,
  writeConditionData,
  readConditionData,
  accessAuxData: "0x",
});

// 1 on-chain read transaction + off-chain download + local AES decryption
const { content, txHash } = await client.consumer.downloadFile({
  uuid,
  accessAuxData: "0x",
  storageProvider: storage,
  timeoutMs: 120_000,
});

console.log(`Stored at CID: ${cid}`);
console.log(`Read tx: ${txHash}`);
await writeFile("./example.decrypted.pdf", Buffer.from(content));
console.log("Decrypted file written to ./example.decrypted.pdf");
HeliaProvider is the only storage backend fully tested on Aeneid in the current release, and it requires Node.js 22+.
uploadFile() and downloadFile() work with raw file bytes. In a browser, start from a File object and convert it with new Uint8Array(await file.arrayBuffer()).

​
Storage Providers

The encrypted-file workflow supports four storage backends:
  • HeliaProvider for in-process IPFS. This is the best starting point for development and the only backend fully tested on Aeneid so far.
  • GatewayProvider for an external IPFS HTTP API plus a gateway URL.
  • StorachaProvider for Storacha / web3.storage.
  • SynapseProvider for Filecoin-backed storage via Synapse.
If you use HeliaProvider, pass the CID.parse function into the constructor as shown above to avoid class mismatches.

​
Step-by-Step (Low-Level)

If you need more control over the process, you can call each step individually.
These snippets continue from the variables in the examples above: walletClient, globalPubKey, requesterPubKey, recipientPrivKey, and dataKey.

​
Encrypt (Low-Level)

import { uuidToLabel } from "@piplabs/cdr-sdk";
import { toHex } from "viem";

const walletAddress = walletClient.account!.address;

// On-chain transaction: allocate a vault using the wallet address as the
// write AND read condition. Only this EOA can write or read.
const { txHash: allocateTx, uuid } = await uploader.allocate({
  updatable: false,
  writeConditionAddr: walletAddress,
  readConditionAddr: walletAddress,
  writeConditionData: "0x",
  readConditionData: "0x",
  skipConditionValidation: true,
});

// Local: derive the label from the UUID
const label = uuidToLabel(uuid);

// Local: TDH2 encrypt the secret
const ciphertext = await uploader.encryptDataKey({
  dataKey,
  globalPubKey,
  label,
});

// On-chain transaction: write encrypted data to the vault
const { txHash: writeTx } = await uploader.write({
  uuid,
  accessAuxData: "0x",
  encryptedData: toHex(ciphertext.raw),
});

​
Decrypt (Low-Level)

import { uuidToLabel } from "@piplabs/cdr-sdk";

// On-chain transaction: submit read request
const { txHash: readTx } = await consumer.read({
  uuid,
  accessAuxData: "0x",
  requesterPubKey,
});

// Off-chain: poll the Story-API endpoint for validator partial decryptions.
// The required threshold is derived from the bucket's own DKG round.
const partials = await consumer.collectPartials({
  uuid,
  requesterPubKey, // the secp256k1 pubkey used in the read request
  timeoutMs: 120_000,
});

// Pure read: fetch the vault ciphertext
const label = uuidToLabel(uuid);
const vault = await observer.getVault(uuid);

// Local: decrypt each partial, then combine them
const recoveredDataKey = await consumer.decryptDataKey({
  ciphertext: {
    raw: Uint8Array.from(Buffer.from(vault.encryptedData.slice(2), "hex")),
    label,
  },
  partials,
  recipientPrivKey,
  globalPubKey,
  label,
});

​
Query DKG State

You can query DKG state and fees without a wallet or WASM initialization: 
import { createPublicClient, http } from "viem";
import { CDRClient } from "@piplabs/cdr-sdk";

const publicClient = createPublicClient({
  transport: http("https://aeneid.storyrpc.io"),
});
const client = new CDRClient({
  network: "testnet",
  publicClient,
  apiUrl: "http://172.192.41.96:1317",
});

const threshold = await client.observer.getOperationalThreshold();
console.log("Operational threshold:", threshold);

const [allocateFee, writeFee, readFee] = await Promise.all([
  client.observer.getAllocateFee(),
  client.observer.getWriteFee(),
  client.observer.getReadFee(),
]);
console.log(
  `Fees — allocate: ${allocateFee}, write: ${writeFee}, read: ${readFee}`,
);

// Query a specific vault
const vault = await client.observer.getVault(1);
console.log("Vault:", vault);

​
Understanding Fees

Each CDR operation has an on-chain fee:
OperationFee QueryDescription
Allocateobserver.getAllocateFee()One-time cost to create a vault
Writeobserver.getWriteFee()Cost per write to a vault
Readobserver.getReadFee()Cost per read/decryption request
Fees are paid in native tokens (wei) and are sent as msg.value with each transaction.