Uploader

The Uploader sub-client handles vault allocation, TDH2 encryption, and writing encrypted data on-chain. Requires a walletClient.

const uploader = client.uploader;

Use uploadCDR() for small secrets stored directly in the vault and uploadFile() when the encrypted bytes should live in an external storage backend.

The SDK also exposes createVault as an alias for uploadCDR, and createFileVault as an alias for uploadFile.

Methods

uploadCDR
uploadFile
allocate
write
encryptDataKey

uploadCDR

High-level method that allocates a vault, encrypts your data, and writes the ciphertext in a single call.

Method	Type
`uploadCDR`	`(params: UploadCDRParams) => Promise<UploadCDRResponse>`

Parameters:

params.dataKey: Uint8Array - The secret payload bytes to encrypt. Despite the name, this can be arbitrary data, not only a cryptographic key.
params.globalPubKey (optional): Uint8Array - The DKG global public key (from observer.getGlobalPubKey()). Auto-queried via the Observer if omitted.
params.updatable: boolean - Whether the vault can be rewritten after initial write
params.writeConditionAddr: `0x${string}` - Address of the write condition contract
params.readConditionAddr: `0x${string}` - Address of the read condition contract
params.writeConditionData: `0x${string}` - ABI-encoded data passed to the write condition
params.readConditionData: `0x${string}` - ABI-encoded data passed to the read condition
params.accessAuxData: `0x${string}` - Auxiliary data passed to conditions during write
params.allocateFeeOverride (optional): bigint - Skip fee query and use this value
params.writeFeeOverride (optional): bigint - Skip fee query and use this value

Example

import { encodeAbiParameters } from "viem";

// DATA Foundation license-gated pattern: only the uploader can write, and only callers
// holding a license token for `ipId` can read. See
// /developers/cdr-sdk/ip-asset-vaults for the full setup.
const OWNER_WRITE_CONDITION = "0x4C9bFC96d7092b590D497A191826C3dA2277c34B";
const LICENSE_READ_CONDITION = "0xC0640AD4CF2CaA9914C8e5C44234359a9102f7a3";
const LICENSE_TOKEN = "0xFe3838BFb30B34170F00030B52eA4893d8aAC6bC";

const writeConditionData = encodeAbiParameters(
  [{ type: "address" }],
  [walletClient.account!.address],
);

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

const globalPubKey = await client.observer.getGlobalPubKey();
const dataKey = new TextEncoder().encode("my secret");

const { uuid, ciphertext, txHashes } = await client.uploader.uploadCDR({
  dataKey,
  globalPubKey,
  updatable: false,
  writeConditionAddr: OWNER_WRITE_CONDITION,
  readConditionAddr: LICENSE_READ_CONDITION,
  writeConditionData,
  readConditionData,
  accessAuxData: "0x",
});

console.log(`Vault UUID: ${uuid}`);
console.log(`Allocate tx: ${txHashes.allocate}`);
console.log(`Write tx: ${txHashes.write}`);

OwnerWriteCondition only implements checkWriteCondition, so it cannot be used as readConditionAddr. For an owner-only flow where the same wallet encrypts and decrypts, use the low-level allocate() example below with your wallet (EOA) address as both conditions and skipConditionValidation: true.

Keep uploadCDR() payloads small enough that the resulting TDH2 ciphertext fits the vault limit (observer.getMaxEncryptedDataSize(), which is 1024 bytes on Aeneid).

UploadCDRResponse

interface UploadCDRResponse {
  uuid: number;
  ciphertext: TDH2Ciphertext;
  txHashes: {
    allocate: `0x${string}`;
    write: `0x${string}`;
  };
}

uploadFile

High-level method that encrypts file bytes locally, uploads the encrypted blob through a StorageProvider, and writes the encrypted file key plus content pointer to CDR in one call. Parameters:

params.content: Uint8Array - File bytes to encrypt and upload
params.storageProvider: StorageProvider - Backend used for upload and download
params.globalPubKey (optional): Uint8Array - DKG global public key. Auto-queried via the Observer if omitted.
params.updatable: boolean - Whether the vault can be rewritten
params.writeConditionAddr: `0x${string}` - Address of the write condition contract
params.readConditionAddr: `0x${string}` - Address of the read condition contract
params.writeConditionData: `0x${string}` - ABI-encoded write condition data
params.readConditionData: `0x${string}` - ABI-encoded read condition data
params.accessAuxData: `0x${string}` - Auxiliary data passed to conditions during write
params.pin (optional): boolean - Whether the storage provider should pin the uploaded blob
params.allocateFeeOverride (optional): bigint - Skip the allocate fee query
params.writeFeeOverride (optional): bigint - Skip the write fee query

Example

import { HeliaProvider } from "@piplabs/cdr-sdk";
import { readFile } from "node:fs/promises";
import { createHelia } from "helia";
import { unixfs } from "@helia/unixfs";
import { CID } from "multiformats/cid";
import { encodeAbiParameters } from "viem";

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

// DATA Foundation license-gated pattern: see /developers/cdr-sdk/ip-asset-vaults for
// the full license setup. For an owner-only file flow, use the low-level
// `allocate()` path with your wallet (EOA) address as both conditions.
const OWNER_WRITE_CONDITION = "0x4C9bFC96d7092b590D497A191826C3dA2277c34B";
const LICENSE_READ_CONDITION = "0xC0640AD4CF2CaA9914C8e5C44234359a9102f7a3";
const LICENSE_TOKEN = "0xFe3838BFb30B34170F00030B52eA4893d8aAC6bC";

const writeConditionData = encodeAbiParameters(
  [{ type: "address" }],
  [walletClient.account!.address],
);

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

const fileBytes = await readFile("./example.pdf");
const globalPubKey = await client.observer.getGlobalPubKey();
const { uuid, cid } = await client.uploader.uploadFile({
  content: new Uint8Array(fileBytes),
  storageProvider: storage,
  globalPubKey,
  updatable: false,
  writeConditionAddr: OWNER_WRITE_CONDITION,
  readConditionAddr: LICENSE_READ_CONDITION,
  writeConditionData,
  readConditionData,
  accessAuxData: "0x",
});

console.log(`Vault UUID: ${uuid}`);
console.log(`Stored CID: ${cid}`);

HeliaProvider is the only storage backend fully tested on Aeneid in the current release. GatewayProvider, StorachaProvider, and SynapseProvider are implemented but were not yet end-to-end validated in the release run.

uploadFile() keeps the file bytes off-chain. The vault stores a TDH2 ciphertext of a small JSON payload containing { cid, key }.

In browser code, pass file bytes from new Uint8Array(await file.arrayBuffer()) instead of readFile(...).

allocate

Creates a new CDR vault on-chain with the specified access control conditions.

Method	Type
`allocate`	`(params: AllocateParams) => Promise<AllocateResponse>`

Parameters:

params.updatable: boolean - Whether the vault can be rewritten
params.writeConditionAddr: `0x${string}` - Write condition contract address
params.readConditionAddr: `0x${string}` - Read condition contract address
params.writeConditionData: `0x${string}` - ABI-encoded write condition data
params.readConditionData: `0x${string}` - ABI-encoded read condition data
params.feeOverride (optional): bigint - Skip fee query
params.skipConditionValidation (optional): boolean - Skip interface validation when intentionally using an EOA condition address

Example

const userAddress = walletClient.account!.address;

const { txHash, uuid } = await client.uploader.allocate({
  updatable: false,
  writeConditionAddr: userAddress,
  readConditionAddr: userAddress,
  writeConditionData: "0x",
  readConditionData: "0x",
  skipConditionValidation: true,
});

console.log(`Vault ${uuid} allocated at tx: ${txHash}`);

uploadCDR() and uploadFile() do not expose skipConditionValidation, so use a real condition contract with those high-level helpers.

AllocateResponse

interface AllocateResponse {
  txHash: `0x${string}`;
  uuid: number; // parsed from VaultAllocated event
}

write

Writes encrypted data to an existing vault. The caller must satisfy the vault’s write condition.

Method	Type
`write`	`(params: WriteParams) => Promise<WriteResponse>`

Parameters:

params.uuid: number - The vault UUID
params.accessAuxData: `0x${string}` - Auxiliary data passed to the write condition
params.encryptedData: `0x${string}` - Hex-encoded TDH2 ciphertext
params.feeOverride (optional): bigint - Skip fee query

Example

import { toHex } from "viem";

const { txHash } = await client.uploader.write({
  uuid: 42,
  accessAuxData: "0x",
  encryptedData: toHex(ciphertext.raw),
});

WriteResponse

interface WriteResponse {
  txHash: `0x${string}`;
}

encryptDataKey

Locally encrypts data using TDH2 threshold encryption. No blockchain interaction.

Method	Type
`encryptDataKey`	`(params: EncryptParams) => Promise<TDH2Ciphertext>`

Parameters:

params.dataKey: Uint8Array - The plaintext data to encrypt
params.globalPubKey (optional): Uint8Array - DKG global public key (34 bytes). Auto-queried via the Observer if omitted.
params.label: Uint8Array - 32-byte label binding ciphertext to a vault (use uuidToLabel(uuid))

Example

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

const label = uuidToLabel(uuid);
const ciphertext = await client.uploader.encryptDataKey({
  dataKey: new TextEncoder().encode("secret"),
  globalPubKey,
  label,
});

console.log(ciphertext.raw); // Uint8Array - serialized TDH2 ciphertext
console.log(ciphertext.label); // Uint8Array - the label used

TDH2Ciphertext

interface TDH2Ciphertext {
  raw: Uint8Array;   // serialized ciphertext (cb-mpc format)
  label: Uint8Array; // 32-byte context binding
}

Get Started

CDR SDK

Protocol SDK (IP & Licensing)

Uploader

Uploader

Methods

uploadCDR

uploadFile

allocate

write

encryptDataKey

​Uploader

​Methods

​uploadCDR

​uploadFile

​allocate

​write

​encryptDataKey

Uploader

Methods

uploadCDR

uploadFile

allocate

write

encryptDataKey